Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Ogre::Animation Class Reference

An animation sequence. More...

#include <OgreAnimation.h>

List of all members.

Public Types

typedef std::map< unsigned
short, NodeAnimationTrack * > 
NodeTrackList
typedef ConstMapIterator<
NodeTrackList
NodeTrackIterator
typedef std::map< unsigned
short, NumericAnimationTrack * > 
NumericTrackList
typedef ConstMapIterator<
NumericTrackList
NumericTrackIterator
typedef std::map< unsigned
short, VertexAnimationTrack * > 
VertexTrackList
typedef ConstMapIterator<
VertexTrackList
VertexTrackIterator
typedef std::set< ushortTrackHandleList
 A list of track handles.
enum  InterpolationMode { IM_LINEAR, IM_SPLINE }
 The types of animation interpolation available. More...
enum  RotationInterpolationMode { RIM_LINEAR, RIM_SPHERICAL }
 The types of rotational interpolation available. More...

Public Member Functions

 Animation (const String &name, Real length)
 You should not use this constructor directly, use the parent object such as Skeleton instead.
virtual ~Animation ()
const StringgetName (void) const
 Gets the name of this animation.
Real getLength (void) const
 Gets the total length of the animation.
NodeAnimationTrackcreateNodeTrack (unsigned short handle)
 Creates a NodeAnimationTrack for animating a Node.
NumericAnimationTrackcreateNumericTrack (unsigned short handle)
 Creates a NumericAnimationTrack for animating any numeric value.
VertexAnimationTrackcreateVertexTrack (unsigned short handle, VertexAnimationType animType)
 Creates a VertexAnimationTrack for animating vertex position data.
NodeAnimationTrackcreateNodeTrack (unsigned short handle, Node *node)
 Creates a new AnimationTrack automatically associated with a Node.
NumericAnimationTrackcreateNumericTrack (unsigned short handle, const AnimableValuePtr &anim)
 Creates a NumericAnimationTrack and associates it with an animable.
VertexAnimationTrackcreateVertexTrack (unsigned short handle, VertexData *data, VertexAnimationType animType)
 Creates a VertexAnimationTrack and associates it with VertexData.
unsigned short getNumNodeTracks (void) const
 Gets the number of NodeAnimationTrack objects contained in this animation.
NodeAnimationTrackgetNodeTrack (unsigned short handle) const
 Gets a node track by it's handle.
bool hasNodeTrack (unsigned short handle) const
 Does a track exist with the given handle?
unsigned short getNumNumericTracks (void) const
 Gets the number of NumericAnimationTrack objects contained in this animation.
NumericAnimationTrackgetNumericTrack (unsigned short handle) const
 Gets a numeric track by it's handle.
bool hasNumericTrack (unsigned short handle) const
 Does a track exist with the given handle?
unsigned short getNumVertexTracks (void) const
 Gets the number of VertexAnimationTrack objects contained in this animation.
VertexAnimationTrackgetVertexTrack (unsigned short handle) const
 Gets a Vertex track by it's handle.
bool hasVertexTrack (unsigned short handle) const
 Does a track exist with the given handle?
void destroyNodeTrack (unsigned short handle)
 Destroys the node track with the given handle.
void destroyNumericTrack (unsigned short handle)
 Destroys the numeric track with the given handle.
void destroyVertexTrack (unsigned short handle)
 Destroys the Vertex track with the given handle.
void destroyAllTracks (void)
 Removes and destroys all tracks making up this animation.
void destroyAllNodeTracks (void)
 Removes and destroys all tracks making up this animation.
void destroyAllNumericTracks (void)
 Removes and destroys all tracks making up this animation.
void destroyAllVertexTracks (void)
 Removes and destroys all tracks making up this animation.
void apply (Real timePos, Real weight=1.0, Real scale=1.0f)
 Applies an animation given a specific time point and weight.
