OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::SkeletonAnimation Class Reference

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...
 
RealgetBoneWeightPtr (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 SkeletonAnimationDefgetDefinition () 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
 
SkeletonInstancemOwner
 
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
oldSlotStartsArray 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
framesFrames to advance, in frames

◆ addTime()

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

Plays the animation forward (or backwards if negative)

Parameters
timeTime to advance, in seconds

◆ getBoneWeight()

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

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

Parameters
boneNameThe 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
boneNameThe 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
boneNameThe name of the bone to set. If this animation doesn't affect that bone (or the name is invalid) this function does nothing.
weightWeight 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
frameFrame 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
constantWeightA constant weight to apply to all bone weights in other animations Should be in range [0; 1]
bPerBoneWhen 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 
)

◆ setTime()

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

Sets the animation to a particular time.

Parameters
timeTime 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: