Inherits from NSObject
Declared in CC3NodeAnimation.h

Overview

A CC3NodeAnimation manages the animation of a node.

An instance is held in the animation property of the node itself, and the node delegates to its CC3NodeAnimation when the establishAnimationFrameAt: method is invoked on the node.

Animations define animated content in in a series of frames (often called key-frames), and can be configured to interpolate the animated state between these frames if necessary, ensuring smooth animation, regardless of how many, or how widely spaced, the frames of actual animated content are.

A single CC3NodeAnimation instance can be shared by multiple nodes. This is a typical situation when creating many copies of a node that is animated.

CC3NodeAnimation is an abstract class. Subclasses define concrete animation data storage.

Tasks

Properties

frameCount

The number of frames of animated content.

@property (nonatomic, readonly) GLuint frameCount

Discussion

This property indicates the number of frames for which animated content is available (often called key-frames). Because animations can be configured to interpolate between frames, it is quite common for the effective number of animated frames to be substantially higher than the number of frames of available animated content.

As an extreme example, this property might indicate only two frames of animated content (a beginning and end state). If that animation played out over 10 seconds, it would interpolate several hundred “tween-frames”, creating a smooth transition from the beginning to end state. More commonly, animations will specify a number of frames of content, to ensure sophisticated and realistic animation.

Declared In

CC3NodeAnimation.h

hasVariableFrameTiming

Indicates whether the time interval between frames can vary from frame to frame, or whether the time interval between frames is constant across all frames.

@property (nonatomic, readonly) BOOL hasVariableFrameTiming

Discussion

If this property returns NO, the frames of this animation are equally spaced in time.

Declared In

CC3NodeAnimation.h

isAnimating

Indicates whether animation is enabled and any animated content (location, quaternion, or scale) is available and enabled.

@property (nonatomic, readonly) BOOL isAnimating

Declared In

CC3NodeAnimation.h

isAnimatingLocation

Indicates whether location animated content is available and is enabled.

@property (nonatomic, readonly) BOOL isAnimatingLocation

Declared In

CC3NodeAnimation.h

isAnimatingQuaternion

Indicates whether rotation quaternion animated content is available and is enabled.

@property (nonatomic, readonly) BOOL isAnimatingQuaternion

Declared In

CC3NodeAnimation.h

isAnimatingScale

Indicates whether scale animated content is available and is enabled.

@property (nonatomic, readonly) BOOL isAnimatingScale

Declared In

CC3NodeAnimation.h

shouldInterpolate

Indicates whether this animation should interpolate between frames, to ensure smooth transitions between frame content.

@property (nonatomic, assign) BOOL shouldInterpolate

Discussion

The initial value of this property is YES.

Declared In

CC3NodeAnimation.h

Class Methods

animationWithFrameCount:

Allocates and initializes an autoreleased instance to animate with the specified number of animation frames.

+ (id)animationWithFrameCount:(GLuint)numFrames

Declared In

CC3NodeAnimation.h

interpolationEpsilon

Indicates a fractional value of a frame below which interpolation will not be performed.

+ (CCTime)interpolationEpsilon

Discussion

If an animation time is within this fraction above or below an exact frame time (relative to the previous or next frame), the frame time itself is used, instead of interpolating between that frame time and the next or previous frame time. This allows the animation to avoid an interpolation calculation if the difference will be unnoticable when compared to simply using the values for that specific frame.

This value is specified as a fraction of a frame (between zero and one). The initial value is set at 0.1, indicating that no interpolation will be performed if the animation time is within 10% of the duration between the frame and the frame before or after it.

Setting the value of this property to zero will cause interpolation to always be performed, and setting the value to one will cause interpolation to never be performed.

The value of this class-side property affects all animation.

Declared In

CC3NodeAnimation.h

setInterpolationEpsilon:

Indicates a fractional value of a frame below which interpolation will not be performed.

+ (void)setInterpolationEpsilon:(CCTime)epsilon

Discussion

If an animation time is within this fraction above or below an exact frame time (relative to the previous or next frame), the frame time itself is used, instead of interpolating between that frame time and the next or previous frame time. This allows the animation to avoid an interpolation calculation if the difference will be unnoticable when compared to simply using the values for that specific frame.

This value is specified as a fraction of a frame (between zero and one). The initial value is set at 0.1, indicating that no interpolation will be performed if the animation time is within 10% of the duration between the frame and the frame before or after it.

Setting the value of this property to zero will cause interpolation to always be performed, and setting the value to one will cause interpolation to never be performed.

The value of this class-side property affects all animation.

Declared In

CC3NodeAnimation.h

Instance Methods

establishFrameAt:forNode:

@deprecated Use establishFrameAt:inNodeAnimationState: instead.

- (void)establishFrameAt:(CCTime)t forNode:(CC3Node *)aNode

Declared In

CC3NodeAnimation.h

establishFrameAt:inNodeAnimationState:

Updates the location, quaternion, and scale of the specified animation state based on the animation frame located at the specified time, which should be a value between zero and one, with zero indicating the first animation frame, and one indicating the last animation frame.

- (void)establishFrameAt:(CCTime)t inNodeAnimationState:(CC3NodeAnimationState *)animState

Discussion

Only those properties of the animation state for which there is animation data will be changed. If the shouldInterpolate property is set to YES, linear interpolation of the frame data is performed, based on the frameCount and the specified time.

Declared In

CC3NodeAnimation.h

initWithFrameCount:

Initializes this instance to animate with the specified number of animation frames.

- (id)initWithFrameCount:(GLuint)numFrames

Declared In

CC3NodeAnimation.h

timeAtFrame:

Returns the time at which the frame at the specified index occurs. The returned time value will be between zero and one, where zero represents the time of the first frame and one represents the time of the last frame.

- (CCTime)timeAtFrame:(GLuint)frameIndex

Discussion

This base implementation assumes a constant time between each frame and the next, so the returned value is calculated as (frameIndex / (frameCount – 1)), which is then clamped to the range between zero and one. Subclasses that allow variable times between frames will override to return the appropriate value.

Declared In

CC3NodeAnimation.h