C# Class Axiom.Animating.Skeleton

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

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 .xsf file format. They are loaded on demand, especially when referenced by a Mesh.

Inheritance: Axiom.Core.Resource

Datei anzeigen Open project: WolfgangSt/axiom Class Usage Examples

Protected Properties

Property	Type	Description
animationList	Axiom.Collections.AnimationCollection
attachmentPoints	List
boneList	BoneCollection
namedBoneList	AxiomCollection
rootBones	BoneList

Public Methods

Method	Description
ContainsAnimation ( string name ) : bool
ContainsBone ( string name ) : bool	Checks to see if a bone exists
CreateAnimation ( string name, float length ) : Animation	Creates a new Animation object for animating this skeleton.
CreateAttachmentPoint ( string name, ushort parentHandle, Axiom.MathLib.Quaternion rotation, Vector3 translation ) : AttachmentPoint	TODO: should this replace an existing attachment point with the same name?
CreateBone ( ) : Bone	Creates a brand new Bone owned by this Skeleton. This method creates an unattached new Bone for this skeleton. Unless this is to be the root bone (there must only be 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.Handle. 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.
CreateBone ( string name ) : Bone	Creates a brand new Bone owned by this Skeleton. This method creates an unattached new Bone for this skeleton. Unless this is to be the root bone (there must only be 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.
CreateBone ( string name, ushort handle ) : Bone	Creates a brand new Bone owned by this Skeleton.
CreateBone ( ushort handle ) : Bone	Creates a brand new Bone owned by this Skeleton.
DumpContents ( string fileName ) : void
GetAnimation ( string name ) : Animation	Returns the animation with the specified name.
GetBone ( string name ) : Bone	Gets a bone by its name.
GetBone ( ushort handle ) : Bone	Gets a bone by its handle.
GetRootBone ( int index ) : Bone	Gets the root bone at the specified index.
InitAnimationState ( Axiom.Animating.AnimationStateSet animSet ) : void	Initialize an animation set suitable for use with this mesh. Only recommended for use inside the engine, not by applications.
RemoveAnimation ( string name ) : void	Removes the animation with the specified name from this skeleton.
Reset ( ) : void	Resets the position and orientation of all bones in this skeleton to their original binding position. 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.
Reset ( bool resetManualBones ) : void	Resets the position and orientation of all bones in this skeleton to their original binding position. 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.
SetAnimationState ( Axiom.Animating.AnimationStateSet animSet ) : void
SetBindingPose ( ) : void	Sets the current position / orientation to be the 'binding pose' ie the layout in which bones were originally bound to a mesh.
Skeleton ( ResourceManager parent, String name, System.UInt64 handle, string group ) : System	Constructor, don't call directly, use SkeletonManager. On creation, a Skeleton has a no bones, you should create them and link them together appropriately.
Skeleton ( ResourceManager parent, String name, System.UInt64 handle, string group, bool isManual, IManualResourceLoader loader ) : System	Constructor, don't call directly, use SkeletonManager. On creation, a Skeleton has a no bones, you should create them and link them together appropriately.
UpdateTransforms ( ) : void	Updates all the derived transforms in the skeleton.

Protected Methods

Method	Description
DeriveRootBone ( ) : void	Internal method which parses the bones to derive the root bone.
load ( ) : void	Generic load, called by SkeletonManager.
unload ( ) : void	Generic unload, called by SkeletonManager.

Private Methods

Method	Description
GetBoneMatrices ( Axiom.MathLib.Matrix4 matrices ) : void	Populates the passed in array with the bone matrices based on the current position. Internal use only. The array passed in must be at least as large as the number of bones. Assumes animation has already been updated.
Skeleton ( ) : System

Method Details

ContainsAnimation() public method

public ContainsAnimation ( string name ) : bool
name	string
return	bool

ContainsBone() public method

Checks to see if a bone exists

public ContainsBone ( string name ) : bool
name	string	Name of the bone to check.
return	bool

CreateAnimation() public method

Creates a new Animation object for animating this skeleton.

public CreateAnimation ( string name, float length ) : Animation
name	string	The name of this animation
length	float	The length of the animation in seconds
return	Animation

CreateAttachmentPoint() public method

TODO: should this replace an existing attachment point with the same name?

public CreateAttachmentPoint ( string name, ushort parentHandle, Axiom.MathLib.Quaternion rotation, Vector3 translation ) : AttachmentPoint
name	string
parentHandle	ushort
rotation	Axiom.MathLib.Quaternion
translation	Vector3
return	AttachmentPoint

CreateBone() public method

Creates a brand new Bone owned by this Skeleton.

This method creates an unattached new Bone for this skeleton. Unless this is to be the root bone (there must only be 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.Handle. 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.

public CreateBone ( ) : Bone
return	Bone

CreateBone() public method

Creates a brand new Bone owned by this Skeleton.

public CreateBone ( string name ) : Bone
name	string	/// The name to give to this new bone - must be unique within this skeleton. /// Note that the way the engine 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. ///
return	Bone

CreateBone() public method

Creates a brand new Bone owned by this Skeleton.

public CreateBone ( string name, ushort handle ) : Bone
name	string	/// The name to give to this new bone - must be unique within this skeleton. /// Note that the way the engine 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. ///
handle	ushort	/// 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. ///
return	Bone

CreateBone() public method

Creates a brand new Bone owned by this Skeleton.

public CreateBone ( ushort handle ) : Bone
handle	ushort	/// 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. ///
return	Bone

DeriveRootBone() protected method

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

protected DeriveRootBone ( ) : void
return	void

DumpContents() public method

public DumpContents ( string fileName ) : void
fileName	string
return	void

GetAnimation() public method

Returns the animation with the specified name.

public GetAnimation ( string name ) : Animation
name	string	Name of the animation to retrieve.
return	Animation

GetBone() public method

Gets a bone by its name.

public GetBone ( string name ) : Bone
name	string	Name of the bone to retrieve.
return	Bone

GetBone() public method

Gets a bone by its handle.

public GetBone ( ushort handle ) : Bone
handle	ushort	Handle of the bone to retrieve.
return	Bone

GetRootBone() public method

Gets the root bone at the specified index.

public GetRootBone ( int index ) : Bone
index	int	Index of the root bone to return.
return	Bone

InitAnimationState() public method

Initialize an animation set suitable for use with this mesh.

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

public InitAnimationState ( Axiom.Animating.AnimationStateSet animSet ) : void
animSet	Axiom.Animating.AnimationStateSet
return	void

RemoveAnimation() public method

Removes the animation with the specified name from this skeleton.

public RemoveAnimation ( string name ) : void
name	string	Name of the animation to remove.
return	void

Reset() public method

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

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.

public Reset ( ) : void
return	void

Reset() public method

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

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.

public Reset ( bool resetManualBones ) : void
resetManualBones	bool
return	void

SetAnimationState() public method

public SetAnimationState ( Axiom.Animating.AnimationStateSet animSet ) : void
animSet	Axiom.Animating.AnimationStateSet
return	void

SetBindingPose() public method

Sets the current position / orientation to be the 'binding pose' ie the layout in which bones were originally bound to a mesh.

public SetBindingPose ( ) : void
return	void

Skeleton() public method

Constructor, don't call directly, use SkeletonManager.

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

public Skeleton ( ResourceManager parent, String name, System.UInt64 handle, string group ) : System
parent	Axiom.Core.ResourceManager
name	String
handle	System.UInt64
group	string
return	System

Skeleton() public method

Constructor, don't call directly, use SkeletonManager.

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

public Skeleton ( ResourceManager parent, String name, System.UInt64 handle, string group, bool isManual, IManualResourceLoader loader ) : System
parent	Axiom.Core.ResourceManager
name	String
handle	System.UInt64
group	string
isManual	bool
loader	IManualResourceLoader
return	System

UpdateTransforms() public method

Updates all the derived transforms in the skeleton.

public UpdateTransforms ( ) : void
return	void

load() protected method

Generic load, called by SkeletonManager.

protected load ( ) : void
return	void

unload() protected method

Generic unload, called by SkeletonManager.

protected unload ( ) : void
return	void

Property Details

animationList protected_oe property

Lookup table for animations related to this skeleton.

protected AnimationCollection,Axiom.Collections animationList
return	Axiom.Collections.AnimationCollection

attachmentPoints protected_oe property

Internal list of bones attached to this skeleton, indexed by handle.

protected List attachmentPoints
return	List

boneList protected_oe property

Internal list of bones attached to this skeleton, indexed by handle.

protected BoneCollection boneList
return	BoneCollection

namedBoneList protected_oe property

Internal list of bones attached to this skeleton, indexed by name.

protected AxiomCollection namedBoneList
return	AxiomCollection

rootBones protected_oe property

Reference to the root bone of this skeleton.

protected BoneList rootBones
return	BoneList