Ogre::Skeleton Class Reference

A collection of Bone objects used to animate a skinned mesh. More...

#include <OgreSkeleton.h>

Inheritance diagram for Ogre::Skeleton:

List of all members.

Public Types

typedef std::vector
< Bone * > BoneList

typedef
VectorIterator
< BoneList > BoneIterator

typedef std::vector
< LinkedSkeletonAnimationSource > LinkedSkeletonAnimSourceList

typedef
ConstVectorIterator
< LinkedSkeletonAnimSourceList > LinkedSkeletonAnimSourceIterator

typedef std::vector
< ushort > BoneHandleMap

Map to translate bone handle from one skeleton to another skeleton.

enum LoadingState {
LOADSTATE_UNLOADED, LOADSTATE_LOADING, LOADSTATE_LOADED, LOADSTATE_UNLOADING,
LOADSTATE_PREPARED, LOADSTATE_PREPARING
}

Enum identifying the loading state of the resource. More...

Public Member Functions

Skeleton (ResourceManager *creator, const String &name, ResourceHandle handle, const String &group, bool isManual=false, ManualResourceLoader *loader=0)

Constructor, don't call directly, use SkeletonManager.

virtual ~Skeleton ()

virtual Bone * createBone (void)

Creates a brand new Bone owned by this Skeleton.

virtual Bone * createBone (unsigned short handle)

Creates a brand new Bone owned by this Skeleton.

virtual Bone * createBone (const String &name)

Creates a brand new Bone owned by this Skeleton.

virtual Bone * createBone (const String &name, unsigned short handle)

Creates a brand new Bone owned by this Skeleton.

virtual unsigned short getNumBones (void) const

Returns the number of bones in this skeleton.

virtual Bone * getRootBone (void) const

Gets the root bone of the skeleton: deprecated in favour of getRootBoneIterator.

virtual BoneIterator getRootBoneIterator (void)

Get an iterator over the root bones in the skeleton, ie those with no parents.

virtual BoneIterator getBoneIterator (void)

Get an iterator over all the bones in the skeleton.

virtual Bone * getBone (unsigned short handle) const

Gets a bone by it's handle.

virtual Bone * getBone (const String &name) const

Gets a bone by it's name.

virtual bool hasBone (const String &name) const

Returns whether this skeleton contains the named bone.

virtual void setBindingPose (void)

Sets the current position / orientation to be the 'binding pose' i.e.

virtual void reset (bool resetManualBones=false)

Resets the position and orientation of all bones in this skeleton to their original binding position.

virtual Animation * createAnimation (const String &name, Real length)

Creates a new Animation object for animating this skeleton.

virtual Animation * getAnimation (const String &name, const LinkedSkeletonAnimationSource **linker=0) const

Returns the named Animation object.

virtual Animation * _getAnimationImpl (const String &name, const LinkedSkeletonAnimationSource **linker=0) const

Internal accessor for animations (returns null if animation does not exist).

virtual bool hasAnimation (const String &name)

Returns whether this skeleton contains the named animation.

virtual void removeAnimation (const String &name)

Removes an Animation from this skeleton.

virtual void setAnimationState (const AnimationStateSet &animSet)

Changes the state of the skeleton to reflect the application of the passed in collection of animations.

virtual void _initAnimationState (AnimationStateSet *animSet)

Initialise an animation set suitable for use with this skeleton.

virtual void _refreshAnimationState (AnimationStateSet *animSet)

Refresh an animation set suitable for use with this skeleton.

virtual void _getBoneMatrices (Matrix4 *pMatrices)

Populates the passed in array with the bone matrices based on the current position.

virtual unsigned short getNumAnimations (void) const

Gets the number of animations on this skeleton.

virtual Animation * getAnimation (unsigned short index) const

Gets a single animation by index.

virtual
SkeletonAnimationBlendMode getBlendMode () const

Gets the animation blending mode which this skeleton will use.

virtual void setBlendMode (SkeletonAnimationBlendMode state)

Sets the animation blending mode this skeleton will use.

virtual void _updateTransforms (void)

Updates all the derived transforms in the skeleton.

virtual void optimiseAllAnimations (bool preservingIdentityNodeTracks=false)

Optimise all of this skeleton's animations.

virtual void addLinkedSkeletonAnimationSource (const String &skelName, Real scale=1.0f)

Allows you to use the animations from another Skeleton object to animate this skeleton.

virtual void removeAllLinkedSkeletonAnimationSources (void)

Remove all links to other skeletons for the purposes of sharing animation.

virtual
LinkedSkeletonAnimSourceIterator getLinkedSkeletonAnimationSourceIterator (void) const

Get an iterator over the linked skeletons used as animation sources.

virtual void _notifyManualBonesDirty (void)

Internal method for marking the manual bones as dirty.

virtual void _notifyManualBoneStateChange (Bone *bone)

Internal method for notifying that a bone is manual.

virtual bool getManualBonesDirty (void) const

Have manual bones been modified since the skeleton was last updated?

virtual bool hasManualBones (void) const

Are there any manually controlled bones?

