Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.ITimeline

The ITimeline graph node interface.

The timeline node is evaluated each logic traversal if activated.
A simple timeline is specified by a start/end time.
The timeline can be controlled by Start(), Pause() and Stop() calls.
All setters are taking effect immediately even if the timeline is running.
A more detailed timeline can use a loop start/end time, resulting in 3 phases:

  • Intro running from start to loop start time.
  • Loop running from loop start to loop end time several times.
  • Outro running from loop end to end time.

The number of loops specifies the counter for of the loop phase.
Endless looping can be achieved by setting number of loops to < 0.
If number of loops is 0 the loop start/end time is ignored which means the timeline simply runs from start to end time.
If the start time is equal to the loop start time the intro phase is skipped.
If the end time is equal to the loop end time the outro phase is skipped.

Timelines may depend on an optional parent timeline, which is in control of actually starting and stopping the current timeline. See GetParentTimelineNodeTarget().

Optionally, a Resource::IAnimation object may be defined, which can be used to retrieve the time range of an animation clip, which is then used for playback. See GetAnimationResourceTarget(), SetClipIndex() and SetClipName().

A timeline also implements the Graph::IBlendable interface, in order to blend multiple timelines together. Blending can be performed both between multiple timeline units as well as multiple stages from a Graph::MultiTimeline. See GetSubTimelineNodeTarget() for latter case.

It is possible to define a bit mask of up to 32 different global trigger groups, which can be used to selectively enable/disable the timeline's effect on e.g. controllers that implement the Graph::ITimeController interface. See SetTriggerGroupMask() and Graph::ITimeController::SetResponseGroupMask(). By default, all 32 groups are triggered.

See sceneGraphStatesSlotsUnits for an overview of state handling during scene graph traversal.
See Graph::ITimelineState for activating a timeline.


Table members

Inherited


Murl.Graph.IStateUnit
Murl.Graph.IBlendable

Methods


GetNodeInterface()

Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant Graph::INode interface, or null if not available

GetParentTimelineNodeTarget()

Get the constant container holding an optional parent timeline. This method returns a constant pointer to the node's Graph::ITimelineNodeTarget parent container, which is used to store an optional timeline parent to inherit values from.

Murl.Graph.IGenericNodeTarget.GraphITimeline GetParentTimelineNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITimeline The constant Graph::ITimelineNodeTarget container, or null if not available.

GetSubTimelineNodeTarget()

Get the constant container holding the optional sub-timelines. This method returns a constant pointer to the node's Graph::ITimelineNodeTarget sub container, which is used to store multiple sub-timeline stages.

Murl.Graph.IGenericNodeTarget.GraphITimeline GetSubTimelineNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITimeline The constant Graph::ITimelineNodeTarget container, or null if not available.

GetAnimationResourceTarget()

Get a constant Graph::IAnimationResourceTarget container. This method returns a constant pointer to a Graph::IAnimationResourceTarget container, which allows to query the optional animation resource that can be used to configure the timeline to play back the time range of a specific animation clip from the resource. See also ITimeline::SetClipIndex().

Murl.Graph.IGenericResourceTarget.ResourceIAnimation GetAnimationResourceTarget()

Returns
Murl.Graph.IGenericResourceTarget.ResourceIAnimation The constant Graph::IAnimationResourceTarget container.

Reset()

Reset the timeline. Stop the timeline, reset the WasRunning() state and call Rewind().

Boolean Reset()

Returns
Boolean true if successful.

ResetTo(startTime)

Reset the timeline to a specified start time. Set the start time and call Reset().

Boolean ResetTo(Number startTime)

Parameters
startTimeThe start time in seconds.
Returns
Boolean true if successful.

Start()

Start or continue the timeline. Does not modify the current time and loop.

Boolean Start()

Returns
Boolean true if successful.

Start(startTime, endTime)

Start the timeline with specified parameters. Set start/end time, calls Rewind() and Start().

Boolean Start(Number startTime, Number endTime)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
Returns
Boolean true if successful.

Start(startTime, endTime, numberOfLoops)

