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:

[legend]

Public Member Functions
	CYITimeline (std::shared_ptr< CYITimelineBackingStore > pBackingStore, CYISceneNode *pRootNode=nullptr)

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

	CYITimeline (std::shared_ptr< CYITimelineBackingStore > pBackingStore, uint64_t uStartTime, uint64_t uDuration, CYISceneNode *pRootNode=nullptr)

virtual	~CYITimeline ()

void	SetTrackTargetNode (uint32_t nTrackID, CYISceneNode *pTargetNode)

void	SetTrackSource (uint32_t nTrackID, const CYIVariant &source)

void	SetTrackTarget (uint32_t nTrackID, const CYIVariant &target)

void	DeleteTrack (uint32_t nTrackID)

void	SetTrackSource (CYISceneNode *pNode, CYITimelineTrack::ATTRIBUTE_TYPE eType, const CYIVariant &source)

void	SetTrackTarget (CYISceneNode *pNode, CYITimelineTrack::ATTRIBUTE_TYPE eType, const CYIVariant &target)

bool	TrackTargetNameExists (const CYIString &trackTargetName)

bool	RemapTrackAttributes (const CYIString &oldTrackTarget, CYISceneNode *pNewTarget, bool bIgnoreOtherTracks=true)

void	UnmapAllTracks ()

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

const CYITimelineTrack *	GetTimelineTrack (uint32_t uIndex) const

uint32_t	GetTrackCount () const

YI_FRAME_MODE	GetStartFrameMode () const

YI_FRAME_MODE	GetEndFrameMode () const

const CYIString &	GetMarkerName () 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 fPercentage)

void	SeekToTime (uint64_t uMillis)

void	Abort ()

void	SetDisablesInput (bool bDisablesInput)

void	Track ()

void	Untrack ()

void	StartForward ()

void	StartReverse ()

void	ContinueForward ()

void	ContinueReverse ()

void	SetDirectionForward ()

void	SetDirectionReverse ()

void	SetFrameModes (YI_FRAME_MODE eStartFrameMode, YI_FRAME_MODE eEndFrameMode)

bool	SetSourcePositions (CYISceneNode *pNode, const glm::vec3 &vPosition)

bool	ClearSourcePositions (CYISceneNode *pNode)

bool	SetTargetPositions (CYISceneNode *pNode, const glm::vec3 &vPosition)

bool	ClearTargetPositions (CYISceneNode *pNode)

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 ()

CYISignalHandler &	operator= (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 *)

Public Member Functions inherited from CYIScriptableRTTIObject
	CYIScriptableRTTIObject ()

virtual	~CYIScriptableRTTIObject ()

virtual const CYIRuntimeTypeInfo *	GetRuntimeTypeInfoForScriptObject () const override

Public Member Functions inherited from CYIScriptableObject
	CYIScriptableObject ()

	CYIScriptableObject (const CYIScriptableObject &other)

CYIScriptableObject &	operator= (const CYIScriptableObject &other)

virtual	~CYIScriptableObject ()

CYIBindingImplementation *	GetBindingImplementation () const

void	SetBindingImplementation (CYIBindingImplementation *pBindingImplementation)

Additional Inherited Members
Public Types inherited from CYIAbstractTimeline
enum	YI_FRAME_MODE { YI_ABSOLUTE, YI_RELATIVE }

enum	STATUS { STOPPED, PLAYING }

enum	DIRECTION { FORWARD, 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	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 (CYIAbstractTimelinePriv *pPriv)

Protected Member Functions inherited from CYIScriptableRTTIObject
virtual std::pair< const CYIRuntimeTypeInfo , const void >	GetRuntimeTypeInfoWithObject () const =0

Protected Attributes inherited from CYIAbstractTimeline
CYIAbstractTimelinePriv *	m_pPriv

Constructor & Destructor Documentation

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::CYITimeline	(	std::shared_ptr< CYITimelineBackingStore >	pBackingStore,
		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::CYITimeline	(	std::shared_ptr< CYITimelineBackingStore >	pBackingStore,
		uint64_t	uStartTime,
		uint64_t	uDuration,
		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 uStartTime and duration uDuration.

virtual CYITimeline::~CYITimeline ( )

virtual

Member Function Documentation

void CYITimeline::DeleteTrack ( uint32_t nTrackID )

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

YI_FRAME_MODE CYITimeline::GetEndFrameMode ( ) const

Returns the end frame mode of this timeline.

See also: CYIAbstractTimeline::SetFrameModes()

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.

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.

YI_FRAME_MODE CYITimeline::GetStartFrameMode ( ) const

Returns the start frame mode of this timeline.

See also: CYIAbstractTimeline::SetFrameModes()

const CYITimelineTrack* CYITimeline::GetTimelineTrack ( uint32_t uIndex ) const

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

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

uint32_t CYITimeline::GetTrackCount ( ) const

Returns the number of tracks present in this timeline.

See also: GetTimelineTrack

bool CYITimeline::RemapTrackAttributes	(	const CYIString &	oldTrackTarget,
		CYISceneNode *	pNewTarget,
		bool	bIgnoreOtherTracks = `true`
	)

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

void CYITimeline::SetTrackSource	(	uint32_t	nTrackID,
		const CYIVariant &	source
	)

Sets the source value for track with ID nTrackID 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.

void CYITimeline::SetTrackSource	(	CYISceneNode *	pNode,
		CYITimelineTrack::ATTRIBUTE_TYPE	eType,
		const CYIVariant &	source
	)

A helper function to set the source value of any track that uses the provided targetnode pNode and has attribute type eType 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 nTrackID, const CYIVariant &source)

void CYITimeline::SetTrackTarget	(	uint32_t	nTrackID,
		const CYIVariant &	target
	)

Sets the target value for track with ID nTrackID 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.

void CYITimeline::SetTrackTarget	(	CYISceneNode *	pNode,
		CYITimelineTrack::ATTRIBUTE_TYPE	eType,
		const CYIVariant &	target
	)

A helper function to set the target value of any track that uses the provided targetnode pNode and has attribute type eType 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 nTrackID, const CYIVariant &target)

void CYITimeline::SetTrackTargetNode	(	uint32_t	nTrackID,
		CYISceneNode *	pTargetNode
	)

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

bool CYITimeline::TrackTargetNameExists ( const CYIString & trackTargetName )

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

void CYITimeline::UnmapAllTracks ( )

Sets the target node of all tracks to nullptr.

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

animation/YiTimeline.h

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation