Inherits from NSObject
Conforms to NSCopying
Declared in CC3Rotator.h

Overview

CC3otator encapsulates the various mechanisms of rotating a node, and converts between them. Nodes delegate responsibility for managing their rotation to an encapsulated instance of CC3Rotator.

Depending on the rotator subclass, rotations can be read in any of the following forms: – three Euler angles – rotation angle around an arbitrary rotation axis – quaternion

This base class represents a read-only rotator and performs only identity rotations. It’s primary purpose is to save memory in nodes that do not require any rotation.

The CC3MutableRotator class adds the ability to set rotations, and is more commonly used. The CC3DirectionalRotator class further adds directional rotational mechanisms (such as rotating to look in a particular direction), and the CC3TargetttingRotator extends this to rotating to look at a particular target location or node, and optionally track that target location or node as it or the node of the rotator move around.

Tasks

Properties

isDirectional

Indicates whether this rotator supports rotating to point towards a specific direction (ie- “look-towards”).

@property (nonatomic, readonly) BOOL isDirectional

Discussion

This implementation always returns NO. Subclasses that support pointing towards a specific direction will override.

Declared In

CC3Rotator.h

isMutable

Indicates whether this rotator supports changing rotation properties, including rotation, quaternion, rotationAxis, and rotationAngle, and supports incremental rotation through the rotateBy…family of methods.

@property (nonatomic, readonly) BOOL isMutable

Discussion

This implementation always returns NO. Subclasses that support changing rotation properties will override.

Declared In

CC3Rotator.h

isTargettable

Indicates whether this rotator supports rotating to point towards a specific target node or target location (ie- “look-at”), including

@property (nonatomic, readonly) BOOL isTargettable

Discussion

This implementation always returns NO. Subclasses that support targetting a specific direction will override.

Declared In

CC3Rotator.h

isTrackingForBumpMapping

If the target node of the node carrying this rotator is a CC3Light, the target can be tracked by the node for the purpose of updating the lighting of a contained bump-map texture, instead of rotating to face the light, as normally occurs with tracking.

@property (nonatomic, readonly) BOOL isTrackingForBumpMapping

Discussion

This property indicates whether the node should update its globalLightPosition from the tracked location of the light, instead of rotating to face the light.

Always returns NO. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

isTrackingTargetDirection

Returns whether this rotator updates the target direction by tracking a target.

@property (nonatomic, readonly) BOOL isTrackingTargetDirection

Discussion

Always returns NO. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

quaternion

The rotation of the node in 3D space, relative to the parent of this node, expressed as a quaternion.

@property (nonatomic, assign, readonly) CC3Quaternion quaternion

Discussion

This base class always returns kCC3QuaternionIdentity.

Declared In

CC3Rotator.h

rotation

The rotational orientation of the node in 3D space, relative to the parent of the node. This value contains three Euler angles, defining a rotation of this node around the X, Y and Z axes. Each angle is specified in degrees.

@property (nonatomic, assign, readonly) CC3Vector rotation

Discussion

Rotation is performed in Y-X-Z order, which is the OpenGL default. Depending on the nature of the object you are trying to control, you can think of this order as yaw, then pitch, then roll, or heading, then inclination, then tilt,

This base class always returns kCC3VectorZero.

Declared In

CC3Rotator.h

rotationAngle

The angular rotation around the axis specified in the rotationAxis property.

@property (nonatomic, assign, readonly) GLfloat rotationAngle

Discussion

This base class always returns zero.

Declared In

CC3Rotator.h

rotationAxis

The axis of rotation of the node in 3D space, relative to the parent of this node, expressed as a directional vector. This axis can be used in conjunction with the rotationAngle property to describe the rotation as a single angular rotation around an arbitrary axis.

@property (nonatomic, assign, readonly) CC3Vector rotationAxis

Discussion

This base class always returns kCC3VectorZero.

Declared In

CC3Rotator.h

rotationMatrix

The rotation matrix derived from the rotation or quaternion properties. Rotation can be specified in terms of either of these properties, and read by either property, even if set by the other property. The matrix will reflect the rotational property most recently set.