Start the timeline with specified parameters. Set start/end time, number of loops, calls Rewind() and Start().

Boolean Start(Number startTime, Number endTime, Integer numberOfLoops)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
numberOfLoopsNumber of loops.
Returns
Boolean true if successful.

Start(startTime, endTime, loopStartTime, loopEndTime, numberOfLoops)

Start the timeline with specified parameters. Set start/end time, loop start/end time, number of loops, calls Rewind() and Start().

Boolean Start(Number startTime, Number endTime, Number loopStartTime, Number loopEndTime, Integer numberOfLoops)

Parameters
startTimeThe start time in seconds.
endTimeThe end time in seconds.
loopStartTimeThe loop start time in seconds.
loopEndTimeThe loop end time in seconds.
numberOfLoopsNumber of loops.
Returns
Boolean true if successful.

Pause()

Pause the timeline.

Boolean Pause()

Returns
Boolean true if timeline was paused, false if timeline is not running.

Stop()

Stop the timeline. Rewind() is called if auto rewind is enabled.

Boolean Stop()

Returns
Boolean true if timeline was stopped, false if timeline is already stopped.

Rewind()

Rewind the timeline. Sets the current time to the start time and the current loop to the start loop. Does not affect the current running state.

Boolean Rewind()

Returns
Boolean true if successful.

Stall()

Stall the timeline. This method acts as a trigger to pause the timeline for a single logic tick. Usually this is called by some node that depends on a steady flow of input data (such as a movie stream) whenever it has to wait for new input data in order to continue decoding. In this case, the timeline may be stalled so that other animations depending on that timeline are kept in sync.

Boolean Stall()

Returns
Boolean true if successful.

SetClipIndex(clipIndex)

Set the clip index. Setting the clip index works in conjunction with an animation resource set via the resource target obtained from GetAnimationResourceTarget().

Boolean SetClipIndex(Integer clipIndex)

Parameters
clipIndexThe clip index to set.
Returns
Boolean true if successful.

GetClipIndex()

Get the clip index.

Integer GetClipIndex()

Returns
Integer The clip index.

SetClipName(clipName)

Set the current clip by name. Setting the clip works only in conjunction with an animation resource set via the resource target obtained from GetAnimationResourceTarget(), from which the actual clip index is retrieved by its name. This method fails if the given clip name is empty, no animation resource is set, or no clip with that name was found in the animation resource.

Boolean SetClipName(String clipName)

Parameters
clipNameThe clip name.
Returns
Boolean true if successful.

GetClipName()

Get the current clip's name. This method returns an empty string when no animation resource is defined or the currently active clip is unnamed.

String GetClipName()

Returns
String The clip name if available.

SetStartTime(startTime)

Set the start time.

Boolean SetStartTime(Number startTime)

Parameters
startTimeThe start time in seconds.
Returns
Boolean true if successful.

GetStartTime()

Get the start time.

Number GetStartTime()

Returns
Number The start time in seconds.

SetEndTime(endTime)

Set the end time.

Boolean SetEndTime(Number endTime)

Parameters
endTimeThe end time in seconds.
Returns
Boolean true if successful.

GetEndTime()

Get the end time.

Number GetEndTime()

Returns
Number The end time in seconds.

SetLoopStartTime(startTime)

Set the loop start time.

Boolean SetLoopStartTime(Number startTime)

Parameters
startTimeThe loop start time in seconds.
Returns
Boolean true if successful.

GetLoopStartTime()

Get the loop start time.

Number GetLoopStartTime()

Returns
Number The loop start time in seconds.

SetLoopEndTime(endTime)

Set the loop end time.

Boolean SetLoopEndTime(Number endTime)

Parameters
endTimeThe loop end time in seconds.
Returns
Boolean true if successful.

GetLoopEndTime()

Get the loop end time.

Number GetLoopEndTime()

Returns
Number The loop end time in seconds.

SetStartLoop(startLoop)

Set the start loop. Loop #0 is considered the intro, if it is desired to start right in the middle of the first actual loop, the start loop should be set to 1.