void apply (Skeleton *skeleton, Real timePos, Real weight=1.0, Real scale=1.0f)
 Applies all node tracks given a specific time point and weight to a given skeleton.
void apply (Entity *entity, Real timePos, Real weight, bool software, bool hardware)
 Applies all vertex tracks given a specific time point and weight to a given entity.
void setInterpolationMode (InterpolationMode im)
 Tells the animation how to interpolate between keyframes.
InterpolationMode getInterpolationMode (void) const
 Gets the current interpolation mode of this animation.
void setRotationInterpolationMode (RotationInterpolationMode im)
 Tells the animation how to interpolate rotations.
RotationInterpolationMode getRotationInterpolationMode (void) const
 Gets the current rotation interpolation mode of this animation.
const NodeTrackList_getNodeTrackList (void) const
 Fast access to NON-UPDATEABLE node track list.
NodeTrackIterator getNodeTrackIterator (void) const
 Get non-updateable iterator over node tracks.
const NumericTrackList_getNumericTrackList (void) const
 Fast access to NON-UPDATEABLE numeric track list.
NumericTrackIterator getNumericTrackIterator (void) const
 Get non-updateable iterator over node tracks.
const VertexTrackList_getVertexTrackList (void) const
 Fast access to NON-UPDATEABLE Vertex track list.
VertexTrackIterator getVertexTrackIterator (void) const
 Get non-updateable iterator over node tracks.
void optimise (bool discardIdentityNodeTracks=true)
 Optimise an animation by removing unnecessary tracks and keyframes.
void _collectIdentityNodeTracks (TrackHandleList &tracks) const
 Internal method for collecting identity node tracks.
void _destroyNodeTracks (const TrackHandleList &tracks)
 Internal method for destroy given node tracks.
Animationclone (const String &newName) const
 Clone this animation.
void _keyFrameListChanged (void)
 Internal method used to tell the animation that keyframe list has been changed, which may cause it to rebuild some internal data.
TimeIndex _getTimeIndex (Real timePos) const
 Internal method used to convert time position to time index object.

Static Public Member Functions

static void setDefaultInterpolationMode (InterpolationMode im)
 Sets the default animation interpolation mode.
static InterpolationMode getDefaultInterpolationMode (void)
 Gets the default interpolation mode for all animations.
static void setDefaultRotationInterpolationMode (RotationInterpolationMode im)
 Sets the default rotation interpolation mode.
static RotationInterpolationMode getDefaultRotationInterpolationMode (void)
 Gets the default rotation interpolation mode for all animations.

Protected Types

typedef std::vector< RealKeyFrameTimeList
 Global keyframe time list used to search global keyframe index.

Protected Member Functions

void optimiseNodeTracks (bool discardIdentityTracks)
void optimiseVertexTracks (void)
void buildKeyFrameTimeList (void) const
 Internal method to build global keyframe time list.

Protected Attributes

NodeTrackList mNodeTrackList
 Node tracks, indexed by handle.
NumericTrackList mNumericTrackList
 Numeric tracks, indexed by handle.
VertexTrackList mVertexTrackList
 Vertex tracks, indexed by handle.
String mName
Real mLength
InterpolationMode mInterpolationMode
RotationInterpolationMode mRotationInterpolationMode
KeyFrameTimeList mKeyFrameTimes
bool mKeyFrameTimesDirty
 Dirty flag indicate that keyframe time list need to rebuild.

Static Protected Attributes

static InterpolationMode msDefaultInterpolationMode
static RotationInterpolationMode msDefaultRotationInterpolationMode


Detailed Description

An animation sequence.

Remarks:
This class defines the interface for a sequence of animation, whether that be animation of a mesh, a path along a spline, or possibly more than one type of animation in one. An animation is made up of many 'tracks', which are the more specific types of animation.
You should not create these animations directly. They will be created via a parent object which owns the animation, e.g. Skeleton.

Definition at line 52 of file OgreAnimation.h.


Member Typedef Documentation

