From 972bb4dc7a2d6874c86f23125d4c665a0959046d Mon Sep 17 00:00:00 2001 From: pavl_g Date: Tue, 30 May 2023 15:18:46 +0300 Subject: [PATCH 1/2] com.jme3.anim.tween.action.BlendableAction: basic javadoc --- .../anim/tween/action/BlendableAction.java | 62 +++++++++++++++++-- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java b/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java index c9882529f9..ad65988a65 100644 --- a/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java +++ b/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2022 jMonkeyEngine + * Copyright (c) 2009-2023 jMonkeyEngine * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -38,6 +38,20 @@ import com.jme3.util.clone.Cloner; import java.util.Collection; +/** + * An implementation of the Action interface that manages the interpolation code + * using the action length (duration) and time per frames in seconds. + * + * + * To implement this interface, override the methods : + *
  • {@link BlendableAction#doInterpolate(double)} and place your interpolation management code.
    • + *
  • {@link BlendableAction#collectTransform(HasLocalTransform, Transform, float, BlendableAction)} and place your interpolation code based on the #{@link BlendableAction#weight}.
    • + *
  • {@link BlendableAction#getTargets()} and place the code to get target objects subjected to interpolation.
    • + * + * Created by Nehon. + * @see ClipAction + * @see BlendAction + */ public abstract class BlendableAction extends Action { protected BlendableAction collectTransformDelegate; @@ -46,11 +60,24 @@ public abstract class BlendableAction extends Action { private double transitionLength = 0.4f; private float weight = 1f; private TransitionTween transition = new TransitionTween(transitionLength); - + + /** + * Callback to the constructor of the super class to assign actions to {@link Action#actions} to be interpolated. + * + * @param tweens actions in raw tween {@link AbstractTween} and its descendants( ex : {@link com.jme3.anim.tween.Tweens#parallel(Tween...)}, + * or an array of {@link Action} and its descendants(ex : {@link ClipAction} and {@link BaseAction}. + * @see Action#Action(Tween...) + */ public BlendableAction(Tween... tweens) { super(tweens); } + /** + * Delegates the interpolation to a specific instance of type {@link BlendableAction} based on its weight attribute. + * This instance will be the source of the animation transition weight. + * + * @param delegate the + */ public void setCollectTransformDelegate(BlendableAction delegate) { this.collectTransformDelegate = delegate; } @@ -61,12 +88,13 @@ public boolean interpolate(double t) { if (t < 0) { return true; } - + + // if the interpolation isn't delegated to a subclass instance, then calculate the transitionWeight from here. if (collectTransformDelegate == null) { if (transition.getLength() > getLength()) { transition.setLength(getLength()); } - if(isForward()) { + if (isForward()) { transition.interpolate(t); } else { float v = Math.max((float)(getLength() - t), 0f); @@ -93,11 +121,32 @@ public float getWeight() { public void setWeight(float weight) { this.weight = weight; } - + + /** + * Override this method and manage the interpolation code inside. + * Called by {@link BlendableAction#interpolate(double)}, after clamping time(t) to a ratio between (0) + * and (1) based on the action length. + * + * @param t the current time of frames. + */ protected abstract void doInterpolate(double t); + /** + * Override this method and collect the target objects for this action that the interpolation will be applied on them. + * + * @return the current involved targets. + */ public abstract Collection getTargets(); + /** + * Override this method and interpolate collected transforms based on the custom weight {@link BlendableAction#weight} from a delegated source. + * This method is dispatched by delegating from another BlendableActions sources using {@link BlendableAction#setCollectTransformDelegate(BlendableAction)}. + * + * @param target the target involved for interpolation. + * @param t the transform to be used in interpolation. + * @param weight the scale factor(delta) used for interpolation. + * @param source the source of the method call(Source of delegation). + */ public abstract void collectTransform(HasLocalTransform target, Transform t, float weight, BlendableAction source); public double getTransitionLength() { @@ -126,8 +175,9 @@ public void setMaxTransitionWeight(double maxTransitionWeight) { } /** + * Retrieves the maximum weight at which the transition can occur. * - * @return The max transition weight (default=1) + * @return the max transition weight (default=1) */ public double getMaxTransitionWeight() { return maxTransitionWeight; From e7a20e546467518c1a24e89fef8584e1198ccaaf Mon Sep 17 00:00:00 2001 From: pavl_g <60224159+Scrappers-glitch@users.noreply.github.com> Date: Sun, 28 Jan 2024 22:25:53 +0300 Subject: [PATCH 2/2] BlendableAction.java: updated copyright * Updated copyright date to 2024. --- .../main/java/com/jme3/anim/tween/action/BlendableAction.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java b/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java index ad65988a65..ee2f720c8c 100644 --- a/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java +++ b/jme3-core/src/main/java/com/jme3/anim/tween/action/BlendableAction.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2009-2023 jMonkeyEngine + * Copyright (c) 2009-2024 jMonkeyEngine * All rights reserved. * * Redistribution and use in source and binary forms, with or without