javax.microedition.m3d
Class AnimationTrack

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.AnimationTrack

public class AnimationTrack

extends Object3D

AnimationTrack associates a KeyframeSequence with an animatable property, and an AnimationController that controls the sequence.

Most of the classes derived from Object3D have one or more animatable properties. An animatable property is a scalar or vector variable that the animation system can directly update; for instance, the orientation of a Node. Animatable properties are identified by the symbolic constants listed below. Some animatable properties are only applicable to one class, such as the SHININESS of a Material, while others apply to two or more classes. An Object3D with animatable properties is called an animatable object. Each animatable property of an animatable object constitutes a unique animation target.

Each animatable object may reference zero or more AnimationTracks. Each of these, when activated by their respective AnimationControllers, is in charge of updating one of the animation targets of the animatable object. The values assigned to the targets are determined by sampling the KeyframeSequence objects referenced by the AnimationTrack objects. Each KeyframeSequence can be referenced by multiple AnimationTracks, allowing the keyframe data to be shared.

Each AnimationTrack is associated with exactly one AnimationController, one KeyframeSequence, and one animatable property, but it may be associated with multiple animation targets. In other words, it can animate the same property in many different objects simultaneously. It is also possible to have several AnimationTrack objects associated with a single animation target. In this case, the final value of the animation target is a linear combination of the values derived from the individual AnimationTracks, weighted by their respective AnimationController weights.

Animation keyframes are input as floating point, and the values produced after interpolation and blending are also in floating point. When applied to their target property, the values must be mapped to the closest representable value that is valid for the property in question. For example, values for a floating point property must be clamped to the valid range for that property; values for an integer property rounded to the closest integer; and values for a boolean property interpreted as true when the value produced by animation is greater than or equal to 0.5, false if less. Exceptions to this rule are stated explicitly if necessary.

Example operation

When the whole scene graph or a subtree of objects is updated (using a call to Object3D.animate), the world time, maintained by the controlling application, is passed to each animatable object. In turn, each animatable object passes the world time to each of the AnimationTrack objects which are bound to it.

The AnimationTrack object then checks to see if the current world time falls within the active interval of its associated AnimationController object. If not, then no further action is taken by this AnimationTrack. If no active AnimationTrack objects are found for an animation target, the value of that target is unchanged. Note, however, that animation targets are independent of each other, and other targets in the same object may still change.

If the AnimationController is active, it is used to determine the sequence time for the animation. (Details of this calculation can be found in the AnimationController class description.) The sequence time is then used to obtain an interpolated value from the KeyframeSequence object. (Details of interpolation in the KeyframeSequence class description.) This sample is then multiplied by the weight factor of the AnimationController object and applied to the target property. If multiple AnimationTrack objects target the same property, they are blended together according to the weights of their respective AnimationController objects; see AnimationController for more details on animation blending.

See Also:

Binary format, KeyframeSequence, AnimationController, Object3D.addAnimationTrack

Field Summary

static int	ALPHA_FACTOR Specifies the alpha factor of a Node as an animation target.
static int	AMBIENT_COLOR Specifies the ambient color of a Material, or the ambient light intensity of a World as an animation target.
static int	BACK_DISTANCE Specifies the back clipping distance of a Camera, or the end distance of a fog range in Fog as an animation target.
static int	COLOR Specifies the color of a Light, the background color of a Background, the fog color in Fog, or the texture blend color in Texture2D as an animation target.
static int	CROP Specifies the cropping parameters of a Sprite node as an animation target.
static int	DENSITY Specifies fog density in Fog as an animation target.
static int	DIFFUSE_COLOR Specifies the diffuse color of a Material as an animation target.
static int	EMISSIVE_COLOR Specifies the emissive color of a Material as an animation target.
static int	FIELD_OF_VIEW Specifies the field of view of a Camera as an animation target.
static int	FRONT_DISTANCE Specifies the front clipping distance of a Camera, or the start distance of a fog range in Fog as an animation target.
static int	INTENSITY Specifies the intensity of a Light as an animation target.
static int	MORPH_WEIGHTS Specifies the morph target weights of a MorphingMesh as an animation target.
static int	OFFSET Specifies the (X, Y) offset of a Background image as an animation target.
static int	ROTATION Specifies the rotation component of the transformation of a Node or a Texture2D as an animation target.
static int	SCALE Specifies the scaling component of the transformation of a Node or a Texture2D as an animation target.
static int	SHININESS Specifies the shininess of a Material as an animation target.
static int	SPECULAR_COLOR Specifies the specular color of a Material as an animation target.
static int	SPOT_ANGLE Specifies the spot angle of a Light as an animation target.
static int	SPOT_EXPONENT Specifies the spot exponent of a Light as an animation target.
static int	TRANSLATION Specifies the translation component of the transformation of a Node or a Texture2D as an animation target.
static int	VISIBILITY Specifies the visibility of a Node as an animation target.

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

