CC3MutableRotator Class Reference
| Inherits from | CC3Rotator : NSObject |
| Declared in | CC3Rotator.h |
Overview
CC3MutableRotator encapsulates the various mechanisms for specifiying rotation, and converts between them.
Rotations can be specified in any of the following methods: – three Euler angles – rotation angle around an arbitrary rotation axis – quaternion Subclasses may also specify other rotational mechanisms (such as pointing).
The rotator maintains an internal rotationMatrix, separate from the node’s globalTransformMatrix, and the rotator can use this rotationMatrix to convert between different rotational specifications. As such, the rotation of a node can be set using any one of the above specifications, and read back as any of the other specifications.
Tasks
-
rotationMatrixproperty -
rotationproperty -
quaternionproperty -
rotationAxisproperty -
rotationAngleproperty -
– rotateBy: -
– rotateByQuaternion: -
– rotateByAngle:aroundAxis: -
isRotationDirtyproperty -
– markRotationDirty -
– orthonormalize -
+ autoOrthonormalizeCount -
+ setAutoOrthonormalizeCount: -
– initOnRotationMatrix: -
+ rotatorOnRotationMatrix:
Properties
isRotationDirty
Indicates whether the rotation matrix is dirty and needs to be recalculated.
@property (nonatomic, readonly) BOOL isRotationDirtyDiscussion
This property is automatically set to YES when one of the rotation properties or operations have been changed, and is reset to NO once the rotationMatrix has been recalculated.
Declared In
CC3Rotator.hquaternion
The rotation of the node in 3D space, relative to the parent of this node, expressed as a quaternion.
@property (nonatomic, assign, readwrite) CC3Quaternion quaternionDeclared In
CC3Rotator.hrotation
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, readwrite) CC3Vector rotationDiscussion
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,
When setting this value, each component is converted to modulo +/-360 degrees.
Declared In
CC3Rotator.hrotationAngle
The angular rotation around the axis specified in the rotationAxis property.
@property (nonatomic, assign, readwrite) GLfloat rotationAngleDiscussion
When setting this value, it is converted to modulo +/-360 degrees.
Declared In
CC3Rotator.hrotationAxis
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, readwrite) CC3Vector rotationAxisDeclared In
CC3Rotator.hrotationMatrix
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, readwrite) CC3Matrix *rotationMatrixDiscussion
The rotation matrix for each instance is local to the node and does not include rotational information about the node’s ancestors.
Declared In
CC3Rotator.hClass Methods
autoOrthonormalizeCount
Indicates how often the basis vectors of the underlying rotation matrix should be orthonormalized.
+ (GLubyte)autoOrthonormalizeCountDiscussion
If this property is set to a value greater than zero, this rotator keeps track of how many times one of the rotateBy… family of methods of a CC3MutableRotator has been invoked. When that count reaches the value of this property, the orthonormalize method is invoked to orthonormalize the underlying matrix, and the count is set back to zero to start the cycle again. See the notes for the CC3MutableRotator orthonormalize method for a further discussion of orthonormalization.
If this property is set to zero, orthonormalization will not occur automatically. The application can invoke the orthonormalize method to cause the rotation matrix to be orthonormalized manually.
The initial value of this property is zero, indicating that orthonormalization will not occur automatically.
Declared In
CC3Rotator.hrotatorOnRotationMatrix:
Allocates and initializes an autoreleased instance to use the specified matrix as the rotationMatrix.
+ (id)rotatorOnRotationMatrix:(CC3Matrix *)aMatrixDeclared In
CC3Rotator.hsetAutoOrthonormalizeCount:
Sets how often the basis vectors of the underlying rotation matrix should be orthonormalized.
+ (void)setAutoOrthonormalizeCount:(GLubyte)aCountDiscussion
If this property is set to a value greater than zero, this rotator keeps track of how many times one of the rotateBy… family of methods of a CC3MutableRotator has been invoked. When that count reaches the value of this property, the orthonormalize method is invoked to orthonormalize the underlying matrix, and the count is set back to zero to start the cycle again. See the notes for the CC3MutableRotator orthonormalize method for a further discussion of orthonormalization.
If this property is set to zero, orthonormalization will not occur automatically. The application can invoke the orthonormalize method to cause the rotation matrix to be orthonormalized manually.
The initial value of this property is zero, indicating that orthonormalization will not occur automatically.
Declared In
CC3Rotator.hInstance Methods
initOnRotationMatrix:
Initializes this instance to use the specified matrix as the rotationMatrix.
- (id)initOnRotationMatrix:(CC3Matrix *)aMatrixDeclared In
CC3Rotator.hmarkRotationDirty
Indicates that the rotation matrix is dirty and needs to be recalculated.
- (void)markRotationDirtyDiscussion
This method is invoked automatically as needed. Usually the application never needs to invoke this method directly.
Declared In
CC3Rotator.horthonormalize
When a large number of incremental rotations are applied to a rotator using the rotateBy… family of methods, accumulated rounding errors can cause the basis vectors of the underlying rotation matrix to lose mutual orthogonality (no longer be orthogonal to each other), and to become individually unnormalized (no longer be unit vectors).
- (void)orthonormalizeDiscussion
Although uncommon, it is possible for visible errors to creep into the rotation of this rotator, after many, many incremental rotations.
If this happens, you can invoke this method to orthonormalize the basis vectors of the underlying rotation matrix.
Instead of keeping track of when to invoke this method within the application, you can also set the class-side autoOrthonormalizeCount property to have this method automatically invoked periodically.
Upon completion of this method, each basis vector in the underlying matrix will be a unit vector that is orthagonal to the other two basis vectors in this matrix.
Error creep only appears through repeated use of the the rotateBy… family of methods. Error creep does not occur when the rotation is set explicitly through any of the rotation properties (rotation, quaternion, rotationAxis/rotationAngle, etc), as these properties populate the rotation matrix directly in orthonormal form each time then are set. Use of this method is not needed if rotations have been set directly using these properties, even when set many times.
This method uses using a Gram-Schmidt process to orthonormalize the basis vectors of the underlying rotation matrix. The Gram-Schmidt process is biased towards the basis vector chosen to start the calculation process. To minimize the effect of this, this implementation chooses a different basis vector to start the orthonormalization process each time this method is invoked, to average the bias across all basis vectors over time.
Declared In
CC3Rotator.hrotateBy:
Rotates this rotator from its current state by the specified Euler angles in degrees.
- (void)rotateBy:(CC3Vector)aRotationDeclared In
CC3Rotator.h