#include <KeyTrackLinearDynamic.h>

Public Member Functions
	AZ_TYPE_INFO_WITH_NAME (KeyTrackLinearDynamic, "EMotionFX::KeyTrackLinear", "{8C6EB52A-9720-467B-9D96-B4B967A113D1}", StorageType)

	KeyTrackLinearDynamic (size_t nrKeys)

void	Reserve (size_t numKeys)

size_t	CalcMemoryUsage (bool includeMembers=true) const

void	Init ()

void	Shrink ()

MCORE_INLINE ReturnType	Interpolate (size_t startKey, float currentTime) const

MCORE_INLINE void	AddKey (float time, const ReturnType &value, bool smartPreAlloc=true)

MCORE_INLINE void	AddKeySorted (float time, const ReturnType &value, bool smartPreAlloc=true)

MCORE_INLINE void	RemoveKey (size_t keyNr)

void	ClearKeys ()

MCORE_INLINE bool	CheckIfIsAnimated (const ReturnType &initialPose, float maxError) const

ReturnType	GetValueAtTime (float currentTime, size_t cachedKey=nullptr, uint8 outWasCacheHit=nullptr, bool interpolate=true) const

MCORE_INLINE KeyFrame< ReturnType, StorageType > *	GetKey (size_t nr)

MCORE_INLINE KeyFrame< ReturnType, StorageType > *	GetFirstKey ()

MCORE_INLINE KeyFrame< ReturnType, StorageType > *	GetLastKey ()

MCORE_INLINE const KeyFrame< ReturnType, StorageType > *	GetKey (size_t nr) const

MCORE_INLINE const KeyFrame< ReturnType, StorageType > *	GetFirstKey () const

MCORE_INLINE const KeyFrame< ReturnType, StorageType > *	GetLastKey () const

MCORE_INLINE float	GetFirstTime () const

MCORE_INLINE float	GetLastTime () const

MCORE_INLINE size_t	GetNumKeys () const

MCORE_INLINE KeyFrame< ReturnType, StorageType > *	FindKey (float curTime) const

MCORE_INLINE size_t	FindKeyNumber (float curTime) const

void	MakeLoopable (float fadeTime=0.3f)

size_t	Optimize (float maxError)

void	SetNumKeys (size_t numKeys)

MCORE_INLINE void	SetKey (size_t keyNr, float time, const ReturnType &value)

MCORE_INLINE void	SetStorageTypeKey (size_t keyNr, float time, const StorageType &value)

MCORE_INLINE AZ::Quaternion	Interpolate (size_t startKey, float currentTime) const

MCORE_INLINE AZ::Quaternion	Interpolate (size_t startKey, float currentTime) const

Static Public Member Functions
static void	Reflect (AZ::ReflectContext *context)

Protected Attributes
AZStd::vector< KeyFrame< ReturnType, StorageType > >	m_keys

Detailed Description

template<class ReturnType, class StorageType = ReturnType>
class EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >

The dynamic linear keyframe track. The difference between the standard and dynamic one is that the dynamic one can reserve memory and grow its contents more efficiently, with far less reallocations. For that reason the dynamic version is more efficient for adding and removing keys dynamically. This is a class holding a set of keyframes.

Constructor & Destructor Documentation

◆ KeyTrackLinearDynamic()

template<class ReturnType , class StorageType >

EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::KeyTrackLinearDynamic ( size_t nrKeys )

Parameters

nrKeys The number of keyframes which the keytrack contains (preallocates this amount of keyframes).

Member Function Documentation

◆ AddKey()

template<class ReturnType , class StorageType >

MCORE_INLINE void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::AddKey	(	float	time,
		const ReturnType &	value,
		bool	smartPreAlloc = `true`
	)

Add a key to the track (at the back).

Parameters

time	The time of the keyframe, in seconds.
value	The value of the keyframe.
smartPreAlloc	Set to true if you wish to automatically pre-allocate space for multiple keys if we run out of space. This can make adding more keys faster.

◆ AddKeySorted()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::AddKeySorted	(	float	time,
		const ReturnType &	value,
		bool	smartPreAlloc = `true`
	)

Adds a key to the track, and automatically detects where to place it. NOTE: you will have to call the Init() method again when you finished adding keys.

Parameters

time	The time value of the keyframe, in seconds.
value	The value of the keyframe at that time.
smartPreAlloc	Set to true if you wish to automatically pre-allocate space for multiple keys if we run out of space. This can make adding more keys faster.

◆ CalcMemoryUsage()

template<class ReturnType , class StorageType >

size_t EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::CalcMemoryUsage ( bool includeMembers = true ) const

Calculate the memory usage, in bytes.

Parameters

includeMembers Specifies whether to include member variables of the keytrack class itself or not (default=true).

Returns: The number of bytes used by this keytrack.

◆ CheckIfIsAnimated()

template<class ReturnType , class StorageType >

MCORE_INLINE bool EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::CheckIfIsAnimated	(	const ReturnType &	initialPose,
		float	maxError
	)		const

Check if a given keytrack is animated or not.

Parameters

initialPose	The base or initial pose to compare to. If the keyframe values are different from this value, the keytrack is considered to be animated.
maxError	The maximum error/difference between the specified initial pose and the keyframes.

Returns: True in case the keytrack is animated, otherwise false is returned.

◆ ClearKeys()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::ClearKeys

Clear all keys.

◆ FindKey()

template<class ReturnType , class StorageType >

MCORE_INLINE KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::FindKey ( float curTime ) const

Find a key at a given time.

Parameters

curTime The time of the key.

Returns: A pointer to the keyframe.

◆ FindKeyNumber()

template<class ReturnType , class StorageType >

MCORE_INLINE size_t EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::FindKeyNumber ( float curTime ) const

Find a key number at a given time. You will need to interpolate between this and the next key.

Parameters

curTime The time to retreive the key for.

Returns: Returns the key number or MCORE_INVALIDINDEX32 when not found.

◆ GetFirstKey() [1/2]

template<class ReturnType , class StorageType >

MCORE_INLINE KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetFirstKey

Returns the first keyframe.

Returns: A pointer to the first keyframe.

◆ GetFirstKey() [2/2]

template<class ReturnType , class StorageType >

MCORE_INLINE const KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetFirstKey

Returns the first keyframe.

Returns: A pointer to the first keyframe.

◆ GetFirstTime()

template<class ReturnType , class StorageType >

MCORE_INLINE float EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetFirstTime

Returns the time value of the first keyframe.

Returns: The time value of the first keyframe, in seconds.

◆ GetKey() [1/2]

template<class ReturnType , class StorageType >

MCORE_INLINE KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetKey ( size_t nr )

Get a given keyframe.

Parameters

nr	The index, so the keyframe number.

Returns: A pointer to the keyframe.

◆ GetKey() [2/2]

template<class ReturnType , class StorageType >

MCORE_INLINE const KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetKey ( size_t nr ) const

Get a given keyframe.

Parameters

nr	The index, so the keyframe number.

Returns: A pointer to the keyframe.

◆ GetLastKey() [1/2]

template<class ReturnType , class StorageType >

MCORE_INLINE KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetLastKey

Returns the last keyframe.

Returns: A pointer to the last keyframe.

◆ GetLastKey() [2/2]

template<class ReturnType , class StorageType >

MCORE_INLINE const KeyFrame< ReturnType, StorageType > * EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetLastKey

Returns the last keyframe.

Returns: A pointer to the last keyframe.

◆ GetLastTime()

template<class ReturnType , class StorageType >

MCORE_INLINE float EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetLastTime

Return the time value of the last keyframe.

Returns: The time value of the last keyframe, in seconds.

◆ GetNumKeys()

template<class ReturnType , class StorageType >

MCORE_INLINE size_t EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetNumKeys

Returns the number of keyframes in this track.

Returns: The number of currently stored keyframes.

◆ GetValueAtTime()

template<class ReturnType , class StorageType >

ReturnType EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::GetValueAtTime	(	float	currentTime,
		size_t *	cachedKey = `nullptr`,
		uint8 *	outWasCacheHit = `nullptr`,
		bool	interpolate = `true`
	)		const

Return the interpolated value at the specified time.

Parameters

currentTime	The time in seconds.
cachedKey	The keyframe number that should first be checked before finding the keyframes to interpolate between using the keyframe finder. If this value is nullptr (default), this cached key is ignored. The cached value will also be overwritten with the new cached key in case of a cache miss.
outWasCacheHit	This output value will contain 0 when this method had an internal cache miss and a value of 1 in case it was a cache hit.
interpolate	Should we interpolate between the keyframes?

Returns: Returns the value at the specified time.

◆ Init()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::Init

Initialize all keyframes in this keytrack. Call this after all keys are added and setup, otherwise the interpolation won't work and nothing will happen.

◆ Interpolate()

template<class ReturnType , class StorageType >

MCORE_INLINE ReturnType EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::Interpolate	(	size_t	startKey,
		float	currentTime
	)		const

Perform interpolation between two keyframes.

Parameters

startKey	The first keyframe index. The interpolation will take place between this keyframe and the one after this one.
currentTime	The global time, in seconds. This time value has to be between the time value of the startKey and the one after that.

Returns: The interpolated value.

◆ MakeLoopable()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::MakeLoopable ( float fadeTime = 0.3f )

Make the keytrack loopable, by adding a new keyframe at the end of the keytrack. This added keyframe will have the same value as the first keyframe.

Parameters

fadeTime The relative offset after the last keyframe. If this value is 0.5, it means it will add a keyframe half a second after the last keyframe currently in the keytrack.

◆ Optimize()

template<class ReturnType , class StorageType >

size_t EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::Optimize ( float maxError )

Optimize the keytrack by removing redundant frames. The way this is done is by comparing differences between the resulting curves when removing specific keyframes. If the error (difference) between those curve before and after keyframe removal is within a given maximum error value, the keyframe can be safely removed since there will not be much "visual" difference. The metric of this maximum error depends on the ReturnType of the keytrack (so the return type values of the keyframes). For vectors this will be the squared length between those two vectors. Partial template specialization needs to be used to add support for optimizing different types, such as quaternions. You can do this by creating a specialization of the MCore::Compare<ReturnType>::CheckIfIsClose(...) method. You can find it in the MCore project in the file Compare.h. We provide implementations for several different types, such as vectors, quaternions and floats.

Parameters

maxError The maximum allowed error value. The higher you set this value, the more keyframes will be removed.

Returns: The method returns the number of removed keyframes.

◆ RemoveKey()

template<class ReturnType , class StorageType >

MCORE_INLINE void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::RemoveKey ( size_t keyNr )

Remove a given keyframe, by number. Do not forget that you have to re-initialize the keytrack after you have removed one or more keyframes. The reason for this is that the possible tangents inside the interpolators have to be recalculated when the key structure has changed.

Parameters

keyNr The keyframe number, must be in range of [0..GetNumKeys()-1].

◆ Reserve()

template<class ReturnType , class StorageType >

MCORE_INLINE void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::Reserve ( size_t numKeys )

Reserve space for a given number of keys. This pre-allocates data, so that adding keys doesn't always do a reallocation.

Parameters

numKeys The number of keys to reserve space for. This is the absolute number of keys, NOT the number to reserve extra.

◆ SetKey()

template<class ReturnType , class StorageType >

MCORE_INLINE void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::SetKey	(	size_t	keyNr,
		float	time,
		const ReturnType &	value
	)

Set the value of a key. Please note that you have to make sure your keys remain in sorted order! (sorted on time value).

Parameters

keyNr	The keyframe number.
time	The time value, in seconds.
value	The value of the key.

◆ SetNumKeys()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::SetNumKeys ( size_t numKeys )

Pre-allocate a given number of keys. Please keep in mind that any existing keys will remain unchanged. However, newly created keys will be uninitialized.

Parameters

numKeys The number of keys to allocate.

◆ SetStorageTypeKey()

template<class ReturnType , class StorageType >

MCORE_INLINE void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::SetStorageTypeKey	(	size_t	keyNr,
		float	time,
		const StorageType &	value
	)

Set the storage type value of a key. Please note that you have to make sure your keys remain in sorted order! (sorted on time value).

Parameters

keyNr	The keyframe number.
time	The time value, in seconds.
value	The storage type value of the key.

◆ Shrink()

template<class ReturnType , class StorageType >

void EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::Shrink

Shrink the memory usage of this track to as small as possible. This removes any possible pre-allocated data for the array.

Member Data Documentation

◆ m_keys

template<class ReturnType , class StorageType = ReturnType>

AZStd::vector<KeyFrame<ReturnType, StorageType> > EMotionFX::KeyTrackLinearDynamic< ReturnType, StorageType >::m_keys

protected

The collection of keys which form the track.

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

Gems/EMotionFX/Code/EMotionFX/Source/KeyTrackLinearDynamic.h
Gems/EMotionFX/Code/EMotionFX/Source/KeyTrackLinearDynamic.inl

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ KeyTrackLinearDynamic()

Member Function Documentation

◆ AddKey()

◆ AddKeySorted()

◆ CalcMemoryUsage()

◆ CheckIfIsAnimated()

◆ ClearKeys()

◆ FindKey()

◆ FindKeyNumber()

◆ GetFirstKey() [1/2]

◆ GetFirstKey() [2/2]

◆ GetFirstTime()

◆ GetKey() [1/2]

◆ GetKey() [2/2]

◆ GetLastKey() [1/2]

◆ GetLastKey() [2/2]

◆ GetLastTime()

◆ GetNumKeys()

◆ GetValueAtTime()

◆ Init()

◆ Interpolate()

◆ MakeLoopable()

◆ Optimize()

◆ RemoveKey()

◆ Reserve()

◆ SetKey()

◆ SetNumKeys()

◆ SetStorageTypeKey()

◆ Shrink()

Member Data Documentation

◆ m_keys