AnimationTrack(KeyframeSequence sequence, int property)
Creates an animation track with the given keyframe sequence targeting the given property.

Method Summary

AnimationController	getController() Retrieves the animation controller used for controlling this animation track.
KeyframeSequence	getKeyframeSequence() Returns the keyframe sequence object which defines the keyframe values for this animation track.
int	getTargetProperty() Returns the property targeted by this AnimationTrack.
int	getTime(int worldTime) Retrieves the current time of this animation track, relative to the start of this animation track.
void	setController(AnimationController controller) Specifies the animation controller to be used for controlling this animation track.

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

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

Field Detail

ALPHA_FACTOR

public static final int ALPHA_FACTOR

Specifies the alpha factor of a Node as an animation target.

Number of components required: 1

See Also:

Constant Field Values

AMBIENT_COLOR

public static final int AMBIENT_COLOR

Specifies the ambient color of a Material, or the ambient light intensity of a World as an animation target.

Number of components required: 3 (RGB)

See Also:

Constant Field Values

BACK_DISTANCE

public static final int BACK_DISTANCE

Specifies the back clipping distance of a Camera, or the end distance of a fog range in Fog as an animation target.

Number of components required: 1

See Also:

Constant Field Values

COLOR

public static final int COLOR

Specifies the color of a Light, the background color of a Background, the fog color in Fog, or the texture blend color in Texture2D as an animation target.

Number of components required: 3 (RGB) or 4 (RGBA)

See Also:

Constant Field Values

CROP

public static final int CROP

Specifies the cropping parameters of a Sprite node as an animation target.

Number of components required: 2 (X, Y) or 4 (X, Y, width, height)

See Also:

Constant Field Values

DENSITY

public static final int DENSITY

Specifies fog density in Fog as an animation target.

Number of components required: 1

See Also:

Constant Field Values

DIFFUSE_COLOR

public static final int DIFFUSE_COLOR

Specifies the diffuse color of a Material as an animation target.

Number of components required: 4 (RGBA)

See Also:

Constant Field Values

EMISSIVE_COLOR

public static final int EMISSIVE_COLOR

Specifies the emissive color of a Material as an animation target.

Number of components required: 3 (RGB)

See Also:

Constant Field Values

FIELD_OF_VIEW

public static final int FIELD_OF_VIEW

Specifies the field of view of a Camera as an animation target.

Number of components required: 1

See Also:

Constant Field Values

FRONT_DISTANCE

public static final int FRONT_DISTANCE

Specifies the front clipping distance of a Camera, or the start distance of a fog range in Fog as an animation target.

Number of components required: 1

See Also:

Constant Field Values

INTENSITY

public static final int INTENSITY

Specifies the intensity of a Light as an animation target.

Number of components required: 1

See Also:

Constant Field Values

MORPH_WEIGHTS

public static final int MORPH_WEIGHTS

Specifies the morph target weights of a MorphingMesh as an animation target. If there are N morph targets in the target mesh, the associated keyframes should be N-element vectors. The sum of each vector is recommended to be 1.0, but this is not enforced.

Since there is no direct reference from this object to its associated MorphingMesh node, there is no way to check at construction time that the number of vector components matches the number of morph targets. Denoting the number of components in the keyframe vectors by V, the following rules apply in case of a mismatch:

If V < N, then morph target weights are set as

 w[i] = v[i]      for 0 <= i < V
 w[i] = 0.0       for V <= i < N

