diff --git a/jme3-core/src/main/java/com/jme3/anim/AnimClip.java b/jme3-core/src/main/java/com/jme3/anim/AnimClip.java index 31cf5b1055..9758c2d718 100644 --- a/jme3-core/src/main/java/com/jme3/anim/AnimClip.java +++ b/jme3-core/src/main/java/com/jme3/anim/AnimClip.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2020 jMonkeyEngine + * Copyright (c) 2009-2021 jMonkeyEngine * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -38,6 +38,8 @@ import java.io.IOException; /** + * A named set of animation tracks that can be played in synchrony. + * * Created by Nehon on 20/12/2017. */ public class AnimClip implements JmeCloneable, Savable { @@ -47,13 +49,27 @@ public class AnimClip implements JmeCloneable, Savable { private AnimTrack[] tracks; + /** + * No-argument constructor needed by SavableClassUtil. + */ protected AnimClip() { } + /** + * Instantiate a zero-length clip with the specified name. + * + * @param name desired name for the new clip + */ public AnimClip(String name) { this.name = name; } + /** + * Replace all tracks in this clip. This method may increase the clip's + * length, but it will never reduce it. + * + * @param tracks the tracks to use (alias created) + */ public void setTracks(AnimTrack[] tracks) { this.tracks = tracks; for (AnimTrack track : tracks) { @@ -63,20 +79,38 @@ public void setTracks(AnimTrack[] tracks) { } } + /** + * Determine the name of this clip. + * + * @return the name + */ public String getName() { return name; } - + /** + * Determine the duration of this clip. + * + * @return the duration (in seconds) + */ public double getLength() { return length; } - + /** + * Access all the tracks in this clip. + * + * @return the pre-existing array + */ public AnimTrack[] getTracks() { return tracks; } + /** + * Create a shallow clone for the JME cloner. + * + * @return a new instance + */ @Override public Object jmeClone() { try { @@ -86,6 +120,15 @@ public Object jmeClone() { } } + /** + * Callback from {@link com.jme3.util.clone.Cloner} to convert this + * shallow-cloned clip into a deep-cloned one, using the specified Cloner + * and original to resolve copied fields. + * + * @param cloner the Cloner that's cloning this clip (not null) + * @param original the instance from which this clip was shallow-cloned (not + * null, unaffected) + */ @Override public void cloneFields(Cloner cloner, Object original) { AnimTrack[] newTracks = new AnimTrack[tracks.length]; @@ -95,11 +138,23 @@ public void cloneFields(Cloner cloner, Object original) { this.tracks = newTracks; } + /** + * Represent this clip as a String. + * + * @return a descriptive string of text (not null, not empty) + */ @Override public String toString() { return "Clip " + name + ", " + length + 's'; } + /** + * Serialize this clip to the specified exporter, for example when saving to + * a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { OutputCapsule oc = ex.getCapsule(this); @@ -108,6 +163,13 @@ public void write(JmeExporter ex) throws IOException { } + /** + * De-serialize this clip from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to read from (not null) + * @throws IOException from the importer + */ @Override public void read(JmeImporter im) throws IOException { InputCapsule ic = im.getCapsule(this); diff --git a/jme3-core/src/main/java/com/jme3/anim/AnimComposer.java b/jme3-core/src/main/java/com/jme3/anim/AnimComposer.java index 7c404e535b..c290f01073 100644 --- a/jme3-core/src/main/java/com/jme3/anim/AnimComposer.java +++ b/jme3-core/src/main/java/com/jme3/anim/AnimComposer.java @@ -65,6 +65,9 @@ public class AnimComposer extends AbstractControl { private float globalSpeed = 1f; private Map layers = new LinkedHashMap<>(); + /** + * Instantiate a composer with a single layer, no actions, and no clips. + */ public AnimComposer() { layers.put(DEFAULT_LAYER, new Layer(this)); } @@ -314,6 +317,12 @@ public Action removeAction(String name) { return actions.remove(name); } + /** + * Add a layer to this composer. + * + * @param name the desired name for the new layer + * @param mask the desired mask for the new layer (alias created) + */ public void makeLayer(String name, AnimationMask mask) { Layer l = new Layer(this); l.mask = mask; @@ -363,6 +372,9 @@ public BlendAction actionBlended(String name, BlendSpace blendSpace, String... c return action; } + /** + * Reset all layers to t=0 with no current action. + */ public void reset() { for (Layer layer : layers.values()) { layer.currentAction = null; @@ -391,6 +403,11 @@ public Set getAnimClipsNames() { return Collections.unmodifiableSet(animClipMap.keySet()); } + /** + * used internally + * + * @param tpf time per frame (in seconds) + */ @Override protected void controlUpdate(float tpf) { for (Layer layer : layers.values()) { @@ -410,19 +427,40 @@ protected void controlUpdate(float tpf) { } } + /** + * used internally + * + * @param rm the RenderManager rendering the controlled Spatial (not null) + * @param vp the ViewPort being rendered (not null) + */ @Override protected void controlRender(RenderManager rm, ViewPort vp) { } + /** + * Determine the global speed applied to all layers. + * + * @return the speed factor (1=normal speed) + */ public float getGlobalSpeed() { return globalSpeed; } + /** + * Alter the global speed applied to all layers. + * + * @param globalSpeed the desired speed factor (1=normal speed, default=1) + */ public void setGlobalSpeed(float globalSpeed) { this.globalSpeed = globalSpeed; } + /** + * Create a shallow clone for the JME cloner. + * + * @return a new instance + */ @Override public Object jmeClone() { try { @@ -433,6 +471,15 @@ public Object jmeClone() { } } + /** + * Callback from {@link com.jme3.util.clone.Cloner} to convert this + * shallow-cloned composer into a deep-cloned one, using the specified + * Cloner and original to resolve copied fields. + * + * @param cloner the Cloner that's cloning this composer (not null) + * @param original the instance from which this composer was shallow-cloned + * (not null, unaffected) + */ @Override public void cloneFields(Cloner cloner, Object original) { super.cloneFields(cloner, original); @@ -456,6 +503,13 @@ public void cloneFields(Cloner cloner, Object original) { } + /** + * De-serialize this composer from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to use (not null) + * @throws IOException from the importer + */ @Override @SuppressWarnings("unchecked") public void read(JmeImporter im) throws IOException { @@ -465,6 +519,13 @@ public void read(JmeImporter im) throws IOException { globalSpeed = ic.readFloat("globalSpeed", 1f); } + /** + * Serialize this composer to the specified exporter, for example when + * saving to a J3O file. + * + * @param ex the exporter to use (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { super.write(ex); diff --git a/jme3-core/src/main/java/com/jme3/anim/AnimTrack.java b/jme3-core/src/main/java/com/jme3/anim/AnimTrack.java index 45b54cf7f9..4c00902016 100644 --- a/jme3-core/src/main/java/com/jme3/anim/AnimTrack.java +++ b/jme3-core/src/main/java/com/jme3/anim/AnimTrack.java @@ -3,10 +3,25 @@ import com.jme3.export.Savable; import com.jme3.util.clone.JmeCloneable; +/** + * Interface to derive animation data from a track. + * + * @param the type of data that's being animated, such as Transform + */ public interface AnimTrack extends Savable, JmeCloneable { + /** + * Determine the track value for the specified time. + * + * @param time the track time (in seconds) + * @param store storage for the value (not null, modified) + */ public void getDataAtTime(double time, T store); - public double getLength(); - + /** + * Determine the duration of the track. + * + * @return the duration (in seconds, ≥0) + */ + public double getLength(); } diff --git a/jme3-core/src/main/java/com/jme3/anim/AnimationMask.java b/jme3-core/src/main/java/com/jme3/anim/AnimationMask.java index 80036776c3..2d6b775a4c 100644 --- a/jme3-core/src/main/java/com/jme3/anim/AnimationMask.java +++ b/jme3-core/src/main/java/com/jme3/anim/AnimationMask.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2020 jMonkeyEngine + * Copyright (c) 2009-2021 jMonkeyEngine * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -38,6 +38,12 @@ */ public interface AnimationMask { + /** + * Test whether the animation should applied to the specified element. + * + * @param target the target element + * @return true if animation should be applied, otherwise false + */ boolean contains(Object target); } diff --git a/jme3-core/src/main/java/com/jme3/anim/Armature.java b/jme3-core/src/main/java/com/jme3/anim/Armature.java index 8ae16cf485..807db3acae 100644 --- a/jme3-core/src/main/java/com/jme3/anim/Armature.java +++ b/jme3-core/src/main/java/com/jme3/anim/Armature.java @@ -145,6 +145,11 @@ public Joint[] getRoots() { return rootJoints; } + /** + * Access all joints in this Armature. + * + * @return a new list of pre-existing joints + */ public List getJointList() { return Arrays.asList(jointList); } @@ -290,7 +295,13 @@ public void cloneFields(Cloner cloner, Object original) { } } - + /** + * De-serialize this Armature from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to read from (not null) + * @throws IOException from the importer + */ @Override @SuppressWarnings("unchecked") public void read(JmeImporter im) throws IOException { @@ -324,6 +335,13 @@ public void read(JmeImporter im) throws IOException { applyInitialPose(); } + /** + * Serialize this Armature to the specified exporter, for example when + * saving to a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { OutputCapsule output = ex.getCapsule(this); diff --git a/jme3-core/src/main/java/com/jme3/anim/ArmatureMask.java b/jme3-core/src/main/java/com/jme3/anim/ArmatureMask.java index a7d5d32f09..3aa2342f28 100644 --- a/jme3-core/src/main/java/com/jme3/anim/ArmatureMask.java +++ b/jme3-core/src/main/java/com/jme3/anim/ArmatureMask.java @@ -2,6 +2,9 @@ import java.util.BitSet; +/** + * An AnimationMask to select joints from a single Armature. + */ public class ArmatureMask implements AnimationMask { final private BitSet affectedJoints = new BitSet(); @@ -62,12 +65,27 @@ public boolean contains(Object target) { return affectedJoints.get(((Joint) target).getId()); } + /** + * Create an ArmatureMask that selects the named Joint and all its + * descendants. + * + * @param armature the Armature containing the joints (not null) + * @param fromJoint the name of the ancestor joint + * @return a new mask + */ public static ArmatureMask createMask(Armature armature, String fromJoint) { ArmatureMask mask = new ArmatureMask(); mask.addFromJoint(armature, fromJoint); return mask; } + /** + * Create an ArmatureMask that selects the named joints. + * + * @param armature the Armature containing the joints (not null) + * @param joints the names of the joints to be included + * @return a new mask + */ public static ArmatureMask createMask(Armature armature, String... joints) { ArmatureMask mask = new ArmatureMask(); mask.addBones(armature, joints); diff --git a/jme3-core/src/main/java/com/jme3/anim/Joint.java b/jme3-core/src/main/java/com/jme3/anim/Joint.java index eefa4797f3..434931d337 100644 --- a/jme3-core/src/main/java/com/jme3/anim/Joint.java +++ b/jme3-core/src/main/java/com/jme3/anim/Joint.java @@ -88,10 +88,17 @@ public class Joint implements Savable, JmeCloneable, HasLocalTransform { */ private Matrix4f inverseModelBindMatrix = new Matrix4f(); - + /** + * Instantiate a nameless Joint. + */ public Joint() { } + /** + * Instantiate a Joint with the specified name. + * + * @param name the desired name + */ public Joint(String name) { this.name = name; } @@ -206,64 +213,139 @@ protected void applyInitialPose() { } } + /** + * Access the accumulated model transform. + * + * @return the pre-existing instance + */ protected JointModelTransform getJointModelTransform() { return jointModelTransform; } + /** + * Replace the accumulated model transform. + * + * @param jointModelTransform the transform to use (alias created) + */ protected void setJointModelTransform(JointModelTransform jointModelTransform) { this.jointModelTransform = jointModelTransform; } + /** + * Access the local translation vector. + * + * @return the pre-existing vector + */ public Vector3f getLocalTranslation() { return localTransform.getTranslation(); } + /** + * Access the local rotation. + * + * @return the pre-existing Quaternion + */ public Quaternion getLocalRotation() { return localTransform.getRotation(); } + /** + * Access the local scale vector. + * + * @return the pre-existing vector + */ public Vector3f getLocalScale() { return localTransform.getScale(); } + /** + * Alter the local translation vector. + * + * @param translation the desired offset vector (not null, unaffected) + */ public void setLocalTranslation(Vector3f translation) { localTransform.setTranslation(translation); } + /** + * Alter the local rotation. + * + * @param rotation the desired rotation (not null, unaffected) + */ public void setLocalRotation(Quaternion rotation) { localTransform.setRotation(rotation); } + /** + * Alter the local scale vector. + * + * @param scale the desired scale factors (not null, unaffected) + */ public void setLocalScale(Vector3f scale) { localTransform.setScale(scale); } + /** + * Add the specified Joint as a child. + * + * @param child the Joint to add (not null, modified) + */ public void addChild(Joint child) { children.add(child); child.parent = this; } + /** + * Alter the name. + * + * @param name the desired name + */ public void setName(String name) { this.name = name; } + /** + * Alter the local transform. + * + * @param localTransform the desired Transform (not null, unaffected) + */ @Override public void setLocalTransform(Transform localTransform) { this.localTransform.set(localTransform); } + /** + * Replace the inverse model bind matrix. + * + * @param inverseModelBindMatrix the matrix to use (alias created) + */ public void setInverseModelBindMatrix(Matrix4f inverseModelBindMatrix) { this.inverseModelBindMatrix = inverseModelBindMatrix; } + /** + * Determine the name. + * + * @return the name + */ public String getName() { return name; } + /** + * Access the parent joint. + * + * @return the pre-existing instance, or null if this is a root joint + */ public Joint getParent() { return parent; } + /** + * Access the list of child joints. + * + * @return the pre-existing list + */ public List getChildren() { return children; } @@ -300,31 +382,66 @@ Node getAttachmentsNode(int jointIndex, SafeArrayList targets) { return attachedNode; } + /** + * Access the initial transform. + * + * @return the pre-existing instance + */ public Transform getInitialTransform() { return initialTransform; } + /** + * Access the local transform. + * + * @return the pre-existing instance + */ @Override public Transform getLocalTransform() { return localTransform; } + /** + * Determine the model transform. + * + * @return a shared instance + */ public Transform getModelTransform() { return jointModelTransform.getModelTransform(); } + /** + * Determine the inverse model bind matrix. + * + * @return the pre-existing instance + */ public Matrix4f getInverseModelBindMatrix() { return inverseModelBindMatrix; } + /** + * Determine this joint's index in the Armature that contains it. + * + * @return an index (≥0) + */ public int getId() { return id; } + /** + * Alter this joint's index in the Armature that contains it. + * + * @param id the desired index (≥0) + */ public void setId(int id) { this.id = id; } + /** + * Create a shallow clone for the JME cloner. + * + * @return a new instance + */ @Override public Object jmeClone() { try { @@ -335,6 +452,15 @@ public Object jmeClone() { } } + /** + * Callback from {@link com.jme3.util.clone.Cloner} to convert this + * shallow-cloned Joint into a deep-cloned one, using the specified Cloner + * and original to resolve copied fields. + * + * @param cloner the Cloner that's cloning this Joint (not null) + * @param original the instance from which this Joint was shallow-cloned + * (not null, unaffected) + */ @Override public void cloneFields(Cloner cloner, Object original) { this.children = cloner.clone(children); @@ -346,7 +472,13 @@ public void cloneFields(Cloner cloner, Object original) { this.inverseModelBindMatrix = cloner.clone(inverseModelBindMatrix); } - + /** + * De-serialize this Joint from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to use (not null) + * @throws IOException from the importer + */ @Override @SuppressWarnings("unchecked") public void read(JmeImporter im) throws IOException { @@ -364,6 +496,13 @@ public void read(JmeImporter im) throws IOException { } } + /** + * Serialize this Joint to the specified exporter, for example when saving + * to a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override @SuppressWarnings("unchecked") public void write(JmeExporter ex) throws IOException { diff --git a/jme3-core/src/main/java/com/jme3/anim/MatrixJointModelTransform.java b/jme3-core/src/main/java/com/jme3/anim/MatrixJointModelTransform.java index acbb4a9a6b..a87fbc0f74 100644 --- a/jme3-core/src/main/java/com/jme3/anim/MatrixJointModelTransform.java +++ b/jme3-core/src/main/java/com/jme3/anim/MatrixJointModelTransform.java @@ -36,6 +36,11 @@ public void applyBindPose(Transform localTransform, Matrix4f inverseModelBindMat localTransform.fromTransformMatrix(modelTransformMatrix); } + /** + * Access the model transform. + * + * @return the pre-existing instance + */ public Matrix4f getModelTransformMatrix() { return modelTransformMatrix; } diff --git a/jme3-core/src/main/java/com/jme3/anim/MorphControl.java b/jme3-core/src/main/java/com/jme3/anim/MorphControl.java index 2299e29244..401f4172ba 100644 --- a/jme3-core/src/main/java/com/jme3/anim/MorphControl.java +++ b/jme3-core/src/main/java/com/jme3/anim/MorphControl.java @@ -353,10 +353,22 @@ private int getRemainingBuffers(Mesh mesh, Renderer renderer) { return renderer.getLimits().get(Limits.VertexAttributes) - nbUsedBuffers; } + /** + * Alter whether this Control approximates tangents. + * + * @param approximateTangents true to approximate tangents, false to get + * them from a VertexBuffer + */ public void setApproximateTangents(boolean approximateTangents) { this.approximateTangents = approximateTangents; } + /** + * Test whether this Control approximates tangents. + * + * @return true if approximating tangents, false if getting them from a + * VertexBuffer + */ public boolean isApproximateTangents() { return approximateTangents; } diff --git a/jme3-core/src/main/java/com/jme3/anim/MorphTrack.java b/jme3-core/src/main/java/com/jme3/anim/MorphTrack.java index 0cbeed7deb..adf1056e76 100644 --- a/jme3-core/src/main/java/com/jme3/anim/MorphTrack.java +++ b/jme3-core/src/main/java/com/jme3/anim/MorphTrack.java @@ -174,18 +174,40 @@ public void getDataAtTime(double t, float[] store) { interpolator.interpolateWeights(blend, startFrame, weights, nbMorphTargets, store); } + /** + * Replace the FrameInterpolator. + * + * @param interpolator the interpolator to use (alias created) + */ public void setFrameInterpolator(FrameInterpolator interpolator) { this.interpolator = interpolator; } + /** + * Access the target geometry. + * + * @return the pre-existing instance + */ public Geometry getTarget() { return target; } + /** + * Replace the target geometry. + * + * @param target the Geometry to use as the target (alias created) + */ public void setTarget(Geometry target) { this.target = target; } + /** + * Serialize this track to the specified exporter, for example when saving + * to a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { OutputCapsule oc = ex.getCapsule(this); @@ -195,6 +217,13 @@ public void write(JmeExporter ex) throws IOException { oc.write(nbMorphTargets, "nbMorphTargets", 0); } + /** + * De-serialize this track from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to use (not null) + * @throws IOException from the importer + */ @Override public void read(JmeImporter im) throws IOException { InputCapsule ic = im.getCapsule(this); diff --git a/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java b/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java index fd312a5d8f..3f2ad3e2a2 100644 --- a/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java +++ b/jme3-core/src/main/java/com/jme3/anim/SkinningControl.java @@ -701,6 +701,13 @@ private void applySkinningTangents(Mesh mesh, Matrix4f[] offsetMatrices, VertexB tb.updateData(ftb); } + /** + * Serialize this Control to the specified exporter, for example when saving + * to a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { super.write(ex); @@ -711,6 +718,13 @@ public void write(JmeExporter ex) throws IOException { oc.write(jointMatricesParam, "boneMatricesParam", null); } + /** + * De-serialize this Control from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to read from (not null) + * @throws IOException from the importer + */ @Override public void read(JmeImporter im) throws IOException { super.read(im); diff --git a/jme3-core/src/main/java/com/jme3/anim/TransformTrack.java b/jme3-core/src/main/java/com/jme3/anim/TransformTrack.java index c9830ef6b5..7df1b515a6 100644 --- a/jme3-core/src/main/java/com/jme3/anim/TransformTrack.java +++ b/jme3-core/src/main/java/com/jme3/anim/TransformTrack.java @@ -268,18 +268,41 @@ public void getDataAtTime(double t, Transform transform) { } } + /** + * Replace the frame interpolator. + * + * @param interpolator the interpolator to use (alias created) + */ public void setFrameInterpolator(FrameInterpolator interpolator) { this.interpolator = interpolator; } + /** + * Access the target affected by this track, which might be a Joint or a + * Spatial. + * + * @return the pre-existing instance + */ public HasLocalTransform getTarget() { return target; } + /** + * Replace the target of this track, which might be a Joint or a Spatial. + * + * @param target the target to use (alias created) + */ public void setTarget(HasLocalTransform target) { this.target = target; } + /** + * Serialize this track to the specified exporter, for example when + * saving to a J3O file. + * + * @param ex the exporter to write to (not null) + * @throws IOException from the exporter + */ @Override public void write(JmeExporter ex) throws IOException { OutputCapsule oc = ex.getCapsule(this); @@ -290,6 +313,13 @@ public void write(JmeExporter ex) throws IOException { oc.write(target, "target", null); } + /** + * De-serialize this track from the specified importer, for example when + * loading from a J3O file. + * + * @param im the importer to read from (not null) + * @throws IOException from the importer + */ @Override public void read(JmeImporter im) throws IOException { InputCapsule ic = im.getCapsule(this); diff --git a/jme3-core/src/main/java/com/jme3/anim/util/JointModelTransform.java b/jme3-core/src/main/java/com/jme3/anim/util/JointModelTransform.java index c73c033169..837c50ca2e 100644 --- a/jme3-core/src/main/java/com/jme3/anim/util/JointModelTransform.java +++ b/jme3-core/src/main/java/com/jme3/anim/util/JointModelTransform.java @@ -10,11 +10,37 @@ */ public interface JointModelTransform { + /** + * Update the joint's transform in model space. + * + * @param localTransform the joint's local transform (not null, unaffected) + * @param parent the joint's parent, or null for a root joint + */ void updateModelTransform(Transform localTransform, Joint parent); + /** + * Determine the joint's skinning transform. + * + * @param outTransform storage for the result (modified if not null) + * @param inverseModelBindMatrix the joint's inverse model bind matrix (not + * null, unaffected) + */ void getOffsetTransform(Matrix4f outTransform, Matrix4f inverseModelBindMatrix); + /** + * Configure joint's local transform for bind pose. + * + * @param localTransform the joint's local transform (not null, unaffected) + * @param inverseModelBindMatrix the joint's inverse model bind matrix (not + * null, unaffected) + * @param parent the joint's parent, or null for a root joint + */ void applyBindPose(Transform localTransform, Matrix4f inverseModelBindMatrix, Joint parent); + /** + * Determine the joint's transform in model space. + * + * @return a new instance or a pre-existing one + */ Transform getModelTransform(); }