CC3MutableRotator encapsulates the various mechanisms for specifiying rotation, and converts between them. More...
#import <CC3Rotator.h>
Public Member Functions | |
| (id) | - initOnRotationMatrix: |
| (void) | - markRotationDirty |
| (void) | - orthonormalize |
| (void) | - rotateBy: |
| (void) | - rotateByAngle:aroundAxis: |
| (void) | - rotateByQuaternion: |
Static Public Member Functions | |
| (GLubyte) | + autoOrthonormalizeCount |
| (id) | + rotatorOnRotationMatrix: |
| (void) | + setAutoOrthonormalizeCount: |
Protected Attributes | |
| BOOL | shouldAutotargetCamera: 1 |
| BOOL | shouldTrackTarget: 1 |
Properties | |
| BOOL | isRotationDirty: 1 |
| CC3Quaternion | quaternion |
| CC3Vector | rotation |
| GLfloat | rotationAngle |
| CC3Vector | rotationAxis |
| CC3Matrix * | rotationMatrix |
Detailed Description
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 transformMatrix, 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.
Member Function Documentation
| + (GLubyte) autoOrthonormalizeCount |
Indicates how often the basis vectors of the underlying rotation matrix should be orthonormalized.
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.
| - (id) initOnRotationMatrix: | (CC3Matrix *) | aMatrix |
Initializes this instance to use the specified matrix as the rotationMatrix.
| - (void) markRotationDirty |
Indicates that the rotation matrix is dirty and needs to be recalculated.
This method is invoked automatically as needed. Usually the application never needs to invoke this method directly.
| - (void) orthonormalize |
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).
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.
| - (void) rotateBy: | (CC3Vector) | aRotation |
Rotates this rotator from its current state by the specified Euler angles in degrees.
| - (void) rotateByAngle: | (GLfloat) | anAngle | |
| aroundAxis: | (CC3Vector) | anAxis | |
Rotates this rotator from its current state by rotating around the specified axis by the specified angle in degrees.
| - (void) rotateByQuaternion: | (CC3Quaternion) | aQuaternion |
Rotates this rotator from its current state by the specified quaternion.
| + (id) rotatorOnRotationMatrix: | (CC3Matrix *) | aMatrix |
Allocates and initializes an autoreleased instance to use the specified matrix as the rotationMatrix.
| + (void) setAutoOrthonormalizeCount: | (GLubyte) | aCount |
Sets how often the basis vectors of the underlying rotation matrix should be orthonormalized.
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.
Member Data Documentation
- (BOOL) shouldAutotargetCamera [protected] |
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.
Always returns NO. Subclasses that support target tracking will override.
Implements CC3Rotator.
Implemented in CC3TargettingRotator.
- (BOOL) shouldTrackTarget [protected] |
Indicates whether the node should track the node set in the target property as the target and the node carrying this rotator move around.
Always returns NO. Subclasses that support target tracking will override.
Implements CC3Rotator.
Implemented in CC3TargettingRotator.
Property Documentation
- (BOOL) isRotationDirty [read, assign] |
Indicates whether the rotation matrix is dirty and needs to be recalculated.
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.
- (CC3Quaternion) quaternion [read, write, assign] |
The rotation of the node in 3D space, relative to the parent of this node, expressed as a quaternion.
Implements CC3Rotator.
- (CC3Vector) rotation [read, write, assign] |
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.
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.
Implements CC3Rotator.
- (GLfloat) rotationAngle [read, write, assign] |
The angular rotation around the axis specified in the rotationAxis property.
When setting this value, it is converted to modulo +/-360 degrees.
Implements CC3Rotator.
- (CC3Vector) rotationAxis [read, write, assign] |
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.
Implements CC3Rotator.
- (CC3Matrix *) rotationMatrix [read, write, retain] |
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.
The rotation matrix for each instance is local to the node and does not include rotational information about the node's ancestors.
Implements CC3Rotator.
The documentation for this class was generated from the following file:
