OGRE-Next: Ogre::SkeletonAnimation Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
Ogre::SkeletonAnimation Class Reference
Core » Animation

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

`#include <OgreSkeletonAnimation.h>`

Inheritance diagram for Ogre::SkeletonAnimation:
[legend]

## 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.
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.
void | _swapBoneWeightsUniquePtr (RawSimdUniquePtr< ArrayReal, MEMCATEGORY_ANIMATION > &inOutBoneWeights)
void | addFrame (Real frames)
| Plays the animation forward (or backwards if negative)
void | addTime (Real time)
| Plays the animation forward (or backwards if negative)
Real | getBoneWeight (IdString boneName) const
| Gets the current per-bone weight of a particular bone.
Real * | getBoneWeightPtr (IdString boneName)
| Gets a pointer current per-bone weight of a particular bone.
Real | getCurrentFrame () const
| Gets the current animation frame, in frames.
Real | getCurrentTime () const
| Gets the current animation time, in seconds. Prefer using getCurrentFrame.
const SkeletonAnimationDef * | getDefinition () const
Real | getDuration () const
| Gets animation length, in seconds.
bool | getEnabled () const
bool | getLoop () const
| Returns current loop setting.
IdString | getName () const
Real | getNumFrames () const
| Gets the frame count.
void | setBoneWeight (IdString boneName, Real weight)
| Sets the per-bone weight to a particular bone.
void | setEnabled (bool bEnable)
| Enables or disables this animation. A disabled animation won't be processed at all.
void | setFrame (Real frame)
| Sets the animation to a particular frame.
void | setLoop (bool bLoop)
| Loop setting.
void | setOverrideBoneWeightsOnActiveAnimations (const Real constantWeight, const bool bPerBone=false)
| Given all the bones this animation uses, sets the weight of these on other animations.
void | setOverrideBoneWeightsOnAllAnimations (const Real constantWeight, const bool bPerBone=false)
void | setTime (Real time)
| Sets the animation to a particular time.

## 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

Referenced by addTime().

## ◆ addTime()

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

Plays the animation forward (or backwards if negative)

Parameters

  time | Time to advance, in seconds

References addFrame(), and mFrameRate.

## ◆ 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.

References mFrameRate.

## ◆ 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

References mEnabled.

## ◆ getLoop()

bool Ogre::SkeletonAnimation::getLoop | ( |  | ) | const
| inline

Returns current loop setting.

See also
  setLoop

References mLoop.

## ◆ 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

Referenced by setTime().

## ◆ 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.

References mLoop.

## ◆ 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

References mFrameRate, and setFrame().

## Member Data Documentation

## ◆ mEnabled

bool Ogre::SkeletonAnimation::mEnabled

Referenced by getEnabled().

## ◆ mFrameRate

Real Ogre::SkeletonAnimation::mFrameRate

Referenced by addTime(), getCurrentTime(), and setTime().

## ◆ mLoop

bool Ogre::SkeletonAnimation::mLoop

Referenced by getLoop(), and setLoop().

## ◆ 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