Represents the instance of a Skeletal animation based on its definition. More...

#include <OgreSkeletonAnimation.h>

Inheritance diagram for Ogre::SkeletonAnimation:

Public Member Functions
	SkeletonAnimation (const SkeletonAnimationDef definition, const FastArray< size_t > slotStarts, SkeletonInstance *owner)

void	_applyAnimation (const TransformArray &boneTransforms)

void	_boneMemoryRebased (const FastArray< size_t > &oldSlotStarts)
	Shifts the values of mBoneWeights to new locations because the bones' mIndex may have changed. More...

void	_initialize ()
	Internal function that initializes a lot of structures that can't be done in the constructor due to how SkeletonInstance is created/pushed in a vector. More...

void	_swapBoneWeightsUniquePtr (RawSimdUniquePtr< ArrayReal, MEMCATEGORY_ANIMATION > &inOutBoneWeights)

void	addFrame (Real frames)
	Plays the animation forward (or backwards if negative) More...

void	addTime (Real time)
	Plays the animation forward (or backwards if negative) More...

Real	getBoneWeight (IdString boneName) const
	Gets the current per-bone weight of a particular bone. More...

Real *	getBoneWeightPtr (IdString boneName)
	Gets a pointer current per-bone weight of a particular bone. More...

Real	getCurrentFrame () const
	Gets the current animation frame, in frames. More...

Real	getCurrentTime () const
	Gets the current animation time, in seconds. Prefer using getCurrentFrame. More...

const SkeletonAnimationDef *	getDefinition () const

Real	getDuration () const
	Gets animation length, in seconds. More...

bool	getEnabled () const

bool	getLoop () const
	Returns current loop setting. More...

IdString	getName () const

Real	getNumFrames () const
	Gets the frame count. More...

void	setBoneWeight (IdString boneName, Real weight)
	Sets the per-bone weight to a particular bone. More...

void	setEnabled (bool bEnable)
	Enables or disables this animation. A disabled animation won't be processed at all. More...

void	setFrame (Real frame)
	Sets the animation to a particular frame. More...

void	setLoop (bool bLoop)
	Loop setting. More...

void	setOverrideBoneWeightsOnActiveAnimations (const Real constantWeight, const bool bPerBone=false)
	Given all the bones this animation uses, sets the weight of these on other animations. More...

void	setOverrideBoneWeightsOnAllAnimations (const Real constantWeight, const bool bPerBone=false)

void	setTime (Real time)
	Sets the animation to a particular time. More...

Public Attributes
bool	mEnabled

Real	mFrameRate

bool	mLoop

SkeletonInstance *	mOwner

FastArray< size_t > const *	mSlotStarts

Real	mWeight

Detailed Description

Represents the instance of a Skeletal animation based on its definition.

Constructor & Destructor Documentation

◆ SkeletonAnimation()

Ogre::SkeletonAnimation::SkeletonAnimation	(	const SkeletonAnimationDef *	definition,
		const FastArray< size_t > *	slotStarts,
		SkeletonInstance *	owner
	)

Member Function Documentation

◆ _applyAnimation()

void Ogre::SkeletonAnimation::_applyAnimation ( const TransformArray & boneTransforms )

◆ _boneMemoryRebased()

void Ogre::SkeletonAnimation::_boneMemoryRebased ( const FastArray< size_t > & oldSlotStarts )

Shifts the values of mBoneWeights to new locations because the bones' mIndex may have changed.

Needed when our BoneMemoryManager performs a cleanup or similar memory change.

Parameters

oldSlotStarts Array with the contents old contents of SkeletonInstance::mSlotStarts, one entry per node hirearchy depth level

◆ _initialize()

void Ogre::SkeletonAnimation::_initialize ( )

Internal function that initializes a lot of structures that can't be done in the constructor due to how SkeletonInstance is created/pushed in a vector.

If you're not an Ogre dev, don't call this directly.

◆ _swapBoneWeightsUniquePtr()

void Ogre::SkeletonAnimation::_swapBoneWeightsUniquePtr ( RawSimdUniquePtr< ArrayReal, MEMCATEGORY_ANIMATION > & inOutBoneWeights )

◆ addFrame()

void Ogre::SkeletonAnimation::addFrame ( Real frames )

Plays the animation forward (or backwards if negative)

Parameters

frames Frames to advance, in frames

◆ addTime()

void Ogre::SkeletonAnimation::addTime ( Real time )

inline

Plays the animation forward (or backwards if negative)

Parameters

time	Time to advance, in seconds

◆ getBoneWeight()

Real Ogre::SkeletonAnimation::getBoneWeight ( IdString boneName ) const

Gets the current per-bone weight of a particular bone.

Parameters

boneName The name of the bone to get. If this animation doesn't affect that bone (or the name is invalid) this function returns 0.

Returns: The weight of the specified bone. 0 if not found.

◆ getBoneWeightPtr()

Real* Ogre::SkeletonAnimation::getBoneWeightPtr ( IdString boneName )

Gets a pointer current per-bone weight of a particular bone.

Useful if you intend to have read/write access to this value very often.

Remarks: !!! EXTREMELY IMPORTANT !!! If any skeleton instance (that shares the same SkeletonDef) is destroyed, the returned value may be invalidated!

If returnPtr is the return value to bone[0], do not assume that returnPtr+1 affects bone[1] or even any other bone. Doing so the behavior is underfined and most likely you could be affecting the contents of other SkeletonInstances.

Parameters

boneName The name of the bone to get. If this animation doesn't affect that bone (or the name is invalid) this function returns a null pointer.

Returns: The pointer to the bone weight of the specified bone. Null pointer if not found.

◆ getCurrentFrame()

Real Ogre::SkeletonAnimation::getCurrentFrame ( ) const

inline

Gets the current animation frame, in frames.

◆ getCurrentTime()

Real Ogre::SkeletonAnimation::getCurrentTime ( ) const

inline

Gets the current animation time, in seconds. Prefer using getCurrentFrame.

◆ getDefinition()

const SkeletonAnimationDef* Ogre::SkeletonAnimation::getDefinition ( ) const

inline

◆ getDuration()

Real Ogre::SkeletonAnimation::getDuration ( ) const

Gets animation length, in seconds.

◆ getEnabled()

bool Ogre::SkeletonAnimation::getEnabled ( ) const

inline

◆ getLoop()

bool Ogre::SkeletonAnimation::getLoop ( ) const

inline

Returns current loop setting.

See also: setLoop

◆ getName()

IdString Ogre::SkeletonAnimation::getName ( ) const

inline

◆ getNumFrames()

Real Ogre::SkeletonAnimation::getNumFrames ( ) const

Gets the frame count.

◆ setBoneWeight()

void Ogre::SkeletonAnimation::setBoneWeight	(	IdString	boneName,
		Real	weight
	)

Sets the per-bone weight to a particular bone.

Useful for fine control over animation strength on a set of nodes (i.e. an arm)

Remarks: By default all bone weights are set to 1.0

Parameters

boneName	The name of the bone to set. If this animation doesn't affect that bone (or the name is invalid) this function does nothing.
weight	Weight to apply to this particular bone. Note that the animation multiplies this value against the global mWeight to obtain the final weight. Normal range is between [0; 1] but not necessarily.

◆ setEnabled()

void Ogre::SkeletonAnimation::setEnabled ( bool bEnable )

Enables or disables this animation. A disabled animation won't be processed at all.

◆ setFrame()

void Ogre::SkeletonAnimation::setFrame ( Real frame )

Sets the animation to a particular frame.

Parameters

frame Frame to set to, in frames

◆ setLoop()

void Ogre::SkeletonAnimation::setLoop ( bool bLoop )

inline

Loop setting.

Looped animations will wrap back to zero when reaching the animation length or go back to the animation length if playing backwards. Non-looped animations will stop at the animation length (or at 0 if backwards) but won't be disabled.

◆ setOverrideBoneWeightsOnActiveAnimations()

void Ogre::SkeletonAnimation::setOverrideBoneWeightsOnActiveAnimations	(	const Real	constantWeight,
		const bool	bPerBone = `false`
	)

Given all the bones this animation uses, sets the weight of these on other animations.

The use case is very specific: Imagine a 3rd person shooter. Normally animations get blended together either additively or cummulative (e.g. to smoothly transition from walk to idle, from idle to run, from run to cover, etc)

However certain animations, such as Reload, need to override all other animations but only on a particular set of bones.

Whether the character is idle, walking or running; we want the reload animation to play at 100% weight (on torso, arms and hands), while the walk/idle/run animations still also play at 100% weight on bones unaffected by the reload (like the legs).

Example code:

// When starting reload
reloadAnim->setOverrideBoneWeightsOnActiveAnimations( 0.0f, false );
reloadAnim->setEnabled( true );
 
// When starting reload is over
reloadAnim->setEnabled( false );
reloadAnim->setOverrideBoneWeightsOnActiveAnimations( 1.0f, false );
 
// To smoothly fade in/out while allowing per-bone granularity:
// fadeOutFactor = 0 means we're fully faded in
// fadeOutFactor = 1 means we're faded out entirely
reloadAnim->setOverrideBoneWeightsOnActiveAnimations( fadeOutFactor, true );
 
// To smoothly fade in/out while overriding all bones:
reloadAnim->setOverrideBoneWeightsOnActiveAnimations( fadeOutFactor, false );

For this function to have any usefulness, the animation from Maya/Blender/etc needs to have been exported with only animation tracks on bones that are modified (i.e. the exporter should not create dummy nodes resetting to default pose on unanimated bones)

If you're using blender2ogre, make sure to tick "Only Keyframed Bones"

Remarks: This overload works only on currently active animations. To override all (active and inactive) animations, use setOverrideBoneWeightsOnAllAnimations

Avoid calling this function unnecessarily (e.g. don't call it every frame if weight value did not change). It's not super expensive, but it is not free either.

Any custom per-bone weight you set on other animations (e.g. by calling other->setBoneWeight) will be overwritten.

Parameters

constantWeight	A constant weight to apply to all bone weights in other animations Should be in range [0; 1]
bPerBone	When false, all other animations are set to constantWeight When true, each bone in other animations are set to: Math::lerp( 1.0f - boneWeight, constantWeight, boneWeight ); This allows you to selectively avoid overriding certain bones while also smoothly fade in/out animations (i.e. gives you finer granularity control)

When true, the math operation we perform boils down to:

for each affectedBone in this_animation
    for each otherAnim in parent->getAnimations()
        finalWeight = lerp( 1.0 - affectedBone->weight,
                            constantWeight, affectedBone->weight );
        otherAnim->setBoneWeight( affectedBone->name, finalWeight );

◆ setOverrideBoneWeightsOnAllAnimations()

void Ogre::SkeletonAnimation::setOverrideBoneWeightsOnAllAnimations	(	const Real	constantWeight,
		const bool	bPerBone = `false`
	)

See also: SkeletonAnimation::setOverrideBoneWeightsOnActiveAnimations

◆ setTime()

void Ogre::SkeletonAnimation::setTime ( Real time )

inline

Sets the animation to a particular time.

Parameters

time	Time to set to, in seconds

Member Data Documentation

◆ mEnabled

bool Ogre::SkeletonAnimation::mEnabled

◆ mFrameRate

Real Ogre::SkeletonAnimation::mFrameRate

◆ mLoop

bool Ogre::SkeletonAnimation::mLoop

◆ mOwner

SkeletonInstance* Ogre::SkeletonAnimation::mOwner

◆ mSlotStarts

FastArray<size_t> const* Ogre::SkeletonAnimation::mSlotStarts

◆ mWeight

Real Ogre::SkeletonAnimation::mWeight

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

OgreSkeletonAnimation.h

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SkeletonAnimation()

Member Function Documentation

◆ _applyAnimation()

◆ _boneMemoryRebased()

◆ _initialize()

◆ _swapBoneWeightsUniquePtr()

◆ addFrame()

◆ addTime()

◆ getBoneWeight()

◆ getBoneWeightPtr()

◆ getCurrentFrame()

◆ getCurrentTime()

◆ getDefinition()

◆ getDuration()

◆ getEnabled()

◆ getLoop()

◆ getName()

◆ getNumFrames()

◆ setBoneWeight()

◆ setEnabled()

◆ setFrame()

◆ setLoop()

◆ setOverrideBoneWeightsOnActiveAnimations()

◆ setOverrideBoneWeightsOnAllAnimations()

◆ setTime()

Member Data Documentation

◆ mEnabled

◆ mFrameRate

◆ mLoop

◆ mOwner

◆ mSlotStarts

◆ mWeight