virtual void _mergeSkeletonAnimations (const Skeleton *source, const BoneHandleMap &boneHandleMap, const StringVector &animations=StringVector())

Merge animations from another Skeleton object into this skeleton.

virtual void _buildMapBoneByHandle (const Skeleton *source, BoneHandleMap &boneHandleMap) const

Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.

virtual void _buildMapBoneByName (const Skeleton *source, BoneHandleMap &boneHandleMap) const

Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.

virtual void prepare ()

Prepares the resource for load, if it is not already.

virtual void load (bool backgroundThread=false)

Loads the resource, if it is not already.

virtual void reload (void)

Reloads the resource, if it is already loaded.

virtual bool isReloadable (void) const

Returns true if the Resource is reloadable, false otherwise.

virtual bool isManuallyLoaded (void) const

Is this resource manually loaded?

virtual void unload (void)

Unloads the resource; this is not permanent, the resource can be reloaded later if required.

virtual size_t getSize (void) const

Retrieves info about the size of the resource.

virtual void touch (void)

'Touches' the resource to indicate it has been used.

virtual const String & getName (void) const

Gets resource name.

virtual ResourceHandle getHandle (void) const

virtual bool isPrepared (void) const

Returns true if the Resource has been prepared, false otherwise.

virtual bool isLoaded (void) const

Returns true if the Resource has been loaded, false otherwise.

virtual bool isLoading () const

Returns whether the resource is currently in the process of background loading.

virtual LoadingState getLoadingState () const

Returns the current loading state.

virtual bool isBackgroundLoaded (void) const

Returns whether this Resource has been earmarked for background loading.

virtual void setBackgroundLoaded (bool bl)

Tells the resource whether it is background loaded or not.

virtual void escalateLoading ()

Escalates the loading of a background loaded resource.

virtual void addListener (Listener *lis)

Register a listener on this resource.

virtual void removeListener (Listener *lis)

Remove a listener on this resource.

virtual const String & getGroup (void)

Gets the group which this resource is a member of.

virtual void changeGroupOwnership (const String &newGroup)

Change the resource group ownership of a Resource.

virtual ResourceManager * getCreator (void)

Gets the manager which created this resource.

virtual const String & getOrigin (void) const

Get the origin of this resource, e.g.

virtual void _notifyOrigin (const String &origin)

Notify this resource of it's origin.

virtual size_t getStateCount () const

Returns the number of times this resource has changed state, which generally means the number of times it has been loaded.

virtual void _dirtyState ()

Manually mark the state of this resource as having been changed.

virtual void _fireBackgroundLoadingComplete (void)

Firing of background loading complete event.

virtual void _fireBackgroundPreparingComplete (void)

Firing of background preparing complete event.

ParamDictionary * getParamDictionary (void)

Retrieves the parameter dictionary for this class.

const ParamDictionary * getParamDictionary (void) const

const ParameterList & getParameters (void) const

Retrieves a list of parameters valid for this object.

virtual bool setParameter (const String &name, const String &value)

Generic parameter setting method.

virtual void setParameterList (const NameValuePairList &paramList)

Generic multiple parameter setting method.

virtual String getParameter (const String &name) const

Generic parameter retrieval method.

virtual void copyParametersTo (StringInterface *dest) const

Method for copying this object's parameters to another object.

void * operator new (size_t sz, const char *file, int line, const char *func)

operator new, with debug line info

void * operator new (size_t sz)

void * operator new (size_t sz, void *ptr)

placement operator new

void * operator new[] (size_t sz, const char *file, int line, const char *func)

array operator new, with debug line info

void * operator new[] (size_t sz)

void operator delete (void *ptr)

void operator delete (void *ptr, const char *, int, const char *)

void operator delete[] (void *ptr)

void operator delete[] (void *ptr, const char *, int, const char *)

Static Public Member Functions

static void cleanupDictionary ()