Boolean SetStartLoop(Integer startLoop)

Parameters
startLoopThe start loop.
Returns
Boolean true if successful.

GetStartLoop()

Get the start loop.

Integer GetStartLoop()

Returns
Integer The start loop.

SetNumberOfLoops(numberOfLoops)

Set the number of loops.

Boolean SetNumberOfLoops(Integer numberOfLoops)

Parameters
numberOfLoopsNumber of loops.
Returns
Boolean true if successful.

GetNumberOfLoops()

Get the number of loops.

Integer GetNumberOfLoops()

Returns
Integer The number of loops.

SetTimeShift(timeShift)

Set the time shift value.

Boolean SetTimeShift(Number timeShift)

Parameters
timeShiftThe time shift value.
Returns
Boolean true if successful.

GetTimeShift()

Get the time shift value.

Number GetTimeShift()

Returns
Number The time shift value.

SetTimeOffset(timeOffset)

Set the time offset value.

Boolean SetTimeOffset(Number timeOffset)

Parameters
timeOffsetThe time offset value.
Returns
Boolean true if successful.

GetTimeOffset()

Get the time offset value.

Number GetTimeOffset()

Returns
Number The time offset value.

SetTimeScale(timeScale)

Set the time scale factor. The recent tick duration is multiplied by the time scale factor and added to the current time each logic tick. The default time scale factor is 1.

Boolean SetTimeScale(Number timeScale)

Parameters
timeScaleThe time scale factor.
Returns
Boolean true if successful.

GetTimeScale()

Get the time scale factor.

Number GetTimeScale()

Returns
Number true The time scale factor.

SetTriggerGroupMask(mask)

Set the active trigger groups for this timeline. A timeline can be configured to influence a number of user-defined controller groups stored as a UInt32 bit mask, allowing up to 32 individual groups. See Graph::IController::SetResponseGroupMask().

Boolean SetTriggerGroupMask(Integer mask)

Parameters
maskThe trigger group bit mask.
Returns
Boolean true if successful.

GetTriggerGroupMask()

Get the active trigger groups for this timeline.

Integer GetTriggerGroupMask()

Returns
Integer The bit mask specifying active trigger groups.

SetAutoRewindEnabled(enabled)

Enable/disable automatic rewind. Automatic rewind is calling Rewind() when the timeline is stopped.

Boolean SetAutoRewindEnabled(Boolean enabled)

Parameters
enabledEnable automatic rewind if true.
Returns
Boolean true if successful.

IsAutoRewindEnabled()

Check if automatic rewind is enabled.

Boolean IsAutoRewindEnabled()

Returns
Boolean true if automatic rewind.

SetStartOnActivateEnabled(enabled)

Enable/disable starting on node activation. If the timeline node or a sub-tree containing the node is changed to active the Start() method is called within the next logic traversal.

Boolean SetStartOnActivateEnabled(Boolean enabled)

Parameters
enabledEnable starting if true.
Returns
Boolean true if successful.

IsStartOnActivateEnabled()

Check if starting on node activation is enabled.

Boolean IsStartOnActivateEnabled()

Returns
Boolean true if enabled.

SetStopOnDeactivateEnabled(enabled)

Enable/disable stopping on node deactivation. If the timeline node or a sub-tree containing the node is changed to inactive the Stop() method is called within the next logic traversal. For potential sideffects see WasRunning().

Boolean SetStopOnDeactivateEnabled(Boolean enabled)

Parameters
enabledEnable stopping if true.
Returns
Boolean true if successful.

IsStopOnDeactivateEnabled()

Check if stopping on node deactivation is enabled.

Boolean IsStopOnDeactivateEnabled()

Returns
Boolean true if enabled.

IsRunning()

Check if the timeline is running. A timeline can be started by calling Start() and stopped by calling Stop().

Boolean IsRunning()

Returns
Boolean true if running.

IsPaused()

Check if the timeline is paused. A timeline can be paused by calling Pause() and continued by calling Start().

Boolean IsPaused()

Returns
Boolean true if paused.

IsStopped()

