![]() |
Murl Engine API
Version 2018.3
|
The ITimeline graph node interface. More...
#include <murl_graph_i_timeline.h>
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:
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 Output-States, Slots und Units for an overview of state handling during scene graph traversal.
See Graph::ITimelineState for activating a timeline.
Public Member Functions | |
virtual INode * | GetNodeInterface ()=0 |
Get the mutable Graph::INode interface. More... | |
virtual const INode * | GetNodeInterface () const =0 |
Get the constant Graph::INode interface. More... | |
virtual ITimelineNodeTarget * | GetParentTimelineNodeTarget ()=0 |
Get the mutable container holding an optional parent timeline. More... | |
virtual const ITimelineNodeTarget * | GetParentTimelineNodeTarget () const =0 |
Get the constant container holding an optional parent timeline. More... | |
virtual ITimelineNodeTarget * | GetSubTimelineNodeTarget ()=0 |
Get the mutable container holding the optional sub-timelines. More... | |
virtual const ITimelineNodeTarget * | GetSubTimelineNodeTarget () const =0 |
Get the constant container holding the optional sub-timelines. More... | |
virtual IAnimationResourceTarget * | GetAnimationResourceTarget ()=0 |
Get a mutable Graph::IAnimationResourceTarget container. More... | |
virtual const IAnimationResourceTarget * | GetAnimationResourceTarget () const =0 |
Get a constant Graph::IAnimationResourceTarget container. More... | |
virtual Bool | Reset ()=0 |
Reset the timeline. More... | |
virtual Bool | ResetTo (Real startTime)=0 |
Reset the timeline to a specified start time. More... | |
virtual Bool | Start ()=0 |
Start or continue the timeline. More... | |
virtual Bool | Start (Real startTime, Real endTime)=0 |
Start the timeline with specified parameters. More... | |
virtual Bool | Start (Real startTime, Real endTime, SInt32 numberOfLoops)=0 |
Start the timeline with specified parameters. More... | |
virtual Bool | Start (Real startTime, Real endTime, Real loopStartTime, Real loopEndTime, SInt32 numberOfLoops)=0 |
Start the timeline with specified parameters. More... | |
virtual Bool | Pause ()=0 |
Pause the timeline. More... | |
virtual Bool | Stop ()=0 |
Stop the timeline. More... | |
virtual Bool | Rewind ()=0 |
Rewind the timeline. More... | |
virtual Bool | Stall () const =0 |
Stall the timeline. More... | |
virtual Bool | SetClipIndex (UInt32 clipIndex)=0 |
Set the clip index. More... | |
virtual UInt32 | GetClipIndex () const =0 |
Get the clip index. More... | |
virtual Bool | SetClipName (const String &clipName)=0 |
Set the current clip by name. More... | |
virtual String | GetClipName () const =0 |
Get the current clip's name. More... | |
virtual Bool | SetStartTime (Real startTime)=0 |
Set the start time. More... | |
virtual Real | GetStartTime () const =0 |
Get the start time. More... | |
virtual Bool | SetEndTime (Real endTime)=0 |
Set the end time. More... | |
virtual Real | GetEndTime () const =0 |
Get the end time. More... | |
virtual Bool | SetLoopStartTime (Real startTime)=0 |
Set the loop start time. More... | |
virtual Real | GetLoopStartTime () const =0 |
Get the loop start time. More... | |
virtual Bool | SetLoopEndTime (Real endTime)=0 |
Set the loop end time. More... | |
virtual Real | GetLoopEndTime () const =0 |
Get the loop end time. More... | |
virtual Bool | SetStartLoop (SInt32 startLoop)=0 |
Set the start loop. More... | |
virtual SInt32 | GetStartLoop () const =0 |
Get the start loop. More... | |
virtual Bool | SetNumberOfLoops (SInt32 numberOfLoops)=0 |
Set the number of loops. More... | |
virtual SInt32 | GetNumberOfLoops () const =0 |
Get the number of loops. More... | |
virtual Bool | SetTimeShift (Double timeShift)=0 |
Set the time shift value. More... | |
virtual Double | GetTimeShift () const =0 |
Get the time shift value. More... | |
virtual Bool | SetTimeOffset (Double timeOffset)=0 |
Set the time offset value. More... | |
virtual Double | GetTimeOffset () const =0 |
Get the time offset value. More... | |
virtual Bool | SetTimeScale (Real timeScale)=0 |
Set the time scale factor. More... | |
virtual Real | GetTimeScale () const =0 |
Get the time scale factor. More... | |
virtual Bool | SetTriggerGroupMask (UInt32 mask)=0 |
Set the active trigger groups for this timeline. More... | |
virtual UInt32 | GetTriggerGroupMask () const =0 |
Get the active trigger groups for this timeline. More... | |
virtual Bool | SetAutoRewindEnabled (Bool enabled)=0 |
Enable/disable automatic rewind. More... | |
virtual Bool | IsAutoRewindEnabled () const =0 |
Check if automatic rewind is enabled. More... | |
virtual Bool | SetStartOnActivateEnabled (Bool enabled)=0 |
Enable/disable starting on node activation. More... | |
virtual Bool | IsStartOnActivateEnabled () const =0 |
Check if starting on node activation is enabled. More... | |
virtual Bool | SetStopOnDeactivateEnabled (Bool enabled)=0 |
Enable/disable stopping on node deactivation. More... | |
virtual Bool | IsStopOnDeactivateEnabled () const =0 |
Check if stopping on node deactivation is enabled. More... | |
virtual Bool | IsRunning () const =0 |
Check if the timeline is running. More... | |
virtual Bool | IsPaused () const =0 |
Check if the timeline is paused. More... | |
virtual Bool | IsStopped () const =0 |
Check if the timeline is stopped. More... | |
virtual Bool | WasStarted () const =0 |
Check if the timeline was started from the beginning. More... | |
virtual Bool | WasRunning () const =0 |
Check if the timeline has stopped running. More... | |
virtual Bool | IsOrWasRunning () const =0 |
Check if the timeline is or was running. More... | |
virtual Bool | HasPassedTime (Real time) const =0 |
Check if the current time has passed a specified time within the most recent tick. More... | |
virtual Bool | HasPassedLoop (SInt32 loop=-1) const =0 |
Check if the current loop has passed a specified loop number within the most recent tick. More... | |
virtual Double | GetRecentTime () const =0 |
Get the recent time. More... | |
virtual Double | GetCurrentTime () const =0 |
Get the current time. More... | |
virtual Double | GetRemainingTime () const =0 |
Get the remaining time. More... | |
virtual void | SetCurrentTime (Double time)=0 |
Set the current time. More... | |
virtual SInt32 | GetRecentLoop () const =0 |
Get the recent loop. More... | |
virtual SInt32 | GetCurrentLoop () const =0 |
Get the current loop. More... | |
virtual SInt32 | GetRemainingLoops () const =0 |
Get the remaining loops. More... | |
virtual Bool | SetCurrentLoop (SInt32 loop)=0 |
Set the current loop. More... | |
virtual IEnums::AnimationState | GetRecentState () const =0 |
Get the recent animation state. More... | |
virtual IEnums::AnimationState | GetCurrentState () const =0 |
Get the current animation state. More... | |
virtual UInt32 | GetNumberOfStages () const =0 |
Get the timeline's number of stages. More... | |
virtual const ITimeline * | GetTimeline (UInt32 stage) const =0 |
Get the timeline's actual node at a given stage. More... | |
![]() | |
virtual Bool | SetUnit (UInt32 unit)=0 |
Set the unit index to use. More... | |
virtual UInt32 | GetUnit () const =0 |
Get the unit index to use. More... | |
![]() | |
virtual Bool | SetBlendFactor (UInt32 stageIndex, Real blendFactor)=0 |
Set the blend factor for a given stage. More... | |
virtual Real | GetBlendFactor (UInt32 stageIndex) const =0 |
Get the blend factor set for a given stage. More... | |
|
pure virtual |
Get the mutable Graph::INode interface.
This method returns a mutable pointer to the node's Graph::INode interface, to be able to query or modify common node properties such as active state, visibility or ID.
|
pure virtual |
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.
|
pure virtual |
Get the mutable container holding an optional parent timeline.
This method returns a mutable pointer to the node's Graph::ITimelineNodeTarget parent container, which is used to store an optional timeline parent to inherit values from.
|
pure virtual |
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.
|
pure virtual |
Get the mutable container holding the optional sub-timelines.
This method returns a mutable pointer to the node's Graph::ITimelineNodeTarget sub container, which is used to store multiple sub-timeline stages.
|
pure virtual |
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.
|
pure virtual |
Get a mutable Graph::IAnimationResourceTarget container.
This method returns a mutable pointer to a Graph::IAnimationResourceTarget container, which allows to add, remove or 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().
|
pure virtual |
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().
|
pure virtual |
Reset the timeline.
Stop the timeline, reset the WasRunning() state and call Rewind().
Reset the timeline to a specified start time.
Set the start time and call Reset().
startTime | The start time in seconds. |
|
pure virtual |
Start or continue the timeline.
Does not modify the current time and loop.
|
pure virtual |
Start the timeline with specified parameters.
Set start/end time, loop start/end time, number of loops, calls Rewind() and Start().
startTime | The start time in seconds. |
endTime | The end time in seconds. |
loopStartTime | The loop start time in seconds. |
loopEndTime | The loop end time in seconds. |
numberOfLoops | Number of loops. |
|
pure virtual |
Pause the timeline.
|
pure virtual |
Stop the timeline.
Rewind() is called if auto rewind is enabled.
|
pure virtual |
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.
|
pure virtual |
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.
Set the clip index.
Setting the clip index works in conjunction with an animation resource set via the resource target obtained from GetAnimationResourceTarget().
clipIndex | The clip index to set. |
|
pure virtual |
Get the clip index.
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.
clipName | The clip name. |
|
pure virtual |
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.
Set the start time.
startTime | The start time in seconds. |
|
pure virtual |
Get the start time.
Set the end time.
endTime | The end time in seconds. |
|
pure virtual |
Get the end time.
Set the loop start time.
startTime | The loop start time in seconds. |
|
pure virtual |
Get the loop start time.
Set the loop end time.
endTime | The loop end time in seconds. |
|
pure virtual |
Get the loop end time.
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.
startLoop | The start loop. |
|
pure virtual |
Get the start loop.
Set the number of loops.
numberOfLoops | Number of loops. |
|
pure virtual |
Get the number of loops.
Set the time shift value.
timeShift | The time shift value. |
|
pure virtual |
Get the time shift value.
Set the time offset value.
timeOffset | The time offset value. |
|
pure virtual |
Get the time offset value.
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.
timeScale | The time scale factor. |
|
pure virtual |
Get the time scale factor.
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().
mask | The trigger group bit mask. |
|
pure virtual |
Get the active trigger groups for this timeline.
Enable/disable automatic rewind.
Automatic rewind is calling Rewind() when the timeline is stopped.
enabled | Enable automatic rewind if true. |
|
pure virtual |
Check if automatic rewind is 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.
enabled | Enable starting if true. |
|
pure virtual |
Check if starting on node activation is 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().
enabled | Enable stopping if true. |
|
pure virtual |
Check if stopping on node deactivation is enabled.
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
Check if the timeline was started from the beginning.
|
pure virtual |
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.
|
pure virtual |
Check if the timeline is or was running.
Returns (IsRunning() || WasRunning()) state.
Check if the current time has passed a specified time within the most recent tick.
Does not consider loops, for evaluating loops see HasPassedLoop().
time | The time to check in seconds. |
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.
loop | The loop number to check. |
|
pure virtual |
Get the recent time.
|
pure virtual |
Get the current time.
This method does not consider loops, for evaluating loops see GetCurrentLoop().
|
pure virtual |
Get the remaining time.
This method calculates GetEndTime() - GetCurrentTime() which does not consider loops, for evaluating loops see GetCurrentLoop().
|
pure virtual |
Set the current time.
This method does not consider loops, for setting loops see SetCurrentLoop().
time | The current time to set in seconds. |
|
pure virtual |
Get the recent loop.
|
pure virtual |
Get the current loop.
The current loop provides the following information for n loops:
|
pure virtual |
Get the remaining loops.
Calculates GetNumberOfLoops() - GetCurrentLoop().
Set the current loop.
The current loop represents the following information for n loops:
loop | The current loop to set. |
|
pure virtual |
Get the recent animation state.
|
pure virtual |
Get the current animation state.
|
pure virtual |
Get the timeline's number of stages.
Get the timeline's actual node at a given stage.
stage | The stage to query. |