@property (nonatomic, retain, readonly) CC3Matrix *rotationMatrix

Discussion

The rotation matrix for each instance is local to the node and does not include rotational information about the node’s ancestors.

This base class always returns nil. Subclasses that support changing rotation will override.

Declared In

CC3Rotator.h

shouldAutotargetCamera

Indicates whether the node should automatically find and track the camera as its target. If this property is set to YES, the node will automatically find and track the camera without having to set the target and shouldTrackTarget properties explicitly.

@property (nonatomic, assign, readonly) BOOL shouldAutotargetCamera

Discussion

Always returns NO. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

shouldRotateToTargetLocation

Returns whether the node should rotate to face a target location.

@property (nonatomic, readonly) BOOL shouldRotateToTargetLocation

Discussion

This implementation always returns NO. Subclasses that support target locations will override.

Declared In

CC3Rotator.h

shouldTrackTarget

Indicates whether the node should track the node set in the target property as the target and the node carrying this rotator move around.

@property (nonatomic, assign, readonly) BOOL shouldTrackTarget

Discussion

Always returns NO. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

shouldUpdateToTarget

Returns whether the node should update itself towards the target.

@property (nonatomic, readonly) BOOL shouldUpdateToTarget

Discussion

This implementation always returns NO. Subclasses that support targets will override.

Declared In

CC3Rotator.h

target

The target node at which this rotator is pointed.

@property (nonatomic, assign, readonly) CC3Node *target

Discussion

Always returns nil. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

targetLocation

The global location towards which this node is facing.

@property (nonatomic, readonly) CC3Vector targetLocation

Discussion

Always returns kCC3VectorNull. Subclasses that support target tracking will override.

Declared In

CC3Rotator.h

targettingConstraint

Indicates whether rotation should be constrained when attempting to rotate the node to point at the target or targetLocation.

@property (nonatomic, readonly) CC3TargettingConstraint targettingConstraint

Discussion

Always returns kCC3TargettingConstraintGlobalUnconstrained. Subclasses that support targetting will override.

Declared In

CC3Rotator.h

Class Methods

rotator

Allocates and initializes an autoreleased instance with an identity rotationMatrix.

+ (id)rotator

Declared In

CC3Rotator.h

Instance Methods

applyRotationTo:

Applies the rotationMatrix to the specified transform matrix. This is accomplished by multiplying the transform matrix by the rotationMatrix.

- (void)applyRotationTo:(CC3Matrix *)aMatrix

Discussion

This method is invoked automatically from the applyRotation method of the node. Usually, the application never needs to invoke this method directly.

Declared In

CC3Rotator.h

clearIfTarget:

If the specified node is the target node at which this rotator is pointed, the target of this rotator is set to nil.

- (BOOL)clearIfTarget:(CC3Node *)aNode

Discussion

This method is required in order to be able to clear the target without retrieving it outside this object to test if it is nil. Since the target is weakly referenced, it may be deallocated while this rotator still maintains a reference to it. Any subsequent attempt to retrieve the target reference may result in attempting to retain and autorelease it, particularly under ARC, which will create a zombie object error.

Declared In

CC3Rotator.h

fullDescription

Returns a string containing a more complete description of this rotator, including rotation properties.

- (NSString *)fullDescription

Declared In

CC3Rotator.h

populateFrom:

Template method that populates this instance from the specified other instance.

- (void)populateFrom:(CC3Rotator *)another

Discussion

This method is invoked automatically during object copying via the copy or copyWithZone: method. In most situations, the application should use the copy method, and should never need to invoke this method directly.

Subclasses that add additional instance state (instance variables) should extend copying by overriding this method to copy that additional state. Superclass that override this method should be sure to invoke the superclass implementation to ensure that superclass state is copied as well.

Declared In

CC3Rotator.h

transformDirection:

Rotates the specified direction vector, and returns the transformed direction.

- (CC3Vector)transformDirection:(CC3Vector)aDirection

Declared In

CC3Rotator.h