typedef std::vector<Real> Ogre::Animation::KeyFrameTimeList [protected]
 

Global keyframe time list used to search global keyframe index.

Definition at line 389 of file OgreAnimation.h.

typedef ConstMapIterator<NodeTrackList> Ogre::Animation::NodeTrackIterator
 

Definition at line 281 of file OgreAnimation.h.

typedef std::map<unsigned short, NodeAnimationTrack*> Ogre::Animation::NodeTrackList
 

Definition at line 280 of file OgreAnimation.h.

typedef ConstMapIterator<NumericTrackList> Ogre::Animation::NumericTrackIterator
 

Definition at line 284 of file OgreAnimation.h.

typedef std::map<unsigned short, NumericAnimationTrack*> Ogre::Animation::NumericTrackList
 

Definition at line 283 of file OgreAnimation.h.

typedef std::set<ushort> Ogre::Animation::TrackHandleList
 

A list of track handles.

Definition at line 332 of file OgreAnimation.h.

typedef ConstMapIterator<VertexTrackList> Ogre::Animation::VertexTrackIterator
 

Definition at line 287 of file OgreAnimation.h.

typedef std::map<unsigned short, VertexAnimationTrack*> Ogre::Animation::VertexTrackList
 

Definition at line 286 of file OgreAnimation.h.


Member Enumeration Documentation

enum Ogre::Animation::InterpolationMode
 

The types of animation interpolation available.

Enumeration values:
IM_LINEAR  Values are interpolated along straight lines.
IM_SPLINE  Values are interpolated along a spline, resulting in smoother changes in direction.

Definition at line 57 of file OgreAnimation.h.

enum Ogre::Animation::RotationInterpolationMode
 

The types of rotational interpolation available.

Enumeration values:
RIM_LINEAR  Values are interpolated linearly.

This is faster but does not necessarily give a completely accurate result.

RIM_SPHERICAL  Values are interpolated spherically.

This is more accurate but has a higher cost.

Definition at line 66 of file OgreAnimation.h.


Constructor & Destructor Documentation

Ogre::Animation::Animation const String name,
Real  length
 

You should not use this constructor directly, use the parent object such as Skeleton instead.

Parameters:
name The name of the animation, should be unique within it's parent (e.g. Skeleton)
length The length of the animation in seconds.

virtual Ogre::Animation::~Animation  )  [virtual]
 


Member Function Documentation

void Ogre::Animation::_collectIdentityNodeTracks TrackHandleList tracks  )  const
 

Internal method for collecting identity node tracks.

Remarks:
This method remove non-identity node tracks form the track handle list.
Parameters:
tracks A list of track handle of non-identity node tracks, where this method will remove non-identity node track handles.

void Ogre::Animation::_destroyNodeTracks const TrackHandleList tracks  ) 
 

Internal method for destroy given node tracks.

const NodeTrackList& Ogre::Animation::_getNodeTrackList void   )  const
 

Fast access to NON-UPDATEABLE node track list.

const NumericTrackList& Ogre::Animation::_getNumericTrackList void   )  const
 

Fast access to NON-UPDATEABLE numeric track list.

TimeIndex Ogre::Animation::_getTimeIndex Real  timePos  )  const
 

Internal method used to convert time position to time index object.

Note:
The time index returns by this function are associated with state of the animation object, if the animation object altered (e.g. create/remove keyframe or track), all related time index will invalidated.
Parameters:
timePos The time position.
Returns:
The time index object which contains wrapped time position (in relation to the whole animation sequence) and lower bound index of global keyframe time list.

const VertexTrackList& Ogre::Animation::_getVertexTrackList void   )  const
 

Fast access to NON-UPDATEABLE Vertex track list.

void Ogre::Animation::_keyFrameListChanged void   ) 
 

Internal method used to tell the animation that keyframe list has been changed, which may cause it to rebuild some internal data.

Definition at line 357 of file OgreAnimation.h.

