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.IRunnable
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.

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.

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.

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.

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.