Cleans up the static 'msDictionary' required to reset Ogre, otherwise the containers are left with invalid pointers, which will lead to a crash as soon as one of the ResourceManager implementers (e.g.

Protected Types

typedef std::map
< String, Bone * > BoneListByName

Lookup by bone name.

typedef std::set
< Bone * > BoneSet

typedef std::map
< String, Animation * > AnimationList

Storage of animations, lookup by name.

typedef std::list
< Listener * > ListenerList

Protected Member Functions

Skeleton ()

Internal constructor for use by SkeletonInstance only.

void deriveRootBone (void) const

Internal method which parses the bones to derive the root bone.

void _dumpContents (const String &filename)

Debugging method.

void loadImpl (void)

Internal implementation of the meat of the 'load' action, only called if this resource is not being loaded from a ManualResourceLoader.

void unloadImpl (void)

Internal implementation of the 'unload' action; called regardless of whether this resource is being loaded from a ManualResourceLoader.

size_t calculateSize (void) const

Calculate the size of a resource; this will only be called after 'load'.

virtual void preLoadImpl (void)

Internal hook to perform actions before the load process, but after the resource has been marked as 'loading'.

virtual void postLoadImpl (void)

Internal hook to perform actions after the load process, but before the resource has been marked as fully loaded.

virtual void preUnloadImpl (void)

Internal hook to perform actions before the unload process.

virtual void postUnloadImpl (void)

Internal hook to perform actions after the unload process, but before the resource has been marked as fully unloaded.

virtual void prepareImpl (void)

Internal implementation of the meat of the 'prepare' action.

virtual void unprepareImpl (void)

Internal function for undoing the 'prepare' action.

virtual void queueFireBackgroundLoadingComplete (void)

Queue the firing of background loading complete event.

virtual void queueFireBackgroundPreparingComplete (void)

Queue the firing of background preparing complete event.

bool createParamDictionary (const String &className)

Internal method for creating a parameter dictionary for the class, if it does not already exist.

Protected Attributes

SkeletonAnimationBlendMode mBlendState

BoneList mBoneList

Storage of bones, indexed by bone handle.

BoneListByName mBoneListByName

BoneList mRootBones

Pointer to root bones (can now have multiple roots).

unsigned short mNextAutoHandle

Bone automatic handles.

BoneSet mManualBones

Manual bones.

bool mManualBonesDirty

Manual bones dirty?

AnimationList mAnimationsList

LinkedSkeletonAnimSourceList mLinkedSkeletonAnimSourceList

List of references to other skeletons to use animations from.

ResourceManager * mCreator

Creator.

String mName

Unique name of the resource.

String mGroup

The name of the resource group.

ResourceHandle mHandle

Numeric handle for more efficient look up than name.

AtomicScalar
< LoadingState > mLoadingState

Is the resource currently loaded?

volatile bool mIsBackgroundLoaded

Is this resource going to be background loaded? Only applicable for multithreaded.

size_t mSize

The size of the resource in bytes.

bool mIsManual

Is this file manually loaded?

String mOrigin

Origin of this resource (e.g. script name) - optional.

ManualResourceLoader * mLoader

Optional manual loader; if provided, data is loaded from here instead of a file.

size_t mStateCount

State count, the number of times this resource has changed state.

ListenerList mListenerList

String mParamDictName

Class name for this instance to be used as a lookup (must be initialised by subclasses).

Static Protected Attributes

static ParamDictionaryMap msDictionary

Dictionary of parameters.

Friends

class SkeletonInstance

Detailed Description

A collection of Bone objects used to animate a skinned mesh.

Remarks:: Skeletal animation works by having a collection of 'bones' which are actually just joints with a position and orientation, arranged in a tree structure. For example, the wrist joint is a child of the elbow joint, which in turn is a child of the shoulder joint. Rotating the shoulder automatically moves the elbow and wrist as well due to this hierarchy.

: So how does this animate a mesh? Well every vertex in a mesh is assigned to one or more bones which affects it's position when the bone is moved. If a vertex is assigned to more than one bone, then weights must be assigned to determine how much each bone affects the vertex (actually a weight of 1.0 is used for single bone assignments). Weighted vertex assignments are especially useful around the joints themselves to avoid 'pinching' of the mesh in this region.

: Therefore by moving the skeleton using preset animations, we can animate the mesh. The advantage of using skeletal animation is that you store less animation data, especially as vertex counts increase. In addition, you are able to blend multiple animations together (e.g. walking and looking around, running and shooting) and provide smooth transitions between animations without incurring as much of an overhead as would be involved if you did this on the core vertex data.

: Skeleton definitions are loaded from datafiles, namely the .skeleton file format. They are loaded on demand, especially when referenced by a Mesh.

Definition at line 80 of file OgreSkeleton.h.

Member Typedef Documentation

typedef std::vector<Bone*> Ogre::Skeleton::BoneList

Definition at line 171 of file OgreSkeleton.h.

typedef VectorIterator<BoneList> Ogre::Skeleton::BoneIterator

Definition at line 172 of file OgreSkeleton.h.

typedef std::vector<LinkedSkeletonAnimationSource> Ogre::Skeleton::LinkedSkeletonAnimSourceList

Definition at line 330 of file OgreSkeleton.h.

typedef ConstVectorIterator<LinkedSkeletonAnimSourceList> Ogre::Skeleton::LinkedSkeletonAnimSourceIterator

Definition at line 332 of file OgreSkeleton.h.

typedef std::vector<ushort> Ogre::Skeleton::BoneHandleMap

Map to translate bone handle from one skeleton to another skeleton.

Definition at line 348 of file OgreSkeleton.h.

typedef std::map<String, Bone*> Ogre::Skeleton::BoneListByName [protected]

Lookup by bone name.

Definition at line 406 of file OgreSkeleton.h.

typedef std::set<Bone*> Ogre::Skeleton::BoneSet [protected]

Definition at line 414 of file OgreSkeleton.h.

typedef std::map<String, Animation*> Ogre::Skeleton::AnimationList [protected]

Storage of animations, lookup by name.

Definition at line 422 of file OgreSkeleton.h.

typedef std::list<Listener*> Ogre::Resource::ListenerList [protected, inherited]

Definition at line 148 of file OgreResource.h.

Member Enumeration Documentation

enum Ogre::Resource::LoadingState [inherited]

Enum identifying the loading state of the resource.

Enumerator:

LOADSTATE_UNLOADED	Not loaded.
LOADSTATE_LOADING	Loading is in progress.
LOADSTATE_LOADED	Fully loaded.
LOADSTATE_UNLOADING	Currently unloading.
LOADSTATE_PREPARED	Fully prepared.
LOADSTATE_PREPARING	Preparing is in progress.

Definition at line 109 of file OgreResource.h.

Constructor & Destructor Documentation

Ogre::Skeleton::Skeleton ( ) [protected]

Internal constructor for use by SkeletonInstance only.

Ogre::Skeleton::Skeleton	(	ResourceManager *	creator,
		const String &	name,
		ResourceHandle	handle,
		const String &	group,
		bool	isManual = `false`,
		ManualResourceLoader *	loader = `0`
	)

Constructor, don't call directly, use SkeletonManager.

Remarks:: On creation, a Skeleton has a no bones, you should create them and link them together appropriately.

virtual Ogre::Skeleton::~Skeleton ( ) [virtual]

Member Function Documentation

virtual Bone* Ogre::Skeleton::createBone ( void ) [virtual]

Creates a brand new Bone owned by this Skeleton.

Remarks:: This method creates an unattached new Bone for this skeleton. Unless this is to be a root bone (there may be more than one of these), you must attach it to another Bone in the skeleton using addChild for it to be any use. For this reason you will likely be better off creating child bones using the Bone::createChild method instead, once you have created the root bone.

: Note that this method automatically generates a handle for the bone, which you can retrieve using Bone::getHandle. If you wish the new Bone to have a specific handle, use the alternate form of this method which takes a handle as a parameter, although you should note the restrictions.

virtual Bone* Ogre::Skeleton::createBone ( unsigned short handle ) [virtual]

Creates a brand new Bone owned by this Skeleton.

Remarks:: This method creates an unattached new Bone for this skeleton and assigns it a specific handle. Unless this is to be a root bone (there may be more than one of these), you must attach it to another Bone in the skeleton using addChild for it to be any use. For this reason you will likely be better off creating child bones using the Bone::createChild method instead, once you have created a root bone.

Parameters:

handle

The handle to give to this new bone - must be unique within this skeleton. You should also ensure that all bone handles are eventually contiguous (this is to simplify their compilation into an indexed array of transformation matrices). For this reason it is advised that you use the simpler createBone method which automatically assigns a sequential handle starting from 0.

virtual Bone* Ogre::Skeleton::createBone ( const String & name ) [virtual]

Creates a brand new Bone owned by this Skeleton.

Remarks:: This method creates an unattached new Bone for this skeleton and assigns it a specific name.Unless this is to be a root bone (there may be more than one of these), you must attach it to another Bone in the skeleton using addChild for it to be any use. For this reason you will likely be better off creating child bones using the Bone::createChild method instead, once you have created the root bone.

Parameters:

name

The name to give to this new bone - must be unique within this skeleton. Note that the way OGRE looks up bones is via a numeric handle, so if you name a Bone this way it will be given an automatic sequential handle. The name is just for your convenience, although it is recommended that you only use the handle to retrieve the bone in performance-critical code.

virtual Bone* Ogre::Skeleton::createBone	(	const String &	name,
		unsigned short	handle
	)			`[virtual]`

Creates a brand new Bone owned by this Skeleton.

Remarks:: This method creates an unattached new Bone for this skeleton and assigns it a specific name and handle. Unless this is to be a root bone (there may be more than one of these), you must attach it to another Bone in the skeleton using addChild for it to be any use. For this reason you will likely be better off creating child bones using the Bone::createChild method instead, once you have created the root bone.

Parameters:

	name	The name to give to this new bone - must be unique within this skeleton.
	handle	The handle to give to this new bone - must be unique within this skeleton.

virtual unsigned short Ogre::Skeleton::getNumBones ( void ) const [virtual]

Returns the number of bones in this skeleton.

virtual Bone* Ogre::Skeleton::getRootBone ( void ) const [virtual]

Gets the root bone of the skeleton: deprecated in favour of getRootBoneIterator.

Remarks:: The system derives the root bone the first time you ask for it. The root bone is the only bone in the skeleton which has no parent. The system locates it by taking the first bone in the list and going up the bone tree until there are no more parents, and saves this top bone as the root. If you are building the skeleton manually using createBone then you must ensure there is only one bone which is not a child of another bone, otherwise your skeleton will not work properly. If you use createBone only once, and then use Bone::createChild from then on, then inherently the first bone you create will by default be the root.

virtual BoneIterator Ogre::Skeleton::getRootBoneIterator ( void ) [virtual]

Get an iterator over the root bones in the skeleton, ie those with no parents.

virtual BoneIterator Ogre::Skeleton::getBoneIterator ( void ) [virtual]

Get an iterator over all the bones in the skeleton.

virtual Bone* Ogre::Skeleton::getBone ( unsigned short handle ) const [virtual]

Gets a bone by it's handle.

virtual Bone* Ogre::Skeleton::getBone ( const String & name ) const [virtual]

Gets a bone by it's name.

virtual bool Ogre::Skeleton::hasBone ( const String & name ) const [virtual]

Returns whether this skeleton contains the named bone.

virtual void Ogre::Skeleton::setBindingPose ( void ) [virtual]

Sets the current position / orientation to be the 'binding pose' i.e.

the layout in which bones were originally bound to a mesh.

virtual void Ogre::Skeleton::reset ( bool resetManualBones = false ) [virtual]

Resets the position and orientation of all bones in this skeleton to their original binding position.

Remarks:: A skeleton is bound to a mesh in a binding pose. Bone positions are then modified from this position during animation. This method returns all the bones to their original position and orientation.

Parameters:

resetManualBones

If set to true, causes the state of manual bones to be reset too, which is normally not done to allow the manual state to persist even when keyframe animation is applied.

virtual Animation* Ogre::Skeleton::createAnimation	(	const String &	name,
		Real	length
	)			`[virtual]`

Creates a new Animation object for animating this skeleton.

Parameters:

	name	The name of this animation
	length	The length of the animation in seconds

Reimplemented in Ogre::SkeletonInstance.

virtual Animation* Ogre::Skeleton::getAnimation	(	const String &	name,
		const LinkedSkeletonAnimationSource **	linker = `0`
	)			const `[virtual]`

Returns the named Animation object.

Remarks:: Will pick up animations in linked skeletons (

See also:: addLinkedSkeletonAnimationSource).

Parameters:

	name	The name of the animation
	linker	Optional pointer to a pointer to the linked skeleton animation where this is coming from.

Reimplemented in Ogre::SkeletonInstance.

virtual Animation* Ogre::Skeleton::_getAnimationImpl	(	const String &	name,
		const LinkedSkeletonAnimationSource **	linker = `0`
	)			const `[virtual]`

Internal accessor for animations (returns null if animation does not exist).

Reimplemented in Ogre::SkeletonInstance.

virtual bool Ogre::Skeleton::hasAnimation ( const String & name ) [virtual]

Returns whether this skeleton contains the named animation.

virtual void Ogre::Skeleton::removeAnimation ( const String & name ) [virtual]

Removes an Animation from this skeleton.

Reimplemented in Ogre::SkeletonInstance.

virtual void Ogre::Skeleton::setAnimationState ( const AnimationStateSet & animSet ) [virtual]

Changes the state of the skeleton to reflect the application of the passed in collection of animations.

Remarks:: Animating a skeleton involves both interpolating between keyframes of a specific animation, and blending between the animations themselves. Calling this method sets the state of the skeleton so that it reflects the combination of all the passed in animations, at the time index specified for each, using the weights specified. Note that the weights between animations do not have to sum to 1.0, because some animations may affect only subsets of the skeleton. If the weights exceed 1.0 for the same area of the skeleton, the movement will just be exaggerated.

Parameters:

virtual void Ogre::Skeleton::_initAnimationState ( AnimationStateSet * animSet ) [virtual]

Initialise an animation set suitable for use with this skeleton.

Remarks:: Only recommended for use inside the engine, not by applications.

Reimplemented in Ogre::SkeletonInstance.

virtual void Ogre::Skeleton::_refreshAnimationState ( AnimationStateSet * animSet ) [virtual]

Refresh an animation set suitable for use with this skeleton.

Remarks:: Only recommended for use inside the engine, not by applications.

Reimplemented in Ogre::SkeletonInstance.

virtual void Ogre::Skeleton::_getBoneMatrices ( Matrix4 * pMatrices ) [virtual]

Populates the passed in array with the bone matrices based on the current position.

Remarks:: Internal use only. The array pointed to by the passed in pointer must be at least as large as the number of bones. Assumes animation has already been updated.

virtual unsigned short Ogre::Skeleton::getNumAnimations ( void ) const [virtual]

Gets the number of animations on this skeleton.

Reimplemented in Ogre::SkeletonInstance.

virtual Animation* Ogre::Skeleton::getAnimation ( unsigned short index ) const [virtual]

Gets a single animation by index.

Remarks:: Will NOT pick up animations in linked skeletons (

See also:: addLinkedSkeletonAnimationSource).

Reimplemented in Ogre::SkeletonInstance.

virtual SkeletonAnimationBlendMode Ogre::Skeleton::getBlendMode ( ) const [virtual]

Gets the animation blending mode which this skeleton will use.

virtual void Ogre::Skeleton::setBlendMode ( SkeletonAnimationBlendMode state ) [virtual]

Sets the animation blending mode this skeleton will use.

virtual void Ogre::Skeleton::_updateTransforms ( void ) [virtual]

Updates all the derived transforms in the skeleton.

virtual void Ogre::Skeleton::optimiseAllAnimations ( bool preservingIdentityNodeTracks = false ) [virtual]

Optimise all of this skeleton's animations.

See also:: Animation::optimise

Parameters:

preservingIdentityNodeTracks

If true, don't destroy identity node tracks.

virtual void Ogre::Skeleton::addLinkedSkeletonAnimationSource	(	const String &	skelName,
		Real	scale = `1.0f`
	)			`[virtual]`

Allows you to use the animations from another Skeleton object to animate this skeleton.

Remarks:: If you have skeletons of identical structure (that means identically named bones with identical handles, and with the same hierarchy), but slightly different proportions or binding poses, you can re-use animations from one in the other. Because animations are actually stored as changes to bones from their bind positions, it's possible to use the same animation data for different skeletons, provided the skeletal structure matches and the 'deltas' stored in the keyframes apply equally well to the other skeletons bind position (so they must be roughly similar, but don't have to be identical). You can use the 'scale' option to adjust the translation and scale keyframes where there are large differences in size between the skeletons.

Note:: This method takes a skeleton name, rather than a more specific animation name, for two reasons; firstly it allows some validation of compatibility of skeletal structure, and secondly skeletons are the unit of loading. Linking a skeleton to another in this way means that the linkee will be prevented from being destroyed until the linker is destroyed.

You cannot set up cyclic relationships, e.g. SkeletonA uses SkeletonB's animations, and SkeletonB uses SkeletonA's animations. This is because it would set up a circular dependency which would prevent proper unloading - make one of the skeletons the 'master' in this case.

Parameters:

	skelName	Name of the skeleton to link animations from. This skeleton will be loaded immediately if this skeleton is already loaded, otherwise it will be loaded when this skeleton is.
	scale	A scale factor to apply to translation and scaling elements of the keyframes in the other skeleton when applying the animations to this one. Compensates for skeleton size differences.

Reimplemented in Ogre::SkeletonInstance.

virtual void Ogre::Skeleton::removeAllLinkedSkeletonAnimationSources ( void ) [virtual]

Remove all links to other skeletons for the purposes of sharing animation.

Reimplemented in Ogre::SkeletonInstance.

virtual LinkedSkeletonAnimSourceIterator Ogre::Skeleton::getLinkedSkeletonAnimationSourceIterator ( void ) const [virtual]

Get an iterator over the linked skeletons used as animation sources.

Reimplemented in Ogre::SkeletonInstance.

virtual void Ogre::Skeleton::_notifyManualBonesDirty ( void ) [virtual]

Internal method for marking the manual bones as dirty.

virtual void Ogre::Skeleton::_notifyManualBoneStateChange ( Bone * bone ) [virtual]

Internal method for notifying that a bone is manual.

virtual bool Ogre::Skeleton::getManualBonesDirty ( void ) const [virtual]

Have manual bones been modified since the skeleton was last updated?

Definition at line 343 of file OgreSkeleton.h.

virtual bool Ogre::Skeleton::hasManualBones ( void ) const [virtual]

Are there any manually controlled bones?

Definition at line


Public Types
typedef std::vector < Bone * >	BoneList
typedef VectorIterator < BoneList >	BoneIterator
typedef std::vector < LinkedSkeletonAnimationSource >	LinkedSkeletonAnimSourceList
typedef ConstVectorIterator < LinkedSkeletonAnimSourceList >	LinkedSkeletonAnimSourceIterator
typedef std::vector < ushort >	BoneHandleMap
	Map to translate bone handle from one skeleton to another skeleton.
enum	LoadingState { LOADSTATE_UNLOADED, LOADSTATE_LOADING, LOADSTATE_LOADED, LOADSTATE_UNLOADING, LOADSTATE_PREPARED, LOADSTATE_PREPARING }
	Enum identifying the loading state of the resource. More...
