CC3Node and its subclasses form the basis of all 3D artifacts in the 3D world, including visible meshes, structures, cameras, lights, resources, and the 3D world itself. More...
#import <CC3Node.h>
Detailed Description
Nodes can be moved, rotated and scaled. Rotation can be specified via either Euler angles or quaternions.
Nodes can be assembled in a structural hierarchy of parents and children, and transformations that are applied to a node are also applied to its descendant nodes. Typically, the root of a structural node hierarchy is an instance of CC3World.
Each node is distinctly touched twice during animation frame handling, once for updating model state via the update: method, and once during frame rendering, via the visitWithVisitor: method. To maximize throughput, the operations of updating model state should be kept separate from the operations of frame rendering, and the two should not be mixed.
Subclasses should respect this design pattern when overriding behaviour. Drawing operations should not be included in state updating, and vice versa. Since OpenGL is a hardware-accelerated state-machine pipeline, this separation allows frame-drawing operations to be performed by the GPU at the same time that state update operations for the next frame are being handled by the CPU, and on some systems, permits frame drawing and model updating to be perfomed on separate threads.
CC3Nodes support the cocos2d CCAction class hierarchy. Nodes can be translated, rotated, and scaled in three dimensions, or made to point towards a direction (for cameras and lights), all under control of cocos2d CCActions. As with other CCActions, these actions can be combined into action sequences or repeating actions, or modified with cocos2d ease actions. See the class CC3TransformTo and its subclasses for actions that operate on CC3Nodes.
To maximize GL throughput, all OpenGL ES 1.1 state is tracked by the singleton instance [CC3OpenGLES11Engine engine]. CC3OpenGLES11Engine only sends state change calls to the GL engine if GL state really is changing. It is critical that all changes to GL state are made through the CC3OpenGLES11Engine singleton. When adding or overriding functionality in this framework, do NOT make gl* function calls directly if there is a corresponding state change tracker in the CC3OpenGLES11Engine singleton. Route the state change request through the CC3OpenGLES11Engine singleton instead.
Member Function Documentation
| - (void) addChild: | (CC3Node *) | aNode |
Adds the specified node as a direct child node to this node.
| - (void) createGLBuffers |
Creates OpenGL ES buffers to be used by the GL engine hardware.
Default behaviour is to invoke the same method on all child nodes. Subclasses that can make use of hardware buffering, notably mesh subclasses, will override and bind their data to GL hardware buffers.
Invoking this method is optional and is not performed automatically. If an application does not wish to use hardware buffering for some nodes, it can do so by avoiding the invocation of this method on those nodes. Typically, however, an applicaiton will simply invoke this method once during initialization of highest-level ancestor node (ususally a subclass of CC3World).
| - (void) deleteGLBuffers |
Deletes any OpenGL buffers that were created by any child nodes via a prior invocation of createGLBuffers.
If the child nodes also retained the data locally, drawing will then revert to distinct GL draw calls, passing data through the GL API on each call, rather than via the bound buffers.
| - (void) disableAllPODAnimation |
Disables animation of this node, and all descendant nodes, from animation data found in the POD file.
Initially, POD animation is enabled for all nodes with POD animation data.
| - (void) disablePODAnimation |
Disables animation of this node from animation data found in the POD file.
This will not disable animation of child nodes. Initially, POD animation is enabled for all nodes with POD animation data.
| - (BOOL) doesIntersectFrustum: | (CC3Frustum *) | aFrustum |
Returns whether the local content of this node intersects the given frustum.
This check does not include checking children, only the local content.
This method is called during the drawing operations of each frame to determine whether this node should be culled from the visible nodes and not drawn. A return value of YES will cause the node to be drawn, a return value of NO will cause the node to be culled and not drawn.
Culling nodes that are not visible to the camera is an important performance enhancement. The node should strive to be as accurate as possible in returning whether it intersects the camera's frustum. Incorrectly returning YES will cause wasted processing within the GL engine. Incorrectly returning NO will cause a node that should at least be partially visible to not be drawn.
In this implementation, if this node has a boundingVolume, this method delegates to it. Otherwise, it simply returns YES. Subclasses may override to change this standard behaviour.
| - (void) enableAllPODAnimation |
Enables animation of this node, and all descendant nodes, from animation data found in the POD file.
Initially, POD animation is enabled for all nodes with POD animation data.
| - (void) enablePODAnimation |
Enables animation of this node from animation data found in the POD file.
This will not enable animation of child nodes. Initially, POD animation is enabled for all nodes with POD animation data.
| - (void) establishPODAnimationFrameAt: | (ccTime) | t |
Updates the location, rotation and scale of this node 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.
Only those properties of this node for which there is animation data will be changed. Linear interpolation of the frame data is performed, based on the number of frames and the specified time.
Delegates to the CC3PODNodeAnimation instance held in the podAnimation property, then passes this notification along to child nodes to align them with the same animation frame.
If disablePODAnimation or disableAllPODAnimation has been invoked on this node, it will be excluded from animation, and this method will not have any affect on this node. However, this method will be propagated to child nodes.
This method is invoked automatically from an instance of CC3PODAnimate that is animating this node. Usually, the application never needs to invoke this method directly.
| - (NSArray*) flatten |
Returns an autoreleased array containing this node and all its descendants.
This is done by invoking flattenInto: with a newly-created array, and returning the array.
| - (void) flattenInto: | (NSMutableArray *) | anArray |
Adds this node to the specified array, and then invokes this method on each child node.
The effect is to populate the array with this node and all its descendants.
| - (CCAction*) getActionByTag: | (int) | tag |
Gets an action from the running action list given its tag.
| - (CC3Node*) getNodeNamed: | (NSString *) | aName |
Retrieves the first node found with the specified name, anywhere in the structural hierarchy of descendants of this node (not just direct children).
The hierarchy search is depth-first.
| - (CC3Node*) getNodeTagged: | (GLuint) | aTag |
Retrieves the first node found with the specified tag, anywhere in the structural hierarchy of descendants of this node (not just direct children).
The hierarchy search is depth-first.
| - (void) linkToPODNodes: | (NSArray *) | nodeArray |
Create links to the nodes in the specified array.
This implementation attaches this node to its parent as identified by the podParentIndex property. Subclasses may override to perform other linking.
| + (id) node |
Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value.
The tag value is generated using a call to nextTag.
| + (id) nodeAtIndex: | (int) | aPODIndex | |
| fromPODResource: | (CC3PODResource *) | aPODRez | |
Allocates and initializes an autoreleased instance from the data of this type at the specified index within the specified POD resource.
| - (PODStructPtr) nodePODStructAtIndex: | (uint) | aPODIndex | |
| fromPODResource: | (CC3PODResource *) | aPODRez | |
Returns the underlying SPODNode data structure from the specified resource, for the SPODNode at the specified index.
The returned pointer must be cast to SPODNode before accessing any internals of the data structure.
| + (id) nodeWithName: | (NSString *) | aName |
Allocates and initializes an autoreleased instance with the specified name and an automatically generated unique tag value.
The tag value is generated using a call to nextTag.
| + (id) nodeWithTag: | (GLuint) | aTag |
Allocates and initializes an unnamed autoreleased instance with the specified tag.
| + (id) nodeWithTag: | (GLuint) | aTag | |
| withName: | (NSString *) | aName | |
Allocates and initializes an autoreleased instance with the specified tag and name.
| - (int) numberOfRunningActions |
Returns the numbers of actions that are running plus the ones that are scheduled to run (actions in actionsToAdd and actions arrays).
Composable actions are counted as 1 action. Example: If you are running 1 Sequence of 7 actions, it will return 1. If you are running 7 Sequences of 2 actions, it will return 7.
| - (void) removeAllChildren |
Removes all child nodes of this node.
| - (void) removeChild: | (CC3Node *) | aNode |
Removes the specified node as a direct child node to this node.
| + (id) rotatorClass |
Rotation tracking for each node is handled by a encapsulated instance of CC3Rotator.
This method returns the subclass of CC3Rotator that will be instantiated and used by instances of this node class. The default is CC3Rotator, but subclasses my override to establish other rotational tracking functionality.
| - (CCAction*) runAction: | (CCAction *) | action |
Executes an action, and returns the action that is executed.
The node becomes the action's target.
| - (void) stopAction: | (CCAction *) | action |
Removes an action from the running action list.
| - (void) stopActionByTag: | (int) | tag |
Removes an action from the running action list given its tag.
| - (void) stopAllActions |
Removes all actions from the running action list.
| - (void) update: | (ccTime) | dt |
This template method is invoked periodically when the nodes of an application are to be updated.
The dt argument gives the interval, in seconds, since the previous update. This value can be used to create realistic real-time motion that is independent of specific frame or update rates. Depending on the setting of the maxUpdateInterval property of the CC3World instance, the value of dt may be clamped to an upper limit before being passed to this method. See the description of the CC3World maxUpdateInterval property for more information about clamping the update interval.
This abstract template implementation does nothing. Subclasses that act predictively, such as those undergoing trajectories, IPO curves, or animation can update their location, rotation and status accordingly. Subclasses that override do not need to invoke this superclass implementation.
As described in the class documentation, in keeping with best practices, updating the model state should be kept separate from frame rendering. Therefore, when overriding this method in a subclass, do not perform any drawing or rending operations. This method should perform model updates only.
This method is invoked automatically by the updateAndTransform:withTransformedAncestor: method. Usually, the application never needs to invoke this method directly.
| - (void) updateAndTransform: | (ccTime) | dt | |
| withTransformedAncestor: | (BOOL) | wasAncestorDirty | |
This method is invoked periodically when the nodes of an application are to be updated.
The dt argument gives the interval, in seconds, since the previous update. This value can be used to create realistic real-time motion that is independent of specific frame or update rates. Depending on the setting of the maxUpdateInterval property of the CC3World instance, the value of dt may be clamped to an upper limit before being passed to this method. See the description of the CC3World maxUpdateInterval property for more information about clamping the update interval.
The wasAncestorDirty flag indicates whether the transform of an ancestor was changed. Changes to ancestor transforms have an impact on the transformMatrix of this instance.
This implementation performs the following activites, in order:
- Invokes update: on this instance to give the instance a chance to update its transform properties. This step can be suppressed by passing the constant kCC3NoUpdate as the dt value to udpateAndTransform:withTransformedAncestor:.
- If changes were made to the transform properties (location, rotation and scale), or to those of an ancestor, as indicated by the wasAncestorDirty flag, the transformMatrix is recalculated.
- If this instance has child nodes, this method is invoked on those child nodes to allow them to update and recalculate their transforms.
Invocation of this method is automatically triggered by the CC3World instance at the root of the node structural assembly. Usually, the application never needs to invoke this method directly.
| - (void) visitWithVisitor: | (CC3NodeDrawingVisitor *) | visitor |
Draws or applies this node to the GL engine.
To avoid unnecessary drawing operations, this node will only be drawn if the node:
- is visible (as indicated by the visible property)
- has content to draw (as indicated by the hasLocalContent property)
- intersects the camera's frustum (which is checked by invoking the method doesIntersectFrustum: of this node).
If all of these tests pass, drawing is required, and this method transforms and draws the local content of this node.
If this node is visible and the visitor indicates that children should also be drawn, this method then passes this notificaton along to the child nodes.
Property Documentation
- (CC3NodeBoundingVolume *) boundingVolume [read, write, retain] |
The bounding volume of this node.
This may be used by culling during drawing operations, or by physics simulations. Different shapes of boundaries are available, permitting tradeoffs between accuracy and computational processing time. By default, nodes do not have a bounding volume. Subclasses may set a suitable bounding volume.
- (NSArray*) children [read, assign] |
The child nodes of this node, in a node structural hierarchy.
- (CC3Vector) globalLocation [read, assign] |
The location of the node in 3D space, relative to the global origin.
This is calculated by using the transformMatrix to translate the global origin (0,0,0).
- (CC3Vector) globalRotation [read, assign] |
The rotation of the node in 3D space, relative to the global X, Y & Z axes.
This is extracted from the transformMatrix. This value contains three Euler angles, defining a global rotation of this node around the X, Y and Z axes. Each angle is specified in degrees.
- (CC3Vector) globalScale [read, assign] |
The scale of the node in 3D space, relative to the global coordinate system, and accumulating the scaling of all ancestor nodes.
- (BOOL) hasLocalContent [read, assign] |
Indicates whether this node has local content that will be drawn.
Default value is NO. Subclasses that do draw content will override to return YES.
- (BOOL) isBasePODNode [read, assign] |
Indicates whether this POD is a base node, meaning that it has no parent.
- (BOOL) isMeshNode [read, assign] |
Indicates whether this node has 3D mesh data to be drawn.
Default value is NO. Subclasses that do draw 3D meshes will override to return YES.
- (BOOL) isTransformRigid [read, assign] |
Indicates whether the current transform applied to this node transform is rigid, meaning that it includes only rotation and translation transformations, and does not include any scaling transformations.
This takes into consideration the transforms of all ancestors.
- (BOOL) isUniformlyScaledGlobally [read, assign] |
Indicates whether current global scaling (via the globalScale property) is uniform along all axes.
This takes into consideration the scaling of all ancestors.
- (BOOL) isUniformlyScaledLocally [read, assign] |
Indicates whether current local scaling (via the scale property) is uniform along all axes.
This does not take into consideration the scaling of any ancestors.
- (CC3Vector) location [read, write, assign] |
The location of the node in 3D space, relative to the parent of this node.
The global location of the node is therefore a combination of the global location of the parent of this node and the value of this location property.
- (CC3Node *) parent [read, write, assign] |
The parent node of this node, in a node structural hierarchy.
- (CC3PODNodeAnimation*) podAnimation [read, write, retain] |
The animation content of this node, which manages animating the node, as defined in the POD file.
This abstract implementation does not map this property to a retained instance variable Concrete subclasses must override to map to an actual retained instance variable.
- (int) podContentIndex [read, write, assign] |
The index of the POD data that forms the type-specific content of this node.
This is distinct from the podIndex property, which is the index of the data for the node, which may be of any node type. Once the type is established, the type-specific content is indexed by the podContentIndex property.
This abstract implementation does not map this property to an instance variable Concrete subclasses must override to map to an actual instance variable.
- (int) podParentIndex [read, write, assign] |
The index of the parent node of this node.
This will be -1 if this node has no parent.
This abstract implementation does not map this property to an instance variable Concrete subclasses must override to map to an actual instance variable.
- (CGPoint) projectedPosition [read, write, assign] |
The current position of the 3D node as projected into the 2D viewport coordinate space.
For most purposes, this is where the node will appear on the screen or window.
The application should usually not set this property directly, but should instead call the projectNode: method of the active CC3Camera instance to have this property calculated. The active camera can be retrieved from the CC3World.
- (CC3Vector4) quaternion [read, write, assign] |
The rotation of the node in 3D space, relative to the parent of this node, expressed as a quaternion.
Rotational transformation can also be specified as Euler angles using the rotation property. Subsequently, this quaternion property can then be read to return the corresponding quaternion.
- (CC3Vector) rotation [read, write, assign] |
The rotational orientation of the node in 3D space, relative to the parent of this node.
The global rotation of the node is therefore a combination of the global rotation of the parent of this node and the value of this rotation property. This value contains three Euler angles, defining a rotation of this nodearound the X, Y and Z axes. Each angle is specified in degrees.
Rotational transformation can also be specified using the quaternion property. Subsequently, this rotation property can then be read to return the corresponding Euler angles.
- (CC3Vector) scale [read, write, assign] |
The scale of the node in each dimension, relative to the parent of this node.
- (CC3GLMatrix *) transformMatrix [read, write, retain] |
The transformation matrix derived from the location, rotation and scale transform properties of this node and any ancestor nodes.
This matrix is recalculated by invoking updateAndTransform:withTransformedAncestor:, which is invoked automatically by the parent CC3World instance.
The transformation matrix for each node is global, in that it includes the transforms of all ancestors to the node. This streamlines rendering in that it allows the transform of each drawable node to be applied directly, and allows the order in which drawable nodes are drawn to be independent of the node structural hierarchy.
- (GLfloat) uniformScale [read, write, assign] |
The scale of the node, uniform in each dimension, relative to the parent of this node.
Unless non-uniform scaling is needed, it is preferable to use this property instead of the scale property.
If non-uniform scaling is applied via the scale property, this uniformScale property will return the length of the scale property vector divided by the length of a unit cube (sqrt(3.0)), as an approximation of the overall scaling condensed to a single scalar value.
- (BOOL) visible [read, write, assign] |
Controls whether this node shoud be displayed.
Initial value is YES. The application can set this to NO to make the node invisible and stop it from being displayed, and also to stop rendering processing on that node. When reading this property, the return value takes into consideration whether the parent is visible. As a result, setting this property to YES and then reading it may return NO if an ancestor has visibility set to NO.
The documentation for this class was generated from the following file:
