Package com.google.ar.sceneform.animation

Class ModelAnimation

java.lang.Object

com.google.ar.sceneform.animation.ModelAnimation

public class ModelAnimation
extends java.lang.Object

An ModelAnimation is a reusable set of keyframe tracks which represent an animation.

This class provides support for animating time positions on a targeted AnimatableModel

Here are some use cases for animations :

• On a very basic 3D model like a single infinite rotating sphere, you should not have to use this class but probably instead just call AnimatableModel#animate()
• For a synchronised animation set like animating a cube and a sphere position and rotation at same time or sequentially, please consider using an AnimatorSet playing a ModelAnimator.ofAnimation(AnimatableModel, String...) or ModelAnimator.ofPropertyValuesHolder(AnimatableModel, android.animation.PropertyValuesHolder...)
• If the mesh is a character, for example, there may be one ModelAnimation for a walkcycle, a second for a jump, a third for sidestepping and so on.
  Assuming a character object has a skeleton, one keyframe track could store the data for the position changes of the lower arm bone over time, a different track the data for the rotation changes of the same bone, a third the track position, rotation or scaling of another bone, and so on. It should be clear, that an ModelAnimation can act on lots of such tracks.
  Assuming the model has morph targets (for example one morph target showing a friendly face and another showing an angry face), each track holds the information as to how the influence of a certain morph target changes during the performance of the clip. In this case you should manage one ObjectAnimator coming from ModelAnimator.ofAnimation(AnimatableModel, ModelAnimation...) per action. And an AnimatorSet to play them sequentially or together.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ModelAnimation.PropertyValuesHolder	This class holds information about a property and the values that that property should take during an animation.

Field Summary

Fields

Modifier and Type	Field	Description
static android.util.Property<ModelAnimation,java.lang.Float>	FRACTION_POSITION	A Property wrapper around the fractionPosition functionality handled by the setFractionPosition(float) and getFractionPosition() methods
static android.util.Property<ModelAnimation,java.lang.Integer>	FRAME_POSITION	A Property wrapper around the framePosition functionality handled by the setFramePosition(int) and getFramePosition() methods
static android.util.FloatProperty<ModelAnimation>	TIME_POSITION	A Property wrapper around the timePosition functionality handled by the setTimePosition(float) and getTimePosition() methods.

Constructor Summary

Constructors

Constructor	Description
ModelAnimation(AnimatableModel model, java.lang.String name, int index, float duration, int frameRate)	ModelAnimation constructed from an Animator

Method Summary

Modifier and Type	Method	Description
static float	fractionToTime(float fraction, float duration)	Get the elapsed time in seconds of a fraction position
static float	frameToTime(int frame, int frameRate)	Get the elapsed time in seconds of a frame position
int	geIndex()	Returns The Zero-based index of the target animation as defined in the original AnimatableModel
float	getDuration()	Returns the duration of this animation in seconds.
long	getDurationMillis()	Returns the duration of this animation in milliseconds.
float	getFractionAtTime(float time)	Get the fraction position at the elapsed time in seconds.
float	getFractionPosition()	Get the fractional value at the current animation position.
int	getFrameAtTime(float time)	Get the frame position at the elapsed time in seconds.
int	getFrameCount()	Returns the total number of frames of this animation.
int	getFramePosition()	Get the current frame number at the current animation position.
int	getFrameRate()	Get the frames per second originally defined in the Animatable.
java.lang.String	getName()	Get the name of the animation
float	getTimeAtFraction(float fraction)	Get the elapsed time in seconds of a fraction position
float	getTimeAtFrame(int frame)	Get the elapsed time in seconds of a frame position
float	getTimePosition()	Get the current time position in seconds at the current animation position.
boolean	isDirty()	Internal usage for applying changes according to rendering update hierarchy.
static long	secondsToMillis(float time)	Convert time in seconds to time in millis
void	setDirty(boolean isDirty)	Set the state of this object properties to changed.
void	setFractionPosition(float fractionPosition)	Sets the current position of (seeks) the animation to the specified fraction position.
void	setFramePosition(int frameNumber)	Sets the current position of (seeks) the animation to the specified frame number according to the getFrameRate().
void	setTimePosition(float timePosition)	Sets the current position of (seeks) the animation to the specified time position in seconds.
static float	timeToFraction(float time, float duration)	Get the fraction position at the elapsed time in seconds.
static int	timeToFrame(float time, int frameRate)	Get the frame position at the elapsed time in seconds.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TIME_POSITION

public static final android.util.FloatProperty<ModelAnimation> TIME_POSITION

A Property wrapper around the timePosition functionality handled by the setTimePosition(float) and getTimePosition() methods.

FRAME_POSITION

public static final android.util.Property<ModelAnimation,java.lang.Integer> FRAME_POSITION

A Property wrapper around the framePosition functionality handled by the setFramePosition(int) and getFramePosition() methods

FRACTION_POSITION

public static final android.util.Property<ModelAnimation,java.lang.Float> FRACTION_POSITION

A Property wrapper around the fractionPosition functionality handled by the setFractionPosition(float) and getFractionPosition() methods

Constructor Detail

ModelAnimation

public ModelAnimation(AnimatableModel model,
                      java.lang.String name,
                      int index,
                      float duration,
                      int frameRate)

ModelAnimation constructed from an Animator

Parameters:

name - This name should corresponds to the one defined and exported in the AnimatableModel.
Typically the action name defined in the 3D creation software.

index - Zero-based index of the target animation as defined in the original AnimatableModel

duration - This original AnimatableModel duration

frameRate - The frames per second defined in the original animation asset

Method Detail

geIndex

public int geIndex()

Returns The Zero-based index of the target animation as defined in the original AnimatableModel

getName

public java.lang.String getName()

Get the name of the animation

This name corresponds to the one defined and exported in the AnimatableModel.
Typically the Action names defined in the 3D creation software.

Returns:

Weak reference to the string name of the animation, or the String.valueOf(animation.getIndex())> if none was specified.

getDuration

public float getDuration()

Returns the duration of this animation in seconds.

getDurationMillis

public long getDurationMillis()

Returns the duration of this animation in milliseconds.

getFrameRate

public int getFrameRate()

Get the frames per second originally defined in the Animatable.

Returns:

The number of frames refresh during one second

getFrameCount

public int getFrameCount()

Returns the total number of frames of this animation.

getTimePosition

public float getTimePosition()

Get the current time position in seconds at the current animation position.

Returns:

timePosition Elapsed time of interest in seconds. Between 0 and getDuration()

See Also:

getDuration()

setTimePosition

public void setTimePosition(float timePosition)

Sets the current position of (seeks) the animation to the specified time position in seconds.

This method will apply rotation, translation, and scale to the AnimatableModel that have been targeted.

Parameters:

timePosition - Elapsed time of interest in seconds. Between 0 and getDuration()

See Also:

getDuration()

getFramePosition

public int getFramePosition()

Get the current frame number at the current animation position.

Returns:

Frame number on the timeline. Between 0 and getFrameCount()

See Also:

getTimePosition(), getFrameCount()

setFramePosition

public void setFramePosition(int frameNumber)

Sets the current position of (seeks) the animation to the specified frame number according to the getFrameRate().

Parameters:

frameNumber - Frame number in the timeline. Between 0 and getFrameCount()

See Also:

setTimePosition(float), getFrameCount()

getFractionPosition

public float getFractionPosition()

Get the fractional value at the current animation position.

Returns:

The fractional (percent) position. Between 0 and 1

See Also:

getTimePosition()

setFractionPosition

public void setFractionPosition(float fractionPosition)

Sets the current position of (seeks) the animation to the specified fraction position.

Parameters:

fractionPosition - The fractional (percent) position. Between 0 and 1.

See Also:

setTimePosition(float)

isDirty

public boolean isDirty()

Internal usage for applying changes according to rendering update hierarchy.
Time position must be applied inside a global Choreographer frame callback to ensure that the transformations are applied in a hierarchical order.

Returns:

true if changes has been made

setDirty

public void setDirty(boolean isDirty)

Set the state of this object properties to changed. And tell the AnimatableModel to take care of it.

getTimeAtFrame

public float getTimeAtFrame(int frame)

Get the elapsed time in seconds of a frame position

Parameters:

frame - Frame number on the timeline

Returns:

Elapsed time of interest in seconds

getFrameAtTime

public int getFrameAtTime(float time)

Get the frame position at the elapsed time in seconds.

Parameters:

time - Elapsed time of interest in seconds

Returns:

The frame number at the specified time

getTimeAtFraction

public float getTimeAtFraction(float fraction)

Get the elapsed time in seconds of a fraction position

Parameters:

fraction - The fractional (from 0 to 1) value of interest

Returns:

Elapsed time at the specified fraction

getFractionAtTime

public float getFractionAtTime(float time)

Get the fraction position at the elapsed time in seconds.

Parameters:

time - Elapsed time of interest in seconds.

Returns:

The fractional (from 0 to 1) value at the specified time

frameToTime

public static float frameToTime(int frame,
                                int frameRate)

Get the elapsed time in seconds of a frame position

Parameters:

frame - Frame number on the timeline

frameRate - The frames per second of the animation

Returns:

Elapsed time of interest in seconds

timeToFrame

public static int timeToFrame(float time,
                              int frameRate)

Get the frame position at the elapsed time in seconds.

Parameters:

time - Elapsed time of interest in seconds.

frameRate - The frames per second of the animation

Returns:

The frame number at the specified time

fractionToTime

public static float fractionToTime(float fraction,
                                   float duration)

Get the elapsed time in seconds of a fraction position

Parameters:

fraction - The fractional (from 0 to 1) value of interest

duration - Duration in seconds

Returns:

Elapsed time at the specified fraction

timeToFraction

public static float timeToFraction(float time,
                                   float duration)

Get the fraction position at the elapsed time in seconds.

Parameters:

time - Elapsed time of interest in seconds.

duration - Duration in seconds

Returns:

The fractional (from 0 to 1) value at the specified time

secondsToMillis

public static long secondsToMillis(float time)

Convert time in seconds to time in millis

Parameters:

time - Elapsed time of interest in seconds.

Returns:

Elapsed time of interest in milliseconds