This is an abstract node class representing a 3D model node that can be pointed in a particular direction, such as a camera or light. More...
#import <CC3TargettingNode.h>
Public Member Functions | |
| (void) | - trackTarget |
Properties | |
| int | podTargetIndex |
| CC3Vector | rightDirection |
| BOOL | shouldTrackTarget |
| CC3Node * | target |
| CC3Vector | targetLocation |
| CC3Vector | upDirection |
| CC3Vector | worldUpDirection |
Detailed Description
The node can be pointed in a direction as an alternative to rotating the node.
Instances can be targetted at another node, and can track that node as both the target and this node move through the 3D world. For instance, if this targetting node was a camera, it could be pointed at another node representing a car, and could track that car as both the car or the camera were moved through the 3D world, always keeping the car in the center of the camera's vision.
There are three directions associated with a targetting node, and these appear as properties in this class. The forwardDirection is the direction that the node is pointing. This property can either be set directly, or indirectly by specifying a targetLocation, or better yet, and actual target node, each of which are settable properties on this node. It should be recognized that both target and targetLocation are simply means to an end in setting the forwardDirection.
But pointing the node in a particualr direction does not completely define its rotation in 3D space, because the node can be oriented in any rotation around the axis along the forwardDirection vector (think of pointing a camera at a scene, and then rotating the camera along the axis of its lens, landscape towards portrait).
This is solved by specifying an additional upDirection, which fixes the rotation around the forwardDirection by specifying which direction is considered to be 'up'. This is further simplified by fixing a worldUpDirection, which does not need to change. The local upDirection then becomes a read-only property calculated from the combination of the forwardDirection, and the worldUpDirection.
The third direction, the rightDirection, represents the direction that is "off to the right" if you were looking down the forwardDirection and 'up' was the upDirection. The rightDirection is calculated from this. Although not really needed, the rightDirection can be useful for some applications, and is provided as a read-only property for completeness.
The forwardDirection, upDirection and rightDirection form the orthagonal axes of the local rotated coordinate system of the node.
Member Function Documentation
| - (void) trackTarget |
If the shouldTrackTarget property is set to YES, orients this node to point towards its target, otherwise does nothing.
This method is invoked automatically if the either the target node or this node moves. Usually, the application should never need to invoke this method directly.
Property Documentation
- (CC3Vector) forwardDirection [read, write, assign] |
The direction in which this node is pointing, relative to the node's coordinate system, which is relative to the parent's rotation.
- (int) podTargetIndex [read, write, assign] |
The index of the node that is the target of this node.
This node will be linked to its target in the linkToPODNodes: method.
This abstract implementation does not map this property to an instance variable Concrete subclasses must override to map to an actual instance variable.
- (CC3Vector) rightDirection [read, assign] |
The direction in the node's coordinate system that would be considered to be "off to the right" relative to where this node is pointing, and what is considered to be 'up'.
This property is read-only, is extracted from the transform matrix, is generally of little use, but is included for completeness in describing the rotation of the node.
- (BOOL) shouldTrackTarget [read, write, assign] |
Indicates whether this instance should track the node set in the target property as the target and this node move around, or should initially point to that target, but should then maintain the same pointing direction, regardless of how the target or this node moves around.
Initially, this property is set to NO, indicating that if the target property is set, this node will initially point to it, but will not track it as it moves.
If this property is set to YES, subsequently changing the value of the rotation, quaternion, or forwardDirection properties will have no effect, since they would interfere with the ability to track the target. To set specific rotations or pointing direction, first set this property back to NO.
- (CC3Node *) target [read, write, retain] |
The target node at which this node is pointed.
If the shouldTrackTarget property is set to YES, this node will track the target so that it always points to the target, regardless of how the target and this node move through the 3D world.
- (CC3Vector) targetLocation [read, write, assign] |
The location of the target.
Instead of specifying a target node with the target property, this property can be used to set a specific location to point towards. This targetLocation is not tracked, and moving the targetting node will cause it to point away from the targetLocation.
When retrieving this property value, if the property was earlier explictly set, it will be retrieved cleanly. However, if rotation was set by Euler angles, quaternions, or forwardDirection, retriving the targetLocation comes with two caveats. The first is that calculating a targetLocation requires the global location of this node, which is only calculated when the node's transformMatrix is calculated after all model updates have been processed. This means that the calculated targetLocation will generally be one frame behind the real value. The second caveat is that the targetLocation requires extrapolating the forwardDirection out to an arbitrary invented point. This can sometimes introduce higher calculation inaccuracies. In general, it is best to use this property directly, both reading and writing it, rather than reading this property after setting one of the other rotational properties.
- (CC3Vector) upDirection [read, assign] |
The direction, in the node's coordinate system, that is considered to be 'up'.
This corresponds to the worldUpDirection, after it has been transformed by the transformationMatrix of this node. For example, rotating the node upwards to point towards an elevated target will move the upDirection of this node away from the worldUpDirection. See the discussion of 'up' vectors in the class notes above. This property is read-only.
- (CC3Vector) worldUpDirection [read, write, assign] |
The direction, in the global coordinate system, that is considered to be 'up'.
As explained above in the description of this class, specifying a forwardDirection is not sufficient to determine the rotation of a node in 3D space. This property indicates which direction should be considered 'up' when orienting the rotation of the node. Initially, this property is set to point parallel to the positive Y-axis, and in most cases, this property can be left with that value.
The documentation for this class was generated from the following file:
