net.rim.device.api.animation
Class AnimationKeyframeSequence

java.lang.Object
  net.rim.device.api.animation.AnimationKeyframeSequence

public final class AnimationKeyframeSequence
extends Object

Defines a class that represents animation sequence data as an ordering of two or more keyframes on a time scale between 0.0 and 1.0. The class also contains information that specifies how to interpolate between the values of each keyframe.

Creating an AnimationKeyframeSequence

 // Create a two channel, three keyframe sequence for a property with a component size of two.
 AnimationKeyframeSequence sequence = new AnimationKeyframeSequence(2, 3, 2, Animation.EASINGCURVE_BOUNCE_IN);
 
 float[] keyValuesChannelOne = {50.0f, 50.0f, 100.0f, 100.0f, 160.0f, 230.0f};
 float[] keyValuesChannelTwo = {30.0f, 80.0f, 75.0f, 80.0f, 200.0f, 145.0f};
 float[] keyTimes = {0.0f, 0.5f, 1.0f};
 // Populate the keyframes.
 // Channel 1 keyframes
 sequence.setKeyframe(0, 0, keyTimes[0], keyValuesChannelOne, 0);
 sequence.setKeyframe(0, 1, keyTimes[1], keyValuesChannelOne, 2);
 sequence.setKeyframe(0, 2, keyTimes[2], keyValuesChannelOne, 4);
 // Channel 2 keyframes
 sequence.setKeyframe(1, 0, keyTimes[0], keyValuesChannelTwo, 0);
 sequence.setKeyframe(1, 1, keyTimes[1], keyValuesChannelTwo, 2);
 sequence.setKeyframe(1, 2, keyTimes[2], keyValuesChannelTwo, 4);
 

Represententing Keyframe Values as By-Values

By default, keyframe values in the sequence are represented as to-values, which means the animation will animate from a specified initial value to another value. A by-value means that the sequence data will be treated as animations from some value, by a given value. To change the keyframe values to by-values, do the following:

 // Create the sequence
 AnimationKeyframeSequence = new AnimationKeyframeSequence(2, 2, Animation.EASINGCURVE_LINEAR);
 float[] keyValues = {25, 40, 55, 60};
 float[] keyTimes = {0.0f, 1.0f};
 // Populate the keyframes
 sequence.setKeyframe(0, keyTimes[0], keyValues, 0);
 sequence.setKeyframe(1, keyTimes[1], keyValues, 2);
 // Set the values to be by-values.
 sequence.setBy(true);
 

Changing the Sequence Value Type

The Animation API supports animating on different value types. The value types are AnimationKeyframeSequence.VALUE_TYPE_VECTOR, AnimationKeyframeSequence.VALUE_TYPE_QUATERNION, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM2D, and AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D. The default value type is AnimationKeyframeSequence.VALUE_TYPE_VECTOR which is suitable for most animations. The other value types, are for more complex cases of animating quaternions and 2D and 3D transforms. These should be used for creating sequence data in conjunction with corresponding classes in the net.rim.device.api.math package that implement Animatable.

 // Create the sequence
 AnimationKeyframeSequence = new AnimationKeyframeSequence(2, 2, Animation.EASINGCURVE_LINEAR);
 float[] keyValues = {25, 40, 55, 60};
 float[] keyTimes = {0.0f, 1.0f};
 // Populate the keyframes
 sequence.setKeyframe(0, keyTimes[0], keyValues, 0);
 sequence.setKeyframe(1, keyTimes[1], keyValues, 2);
 sequence.setValueType(VALUE_TYPE_TRANSFORM3D);
 

Using Spline Interpolation

You can set the easing curve to be a custom Bezier spline curve. A set of control points can be defined per two keyframes. This allows complex and custom easing curve definition.

 // Create the sequence, specifying EASINGCURVE_SPLINE as the easing curve.
 AnimationKeyframeSequence = new AnimationKeyframeSequence(3, 1, Animation.EASINGCURVE_SPLINE);
 float[] keyValues = {25, 75, 125};
 float[] keyTimes = {0.0f, 0.5f, 1.0f};
 // Populate the keyframes
 sequence.setKeyframe(0, keyTimes[0], keyValues, 0);
 sequence.setKeyframe(1, keyTimes[1], keyValues, 1);
 sequence.setKeyframe(2, keyTimes[2], keyValues, 2);
 // Set the control points. The interpolation between the first two keyframes will be linear. The interpolation
 // of the second two keyframes will use a different spline curve that is similar to an ease-in curve.
 float[] splinePoints = {0.0f, 0.0f, 1.0f, 1.0f, 0.0f, 0.75f, 1.0f, 0.25f};
 sequence.setKeysplines(splinePoints)
 

Since:

BlackBerry API 6.0.0

Field Summary
static int	CHANNEL_COUNT_MAX Constant that specifies the maximum number of channels.
static int	KEYFRAME_COUNT_MAX Constant that specifies the maximum number of keyframes.
static float	KEYFRAME_RELATIVE Constant that indicates that the sequence data is relative.
static int	PROPERTY_COUNT_MAX Constant that specifies the maximum number of property values that can be animated in one channel of data.
static int	VALUE_TYPE_QUATERNION Constant that specifies a quaternion value type.
static int	VALUE_TYPE_TRANSFORM2D Constant that specifies a transform 2D value type.
static int	VALUE_TYPE_TRANSFORM3D Constant that specifies a transform 3D value type.
static int	VALUE_TYPE_VECTOR Constant that specifies a vector value type.

Constructor Summary

AnimationKeyframeSequence(int keyframeCount, int propertyComponentCount, int easingCurve)
Class constructor.

AnimationKeyframeSequence(int channelCount, int keyframeCount, int propertyComponentCount, int easingCurve)
Class constructor.

Method Summary
int	getChannelCount() Gets the number of data channels in the sequence.
int	getEasingCurve() Gets the easing curve currently being applied on the sequence.
float	getKeyTime(int index) Gets the key time for the specified keyframe.
float	getKeyframe(int index, float[] value, int offset) Gets the time stamp and key values for the specified keyframe.
float	getKeyframe(int channel, int index, float[] value, int offset) Gets the time stamp and key values for the specified keyframe on the speficied data channel.
int	getKeyframeCount() Gets the number of keyframes in the sequence.
int	getKeysplines(float[] controlPoints) Gets the spline control points used across all keyframes in the sequence.
int	getValueType() Gets the value type of the sequence.
boolean	isBy() Indicates if the key values in the sequence are treated as by-values.
void	setBy(boolean isBy) Configures whether the key values in the sequence are treated as by-values.
void	setEasingCurve(int easingCurve) Sets the easing curve used to interpolate the data on the sequence.
void	setKeyframe(int index, float time, float[] value, int offset) Sets the time stamp and key value for the given keyframe.
void	setKeyframe(int channel, int index, float time, float[] value, int offset) Sets the time stamp and key value for the specified keyframe on the specified data channel.
void	setKeysplines(float[] controlPoints) Sets the spline control points for all keyframes in the sequence.
void	setValueType(int valueType) Sets the value type of the sequence.

Methods inherited from class java.lang.Object

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

Field Detail

VALUE_TYPE_VECTOR

public static final int VALUE_TYPE_VECTOR

Constant that specifies a vector value type. Used for interpolating values independently.

See Also:

AnimationKeyframeSequence.setValueType(int), AnimationKeyframeSequence.getValueType(), Constant Field Values

Since:

BlackBerry API 6.0.0

VALUE_TYPE_QUATERNION

public static final int VALUE_TYPE_QUATERNION

Constant that specifies a quaternion value type. Used for interpolating angles.

See Also:

AnimationKeyframeSequence.setValueType(int), AnimationKeyframeSequence.getValueType(), Constant Field Values

Since:

BlackBerry API 6.0.0

VALUE_TYPE_TRANSFORM2D

public static final int VALUE_TYPE_TRANSFORM2D

Constant that specifies a transform 2D value type. Used for interpolating 2D transformation matrices.

See Also:

AnimationKeyframeSequence.setValueType(int), AnimationKeyframeSequence.getValueType(), Constant Field Values

Since:

BlackBerry API 6.0.0

VALUE_TYPE_TRANSFORM3D

public static final int VALUE_TYPE_TRANSFORM3D

Constant that specifies a transform 3D value type. Used for interpolating 3D transformation matrices.

See Also:

AnimationKeyframeSequence.setValueType(int), AnimationKeyframeSequence.getValueType(), Constant Field Values

Since:

BlackBerry API 6.0.0

KEYFRAME_RELATIVE

public static final float KEYFRAME_RELATIVE

Constant that indicates that the sequence data is relative.

See Also:

AnimationKeyframeSequence.setKeyframe(int,int,float,float[],int), AnimationKeyframeSequence.setKeyframe(int,float,float[],int), AnimationKeyframeSequence.getKeyframe(int,int,float[],int), AnimationKeyframeSequence.getKeyframe(int,float[],int), Constant Field Values

Since:

BlackBerry API 6.0.0

PROPERTY_COUNT_MAX

public static final int PROPERTY_COUNT_MAX

Constant that specifies the maximum number of property values that can be animated in one channel of data.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

CHANNEL_COUNT_MAX

public static final int CHANNEL_COUNT_MAX

Constant that specifies the maximum number of channels.

See Also:

AnimationKeyframeSequence.AnimationKeyframeSequence(int, int, int, int), Constant Field Values

Since:

BlackBerry API 7.0.0

KEYFRAME_COUNT_MAX

public static final int KEYFRAME_COUNT_MAX

Constant that specifies the maximum number of keyframes.

See Also:

AnimationKeyframeSequence.AnimationKeyframeSequence(int, int, int), AnimationKeyframeSequence.AnimationKeyframeSequence(int, int, int, int), Constant Field Values

Since:

BlackBerry API 7.0.0

Constructor Detail

AnimationKeyframeSequence

public AnimationKeyframeSequence(int keyframeCount,
                                 int propertyComponentCount,
                                 int easingCurve)

Class constructor.

Creates an AnimationKeyframeSequence with the specified number of keyframes for a property with the given property component count.

Parameters:

keyframeCount - The number of keyframes in the sequence.

propertyComponentCount - The number of components that compose the animatable property that the sequence will animate.

easingCurve - The easing curve to be used to interpolate through the sequence data.

Throws:

IllegalArgumentException - if keyframeCount < 2.

IllegalArgumentException - if propertyComponentCount < 1 or propertyComponentCount > AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

IllegalArgumentException - if easingCurve is not a valid type.

Since:

BlackBerry API 6.0.0

AnimationKeyframeSequence

public AnimationKeyframeSequence(int channelCount,
                                 int keyframeCount,
                                 int propertyComponentCount,
                                 int easingCurve)

Class constructor.

Creates an AnimationKeyframeSequence consisting of the specified number of data channels and the specified number of keyframes for a property with the specified property component count.

Parameters:

channelCount - The number of data channels in the sequence.

keyframeCount - The number of keyframes in the sequence.

propertyComponentCount - The number of components that compose the animatable property that the sequence will animate.

easingCurve - The easing curve to be used to interpolate through the sequence data.

Throws:

IllegalArgumentException - if channelCount < 1.

IllegalArgumentException - if keyframeCount < 2.

IllegalArgumentException - if propertyComponentCount < 1 or propertyComponentCount > AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

IllegalArgumentException - if easingCurve is not a valid type.

Since:

BlackBerry API 6.0.0

Method Detail

getChannelCount

public int getChannelCount()

Gets the number of data channels in the sequence.

Returns:

The number of data channels in the sequence.

Since:

BlackBerry API 6.0.0

getKeyframeCount

public int getKeyframeCount()

Gets the number of keyframes in the sequence.

Returns:

The number of keyframes in the sequence.

Since:

BlackBerry API 6.0.0

getEasingCurve

public int getEasingCurve()

Gets the easing curve currently being applied on the sequence.

Returns:

easing curve to used to interpolate through the sequence data.

Since:

BlackBerry API 6.0.0

setEasingCurve

public void setEasingCurve(int easingCurve)

Sets the easing curve used to interpolate the data on the sequence.

Parameters:

easingCurve - The easing curve to be used to interpolate through the sequence data.

Throws:

IllegalArgumentException - if easingCurve is not a valid type.

Since:

BlackBerry API 6.0.0

getValueType

public int getValueType()

Gets the value type of the sequence.

Value type will be one of AnimationKeyframeSequence.VALUE_TYPE_VECTOR, AnimationKeyframeSequence.VALUE_TYPE_QUATERNION, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM2D, or AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D.

Returns:

The value type of the sequence data.

See Also:

AnimationKeyframeSequence.VALUE_TYPE_VECTOR, AnimationKeyframeSequence.VALUE_TYPE_QUATERNION, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM2D, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D

Since:

BlackBerry API 6.0.0

setValueType

public void setValueType(int valueType)

Sets the value type of the sequence. The default value type is AnimationKeyframeSequence.VALUE_TYPE_VECTOR.

Parameters:

valueType - The type of the data. Must be one of AnimationKeyframeSequence.VALUE_TYPE_VECTOR, AnimationKeyframeSequence.VALUE_TYPE_QUATERNION, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D, or AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D.

Throws:

IllegalArgumentException - if valueType is not one of the constants defined above.

See Also:

AnimationKeyframeSequence.VALUE_TYPE_VECTOR, AnimationKeyframeSequence.VALUE_TYPE_QUATERNION, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM2D, AnimationKeyframeSequence.VALUE_TYPE_TRANSFORM3D

Since:

BlackBerry API 6.0.0

getKeyframe

public float getKeyframe(int index,
                         float[] value,
                         int offset)

Gets the time stamp and key values for the specified keyframe.

Parameters:

index - The index of the keyframe to retrieve.

value - Array used to store the keyframe value vector, or null to only return the time stamp.

offset - The offset at which to populate the value float array.

Returns:

The key time value of the keyframe. AnimationKeyframeSequence.KEYFRAME_RELATIVE if querying the first keyframe and the sequence is relative.

Throws:

IllegalArgumentException - if index < 0 or index >= the keyframe count.

IllegalArgumentException - if offset < 0.

IllegalArgumentException - if value.length < offset + the property component count.

Since:

BlackBerry API 6.0.0

getKeyframe

public float getKeyframe(int channel,
                         int index,
                         float[] value,
                         int offset)

Gets the time stamp and key values for the specified keyframe on the speficied data channel.

Parameters:

channel - The data channel to get keyframe information for.

index - The index of the keyframe to retrieve.

value - Array used to store the keyframe value vector, or null to only return the time stamp.

offset - The offset at which to populate the value float array.

Returns:

The key time value of the keyframe; AnimationKeyframeSequence.KEYFRAME_RELATIVE if querying the first keyframe and the sequence is relative.

Throws:

IllegalArgumentException - if channel < 0 or channel >= the channel count.

IllegalArgumentException - if index < 0 or index >= the keyframe count.

IllegalArgumentException - if offset < 0.

IllegalArgumentException - if value.length < offset + the property component count.

Since:

BlackBerry API 6.0.0

setKeyframe

public void setKeyframe(int index,
                        float time,
                        float[] value,
                        int offset)

