Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

com.jme3.anim.tween.action.BlendSpace: basic javadoc #2022

Open
wants to merge 19 commits into
base: master
Choose a base branch
from
Open
Changes from 9 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
be87dee
com.jme3.anim.tween.action.BlendSpace: basic javadoc
pavly-gerges May 27, 2023
4a5100d
class-entry-javadoc: documentation of different cases of blending-wei…
pavly-gerges May 28, 2023
c90cd78
class-entry-javadoc: inlined value domain with the value at 'Blending…
pavly-gerges May 28, 2023
7c5e36c
BlendSpace#getWeight(): extra clarification of the transformations word
pavly-gerges May 28, 2023
8ca8d9d
class-entry-javadoc: added reference for more
pavly-gerges May 28, 2023
d4570dc
class-entry-javadoc: added zero and negative case scenarios
pavly-gerges May 28, 2023
433bf5d
class-entry-javadoc: restricts blend weight values to [0, 1]
pavly-gerges May 29, 2023
a8602f8
BlendSpace: better documentation formatting
pavly-gerges May 29, 2023
bbd041c
class-entry-javadoc: more clarifications on the 'blending' definition
pavly-gerges May 29, 2023
a3603f2
class-entry-javadoc: removed irrelevant IllegalArgumentException docu…
pavly-gerges May 29, 2023
dd1dbac
Strict blend weight range
pavly-gerges May 29, 2023
bffb6a9
BlendSpace#getWeight(): sentence typos
pavly-gerges May 29, 2023
6c8a00f
BlendSpace#setBlendAction(...): javadoc mark the argument as not-null
pavly-gerges May 30, 2023
95f815b
BlendSpace#getWeight(): moved the blend weight range to the return ta…
pavly-gerges May 31, 2023
637275f
BlendSpace#getWeight(): explicitly saying "negative values and values…
pavly-gerges May 31, 2023
bf37824
BlendSpace.java: updated copyright to 2024
pavly-gerges Jan 22, 2024
9bc1eda
Class-JavaDoc: better explanation of the interface purpose
pavly-gerges Jan 24, 2024
ab466ac
Class-JavaDoc: denoted that extrapolations are disabled in a blending…
pavly-gerges Jan 24, 2024
7a18af3
Update BlendSpace.java
pavly-gerges Jan 24, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions jme3-core/src/main/java/com/jme3/anim/tween/action/BlendSpace.java
Original file line number Diff line number Diff line change
@@ -1,10 +1,84 @@
/*
* 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;

/**
* Controls the blending between 2 successive actions in a {@link BlendAction} by adjusting blending weight value
* {@link BlendSpace#getWeight()} during application runtime based on an arbitrary value {@link BlendSpace#setValue(float)}.
*
* <p>
* Notes:
* <li> Blending is the action of mixing between 2 successive animation {@link BlendableAction}s by interpolating their transforms and
* then applying the result on the assigned {@link HasLocalTransform} object, the {@link BlendSpace} provides this blending action with a blend weight value. </li>
* <li> The blend weight is the value for the interpolation for the target transforms. </li>
* <li> The blend weight value should lie in this interval [0, 1]. </li>
* </p>
*
* <p>
* Different blending weight case scenarios managed by {@link BlendAction} internally:
* <li> In case of (0 < Blending weight < 1), the blending is executed each update among 2 actions, the first action will use
* a blend value of 1 and the second action will use the blend space weight as a value for the interpolation. </li>
* <li> In case of (Blending weight = 0), the blending hasn't started yet, only the first action will be interpolated at (weight = 1). </li>
* <li> In case of (Blending weight = 1), the blending is finished and only the second action will continue to run at (weight = 1). </li>
pavly-gerges marked this conversation as resolved.
Show resolved Hide resolved
* <li> Negative values and values greater than 1 aren't allowed and will result in an IllegalArgumentException. </li>
pavly-gerges marked this conversation as resolved.
Show resolved Hide resolved
* <li> Find more at {@link BlendAction#doInterpolate(double)} and {@link BlendAction#collectTransform(HasLocalTransform, Transform, float, BlendableAction)}. </li>
* </p>
*
* Created by Nehon.
* @see LinearBlendSpace an example of blendspace implementation
*/
public interface BlendSpace {

/**
* Adjusts the target blend action instance that will utilize the blend weight value provided by this blend-space implementation.
*
* @param action the blend action instance that will utilize this blend-space.
*/
public void setBlendAction(BlendAction action);

/**
* Provides the blend weight value to the assigned {@link BlendAction} instance,
* this value will be used for interpolating a collection of actions' transformations (keyframes).
*
* @return the blending weight value.
pavly-gerges marked this conversation as resolved.
Show resolved Hide resolved
* @see LinearBlendSpace#getWeight()
*/
public float getWeight();

/**
* An arbitrary value used for adjusting the blending weight value.
*
* @param value the value in floats.
* @see LinearBlendSpace#setValue(float)
*/
public void setValue(float value);
}