You.i Engine
CYITimeline Class Reference

Detailed Description

A timeline which sources its data from a backing store.

This class interprets a slide of data from a backing store as a timeline. The timeline can be played and notify users when it has completed.

Timelines are composed of zero or more timeline 'tracks'. Each track can have an associated scene node. Each track affects a single property of that scene node.

By default, the timeline 'plays back' the data from its backing store without modifications. However, a user can configure a source or target value for each timeline track. The configured frame mode for the start and end frame is then used, in conjunction with the configured source and target value, to remap the backing store values to a new set of values. When no source or target value is specified, the timeline plays 'as is', using data directly from its backing store.

The following table gives an overview of the possible combinations of frame modes, source and target, and their effect on the timeline. In that table, A represents the backing-store start value, B represents the backing-store end value, S represents an optional user-assigned source value and T represents an optional user-assigned end value.

Start Mode End Mode Source Target Start value End value Effect on timeline Description
YI_ABSOLUTE YI_ABSOLUTE None None A B None The timeline uses the backing store data directly.
YI_RELATIVE YI_ABSOLUTE None None A B None No configured source or target means the 'YI_RELATIVE' mode has no effect.
YI_ABSOLUTE YI_RELATIVE None None A B None No configured source or target means the 'YI_RELATIVE' mode has no effect.
YI_RELATIVE YI_ABSOLUTE None T T+A-B T Offset The timeline is offset such that the end value is T. The start value is thus relative to the end value.
YI_ABSOLUTE YI_RELATIVE S None S S+A-B Offset The timeline is offset such that the start value is S. The end value is thus relative to the start value.
YI_RELATIVE YI_ABSOLUTE S None A B None Configuring a source value when the start mode is 'YI_RELATIVE' has no effect.
YI_ABSOLUTE YI_RELATIVE None T A B None Configuring a target value when the end mode is 'YI_RELATIVE' has no effect.
YI_RELATIVE YI_ABSOLUTE S T A B Offset The timeline is offset such that the end value is T. The configured source value is ignored.
YI_ABSOLUTE YI_RELATIVE S T A B Offset The timeline is offset such that the start value is S. The configured target value is ignored.
YI_ABSOLUTE YI_ABSOLUTE S T S T Stretch The timeline is 'streched' such that its start value is S instead of A, and such that its end value is T instead of B.
YI_ABSOLUTE YI_ABSOLUTE None T A T Stretch The timeline is 'streched' such that its end value is T instead of B.
YI_ABSOLUTE YI_ABSOLUTE S None S B Stretch The timeline is 'streched' such that its start value is S instead of A
YI_RELATIVE YI_RELATIVE Any Any N/A N/A N/A Configuring both the start and end mode as 'YI_RELATIVE' is not supported.
Note
When a source and/or target value is specified and the timeline has a SCALE track, then all of the timeline values for the SCALE track along with the source and target values must be strictly positive. If any of the SCALE values is negative or if the SCALE values from the backing store become negative, then the effective scale for that track will be 0.
When a source and/or target value is specified and both the start and end frame mode is set to YI_ABSOLUTE, animations can only be played if the start and end values in the backing store are different. If the values are identical, the animation for that particular component will go directly to the end value. For example, consider a timeline with a position track. That track has a start position of (10, 10, 10), and an end position of (20, 10, 20). A user then sets a target position of (30, 30, 30). Because there the start and end positions are identical in the backing store (they're both 10), the timeline, when played, will animate the position of the object from (10, 30, 10) to (30, 30, 30) instead of the expected (10, 10, 10) to (30, 30, 30).
Specifying a source or target value for a timeline track is not supported for tracks with attribute types ORIENTATION and IS_VISIBLE.
See also
CYIAbstractTimeline
CYITimelineTrack

#include <animation/YiTimeline.h>

Inheritance diagram for CYITimeline:

Public Member Functions

 CYITimeline (std::shared_ptr< CYITimelineBackingStore > pBackingStore, CYISceneNode *pRootNode=nullptr)
 
 CYITimeline (std::shared_ptr< CYITimelineBackingStore > pBackingStore, const CYIMarkerData *pMarker, CYISceneNode *pRootNode=nullptr)
 
 CYITimeline (std::shared_ptr< CYITimelineBackingStore > pBackingStore, uint64_t startTime, uint64_t duration, CYISceneNode *pRootNode=nullptr)
 
virtual ~CYITimeline ()
 
void SetTrackTargetNode (uint32_t trackID, CYISceneNode *pTargetNode)
 
void SetTrackSource (uint32_t trackID, const CYIVariant &source)
 
void SetTrackTarget (uint32_t trackID, const CYIVariant &target)
 
void DeleteTrack (uint32_t trackID)
 
void SetTrackSource (CYISceneNode *pNode, CYITimelineTrack::AttributeType type, const CYIVariant &source)
 
void SetTrackTarget (CYISceneNode *pNode, CYITimelineTrack::AttributeType type, const CYIVariant &target)
 
bool TrackTargetNameExists (const CYIString &trackTargetName)
 
bool RemapTrackAttributes (const CYIString &oldTrackTarget, CYISceneNode *pNewTarget, bool ignoreOtherTracks=true)
 
void UnmapAllTracks ()
 
void GetOrderedTrackTargets (std::vector< CYISceneNode *> *pTargets)
 
const CYITimelineTrackGetTimelineTrack (size_t index) const
 
size_t GetTrackCount () const
 
FrameMode GetStartFrameMode () const
 
FrameMode GetEndFrameMode () const
 
const CYIStringGetMarkerName () const
 
- Public Member Functions inherited from CYIAbstractTimeline
virtual ~CYIAbstractTimeline ()
 
void Start ()
 
void Finish ()
 
void Pause ()
 
void Continue ()
 
void SetDirection (Direction direction)
 
Direction GetDirection () const
 
Status GetStatus () const
 
uint64_t GetStartTime () const
 
uint64_t GetCurrentTime () const
 
float GetTimeAsPercentage () const
 
uint64_t GetTotalTime () const
 
void SeekToPercentage (float percentage)
 
void SeekToTime (uint64_t millis)
 
void Abort ()
 
void SetDisablesInput (bool disablesInput)
 
void Track ()
 
void Untrack ()
 
void StartForward ()
 
void StartReverse ()
 
void ContinueForward ()
 
void ContinueReverse ()
 
void SetDirectionForward ()
 
void SetDirectionReverse ()
 
void SetFrameModes (FrameMode startFrameMode, FrameMode endFrameMode)
 
bool SetSourcePositions (CYISceneNode *pNode, const glm::vec3 &position)
 
bool ClearSourcePositions (CYISceneNode *pNode)
 
bool SetTargetPositions (CYISceneNode *pNode, const glm::vec3 &position)
 
bool ClearTargetPositions (CYISceneNode *pNode)
 
bool SetSourceScales (CYISceneNode *pNode, const glm::vec3 &scale)
 
bool ClearSourceScales (CYISceneNode *pNode)
 
void SetLooping (bool isLooping)
 
bool GetLooping () const
 
const std::shared_ptr< CYITimelineProxy > & GetProxy () const
 
void SetRootNode (CYISceneNode *pRootNode)
 
const std::shared_ptr< CYISceneNodeProxy > & GetRootNode () const
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &rSignalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &rSignalHandler)
 
void MoveToThread (CYIThread *pThread)
 This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
 
CYIThreadHandle GetThreadAffinity () const
 
void SetThreadAffinity (const CYIThreadHandle &rThreadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &rSignal) const
 
void Disconnect (CYISignalBase &rSignal)
 
void DisconnectFromAllSignals ()
 
- Public Member Functions inherited from CYIThread::Listener
 Listener ()
 
virtual ~Listener ()
 
virtual void OnThreadStarted (CYIThread *)
 
virtual void OnThreadTerminated (CYIThread *)
 
virtual void OnThreadFinished (CYIThread *)
 

Additional Inherited Members

- Public Types inherited from CYIAbstractTimeline
enum  FrameMode : uint8_t {
  FrameMode::Absolute,
  FrameMode::Relative
}
 
enum  Status : uint8_t {
  Status::Stopped,
  Status::Playing
}
 
enum  Direction : uint8_t {
  Direction::Forward,
  Direction::Reverse
}
 
- Public Attributes inherited from CYIAbstractTimeline
CYISignal Playing
 called whenever the timeline starts playing (from any position) More...
 
CYISignal Paused
 called whenever the timeline stops playing, including if the timeline execution completes normally More...
 
CYISignal Aborted
 called when the timeline execution is aborted by the Abort() function More...
 
