diff --git a/jme3-core/src/main/java/com/jme3/anim/tween/action/Action.java b/jme3-core/src/main/java/com/jme3/anim/tween/action/Action.java index 0fb423f336..344a69b216 100644 --- a/jme3-core/src/main/java/com/jme3/anim/tween/action/Action.java +++ b/jme3-core/src/main/java/com/jme3/anim/tween/action/Action.java @@ -1,3 +1,34 @@ +/* + * Copyright (c) 2009-2023 jMonkeyEngine + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * * Neither the name of 'jMonkeyEngine' nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ package com.jme3.anim.tween.action; import com.jme3.anim.AnimationMask; @@ -5,14 +36,43 @@ import com.jme3.util.clone.Cloner; import com.jme3.util.clone.JmeCloneable; +/** + * Wraps an array of Tween actions into an action object. + * + *

+ * Notes : + *

  • The sequence of tweens is determined by {@link com.jme3.anim.tween.Tweens} utility class and the {@link BaseAction} interpolates that sequence.
    • + *
  • This implementation mimics the {@link com.jme3.anim.tween.AbstractTween}, but it delegates the interpolation method {@link Tween#interpolate(double)} + * to the {@link BlendableAction} class.
    • + *

    + * + * Created by Nehon. + * + * @see BlendableAction + * @see BaseAction + */ public abstract class Action implements JmeCloneable, Tween { - + + /** + * A sequence of actions which wraps given tween actions. + */ protected Action[] actions; private double length; private double speed = 1; private AnimationMask mask; private boolean forward = true; - + + /** + * Instantiates an action object that wraps a tween actions array by extracting their actions to the collection {@link Action#actions}. + *

    + * Notes : + *

  • If intentions are to wrap some tween actions, then subclasses have to call this constructor, examples : {@link BlendableAction} and {@link BlendAction}.
    • + *
  • If intentions are to make an implementation of {@link Action} that shouldn't wrap tweens of actions, then subclasses shouldn't call this + * constructor, examples : {@link ClipAction} and {@link BaseAction}.
    • + *

    + * + * @param tweens the tween actions to be wrapped (not null). + */ protected Action(Tween... tweens) { this.actions = new Action[tweens.length]; for (int i = 0; i < tweens.length; i++) { @@ -24,14 +84,19 @@ protected Action(Tween... tweens) { } } } - + + /** + * Retrieves the length (the duration) of the current action. + * + * @return the length of the action in seconds. + */ @Override public double getLength() { return length; } /** - * Alter the length (duration) of this Action. This can be used to extend + * Alters the length (duration) of this Action. This can be used to extend * or truncate an Action. * * @param length the desired length (in unscaled seconds, default=0) @@ -40,44 +105,66 @@ public void setLength(double length) { this.length = length; } + /** + * Retrieves the speedup factor applied by the layer for this action. + * + * @see Action#setSpeed(double) for detailed documentation + * @return the speed of frames. + */ public double getSpeed() { return speed; } + /** + * Alters the speedup factor applied by the layer running this action. + *

    + * Notes: + *

  • This factor controls the animation direction, if the speed is a positive value then the animation will run forward and vice versa.
    • + *
  • The speed factor gets applied, inside the {@link com.jme3.anim.AnimLayer}, on each interpolation step by this formula : time += tpf * action.getSpeed() * composer.globalSpeed.
    • + *
  • Default speed is 1.0, it plays the animation clips at their normal speed.
    • + *
  • Setting the speed factor to Zero will stop the animation, while setting it to a negative number will play the animation in a backward fashion.
    • + *

    + * + * @param speed the speed of frames. + */ public void setSpeed(double speed) { this.speed = speed; - if( speed < 0){ + if (speed < 0) { setForward(false); } else { setForward(true); } } + /** + * Retrieves the animation mask for this action. + * The animation mask controls which part of the model would be animated. A model part can be + * registered using a {@link com.jme3.anim.Joint}. + * + * @return the animation mask instance, or null if this action will animate the entire model + * @see com.jme3.anim.AnimLayer to adjust the animation mask to control which part will be animated + */ public AnimationMask getMask() { return mask; } + /** + * Meant for internal use only. + * + *

    + * Note: This method can be invoked from the user code only if this Action is wrapped by a {@link BaseAction} and + * the {@link BaseAction#isMaskPropagationEnabled()} is false. + *

    + * + * @param mask an animation mask to be applied to this action. + * @see com.jme3.anim.AnimLayer to adjust the animation mask to control which part will be animated + */ public void setMask(AnimationMask mask) { this.mask = mask; } - protected boolean isForward() { - return forward; - } - - protected void setForward(boolean forward) { - if(this.forward == forward){ - return; - } - this.forward = forward; - for (Action action : actions) { - action.setForward(forward); - } - - } - /** - * Create a shallow clone for the JME cloner. + * Creates a shallow clone for the JME cloner. * * @return a new action (not null) */ @@ -105,4 +192,29 @@ public void cloneFields(Cloner cloner, Object original) { actions = cloner.clone(actions); mask = cloner.clone(mask); } + + /** + * Tests whether the Action is running in the "forward" mode. + * + * @return true if the animation action is running forward, false otherwise. + */ + protected boolean isForward() { + return forward; + } + + /** + * Adjusts the forward flag which controls the animation action directionality. + * + * @param forward true to run the animation forward, false otherwise. + * @see Action#setSpeed(double) to change the directionality of the tween actions, negative numbers play the animation in a backward fashion + */ + protected void setForward(boolean forward) { + if (this.forward == forward) { + return; + } + this.forward = forward; + for (Action action : actions) { + action.setForward(forward); + } + } }