Public Member Functions
	Skeleton (ResourceManager creator, const String &name, ResourceHandle handle, const String &group, bool isManual=false, ManualResourceLoader loader=0)
	Constructor, don't call directly, use SkeletonManager.
virtual	~Skeleton ()
virtual Bone *	createBone (void)
	Creates a brand new Bone owned by this Skeleton.
virtual Bone *	createBone (unsigned short handle)
	Creates a brand new Bone owned by this Skeleton.
virtual Bone *	createBone (const String &name)
	Creates a brand new Bone owned by this Skeleton.
virtual Bone *	createBone (const String &name, unsigned short handle)
	Creates a brand new Bone owned by this Skeleton.
virtual unsigned short	getNumBones (void) const
	Returns the number of bones in this skeleton.
virtual Bone *	getRootBone (void) const
	Gets the root bone of the skeleton: deprecated in favour of getRootBoneIterator.
virtual BoneIterator	getRootBoneIterator (void)
	Get an iterator over the root bones in the skeleton, ie those with no parents.
virtual BoneIterator	getBoneIterator (void)
	Get an iterator over all the bones in the skeleton.
virtual Bone *	getBone (unsigned short handle) const
	Gets a bone by it's handle.
virtual Bone *	getBone (const String &name) const
	Gets a bone by it's name.
virtual bool	hasBone (const String &name) const
	Returns whether this skeleton contains the named bone.
virtual void	setBindingPose (void)
	Sets the current position / orientation to be the 'binding pose' i.e.