CYISignal Started
 called when playback of the timeline is initiated by one of the Start() functions More...
 
CYISignal Completed
 called when playback of the timeline completes normally (or when the Finish() function is called) More...
 
CYISignal TimelineLooped
 called whenever a loop completes and the next loop starts More...
 
CYISignal PlayingForward
 same as Playing, but triggered only when direction is forward More...
 
CYISignal PlayingReverse
 same as Playing, but triggered only when direction is reverse More...
 
CYISignal PausedForward
 same as Paused, but triggered only when direction is forward More...
 
CYISignal PausedReverse
 same as Paused, but triggered only when direction is reverse More...
 
CYISignal StartedForward
 same as Started, but triggered only when direction is forward More...
 
CYISignal StartedReverse
 same as Started, but triggered only when direction is reverse More...
 
CYISignal CompletedForward
 same as Completed, but triggered only when direction is forward More...
 
CYISignal CompletedReverse
 same as Completed, but triggered only when direction is reverse More...
 
- Protected Member Functions inherited from CYIAbstractTimeline
 CYIAbstractTimeline (std::unique_ptr< CYIAbstractTimelinePriv > pPriv)
 
- Protected Attributes inherited from CYIAbstractTimeline
std::unique_ptr< CYIAbstractTimelinePriv > m_pPriv
 

Constructor & Destructor Documentation

◆ CYITimeline() [1/3]

CYITimeline::CYITimeline ( std::shared_ptr< CYITimelineBackingStore pBackingStore,
CYISceneNode pRootNode = nullptr 
)

Creates a CYITimeline using backing store pBackingStore. pRootNode should be specified if there is a node associated with the timeline at the time of creation. The timeline will span the full length of the backing store.

See also
SetRootNode

◆ CYITimeline() [2/3]

CYITimeline::CYITimeline ( std::shared_ptr< CYITimelineBackingStore pBackingStore,
const CYIMarkerData pMarker,
CYISceneNode pRootNode = nullptr 
)

Creates a CYITimeline using backing store pBackingStore. pRootNode should be specified if there is a node associated with the timeline at the time of creation. The timeline will be configured using the data from pMarker.

See also
SetRootNode

◆ CYITimeline() [3/3]

CYITimeline::CYITimeline ( std::shared_ptr< CYITimelineBackingStore pBackingStore,
uint64_t  startTime,
uint64_t  duration,
CYISceneNode pRootNode = nullptr 
)

Creates a CYITimeline using backing store pBackingStore. pRootNode should be specified if there is a node associated with the timeline at the time of creation. The timeline will be created using start time startTime and duration duration.

◆ ~CYITimeline()

virtual CYITimeline::~CYITimeline ( )
virtual

Member Function Documentation

◆ DeleteTrack()

void CYITimeline::DeleteTrack ( uint32_t  trackID)

Deletes track with ID trackID. Has no effect if no such track exists.

◆ GetEndFrameMode()