void Ogre::Animation::apply Entity entity,
Real  timePos,
Real  weight,
bool  software,
bool  hardware
 

Applies all vertex tracks given a specific time point and weight to a given entity.

Remarks:
Parameters:
entity The Entity to which this animation should be applied
timePos The time position in the animation to apply.
weight The weight at which the animation should be applied (only affects pose animation)
software Whether to populate the software morph vertex data
hardware Whether to populate the hardware morph vertex data

void Ogre::Animation::apply Skeleton skeleton,
Real  timePos,
Real  weight = 1.0,
Real  scale = 1.0f
 

Applies all node tracks given a specific time point and weight to a given skeleton.

Remarks:
Where you have associated animation tracks with Node objects, you can eaily apply an animation to those nodes by calling this method.
Parameters:
timePos The time position in the animation to apply.
weight The influence to give to this track, 1.0 for full influence, less to blend with other animations.
scale The scale to apply to translations and scalings, useful for adapting an animation to a different size target.

void Ogre::Animation::apply Real  timePos,
Real  weight = 1.0,
Real  scale = 1.0f
 

Applies an animation given a specific time point and weight.

Remarks:
Where you have associated animation tracks with objects, you can eaily apply an animation to those objects by calling this method.
Parameters:
timePos The time position in the animation to apply.
weight The influence to give to this track, 1.0 for full influence, less to blend with other animations.
scale The scale to apply to translations and scalings, useful for adapting an animation to a different size target.

void Ogre::Animation::buildKeyFrameTimeList void   )  const [protected]
 

Internal method to build global keyframe time list.

Animation* Ogre::Animation::clone const String newName  )  const
 

Clone this animation.

Note:
The pointer returned from this method is the only one recorded, thus it is up to the caller to arrange for the deletion of this object.

NodeAnimationTrack* Ogre::Animation::createNodeTrack unsigned short  handle,
Node node
 

Creates a new AnimationTrack automatically associated with a Node.

Remarks:
This method creates a standard AnimationTrack, but also associates it with a target Node which will receive all keyframe effects.
Parameters:
handle Numeric handle to give the track, used for accessing the track later. Must be unique within this Animation.
node A pointer to the Node object which will be affected by this track

NodeAnimationTrack* Ogre::Animation::createNodeTrack unsigned short  handle  ) 
 

Creates a NodeAnimationTrack for animating a Node.

Parameters:
handle Handle to give the track, used for accessing the track later. Must be unique within this Animation.

NumericAnimationTrack* Ogre::Animation::createNumericTrack unsigned short  handle,
const AnimableValuePtr anim
 

Creates a NumericAnimationTrack and associates it with an animable.

Parameters:
handle Handle to give the track, used for accessing the track later.
anim Animable object link Must be unique within this Animation.

NumericAnimationTrack* Ogre::Animation::createNumericTrack unsigned short  handle  ) 
 

Creates a NumericAnimationTrack for animating any numeric value.

Parameters:
handle Handle to give the track, used for accessing the track later. Must be unique within this Animation.

VertexAnimationTrack* Ogre::Animation::createVertexTrack unsigned short  handle,
VertexData data,
VertexAnimationType  animType
 

Creates a VertexAnimationTrack and associates it with VertexData.

Parameters:
handle Handle to give the track, used for accessing the track later.
data VertexData object link
animType The animation type Must be unique within this Animation.

VertexAnimationTrack* Ogre::Animation::createVertexTrack unsigned short  handle,
VertexAnimationType  animType
 

Creates a VertexAnimationTrack for animating vertex position data.

Parameters:
handle Handle to give the track, used for accessing the track later. Must be unique within this Animation, and is used to identify the target. For example when applied to a Mesh, the handle must reference the index of the geometry being modified; 0 for the shared geometry, and 1+ for SubMesh geometry with the same index-1.
animType Either morph or pose animation,

void Ogre::Animation::destroyAllNodeTracks void   ) 
 

