From c7a5dcf72de77747d210070b86acf45d78f24199 Mon Sep 17 00:00:00 2001 From: "sha..rd" Date: Wed, 15 Jun 2011 20:29:47 +0000 Subject: [PATCH] * 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 | 98 ++++++++++++++----- .../com/jme3/animation/BoneAnimation.java | 34 ++++--- .../src/core/com/jme3/animation/Skeleton.java | 27 +++-- .../control/KinematicRagdollControl.java | 4 +- 4 files changed, 111 insertions(+), 52 deletions(-) diff --git a/engine/src/core/com/jme3/animation/Bone.java b/engine/src/core/com/jme3/animation/Bone.java index 69f2ef7ae..fc8b4c536 100644 --- a/engine/src/core/com/jme3/animation/Bone.java +++ b/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. + *

+ * Only copies the name and bind pose from the original. + *

+ * 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. + *

+ * The rest of the data is NOT 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. + *

+ * 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. + *

+ * The bind pose transform of the bone is its "default" + * transform with no animation applied. * * @return the inverse world bind pose rotation. */ @@ -241,12 +255,51 @@ public final class Bone implements Savable { /** * Returns the inverse world bind pose scale. + *

+ * The bind pose transform of the bone is its "default" + * transform with no animation applied. * * @return the inverse world bind pose scale. */ public Vector3f getWorldBindInverseScale() { return worldBindInverseScale; } + + /** + * Returns the world bind pose position. + *

+ * 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. + *

+ * 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. + *

+ * 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. @@ -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. + *

+ * 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,15 +555,11 @@ 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); - } - + initialScale.set(scale); + localPos.set(translation); localRot.set(rotation); - if (scale != null) { - localScale.set(scale); - } + localScale.set(scale); } private String toString(int depth) { @@ -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; - } } diff --git a/engine/src/core/com/jme3/animation/BoneAnimation.java b/engine/src/core/com/jme3/animation/BoneAnimation.java index 6793ae4e4..966e26a62 100644 --- a/engine/src/core/com/jme3/animation/BoneAnimation.java +++ b/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 + * BoneAnimation updates each of its tracks with the skeleton and time * to apply the animation. * * @author Kirill Vainer @@ -69,36 +69,40 @@ 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() { + 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() { + 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. + *

+ * 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) { + 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() { + public BoneTrack[] getTracks(){ return tracks; } diff --git a/engine/src/core/com/jme3/animation/Skeleton.java b/engine/src/core/com/jme3/animation/Skeleton.java index 666a51543..88dca1329 100644 --- a/engine/src/core/com/jme3/animation/Skeleton.java +++ b/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. + * Skeleton 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. + *

+ * 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. + *

+ * 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() { } diff --git a/engine/src/jbullet/com/jme3/bullet/control/KinematicRagdollControl.java b/engine/src/jbullet/com/jme3/bullet/control/KinematicRagdollControl.java index 08809f3a2..a7dd9dd19 100644 --- a/engine/src/jbullet/com/jme3/bullet/control/KinematicRagdollControl.java +++ b/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