javax.microedition.m3g
Class AnimationTrack

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.AnimationTrack

public class AnimationTrack

extends Object3D

Associates a KeyframeSequence with an AnimationController and an animatable property.

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.

Most classes derived from Object3D have one or more animatable properties. An Object3D instance 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.

Implementation guidelines

Clamping of interpolated values

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.

In summary, applying an animated quantity to its target property must never result in an exception or otherwise illegal state.

Example implementation

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 are 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 Specifies the alpha factor of a Node, or the alpha component of the Background color, Material diffuse color, or VertexBuffer default color as an animation target.
static int	AMBIENT_COLOR Specifies the ambient color of a Material as an animation target.
static int	COLOR Specifies the color of a Light, Background, or Fog, or the texture blend color in Texture2D, or the VertexBuffer default color as an animation target.
static int	CROP Specifies the cropping parameters of a Sprite3D or Background as an animation target.
static int	DENSITY Specifies the 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	FAR_DISTANCE Specifies the far distance of a Camera or Fog as an animation target.
static int	FIELD_OF_VIEW Specifies the field of view of a Camera 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	NEAR_DISTANCE Specifies the near distance of a Camera or Fog as an animation target.
static int	ORIENTATION Specifies the orientation (R) component of a Transformable object as an animation target.
static int	PICKABILITY Specifies the picking enable flag of a Node as an animation target.
static int	SCALE Specifies the scale (S) component of a Transformable object 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 (T) component of a Transformable object as an animation target.
static int	VISIBILITY Specifies the rendering enable flag of a Node as an animation target.

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.
void	setController(AnimationController controller) Specifies the animation controller to be used for controlling this animation track.

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Field Detail

ALPHA

public static final int ALPHA

Specifies the alpha factor of a Node, or the alpha component of the Background color, Material diffuse color, or VertexBuffer default color as an animation target. The interpolated value is clamped to the range [0, 1].

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 as an animation target. The interpolated value of each color component is clamped to the range [0, 1].

Number of components required: 3 (RGB)

See Also:

Constant Field Values

COLOR

public static final int COLOR

Specifies the color of a Light, Background, or Fog, or the texture blend color in Texture2D, or the VertexBuffer default color as an animation target. The interpolated value of each color component is clamped to the range [0, 1].

Note that the alpha component of the background color or default color is targeted separately using the identifier ALPHA (the other COLOR targets do not have an alpha component).

Number of components required: 3 (RGB)

See Also:

Constant Field Values

CROP

public static final int CROP

Specifies the cropping parameters of a Sprite3D or Background as an animation target. The required parameters are the X and Y coordinates of the crop rectangle upper left corner, and the width and height of the crop rectangle, in that order.

The X and Y parameters may take on any value, regardless of whether the target object is a Sprite3D or Background. The width and height, however, have differing limits depending on the target.

In case of a Background target, negative values of width and height are clamped to zero. In case of a Sprite3D target, they are clamped to the range [-N, N], where N is the implementation specific maximum sprite crop size. Recall that negative values of width and height cause the displayed image to be flipped in the corresponding dimensions.

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 the fog density in Fog as an animation target. If the interpolated value is negative, it is clamped to zero.

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. The interpolated value of each color component is clamped to the range [0, 1].

Note that the alpha component of the diffuse color is targeted separately, using the identifier ALPHA.

Number of components required: 3 (RGB)

See Also:

Constant Field Values

EMISSIVE_COLOR

public static final int EMISSIVE_COLOR

Specifies the emissive color of a Material as an animation target. The interpolated values of the color components are clamped to the range [0, 1].

Number of components required: 3 (RGB)

See Also:

Constant Field Values

FAR_DISTANCE

public static final int FAR_DISTANCE

Specifies the far distance of a Camera or Fog as an animation target. In case of a Camera target in perspective mode, negative values and zero are clamped to the smallest representable positive number. In case of a Fog target, or a camera target in parallel mode, the value is not clamped.

Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in perspective or parallel mode.

Number of components required: 1

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. The interpolated value is clamped to the range (0, 180) in case of a perspective Camera. In case of a parallel camera, negative values and zero are clamped to the smallest representable positive number.

Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in perspective or parallel mode.

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.

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

NEAR_DISTANCE

public static final int NEAR_DISTANCE

Specifies the near distance of a Camera or Fog as an animation target. In case of a Camera target in perspective mode, negative values and zero are clamped to the smallest representable positive number. In case of a Fog target, or a camera target in parallel mode, the value is not clamped.

Animating any of the camera parameters (near, far, field of view) only has an effect if the camera is in perspective or parallel mode.

Number of components required: 1

See Also:

Constant Field Values

ORIENTATION

public static final int ORIENTATION

Specifies the orientation (R) component of a Transformable object as an animation target.

The orientation is specified as a 4-element vector defining a quaternion. The quaternion components in the keyframes are ordered as follows:

• v[0] coefficient of i (related to the x component of the rotation axis)
• v[1] coefficient of j (related to the y component of the rotation axis)
• v[2] coefficient of k (related to the z component of the rotation axis)
• v[3] the scalar component (related to the rotation angle)

The quaternion resulting from interpolation is normalized automatically before applying it to the target, as specified in the AnimationController class description, section "Animation weighting".

Note that there are only two stages in the animation process where the implementation must normalize quaternions. They must not be normalized anywhere else. The first is when SLERP or SQUAD keyframes are fed in. The other is when the final, weighted result is applied to the target object.

Number of components required: 4

See Also:

Constant Field Values

PICKABILITY

public static final int PICKABILITY

Specifies the picking enable flag of a Node as an animation target.

Number of components required: 1

See Also:

Constant Field Values

SCALE

public static final int SCALE

Specifies the scale (S) component of a Transformable object as an animation target. The number of keyframe components in the associated KeyframeSequence 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. The interpolated value is clamped to the range [0, 128].

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. The interpolated value of each color component is clamped to the range [0, 1].

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. The interpolated value is clamped to the range [0, 90].

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. The interpolated value is clamped to the range [0, 128].

Number of components required: 1

See Also:

Constant Field Values

TRANSLATION

public static final int TRANSLATION

Specifies the translation (T) component of a Transformable object as an animation target.

Number of components required: 3 (XYZ)

See Also:

Constant Field Values

VISIBILITY

public static final int VISIBILITY

Specifies the rendering enable flag of a Node as an animation target.

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, ..., VISIBILITY

Throws:

java.lang.NullPointerException - if sequence is null

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