Removes and destroys all tracks making up this animation.

void Ogre::Animation::destroyAllNumericTracks void   ) 
 

Removes and destroys all tracks making up this animation.

void Ogre::Animation::destroyAllTracks void   ) 
 

Removes and destroys all tracks making up this animation.

void Ogre::Animation::destroyAllVertexTracks void   ) 
 

Removes and destroys all tracks making up this animation.

void Ogre::Animation::destroyNodeTrack unsigned short  handle  ) 
 

Destroys the node track with the given handle.

void Ogre::Animation::destroyNumericTrack unsigned short  handle  ) 
 

Destroys the numeric track with the given handle.

void Ogre::Animation::destroyVertexTrack unsigned short  handle  ) 
 

Destroys the Vertex track with the given handle.

static InterpolationMode Ogre::Animation::getDefaultInterpolationMode void   )  [static]
 

Gets the default interpolation mode for all animations.

static RotationInterpolationMode Ogre::Animation::getDefaultRotationInterpolationMode void   )  [static]
 

Gets the default rotation interpolation mode for all animations.

InterpolationMode Ogre::Animation::getInterpolationMode void   )  const
 

Gets the current interpolation mode of this animation.

Remarks:
See setInterpolationMode for more info.

Real Ogre::Animation::getLength void   )  const
 

Gets the total length of the animation.

const String& Ogre::Animation::getName void   )  const
 

Gets the name of this animation.

NodeAnimationTrack* Ogre::Animation::getNodeTrack unsigned short  handle  )  const
 

Gets a node track by it's handle.

NodeTrackIterator Ogre::Animation::getNodeTrackIterator void   )  const
 

Get non-updateable iterator over node tracks.

Definition at line 293 of file OgreAnimation.h.

NumericAnimationTrack* Ogre::Animation::getNumericTrack unsigned short  handle  )  const
 

Gets a numeric track by it's handle.

NumericTrackIterator Ogre::Animation::getNumericTrackIterator void   )  const
 

Get non-updateable iterator over node tracks.

Definition at line 300 of file OgreAnimation.h.

unsigned short Ogre::Animation::getNumNodeTracks void   )  const
 

Gets the number of NodeAnimationTrack objects contained in this animation.

unsigned short Ogre::Animation::getNumNumericTracks void   )  const
 

Gets the number of NumericAnimationTrack objects contained in this animation.

unsigned short Ogre::Animation::getNumVertexTracks void   )  const
 

Gets the number of VertexAnimationTrack objects contained in this animation.

RotationInterpolationMode Ogre::Animation::getRotationInterpolationMode void   )  const
 

Gets the current rotation interpolation mode of this animation.

Remarks:
See setRotationInterpolationMode for more info.

VertexAnimationTrack* Ogre::Animation::getVertexTrack unsigned short  handle  )  const
 

Gets a Vertex track by it's handle.

VertexTrackIterator Ogre::Animation::getVertexTrackIterator void   )  const
 

Get non-updateable iterator over node tracks.

Definition at line 307 of file OgreAnimation.h.

bool Ogre::Animation::hasNodeTrack unsigned short  handle  )  const
 

Does a track exist with the given handle?

bool Ogre::Animation::hasNumericTrack unsigned short  handle  )  const
 

Does a track exist with the given handle?

bool Ogre::Animation::hasVertexTrack unsigned short  handle  )  const
 

Does a track exist with the given handle?

void Ogre::Animation::optimise bool  discardIdentityNodeTracks = true  ) 
 

Optimise an animation by removing unnecessary tracks and keyframes.

