OGRE: Ogre::SkeletonInstance Class Reference

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

SkeletonInstance (const SkeletonPtr &masterCopy)

Constructor, don't call directly, this will be created automatically when you create an Entity based on a skeletally animated Mesh.

~SkeletonInstance ()

unsigned short getNumAnimations (void) const

Gets the number of animations on this skeleton.

Animation * getAnimation (unsigned short index) const

Gets a single animation by index.

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

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

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

Creates a new Animation object for animating this skeleton.

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

Returns the named Animation object.

void removeAnimation (const String &name)

Removes an Animation from this skeleton.

TagPoint * createTagPointOnBone (Bone *bone, const Quaternion &offsetOrientation=Quaternion::IDENTITY, const Vector3 &offsetPosition=Vector3::ZERO)

Creates a TagPoint ready to be attached to a bone.

void freeTagPoint (TagPoint *tagPoint)

Frees a TagPoint that already attached to a bone.

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

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.

void removeAllLinkedSkeletonAnimationSources (void)

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

LinkedSkeletonAnimSourceIterator getLinkedSkeletonAnimationSourceIterator (void) const

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

void _initAnimationState (AnimationStateSet *animSet)

Initialise an animation set suitable for use with this skeleton.

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

void _refreshAnimationState (AnimationStateSet *animSet)

Refresh an animation set suitable for use with this skeleton.

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

const String & getName (void) const

Gets resource name.

ResourceHandle getHandle (void) const

const String & getGroup (void)

Gets the group which this resource is a member of.

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 bool hasAnimation (const String &name)

Returns whether this skeleton contains the named animation.

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 _getBoneMatrices (Matrix4 *pMatrices)

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

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 _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 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)

virtual void removeListener (Listener *lis)

Remove a listener on this resource.

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::list
< TagPoint * > TagPointList

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

void cloneBoneAndChildren (Bone *source, Bone *parent)

void loadImpl (void)

Overridden from Skeleton.

void unloadImpl (void)

Overridden from Skeleton.

void deriveRootBone (void) const

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

void _dumpContents (const String &filename)

Debugging method.

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

SkeletonPtr

mSkeleton

Pointer back to master Skeleton.

TagPointList

mActiveTagPoints

Active tag point list.

TagPointList

mFreeTagPoints

Free tag point list.

unsigned short mNextTagPointAutoHandle

TagPoint automatic handles.

SkeletonAnimationBlendMode

mBlendState

BoneList

mBoneList

Storage of bones, indexed by bone handle.

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.

Detailed Description

Member Typedef Documentation

typedef std::list<TagPoint*> Ogre::SkeletonInstance::TagPointList [protected]

Definition at line 118 of file OgreSkeletonInstance.h.

typedef std::vector<Bone*> Ogre::Skeleton::BoneList [inherited]

Definition at line 171 of file OgreSkeleton.h.

typedef VectorIterator<BoneList> Ogre::Skeleton::BoneIterator [inherited]

Definition at line 172 of file OgreSkeleton.h.

typedef std::vector<LinkedSkeletonAnimationSource> Ogre::Skeleton::LinkedSkeletonAnimSourceList [inherited]

Definition at line 330 of file OgreSkeleton.h.

typedef ConstVectorIterator<LinkedSkeletonAnimSourceList> Ogre::Skeleton::LinkedSkeletonAnimSourceIterator [inherited]

Definition at line 332 of file OgreSkeleton.h.

typedef std::vector<ushort> Ogre::Skeleton::BoneHandleMap [inherited]

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, inherited]

Lookup by bone name.

Definition at line 406 of file OgreSkeleton.h.

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

Definition at line 414 of file OgreSkeleton.h.

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

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::SkeletonInstance::SkeletonInstance ( const SkeletonPtr & masterCopy )

Constructor, don't call directly, this will be created automatically when you create an Entity based on a skeletally animated Mesh.

Ogre::SkeletonInstance::~SkeletonInstance ( )

Member Function Documentation

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

Gets the number of animations on this skeleton.

Reimplemented from Ogre::Skeleton.

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

Gets a single animation by index.

Reimplemented from Ogre::Skeleton.

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

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

Reimplemented from Ogre::Skeleton.

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

Creates a new Animation object for animating this skeleton.

Remarks:: This method updates the reference skeleton, not just this instance!

Parameters:

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

Reimplemented from Ogre::Skeleton.

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

Returns the named Animation object.

Reimplemented from Ogre::Skeleton.

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

Removes an Animation from this skeleton.

Remarks:: This method updates the reference skeleton, not just this instance!

Reimplemented from Ogre::Skeleton.

TagPoint* Ogre::SkeletonInstance::createTagPointOnBone	(	Bone *	bone,
		const Quaternion &	offsetOrientation = `Quaternion::IDENTITY`,
		const Vector3 &	offsetPosition = `Vector3::ZERO`
	)

Creates a TagPoint ready to be attached to a bone.

void Ogre::SkeletonInstance::freeTagPoint ( TagPoint * tagPoint )

Frees a TagPoint that already attached to a bone.

void Ogre::SkeletonInstance::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.

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 from Ogre::Skeleton.

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

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

Reimplemented from Ogre::Skeleton.

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

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

Reimplemented from Ogre::Skeleton.

void Ogre::SkeletonInstance::_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 from Ogre::Skeleton.

void Ogre::SkeletonInstance::_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 from Ogre::Skeleton.

const String& Ogre::SkeletonInstance::getName ( void ) const [virtual]

Gets resource name.

Reimplemented from Ogre::Resource.

ResourceHandle Ogre::SkeletonInstance::getHandle ( void ) const [virtual]

Reimplemented from Ogre::Resource.

const String& Ogre::SkeletonInstance::getGroup ( void ) [virtual]

Gets the group which this resource is a member of.

Reimplemented from Ogre::Resource.

void Ogre::SkeletonInstance::cloneBoneAndChildren	(	Bone *	source,
		Bone *	parent
	)			`[protected]`

void Ogre::SkeletonInstance::loadImpl ( void ) [protected, virtual]

Overridden from Skeleton.

Reimplemented from Ogre::Skeleton.

void Ogre::SkeletonInstance::unloadImpl ( void ) [protected, virtual]

Overridden from Skeleton.

Reimplemented from Ogre::Skeleton.

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

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, inherited]

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, inherited]

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, inherited]`

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, inherited]

Returns the number of bones in this skeleton.

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

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.