Sets the time stamp and key value for the given keyframe.

To create a relative "By-Animation" or "To-Animation", one must pass in AnimationKeyframeSequence.KEYFRAME_RELATIVE for the keytime value of the first keyframe (index == 0). By default, the first key frame is treated as a relative value.

Parameters:

index - The index of the keyframe to set.

time - The time stamp for this keyframe.

value - Array containing the value vector for this keyframe.

offset - The offset of the value vector in the value float array.

Throws:

IllegalArgumentException - if value is null.

IllegalArgumentException - if index < 0 or index >= the keyframe count.

IllegalArgumentException - if offset < 0.

IllegalArgumentException - if value.length < offset + the property component count.

IllegalArgumentException - if time < 0.0 or time > 1.0.

IllegalArgumentException - if index == 0 and time != 0.0f.

IllegalArgumentException - if index == the last keyframe and time != 1.0f.

Since:

BlackBerry API 6.0.0

setKeyframe

public void setKeyframe(int channel,
                        int index,
                        float time,
                        float[] value,
                        int offset)

Sets the time stamp and key value for the specified keyframe on the specified data channel.

To create a relative "By-Animation" or "To-Animation", you must pass in AnimationKeyframeSequence.KEYFRAME_RELATIVE for the keytime value of the first keyframe (index == 0). By default, the first key frame is treated as a relative value.

Parameters:

channel - The data channel to get keyframe information for.

index - The index of the keyframe to set.

time - The time stamp for this keyframe.

value - Array containing the value vector for this keyframe.

offset - The offset of the value vector in the value float array.

Throws:

IllegalArgumentException - if channel < 0 or channel >= the channel count.

IllegalArgumentException - if value is null.

IllegalArgumentException - if index < 0 or index >= the keyframe count.

IllegalArgumentException - if offset < 0.

IllegalArgumentException - if value.length < offset + the property component count.

IllegalArgumentException - if time < 0.0 or time > 1.0.

IllegalArgumentException - if index == 0 and time != 0.0f.

IllegalArgumentException - if index == the last keyframe and time != 1.0f.

Since:

BlackBerry API 6.0.0

getKeyTime

public float getKeyTime(int index)

Gets the key time for the specified keyframe.

Parameters:

index - The key frame.

Returns:

The key time for the given keyframe

Throws:

IndexOutOfBoundsException - if index < 0 or index >= keyframe count.

Since:

BlackBerry API 6.0.0

setKeysplines

public void setKeysplines(float[] controlPoints)

Sets the spline control points for all keyframes in the sequence.

Parameters:

controlPoints - The control points to be set.

Throws:

IllegalArgumentException - if controlPoints is null.

IllegalArgumentException - if controlPoints.length % 4 != 0.

IllegalArgumentException - if any of the values in controlPoints is outside of the range [0.0, 1.0].

Since:

BlackBerry API 6.0.0

getKeysplines

public int getKeysplines(float[] controlPoints)

Gets the spline control points used across all keyframes in the sequence.

If no key splines have been set on the sequence at the time this method is invoked, it will return 0 and controlPoints will be unmodified.

Parameters:

controlPoints - The control points to be fill. Passing null will only return number of keyframes there are keysplines defined for.

Returns:

The number of keyframes there are keysplines defined for.

Throws:

IllegalArgumentException - if controlPoints is not null and controlPoints.length < getKeySplines(null).

Since:

BlackBerry API 6.0.0

isBy

public boolean isBy()

Indicates if the key values in the sequence are treated as by-values.

Returns:

true if the sequence contains to-values, false if the sequence contains by-values.

Since:

BlackBerry API 6.0.0

setBy

public void setBy(boolean isBy)

Configures whether the key values in the sequence are treated as by-values.

Parameters:

isBy - if true the key values will be treated as by-values, if false the key values will be treated as to-values, which is the default.

Since:

BlackBerry API 6.0.0