* Javadocs for com.jme3.animation

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@7638 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

engine/src/core/com/jme3/animation/Bone.java

@@ -114,8 +114,18 @@ public final class Bone implements Savable {
     }
 
     /**
-     * Copy constructor. local bind and world inverse bind transforms shallow copied.
-     * @param source
+     * Special-purpose copy constructor. 
+     * <p>
+     * Only copies the name and bind pose from the original.
+     * <p>
+     * WARNING: Local bind pose and world inverse bind pose transforms shallow 
+     * copied. Modifying that data on the original bone will cause it to
+     * be recomputed on any cloned bones.
+     * <p>
+     * The rest of the data is <em>NOT</em> copied, as it will be
+     * generated automatically when the bone is animated.
+     * 
+     * @param source The bone from which to copy the data.
      */
     Bone(Bone source) {
         this.name = source.name;
@@ -134,9 +144,7 @@ public final class Bone implements Savable {
     }
 
     /**
-     * Used for binary loading as a Savable; the object must be constructed,
-     * then the parameters usually present in the constructor for this class are
-     * restored from the file the object was saved to.
+     * Serialization only. Do not use.
      */
     public Bone() {
     }
@@ -223,6 +231,9 @@ public final class Bone implements Savable {
 
     /**
      * Returns the inverse world bind pose position.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
      * 
      * @return the inverse world bind pose position.
      */
@@ -232,6 +243,9 @@ public final class Bone implements Savable {
 
     /**
      * Returns the inverse world bind pose rotation.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
      * 
      * @return the inverse world bind pose rotation.
      */
@@ -241,6 +255,9 @@ public final class Bone implements Savable {
 
     /**
      * Returns the inverse world bind pose scale.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
      * 
      * @return the inverse world bind pose scale.
      */
@@ -248,6 +265,42 @@ public final class Bone implements Savable {
         return worldBindInverseScale;
     }
     
+    /**
+     * Returns the world bind pose position.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
+     * 
+     * @return the world bind pose position.
+     */
+    public Vector3f getWorldBindPosition() {
+        return initialPos;
+    }
+
+    /**
+     * Returns the world bind pose rotation.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
+     * 
+     * @return the world bind pose rotation.
+     */
+    public Quaternion getWorldBindRotation() {
+        return initialRot;
+    }
+    
+    /**
+     * Returns the world bind pose scale.
+     * <p>
+     * The bind pose transform of the bone is its "default"
+     * transform with no animation applied.
+     * 
+     * @return the world bind pose scale.
+     */
+    public Vector3f getWorldBindScale() {
+        return initialScale;
+    }
+
     /**
      * If enabled, user can control bone transform with setUserTransforms.
      * Animation transforms are not applied to this bone when enabled.
@@ -259,7 +312,8 @@ public final class Bone implements Savable {
     /**
      * Add a new child to this bone. Shouldn't be used by user code.
      * Can corrupt skeleton.
-     * @param bone
+     * 
+     * @param bone The bone to add
      */
     public void addChild(Bone bone) {
         children.add(bone);
@@ -267,7 +321,11 @@ public final class Bone implements Savable {
     }
 
     /**
-     * Updates the world transforms for this bone, and, possibly the attach node if not null.
+     * Updates the world transforms for this bone, and, possibly the attach node
+     * if not null.
+     * <p>
+     * The world transform of this bone is computed by combining the parent's
+     * world transform with this bones' local transform.
      */
     public final void updateWorldVectors() {
         if (parent != null) {
@@ -376,8 +434,7 @@ public final class Bone implements Savable {
     }
 
     /**
-     * Set user transform.
-     * Combine the given transforms to bone's current transforms
+     * Sets user transform.
      */
     public void setUserTransforms(Vector3f translation, Quaternion rotation, Vector3f scale) {
         if (!userControl) {
@@ -397,12 +454,13 @@ public final class Bone implements Savable {
      * Must update all bones in skeleton for this to work.
      * @param translation
      * @param rotation
-     *///TODO: add scale here ???
+     */
     public void setUserTransformsWorld(Vector3f translation, Quaternion rotation) {
         if (!userControl) {
             throw new IllegalStateException("User control must be on bone to allow user transforms");
         }
         
+        // TODO: add scale here ???
         worldPos.set(translation);
         worldRot.set(rotation);
     }
@@ -497,16 +555,12 @@ public final class Bone implements Savable {
     public void setBindTransforms(Vector3f translation, Quaternion rotation, Vector3f scale) {
         initialPos.set(translation);
         initialRot.set(rotation);
-        if (scale != null) {
         initialScale.set(scale);
-        }
         
         localPos.set(translation);
         localRot.set(rotation);
-        if (scale != null) {
         localScale.set(scale);
     }
-    }
 
     private String toString(int depth) {
         StringBuilder sb = new StringBuilder();
@@ -562,12 +616,4 @@ public final class Bone implements Savable {
         output.write(initialScale, "initialScale", new Vector3f(1.0f, 1.0f, 1.0f));
         output.writeSavableArrayList(children, "children", null);
     }
-
-    public Vector3f getInitialPos() {
-        return initialPos;
-    }
-
-    public Quaternion getInitialRot() {
-        return initialRot;
-    }
 }

engine/src/core/com/jme3/animation/BoneAnimation.java

@@ -40,7 +40,7 @@ import java.io.IOException;
 import java.util.BitSet;
 
 /**
- * Bone animation updates each of its tracks with the skeleton and time
+ * <code>BoneAnimation</code> updates each of its tracks with the skeleton and time
  * to apply the animation.
  * 
  * @author Kirill Vainer
@@ -69,34 +69,38 @@ public final class BoneAnimation implements Savable {
     }
 
     /**
-     * Returns the animation name
-     * @return 
+     * The name of the bone animation
+     * @return name of the bone animation
      */
     public String getName(){
         return name;
     }
 
     /**
-     * returns the animation length (in seconds)
-     * @return 
+     * Returns the length in seconds of this animation
+     * 
+     * @return the length in seconds of this animation
      */
     public float getLength(){
         return length;
     }
 
     /**
-     * Sets the bone tracks to this bone animation
-     * @see BoneTrack
-     * @param tracks 
+     * Set the {@link BoneTrack}s to be used by this animation.
+     * <p>
+     * The array should be organized so that the appropriate BoneTrack can
+     * be retrieved based on a bone index. 
+     * 
+     * @param tracks The tracks to set.
      */
     public void setTracks(BoneTrack[] tracks){
         this.tracks = tracks;
     }
 
     /**
-     * returns the bone tracks of this animation
-     * @see BoneTrack
-     * @return 
+     * Returns the tracks set in {@link #setTracks(com.jme3.animation.BoneTrack[]) }.
+     * 
+     * @return the tracks set previously
      */
     public BoneTrack[] getTracks(){
         return tracks;

engine/src/core/com/jme3/animation/Skeleton.java

@@ -44,14 +44,17 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * A skeleton is a hierarchy of bones.
+ * <code>Skeleton</code> is a convenience class for managing a bone hierarchy.
  * Skeleton updates the world transforms to reflect the current local
  * animated matrixes.
+ * 
+ * @author Kirill Vainer
  */
 public final class Skeleton implements Savable {
 
     private Bone[] rootBones;
     private Bone[] boneList;
+    
     /**
      * Contains the skinning matrices, multiplying it by a vertex effected by a bone
      * will cause it to go to the animated position.
@@ -59,8 +62,13 @@ public final class Skeleton implements Savable {
     private transient Matrix4f[] skinningMatrixes;
 
     /**
-     * Creates a skeleton from a bone list. The root bone is found automatically.
-     * @param boneList
+     * Creates a skeleton from a bone list. 
+     * The root bones are found automatically.
+     * <p>
+     * Note that using this constructor will cause the bones in the list
+     * to have their bind pose recomputed based on their local transforms.
+     * 
+     * @param boneList The list of bones to manage by this Skeleton
      */
     public Skeleton(Bone[] boneList) {
         this.boneList = boneList;
@@ -84,9 +92,12 @@ public final class Skeleton implements Savable {
     }
 
     /**
-     * Copy constructor.
-     * Most of the skeleton data is deeply-copied except the bone bind and inverseBind transforms.
-     * @param source
+     * Special-purpose copy constructor.
+     * <p>
+     * Shallow copies bind pose data from the source skeleton, does not
+     * copy any other data.
+     * 
+     * @param source The source Skeleton to copy from
      */
     public Skeleton(Skeleton source) {
         Bone[] sourceList = source.boneList;
@@ -107,9 +118,7 @@ public final class Skeleton implements Savable {
     }
 
     /**
-     * Used for binary loading as a Savable; the object must be constructed,
-     * then the parameters usually present in the constructor for this class are
-     * restored from the file the object was saved to.
+     * Serialization only. Do not use.
      */
     public Skeleton() {
     }

engine/src/jbullet/com/jme3/bullet/control/KinematicRagdollControl.java

@@ -193,9 +193,9 @@ public class KinematicRagdollControl implements PhysicsControl, PhysicsCollision
                 if (link.bone.getParent() == null) {
 
                     //offsetting the physic's position/rotation by the root bone inverse model space position/rotaion
-                    modelPosition.set(p).subtractLocal(link.bone.getInitialPos());
+                    modelPosition.set(p).subtractLocal(link.bone.getWorldBindPosition());
                     targetModel.getParent().getWorldTransform().transformInverseVector(modelPosition, modelPosition);
-                    modelRotation.set(q).multLocal(tmpRot2.set(link.bone.getInitialRot()).inverseLocal());
+                    modelRotation.set(q).multLocal(tmpRot2.set(link.bone.getWorldBindRotation()).inverseLocal());
 
 
                     //applying transforms to the model