virtual void	reset (bool resetManualBones=false)
	Resets the position and orientation of all bones in this skeleton to their original binding position.
virtual Animation *	createAnimation (const String &name, Real length)
	Creates a new Animation object for animating this skeleton.
virtual Animation *	getAnimation (const String &name, const LinkedSkeletonAnimationSource **linker=0) const
	Returns the named Animation object.
virtual Animation *	_getAnimationImpl (const String &name, const LinkedSkeletonAnimationSource **linker=0) const
	Internal accessor for animations (returns null if animation does not exist).
virtual bool	hasAnimation (const String &name)
	Returns whether this skeleton contains the named animation.
virtual void	removeAnimation (const String &name)
	Removes an Animation from this skeleton.
virtual void	setAnimationState (const AnimationStateSet &animSet)
	Changes the state of the skeleton to reflect the application of the passed in collection of animations.
virtual void	_initAnimationState (AnimationStateSet *animSet)
	Initialise an animation set suitable for use with this skeleton.
virtual void	_refreshAnimationState (AnimationStateSet *animSet)
	Refresh an animation set suitable for use with this skeleton.
virtual void	_getBoneMatrices (Matrix4 *pMatrices)
	Populates the passed in array with the bone matrices based on the current position.
virtual unsigned short	getNumAnimations (void) const
	Gets the number of animations on this skeleton.
virtual Animation *	getAnimation (unsigned short index) const
	Gets a single animation by index.
virtual SkeletonAnimationBlendMode	getBlendMode () const
	Gets the animation blending mode which this skeleton will use.
virtual void	setBlendMode (SkeletonAnimationBlendMode state)
	Sets the animation blending mode this skeleton will use.
virtual void	_updateTransforms (void)
	Updates all the derived transforms in the skeleton.
virtual void	optimiseAllAnimations (bool preservingIdentityNodeTracks=false)
	Optimise all of this skeleton's animations.
virtual void	addLinkedSkeletonAnimationSource (const String &skelName, Real scale=1.0f)
	Allows you to use the animations from another Skeleton object to animate this skeleton.
virtual void	removeAllLinkedSkeletonAnimationSources (void)
	Remove all links to other skeletons for the purposes of sharing animation.
virtual LinkedSkeletonAnimSourceIterator	getLinkedSkeletonAnimationSourceIterator (void) const
	Get an iterator over the linked skeletons used as animation sources.
virtual void	_notifyManualBonesDirty (void)
	Internal method for marking the manual bones as dirty.
virtual void	_notifyManualBoneStateChange (Bone *bone)
	Internal method for notifying that a bone is manual.
virtual bool	getManualBonesDirty (void) const
	Have manual bones been modified since the skeleton was last updated?
virtual bool	hasManualBones (void) const
	Are there any manually controlled bones?
virtual void	_mergeSkeletonAnimations (const Skeleton *source, const BoneHandleMap &boneHandleMap, const StringVector &animations=StringVector())
	Merge animations from another Skeleton object into this skeleton.
virtual void	_buildMapBoneByHandle (const Skeleton *source, BoneHandleMap &boneHandleMap) const
	Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.
virtual void	_buildMapBoneByName (const Skeleton *source, BoneHandleMap &boneHandleMap) const
	Build the bone handle map to use with Skeleton::_mergeSkeletonAnimations.
virtual void	prepare ()
	Prepares the resource for load, if it is not already.
virtual void	load (bool backgroundThread=false)
	Loads the resource, if it is not already.
virtual void	reload (void)
	Reloads the resource, if it is already loaded.
virtual bool	isReloadable (void) const
	Returns true if the Resource is reloadable, false otherwise.
virtual bool	isManuallyLoaded (void) const
	Is this resource manually loaded?
virtual void	unload (void)
	Unloads the resource; this is not permanent, the resource can be reloaded later if required.
virtual size_t	getSize (void) const
	Retrieves info about the size of the resource.
virtual void	touch (void)
	'Touches' the resource to indicate it has been used.
virtual const String &	getName (void) const
	Gets resource name.
virtual ResourceHandle	getHandle (void) const
virtual bool	isPrepared (void) const
	Returns true if the Resource has been prepared, false otherwise.
virtual bool	isLoaded (void) const
	Returns true if the Resource has been loaded, false otherwise.
virtual bool	isLoading () const
	Returns whether the resource is currently in the process of background loading.
virtual LoadingState	getLoadingState () const
	Returns the current loading state.
virtual bool	isBackgroundLoaded (void) const
	Returns whether this Resource has been earmarked for background loading.
virtual void	setBackgroundLoaded (bool bl)
	Tells the resource whether it is background loaded or not.
virtual void	escalateLoading ()
	Escalates the loading of a background loaded resource.
virtual void	addListener (Listener *lis)
	Register a listener on this resource.
virtual void	removeListener (Listener *lis)
	Remove a listener on this resource.
virtual const String &	getGroup (void)
	Gets the group which this resource is a member of.
virtual void	changeGroupOwnership (const String &newGroup)
	Change the resource group ownership of a Resource.
virtual ResourceManager *	getCreator (void)
	Gets the manager which created this resource.
virtual const String &	getOrigin (void) const
	Get the origin of this resource, e.g.
virtual void	_notifyOrigin (const String &origin)
	Notify this resource of it's origin.
virtual size_t	getStateCount () const
	Returns the number of times this resource has changed state, which generally means the number of times it has been loaded.
virtual void	_dirtyState ()
	Manually mark the state of this resource as having been changed.
virtual void	_fireBackgroundLoadingComplete (void)
	Firing of background loading complete event.
virtual void	_fireBackgroundPreparingComplete (void)
	Firing of background preparing complete event.
ParamDictionary *	getParamDictionary (void)
	Retrieves the parameter dictionary for this class.
const ParamDictionary *	getParamDictionary (void) const
const ParameterList &	getParameters (void) const
	Retrieves a list of parameters valid for this object.
virtual bool	setParameter (const String &name, const String &value)
	Generic parameter setting method.
virtual void	setParameterList (const NameValuePairList &paramList)
	Generic multiple parameter setting method.
virtual String	getParameter (const String &name) const
	Generic parameter retrieval method.
virtual void	copyParametersTo (StringInterface *dest) const
	Method for copying this object's parameters to another object.
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
Static Public Member Functions
static void	cleanupDictionary ()
	Cleans up the static 'msDictionary' required to reset Ogre, otherwise the containers are left with invalid pointers, which will lead to a crash as soon as one of the ResourceManager implementers (e.g.
Protected Types
typedef std::map < String, Bone * >	BoneListByName
	Lookup by bone name.
typedef std::set < Bone * >	BoneSet
typedef std::map < String, Animation * >	AnimationList
	Storage of animations, lookup by name.
typedef std::list < Listener * >	ListenerList
Protected Member Functions
	Skeleton ()
	Internal constructor for use by SkeletonInstance only.
void	deriveRootBone (void) const
	Internal method which parses the bones to derive the root bone.
void	_dumpContents (const String &filename)
	Debugging method.
void	loadImpl (void)
	Internal implementation of the meat of the 'load' action, only called if this resource is not being loaded from a ManualResourceLoader.
void	unloadImpl (void)
	Internal implementation of the 'unload' action; called regardless of whether this resource is being loaded from a ManualResourceLoader.
size_t	calculateSize (void) const
	Calculate the size of a resource; this will only be called after 'load'.
virtual void	preLoadImpl (void)
	Internal hook to perform actions before the load process, but after the resource has been marked as 'loading'.
virtual void	postLoadImpl (void)
	Internal hook to perform actions after the load process, but before the resource has been marked as fully loaded.
virtual void	preUnloadImpl (void)
	Internal hook to perform actions before the unload process.
virtual void	postUnloadImpl (void)
	Internal hook to perform actions after the unload process, but before the resource has been marked as fully unloaded.
virtual void	prepareImpl (void)
	Internal implementation of the meat of the 'prepare' action.
virtual void	unprepareImpl (void)
	Internal function for undoing the 'prepare' action.
virtual void	queueFireBackgroundLoadingComplete (void)
	Queue the firing of background loading complete event.
virtual void	queueFireBackgroundPreparingComplete (void)
	Queue the firing of background preparing complete event.
bool	createParamDictionary (const String &className)
	Internal method for creating a parameter dictionary for the class, if it does not already exist.
Protected Attributes
SkeletonAnimationBlendMode	mBlendState
BoneList	mBoneList
	Storage of bones, indexed by bone handle.
BoneListByName	mBoneListByName
BoneList	mRootBones
	Pointer to root bones (can now have multiple roots).
unsigned short	mNextAutoHandle
	Bone automatic handles.
BoneSet	mManualBones
	Manual bones.
bool	mManualBonesDirty
	Manual bones dirty?
AnimationList	mAnimationsList
LinkedSkeletonAnimSourceList	mLinkedSkeletonAnimSourceList
	List of references to other skeletons to use animations from.
ResourceManager *	mCreator
	Creator.
String	mName
	Unique name of the resource.
String	mGroup
	The name of the resource group.
ResourceHandle	mHandle
	Numeric handle for more efficient look up than name.
AtomicScalar < LoadingState >	mLoadingState
	Is the resource currently loaded?
volatile bool	mIsBackgroundLoaded
	Is this resource going to be background loaded? Only applicable for multithreaded.
size_t	mSize
	The size of the resource in bytes.
bool	mIsManual
	Is this file manually loaded?
String	mOrigin
	Origin of this resource (e.g. script name) - optional.
ManualResourceLoader *	mLoader
	Optional manual loader; if provided, data is loaded from here instead of a file.
size_t	mStateCount
	State count, the number of times this resource has changed state.
ListenerList	mListenerList
String	mParamDictName
	Class name for this instance to be used as a lookup (must be initialised by subclasses).
Static Protected Attributes
static ParamDictionaryMap	msDictionary
	Dictionary of parameters.
Friends
class	SkeletonInstance