Remarks:
When you export an animation, it is possible that certain tracks have been keyframed but actually don't include anything useful - the keyframes include no transformation. These tracks can be completely eliminated from the animation and thus speed up the animation. In addition, if several keyframes in a row have the same value, then they are just adding overhead and can be removed.
Note:
Since track-less and identity track has difference behavior for accumulate animation blending if corresponding track presenting at other animation that is non-identity, and in normally this method didn't known about the situation of other animation, it can't deciding whether or not discards identity tracks. So there have a parameter allow you choose what you want, in case you aren't sure how to do that, you should use Skeleton::optimiseAllAnimations instead.
Parameters:
discardIdentityNodeTracks If true, discard identity node tracks.

void Ogre::Animation::optimiseNodeTracks bool  discardIdentityTracks  )  [protected]
 

void Ogre::Animation::optimiseVertexTracks void   )  [protected]
 

static void Ogre::Animation::setDefaultInterpolationMode InterpolationMode  im  )  [static]
 

Sets the default animation interpolation mode.

Remarks:
Every animation created after this option is set will have the new interpolation mode specified. You can also change the mode per animation by calling the setInterpolationMode method on the instance in question.

static void Ogre::Animation::setDefaultRotationInterpolationMode RotationInterpolationMode  im  )  [static]
 

Sets the default rotation interpolation mode.

Remarks:
Every animation created after this option is set will have the new interpolation mode specified. You can also change the mode per animation by calling the setInterpolationMode method on the instance in question.

void Ogre::Animation::setInterpolationMode InterpolationMode  im  ) 
 

Tells the animation how to interpolate between keyframes.

Remarks:
By default, animations normally interpolate linearly between keyframes. This is fast, but when animations include quick changes in direction it can look a little unnatural because directions change instantly at keyframes. An alternative is to tell the animation to interpolate along a spline, which is more expensive in terms of calculation time, but looks smoother because major changes in direction are distributed around the keyframes rather than just at the keyframe.
You can also change the default animation behaviour by calling Animation::setDefaultInterpolationMode.

void Ogre::Animation::setRotationInterpolationMode RotationInterpolationMode  im  ) 
 

Tells the animation how to interpolate rotations.

Remarks:
By default, animations interpolate linearly between rotations. This is fast but not necessarily completely accurate. If you want more accurate interpolation, use spherical interpolation, but be aware that it will incur a higher cost.
You can also change the default rotation behaviour by calling Animation::setDefaultRotationInterpolationMode.


Member Data Documentation

InterpolationMode Ogre::Animation::mInterpolationMode [protected]
 

Definition at line 382 of file OgreAnimation.h.

KeyFrameTimeList Ogre::Animation::mKeyFrameTimes [mutable, protected]
 

Definition at line 390 of file OgreAnimation.h.

bool Ogre::Animation::mKeyFrameTimesDirty [mutable, protected]
 

Dirty flag indicate that keyframe time list need to rebuild.

Definition at line 392 of file OgreAnimation.h.

Real Ogre::Animation::mLength [protected]
 

Definition at line 380 of file OgreAnimation.h.

String Ogre::Animation::mName [protected]
 

Definition at line 378 of file OgreAnimation.h.

NodeTrackList Ogre::Animation::mNodeTrackList [protected]
 

Node tracks, indexed by handle.

Definition at line 373 of file OgreAnimation.h.

NumericTrackList Ogre::Animation::mNumericTrackList [protected]
 

Numeric tracks, indexed by handle.

Definition at line 375 of file OgreAnimation.h.

RotationInterpolationMode Ogre::Animation::mRotationInterpolationMode [protected]
 

Definition at line 383 of file OgreAnimation.h.

InterpolationMode Ogre::Animation::msDefaultInterpolationMode [static, protected]
 

Definition at line 385 of file OgreAnimation.h.

RotationInterpolationMode Ogre::Animation::msDefaultRotationInterpolationMode [static, protected]
 

Definition at line 386 of file OgreAnimation.h.

VertexTrackList Ogre::Animation::mVertexTrackList [protected]
 

Vertex tracks, indexed by handle.

Definition at line 377 of file OgreAnimation.h.


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

Copyright © 2000-2005 by The OGRE Team
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Sep 30 10:51:02 2007