If V > N, then morph target weights are set as

 w[i] = v[i]      for 0 <= i < N
 v[i] ignored     for N <= i < V

Number of components required: N

See Also:

Constant Field Values

OFFSET

public static final int OFFSET

Specifies the (X, Y) offset of a Background image as an animation target.

Number of components required: 2

See Also:

Constant Field Values

ROTATION

public static final int ROTATION

Specifies the rotation component of the transformation of a Node or a Texture2D as an animation target.

In this case, the orientation is specified as a 4-element vector defining a unit quaternion. Each element is defined as follows:

• v[0] coefficient of i (imaginary axis parallel to x)
• v[1] coefficient of j (imaginary axis parallel to y)
• v[2] coefficient of k (imaginary axis parallel to z)
• v[3] scalar component of quaternion

Number of components required: 4

See Also:

Constant Field Values

SCALE

public static final int SCALE

Specifies the scaling component of the transformation of a Node or a Texture2D as an animation target. The number of keyframe components in the associated VectorSequence can be either one or three for uniform or non-uniform scaling, respectively.

Number of components required: 1 or 3 (XYZ)

See Also:

Constant Field Values

SHININESS

public static final int SHININESS

Specifies the shininess of a Material as an animation target.

Number of components required: 1

See Also:

Constant Field Values

SPECULAR_COLOR

public static final int SPECULAR_COLOR

Specifies the specular color of a Material as an animation target.

Number of components required: 3 (RGB)

See Also:

Constant Field Values

SPOT_ANGLE

public static final int SPOT_ANGLE

Specifies the spot angle of a Light as an animation target.

Number of components required: 1

See Also:

Constant Field Values

SPOT_EXPONENT

public static final int SPOT_EXPONENT

Specifies the spot exponent of a Light as an animation target.

Number of components required: 1

See Also:

Constant Field Values

TRANSLATION

public static final int TRANSLATION

Specifies the translation component of the transformation of a Node or a Texture2D as an animation target.

Number of components required: 3 (XYZ)

See Also:

Constant Field Values

VISIBILITY

public static final int VISIBILITY

Specifies the visibility of a Node as an animation target. A node is defined to be visible if isEnabled returns true, and invisible otherwise.

Number of components required: 1

See Also:

Constant Field Values

Constructor Detail

AnimationTrack

public AnimationTrack(KeyframeSequence sequence,
                      int property)

Creates an animation track with the given keyframe sequence targeting the given property. The keyframe sequence must be compatible with the target property; for example, to animate the translation component of a transformation, the keyframes must be 3-element vectors.

No controller is initially attached to the track.

Parameters:

sequence - a KeyframeSequence containing the keyframe data for this animation track

property - one of ALPHA_FACTOR, ..., VISIBILITY

Throws:

java.lang.IllegalArgumentException - if property is not one of the symbolic constants listed above

java.lang.IllegalArgumentException - if sequence is not compatible with property

Method Detail

setController

public void setController(AnimationController controller)

Specifies the animation controller to be used for controlling this animation track. The controller determines the mapping from world time to sequence time, the speed of animation, and the active interval for all tracks under its control.

Parameters:

controller - an AnimationController object which defines the active state and sequence time for this animation sequence; if this is null then the behaviour is equivalent to associating this object with an inactive animation controller

See Also:

getController

getController

public AnimationController getController()

Retrieves the animation controller used for controlling this animation track.

Returns:

the AnimationController object which defines the active state and sequence time for this animation sequence, as set by setController. If no controller has yet been attached, this method returns null

See Also:

setController

getKeyframeSequence

public KeyframeSequence getKeyframeSequence()

Returns the keyframe sequence object which defines the keyframe values for this animation track.

Returns:

the KeyframeSequence object which defines the keyframe values

getTargetProperty

public int getTargetProperty()

Returns the property targeted by this AnimationTrack. The target property is one of the symbolic constants listed above.

Returns:

the object property targeted by this track

getTime

public int getTime(int worldTime)

Retrieves the current time of this animation track, relative to the start of this animation track. This is defined by the state of the currently associated animation controller. If no controller is attached, then this value is consistently returned as 0.

Parameters:

worldTime - the world time to query sequence time at

Returns:

the sequence time when world time equals worldTime