com.jme.animation
Class BoneAnimation

java.lang.Object
  extended by com.jme.animation.BoneAnimation
All Implemented Interfaces:
Savable, java.io.Serializable

public class BoneAnimation
extends java.lang.Object
implements java.io.Serializable, Savable

BoneAnimation defines a component that manipulates the position of a skeletal system based on a collection of keyframes. In the simplest case, BoneAnimation directly affects a single bone, and the skeletal system is a tree (skeleton) of these BoneAnimations. The BoneAnimation is defined with an array of keyframe times and a BoneTransform for each bone directly controlled. The animations can have a heirarchical composition, and at any level the animation may not control a bone, but simply control sub-animations. In a typical application, the skeletal tree described above is collapsed down so that only one BoneAnimation object is used at display-time. Though it implements no interface, the intention is that an update method of this class should be called by a Controller.

See Also:
optimize(boolean), BoneTransform, Controller, update(float, int, float), Serialized Form

Field Summary
static int BEZIER
           
static int LINEAR
           
 
Constructor Summary
BoneAnimation()
           
BoneAnimation(java.lang.String name)
          Contructor creates a new animation.
BoneAnimation(java.lang.String name, Bone bone, int numKeyframes)
          Creates a new, linear-interpolating BoneAnimation with a name, the bone it will control and the number of keyframes it will have.
 
Method Summary
 void addBoneAnimation(BoneAnimation ba)
          addBoneAnimation adds a child animation to this animation.
 void addBoneTransforms(BoneTransform bt)
          addBoneTransform adds a bone transform array pair that this bone animation uses to update.
 void addEvent(int frame, AnimationEvent event)
          adds an AnimationEvent to this animation for a specified frame.
 void addSync(java.lang.String name, int[] frames)
          add a sync tag to this animation.
 boolean assignSkeleton(Bone b)
          Assigns this animation to a provided skeleton.
 boolean containsSyncTags()
           
 java.util.Set<java.lang.String> getAllSyncTags()
           
 AnimationProperties getAnimationProperties()
           
 java.util.ArrayList<BoneTransform> getBoneTransforms()
          returns the list of BoneTransforms for this animation.
 java.lang.Class getClassTag()
           
 int getCurrentFrame()
          returns the current frame that animation is currently working towards or set to.
 float getCurrentTime()
          returns the current time of the animation.
 Spatial getDestSpatial()
           
 int getEndFrame()
          retrieves the end frame of the animation.
 float getInterpolationRate()
          retrieves the rate at which interpolation occurs, this is in unit seconds.
 float[] getKeyFrameTimes()
          returns the list of keyframe times for this animation.
 java.lang.String getName()
          returns the name of this animation.
 Bone getSourceBone()
           
 int getStartFrame()
          retrieves the start frame of the animation.
 BoneAnimation getSubanimation(int i)
          returns a child animation from a given index.
 int[] getSyncFrames(java.lang.String name)
           
 java.util.ArrayList<java.lang.String> getSyncNames(int frame)
           
 boolean hasChildren()
          hasChildren returns true if this BoneAnimation has child BoneAnimations, false otherwise.
 boolean isInterpolate()
          returns true if this animation should interpolate between keyframes, false otherwise.
 boolean isValid()
          returns true if this animation is valid (i.e.
 void optimize(boolean removeChildren)
          optimize will attempt to condense the BoneAnimation into as few children as possible.
 void read(JMEImporter e)
           
 void reset()
           
 void resetCurrentTime()
           
 void setAnimationProperties(AnimationProperties props)
           
 void setCurrentFrame(int frame)
          setCurrentFrame will set the current position of the animation to the supplied frame.
 void setDestSpatial(Spatial destSpatial)
           
 void setEndFrame(int endFrame)
          sets the end frame of the animation.
 void setInitialFrame(int frame)
           
 void setInterpolate(boolean interpolate)
          sets whether this animation should interpolate between frames.
 void setInterpolationRate(float interpolationRate)
          sets the rate at which interpolation occurs, this is in unit seconds.
 void setInterpolationTypes(int[] types)
          Sets the interpolation types array for the keyframes.
 void setName(java.lang.String name)
          sets the name of this animation.
 void setSourceBone(Bone sourceBone)
           
 void setStartFrame(int startFrame)
          sets the start frame of the animation.
 void setTimes(float[] times)
          Sets the times array for the keyframes.
 int subanimationCount()
          returns the number of children animations that are attached to this animation.
 java.lang.String toString()
          returns the string representation of this animation.
 void update(float time, int repeat, float speed)
          update is called during the update phase of the game cycle.
 void update(float time, int repeat, float speed, float blendRate)
          This method of update() supports Blending.
 void write(JMEExporter e)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LINEAR

public static final int LINEAR
See Also:
Constant Field Values

BEZIER

public static final int BEZIER
See Also:
Constant Field Values
Constructor Detail

BoneAnimation

public BoneAnimation()

BoneAnimation

public BoneAnimation(java.lang.String name)
Contructor creates a new animation. The name is the name of the animation.

Parameters:
name - the name of the animation.

BoneAnimation

public BoneAnimation(java.lang.String name,
                     Bone bone,
                     int numKeyframes)
Creates a new, linear-interpolating BoneAnimation with a name, the bone it will control and the number of keyframes it will have.

Parameters:
name - the name of the animation
bone - the bone the animation affects
numKeyframes - the number of keyframes the animation has.
Method Detail

addBoneAnimation

public void addBoneAnimation(BoneAnimation ba)
addBoneAnimation adds a child animation to this animation. This child's update will be called with the parent's.

Parameters:
ba - the child animation to add to this animation.

addEvent

public void addEvent(int frame,
                     AnimationEvent event)
adds an AnimationEvent to this animation for a specified frame.

Parameters:
frame - the frame number to trigger the event.
event - the event to trigger.

addSync

public void addSync(java.lang.String name,
                    int[] frames)
add a sync tag to this animation.

Parameters:
name - the name of the sync tag.
frames - the frames that are tied to this sync tag.

getSyncFrames

public int[] getSyncFrames(java.lang.String name)

containsSyncTags

public boolean containsSyncTags()

getAllSyncTags

public java.util.Set<java.lang.String> getAllSyncTags()

getSyncNames

public java.util.ArrayList<java.lang.String> getSyncNames(int frame)

setInitialFrame

public void setInitialFrame(int frame)

setCurrentFrame

public void setCurrentFrame(int frame)
setCurrentFrame will set the current position of the animation to the supplied frame. If the frame is outside of the start/end frame subset, the frame will work towards the start frame.

Parameters:
frame - the frame to set the current animation frame to.

addBoneTransforms

public void addBoneTransforms(BoneTransform bt)
addBoneTransform adds a bone transform array pair that this bone animation uses to update. This BoneTransform is added to the list of bone transforms currently in place.

Parameters:
bt - the BoneTransform to add to this list.

update

public void update(float time,
                   int repeat,
                   float speed)
update is called during the update phase of the game cycle. If this animation is not active, this method immediately returns. The update of the bone is dependent on the repeat type (see 'repeat' param below). This version of update() does not support Blending.

Parameters:
time - The time supplied is the time between frames (normally) and this is used to define what frame of animation we should be at and how to interpolate between frames.
repeat - Controller.RT_CLAMP will cause the bones to animate through a single cycle and stop. Controller.RT_CYCLE will cause the animation to reverse when it reaches one of the ends of the cycle. Controller.RT_WRAP will start the animation over from the beginning.
See Also:
update(float, int, float, float), Controller

update

public void update(float time,
                   int repeat,
                   float speed,
                   float blendRate)
This method of update() supports Blending.

See Also:
update(float, int, float)

isValid

public boolean isValid()
returns true if this animation is valid (i.e. contains valid information)

Returns:

subanimationCount

public int subanimationCount()
returns the number of children animations that are attached to this animation.

Returns:
the number of children animations this bone animation is responsible for.

getSubanimation

public BoneAnimation getSubanimation(int i)
returns a child animation from a given index. If the index is invalid, null is returned.

Parameters:
i - the index to obtain the animation.
Returns:
the animation at a given index, null if the index is invalid.

setTimes

public void setTimes(float[] times)
Sets the times array for the keyframes. This array should be the same size as the transforms array and the types array. This is left to the user to insure, if they are not the same, an ArrayIndexOutOfBounds exception will be thrown during update.

Parameters:
times - the times to set.

setInterpolationTypes

public void setInterpolationTypes(int[] types)
Sets the interpolation types array for the keyframes. This array should be the same size as the transforms array and the types array. This is left to the user to insure, if they are not the same, an ArrayIndexOutOfBounds exception will be thrown during update.

If the interpolation type array is null, interpolation work will be skipped (performance benefit if interpolation not required).

Parameters:
types - the interpolation types to set, or null for no interpolation.

getName

public java.lang.String getName()
returns the name of this animation.

Returns:
the name of this animation

setName

public void setName(java.lang.String name)
sets the name of this animation.

Parameters:
name - the name of this animation.

getCurrentFrame

public int getCurrentFrame()
returns the current frame that animation is currently working towards or set to.

Returns:
the current frame of this animation.

getCurrentTime

public float getCurrentTime()
returns the current time of the animation.

Returns:
the current time of this animation.

getEndFrame

public int getEndFrame()
retrieves the end frame of the animation. The end frame defines where the animation will "stop".

Returns:
the end frame of the animation.

setEndFrame

public void setEndFrame(int endFrame)
sets the end frame of the animation. The end frame defines where the animation will "stop".

Parameters:
endFrame - the end frame of the animation.

getStartFrame

public int getStartFrame()
retrieves the start frame of the animation. The start frame defines where the animation will "start".

Returns:
the start frame of the animation.

setStartFrame

public void setStartFrame(int startFrame)
sets the start frame of the animation. The start frame defines where the animation will "start".

Parameters:
startFrame - the start frame of the animation.

isInterpolate

public boolean isInterpolate()
returns true if this animation should interpolate between keyframes, false otherwise.

Returns:
true if we will interpolation between frames.

setInterpolate

public void setInterpolate(boolean interpolate)
sets whether this animation should interpolate between frames. It also sets the children of this animation to the interpolation value. True will interpolate between frames, false will not.

Parameters:
interpolate - true to interpolate, false otherwise.

getInterpolationRate

public float getInterpolationRate()
retrieves the rate at which interpolation occurs, this is in unit seconds. Therefore, 0.25 would be a quater of a second.

Returns:
the interpolation rate.

setInterpolationRate

public void setInterpolationRate(float interpolationRate)
sets the rate at which interpolation occurs, this is in unit seconds. Therefore, 0.25 would be a quater of a second.

Parameters:
interpolationRate - the interpolation rate.

hasChildren

public boolean hasChildren()
hasChildren returns true if this BoneAnimation has child BoneAnimations, false otherwise.

Returns:
true if this animation has child animations, false otherwise.

getKeyFrameTimes

public float[] getKeyFrameTimes()
returns the list of keyframe times for this animation.

Returns:
the list of keyframe times for this animation.

getBoneTransforms

public java.util.ArrayList<BoneTransform> getBoneTransforms()
returns the list of BoneTransforms for this animation.

Returns:
the list of BoneTransforms for this animation.

optimize

public void optimize(boolean removeChildren)
optimize will attempt to condense the BoneAnimation into as few children as possible. This allows the proper sharing of keyframe times and calculation of current time and current frame. If a child animation has no children of its own, and its keyframes are equal to this animation, the BoneTransforms are assimilated into this animation and the child is deleted.


toString

public java.lang.String toString()
returns the string representation of this animation.

Overrides:
toString in class java.lang.Object

assignSkeleton

public boolean assignSkeleton(Bone b)
Assigns this animation to a provided skeleton. The skeleton bones are examined to assign transforms as needed. If no bones are properly assigned to a transform, false is returned. If the assignment is successful, true is returned.

Parameters:
b - the skeleton to assign.
Returns:
true if this was successful, false otherwise.

write

public void write(JMEExporter e)
           throws java.io.IOException
Specified by:
write in interface Savable
Throws:
java.io.IOException

read

public void read(JMEImporter e)
          throws java.io.IOException
Specified by:
read in interface Savable
Throws:
java.io.IOException

getClassTag

public java.lang.Class getClassTag()
Specified by:
getClassTag in interface Savable

resetCurrentTime

public void resetCurrentTime()

reset

public void reset()

getDestSpatial

public Spatial getDestSpatial()

setDestSpatial

public void setDestSpatial(Spatial destSpatial)

getSourceBone

public Bone getSourceBone()

setSourceBone

public void setSourceBone(Bone sourceBone)

getAnimationProperties

public AnimationProperties getAnimationProperties()

setAnimationProperties

public void setAnimationProperties(AnimationProperties props)