Check if the timeline is stopped. A timeline can be stopped by calling Stop() and started by calling Start().

Boolean IsStopped()

Returns
Boolean true if stopped.

WasStarted()

Check if the timeline was started from the beginning.

Boolean WasStarted()

Returns
Boolean true if started.

WasRunning()

Check if the timeline has stopped running. If the timeline is stopped this state is true within the current logic tick only and will be cleared at the next logic traversal.
(!) This state remains unchanged if the timeline node or a sub-tree containing the node is set to inactive within the current logic tick or if SetStopOnDeactivateEnabled() is enabled. In such a case the Reset() method can be called to clear the state.

Boolean WasRunning()

Returns
Boolean true if stopped.

IsOrWasRunning()

Check if the timeline is or was running. Returns (IsRunning() || WasRunning()) state.

Boolean IsOrWasRunning()

Returns
Boolean true if IsRunning() or WasRunning() is true.

HasPassedTime(time)

Check if the current time has passed a specified time within the most recent tick. Does not consider loops, for evaluating loops see HasPassedLoop().

Boolean HasPassedTime(Number time)

Parameters
timeThe time to check in seconds.
Returns
Boolean true if the current time has passed a specified time within the most recent tick.

HasPassedLoop(loop)

Check if the current loop has passed a specified loop number within the most recent tick. If the loop number to check is negative, true is returned each time the current loop has changed.

Boolean HasPassedLoop(Integer loop)

Parameters
loopThe loop number to check.
Returns
Boolean true if the current loop has passed a specified loop within the most recent tick.

GetRecentTime()

Get the recent time.

Number GetRecentTime()

Returns
Number The recent time in seconds.

GetCurrentTime()

Get the current time. This method does not consider loops, for evaluating loops see GetCurrentLoop().

Number GetCurrentTime()

Returns
Number The current time in seconds.

GetRemainingTime()

Get the remaining time. This method calculates GetEndTime() - GetCurrentTime() which does not consider loops, for evaluating loops see GetCurrentLoop().

Number GetRemainingTime()

Returns
Number The remaining time in seconds.

SetCurrentTime(time)

Set the current time. This method does not consider loops, for setting loops see SetCurrentLoop().

SetCurrentTime(Number time)

Parameters
timeThe current time to set in seconds.

GetRecentLoop()

Get the recent loop.

Integer GetRecentLoop()

Returns
Integer The recent loop, 0 if number of loops is 0.

GetCurrentLoop()

Get the current loop. The current loop provides the following information for n loops:

  • 0 Intro running from start to loop start time.
  • 1 .. n Loop running from loop start to loop end time.
  • n + 1 Outro running from loop end to end time.

Integer GetCurrentLoop()

Returns
Integer The current loop, 0 if number of loops is 0.

GetRemainingLoops()

Get the remaining loops. Calculates GetNumberOfLoops() - GetCurrentLoop().

Integer GetRemainingLoops()

Returns
Integer The remaining loops, -1 if number of loops is < 0, 0 if number of loops is 0 or intro/outro is running.

SetCurrentLoop(loop)

Set the current loop. The current loop represents the following information for n loops:

  • 0 Intro running from start to loop start time.
  • 1 .. n Loop running from loop start to loop end time.
  • n + 1 Outro running from loop end to end time.

Boolean SetCurrentLoop(Integer loop)

Parameters
loopThe current loop to set.
Returns
Boolean true if successful, false if the loop number is out of range.

GetRecentState()

Get the recent animation state.

Murl.IEnums.AnimationState GetRecentState()

Returns
Murl.IEnums.AnimationState The recent animation state.

GetCurrentState()

Get the current animation state.

Murl.IEnums.AnimationState GetCurrentState()

Returns
Murl.IEnums.AnimationState The current animation state.

GetNumberOfStages()

Get the timeline's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.

GetTimeline(stage)

Get the timeline's actual node at a given stage.

Murl.Graph.ITimeline GetTimeline(Integer stage)

Parameters
stageThe stage to query.
Returns
Murl.Graph.ITimeline The timeline sub-object.