FrameMode CYITimeline::GetEndFrameMode ( ) const

Returns the end frame mode of this timeline.

See also
CYIAbstractTimeline::SetFrameModes()

◆ GetMarkerName()

const CYIString& CYITimeline::GetMarkerName ( ) const

Returns the marker name associated with this timeline. If no marker is associated with this timeline empty string will be returned.

◆ GetOrderedTrackTargets()

void CYITimeline::GetOrderedTrackTargets ( std::vector< CYISceneNode *> *  pTargets)

Iterates over all tracks which have an associated target node and attribute type IS_VISIBLE. For each such track, the associated target node is added to pTarget.

◆ GetStartFrameMode()

FrameMode CYITimeline::GetStartFrameMode ( ) const

Returns the start frame mode of this timeline.

See also
CYIAbstractTimeline::SetFrameModes()

◆ GetTimelineTrack()

const CYITimelineTrack* CYITimeline::GetTimelineTrack ( size_t  index) const

Returns the timeline track with index index. Returns nullptr if no such track exists.

Warning
This function returns the track with a specified index, NOT a specified track ID.

◆ GetTrackCount()

size_t CYITimeline::GetTrackCount ( ) const

Returns the number of tracks present in this timeline.

See also
GetTimelineTrack

◆ RemapTrackAttributes()

bool CYITimeline::RemapTrackAttributes ( const CYIString oldTrackTarget,
CYISceneNode pNewTarget,
bool  ignoreOtherTracks = true 
)

Replaces the target node of any track whose target name is oldTrackTarget with the target node pNewTarget. If ignoreOtherTracks is true, all other tracks will have their target node set to nullptr.

◆ SetTrackSource() [1/2]

void CYITimeline::SetTrackSource ( uint32_t  trackID,
const CYIVariant source 
)

Sets the source value for track with ID trackID to source. Call with an invalid CYIVariant to remove the source value (and use the value of the first frame of the timeline). Has no effect if no such track exists.

◆ SetTrackSource() [2/2]

void CYITimeline::SetTrackSource ( CYISceneNode pNode,
CYITimelineTrack::AttributeType  type,
const CYIVariant source 
)

A helper function to set the source value of any track that uses the provided targetnode pNode and has attribute type type to the provided source value source. Call with an invalid CYIVariant to remove the source value (and use the value of the first frame of the timeline). Has no effect if no track has the provided target node and attribute type.

See also
SetTrackSource(uint32_t trackID, const CYIVariant &source)

◆ SetTrackTarget() [1/2]

void CYITimeline::SetTrackTarget ( uint32_t  trackID,
const CYIVariant target 
)

Sets the target value for track with ID trackID to target. Call with an invalid CYIVariant to remove the target value (and use the value of the last frame of the timeline). Has no effect if no such track exists.

◆ SetTrackTarget() [2/2]

void CYITimeline::SetTrackTarget ( CYISceneNode pNode,
CYITimelineTrack::AttributeType  type,
const CYIVariant target 
)

A helper function to set the target value of any track that uses the provided targetnode pNode and has attribute type type to the provided target value target. Call with an invalid CYIVariant to remove the target value (and use the value of the last frame of the timeline). Has no effect if no track has the provided target node and attribute type.

See also
SetTrackTarget(uint32_t trackID, const CYIVariant &target)

◆ SetTrackTargetNode()

void CYITimeline::SetTrackTargetNode ( uint32_t  trackID,
CYISceneNode pTargetNode 
)

Sets the scene node affected by track with ID trackID to pTargetNode. Has no effect if no such track exists.

◆ TrackTargetNameExists()

bool CYITimeline::TrackTargetNameExists ( const CYIString trackTargetName)

Returns true if a track exists with the track target name trackTargetName.

◆ UnmapAllTracks()

void CYITimeline::UnmapAllTracks ( )

Sets the target node of all tracks to nullptr.


The documentation for this class was generated from the following file: