Skip to content

Commit

Permalink
improve the TransformTrack javadoc (#1642)
Browse files Browse the repository at this point in the history 
* TransformTrack:  don't imply that the target must be a bone

* TransformTrack:  don't imply that the track must be a joint track

* TransformTrack:  delete mentions of "this track" from the javadoc

* TransformTrack:  do getters return internal arrays or copies?

* TransformTrack:  consistent verb forms and better grammar in javadoc

* TransformTrack:  no need to mention that "times" is a float array

* TransformTrack:  mention that setTimes() creates an alias

* TransformTrack:  document arguments that can be null

* TransformTrack:  clearer descriptions of the class and its fields

* "frame" -> "keyframe", in case it's unclear they're the same thing

* document where argument length must be the same as times.length

* TransformTrack:  summary fragments shouldn't form a complete sentence

* TransformTrack:  capitalize and punctuate the summary fragments

* TransformTrack:  indent block-tag continuation lines
  • Loading branch information
@stephengold
stephengold authored Nov 14, 2021
1 parent 3ccc518 commit dc91668
Showing 1 changed file with 48 additions and 35 deletions.
83 changes: 48 additions & 35 deletions jme3-core/src/main/java/com/jme3/anim/TransformTrack.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,22 +42,23 @@
import java.io.IOException;

/**
* Contains a list of transforms and times for each keyframe.
* An AnimTrack that transforms a Joint or Spatial
* using a list of transforms and times for keyframes.
*
* @author Rémy Bouquet
*/
public class TransformTrack implements AnimTrack<Transform> {

private double length;
private FrameInterpolator interpolator = FrameInterpolator.DEFAULT;
private HasLocalTransform target;

/**
* Transforms and times for track.
* Transforms and times for keyframes.
*/
private CompactVector3Array translations;
private CompactQuaternionArray rotations;
private CompactVector3Array scales;
private FrameInterpolator interpolator = FrameInterpolator.DEFAULT;
private float[] times;

/**
Expand All @@ -67,39 +68,42 @@ protected TransformTrack() {
}

/**
* Creates a transform track for the given bone index
* Creates a transform track for the given target.
*
* @param target the target Joint or Spatial of the new track
* @param times a float array with the time of each frame
* @param translations the translation of the bone for each frame
* @param rotations the rotation of the bone for each frame
* @param scales the scale of the bone for each frame
* @param times the time for each keyframe, or null for none
* @param translations the translation of the target for each keyframe
* (same length as times) or null for no translation
* @param rotations the rotation of the target for each keyframe
* (same length as times) or null for no rotation
* @param scales the scale of the target for each keyframe
* (same length as times) or null for no scaling
*/
public TransformTrack(HasLocalTransform target, float[] times, Vector3f[] translations, Quaternion[] rotations, Vector3f[] scales) {
this.target = target;
this.setKeyframes(times, translations, rotations, scales);
}

/**
* return the array of rotations of this track
* Copies the rotations.
*
* @return an array, or null if no rotations
* @return a new array, or null if no rotations
*/
public Quaternion[] getRotations() {
return rotations == null ? null : rotations.toObjectArray();
}

/**
* returns the array of scales for this track
* Copies the scales.
*
* @return an array or null
* @return a new array, or null if no scales
*/
public Vector3f[] getScales() {
return scales == null ? null : scales.toObjectArray();
}

/**
* returns the arrays of time for this track
* Gives access to the keyframe times.
*
* @return the pre-existing array
*/
Expand All @@ -108,19 +112,19 @@ public float[] getTimes() {
}

/**
* returns the array of translations of this track
* Copies the translations.
*
* @return an array, or null if no translations
* @return a new array, or null if no translations
*/
public Vector3f[] getTranslations() {
return translations == null ? null : translations.toObjectArray();
}


/**
* Sets the keyframes times for this Joint track
* Sets the keyframe times.
*
* @param times the keyframes times
* @param times the desired keyframe times (alias created, not null, not empty)
*/
public void setTimes(float[] times) {
if (times == null || times.length == 0) {
Expand All @@ -132,9 +136,10 @@ public void setTimes(float[] times) {
}

/**
* Set the translations for this joint track
* Sets the translations.
*
* @param translations the translation of the bone for each frame
* @param translations the desired translation of the target for each
* keyframe (not null, same length as "times")
*/
public void setKeyframesTranslation(Vector3f[] translations) {
if (times == null) {
Expand All @@ -154,9 +159,10 @@ public void setKeyframesTranslation(Vector3f[] translations) {
}

/**
* Set the scales for this joint track
* Sets the scales.
*
* @param scales the scales of the bone for each frame
* @param scales the desired scale of the target for each keyframe (not
* null, same length as "times")
*/
public void setKeyframesScale(Vector3f[] scales) {
if (times == null) {
Expand All @@ -176,9 +182,10 @@ public void setKeyframesScale(Vector3f[] scales) {
}

/**
* Set the rotations for this joint track
* Sets the rotations.
*
* @param rotations the rotations of the bone for each frame
* @param rotations the desired rotation of the target for each keyframe
* (not null, same length as "times")
*/
public void setKeyframesRotation(Quaternion[] rotations) {
if (times == null) {
Expand All @@ -199,12 +206,19 @@ public void setKeyframesRotation(Quaternion[] rotations) {


/**
* Set the translations, rotations and scales for this bone track
* Sets the translations, rotations, and/or scales.
*
* @param times a float array with the time of each frame
* @param translations the translation of the bone for each frame
* @param rotations the rotation of the bone for each frame
* @param scales the scale of the bone for each frame
* @param times the desired time for each keyframe,
* or null to leave the times unchanged
* @param translations the desired translation of the target for each
* keyframe (same length as times)
* or null to leave the translations unchanged
* @param rotations the desired rotation of the target for each keyframe
* (same length as times)
* or null to leave the rotations unchanged
* @param scales the desired scale of the target for each keyframe
* (same length as times)
* or null to leave the scales unchanged
*/
public void setKeyframes(float[] times, Vector3f[] translations, Quaternion[] rotations, Vector3f[] scales) {
if (times != null) {
Expand Down Expand Up @@ -248,7 +262,7 @@ public void getDataAtTime(double t, Transform transform) {
int endFrame = 1;
float blend = 0;
if (time >= times[lastFrame]) {
// extrapolate beyond the final frame of the animation
// extrapolate beyond the final keyframe of the animation
startFrame = lastFrame;

float inferredInterval = times[lastFrame] - times[lastFrame - 1];
Expand Down Expand Up @@ -281,7 +295,7 @@ public void getDataAtTime(double t, Transform transform) {
}

/**
* Replace the frame interpolator.
* Replaces the frame interpolator.
*
* @param interpolator the interpolator to use (alias created)
*/
Expand All @@ -290,8 +304,7 @@ public void setFrameInterpolator(FrameInterpolator interpolator) {
}

/**
* Access the target affected by this track, which might be a Joint or a
* Spatial.
* Gives access to the target, which might be a Joint or a Spatial.
*
* @return the pre-existing instance
*/
Expand All @@ -300,7 +313,7 @@ public HasLocalTransform getTarget() {
}

/**
* Replace the target of this track, which might be a Joint or a Spatial.
* Replaces the target, which might be a Joint or a Spatial.
*
* @param target the target to use (alias created)
*/
Expand All @@ -309,7 +322,7 @@ public void setTarget(HasLocalTransform target) {
}

/**
* Serialize this track to the specified exporter, for example when
* Serializes this track to the specified exporter, for example when
* saving to a J3O file.
*
* @param ex the exporter to write to (not null)
Expand All @@ -326,7 +339,7 @@ public void write(JmeExporter ex) throws IOException {
}

/**
* De-serialize this track from the specified importer, for example when
* De-serializes this track from the specified importer, for example when
* loading from a J3O file.
*
* @param im the importer to read from (not null)
Expand Down

0 comments on commit dc91668

Please sign in to comment.