CC3World is a CC3Node that manages a 3D scene. More...
#import <CC3World.h>
Public Member Functions | |
| (void) | - addContentFromPODFile: |
| (void) | - addContentFromPODResourceFile: |
| (void) | - drawWorld |
| (void) | - initializeWorld |
| (void) | - nodeSelected:byTouchEvent:at: |
| (void) | - pause |
| (void) | - play |
| (void) | - touchEvent:at: |
| (void) | - updateWorld: |
Static Public Member Functions | |
| (id) | + world |
Properties | |
| CC3Camera * | activeCamera |
| ccColor4F | ambientLight |
| CC3NodeSequencer * | drawingSequencer |
| BOOL | isRunning |
| BOOL | isUsingDrawingSequence |
| ccTime | maxUpdateInterval |
| CC3PerformanceStatistics * | performanceStatistics |
| CC3ViewportManager * | viewportManager |
Detailed Description
CC3World is a CC3Node that manages a 3D scene.
CC3World has the following responsibilities:
- Acts as the root of the CC3Node structural assembly for the scene
- Manages updating scene activity, including nodes, lights, and the camera based on a periodic animation trigger from the CC3Layer
- Manages the drawing of the 3D artifacts to the GL engine
- Manages the transition from 2D to 3D behaviour during each drawing frame
- Manages the ordering of drawing of the 3D objects to maximize performance
- facilitates user interaction with the world by interacting with UI events occuring in the CC3Layer controls
- supports selection of 3D nodes via UI touch events
- collects performance statistics
When creating a 3D application, you will almost always create a subclass of CC3World to define the control, features, and behaviour of your 3D world suitable to your application. In your CC3World subclass, your will typically override one or more of the following template methods:
- initializeWorld - assemble the objects of your 3D world, or load them from files.
- updateBeforeTransform: - periodically update the activity of your 3D world prior to the automatic recalulation of the node's transformation matrix, and prior to the automatic invoking the same method on each of child node of this node.
- updateAfterTransform: - periodically update the activity of your 3D world after the automatic recalulation of the node's transformMatrix and prior to the automatic invoking the same method on each of child node of this node.
In these methods, you can manipulate most nodes by setting their properties. You can move and orient nodes using the node's location, rotation and scale properties, and can show or hide nodes with the node's visible property.
You should override the udpateBeforeTransform: method if you need to make changes to the transform properties (location, rotation, scale), of any node. These changes will them automatically be applied to the transformMatrix of the node and its child nodes.
You should override the updateAfterTransform: method if you need access to the global transform properties (globalLocation, globalRotation, globalScale), of a node since these properties are only valid after the transformMatrix has been recalculated. An example of where access to the global transform properties would be useful is in the execution of collision detection algorithms.
To access nodes in your world, you can use the method getNodeNamed: on the CC3World (or any node). However, if you need to access the same node repeatedly, for example to update it on every frame, it's highly recommended that you retrieve it once and then cache it in an instance variable in your CC3World instance.
By default, the initializeWorld, updateBeforeTransform:, and updateAfterTransform: methods do nothing. Subclasses do not need to invoke this default superclass implementations in the overridden methods. The updateBeforeTransform: and updateAfterTransform: methods are defined in the CC3Node class. See the documentation there.
You must add at least one CC3Camera to your 3D world to make it viewable. This camera may be added directly, or it may be added as part of a larger node assembly. Regardless of the technique used to add cameras, the CC3World will take the first camera added and automatically make it the activeCamera.
The camera can also be used to project global locations within the 3D world onto a 2D point on the screen view, and can be used to project 2D screen points onto a ray or plane intersection within the 3D world. See the class notes of CC3Camera for more information on mapping between 3D and 2D locations.
During drawing, the nodes can be traversed in the hierarchical order of the node structural assembly, starting at the CC3World instance that forms the root node of the node assembly. Alternately, and preferrably, the CC3World can use a CC3NodeSequencer instance to arrange the nodes into a linear sequence, ordered and grouped based on definable sorting priorities. This is beneficial, because it allows the application to order and group drawing operations in ways that reduce the number and scope of state changes within the GL engine, thereby improving performance and throughput.
For example, when drawing, nodes could be grouped by the drawing sequencer so that opaque objects are drawn prior to blended objects, and an application with many objects that use the same material or mesh can be sorted so that nodes with like materials or meshes are grouped together. It is highly recommended that you use a CC3NodeSequencer, and this is the default configuration for CC3World instances.
The CC3World maintains this drawing sequence separately from the hierarchical node assembly. This allows the maintenance of the hierarchical parent-child relationships for operations such as movement and transformations, while simultaneously enabling more efficient drawing operations through node drawing sequencing.
An instance of CC3World is held by an instance of CC3Layer, which is a subclass of the cocos2d CCLayer class, and can participate with other cocos2d layers and CCNodes in an overall cocos2d scene. During drawing, the CC3Layer delegates all 3D operations to its CC3World instance. You will also typically create a subclass of CC3Layer that is customized for your application. In most cases, you will add methods and state to both your CC3World and CC3Layer subclasses to facilitate user interaction.
The CC3Layer and CC3World can process touch events to select the 3D node visible under the touch point. To enable touch selection of 3D nodes, set the isTouchEnabled property of your customized CC3Layer to YES, and set the isTouchEnabled property to YES on any node that you wish to be selectable via touch events. Subsequently, whenever a touch event occurs, the callback method nodeSelected:byTouchEvent:at: will be invoked on your customized CC3World instance. See the description of the nodeSelected:byTouchEvent:at: method and the CC3Node isTouchEnabled property for useful hints about choosing which nodes to enable for touch selection.
Since the touch-move events are both voluminous and seldom used, the implementation of ccTouchMoved:withEvent: has been left out of the default CC3Layer implementation. To receive and handle touch-move events for object picking, copy the commented-out ccTouchMoved:withEvent: template method implementation in CC3Layer to your customized CC3Layer subclass.
Depending on the complexity of the application, it may instantiate a single CC3World, instance, or multiple instances if the application progresses from scene to scene. Similarly, the application may have a single CC3Layer, or multiple CC3Layers. Each CC3Layer may have its own CC3World instance, or may share a single instance.
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.
You can collect statistics about the performance of your cocos3d application by setting the performanceStatistics property to an appropriate instance of a statistics collector. By default, no statistics are collected. See the notes of the performanceStatistics property for more information.
Member Function Documentation
| - (void) addContentFromPODFile: | (NSString *) | aFilepath |
Instantiates an instance of CC3PODResourceNode, loads it from the POD file at the specified path, which must be an absolute path, and adds the CC3PODResourceNode instance as a child node to this CC3World instance.
| - (void) addContentFromPODResourceFile: | (NSString *) | aRezPath |
Instantiates an instance of CC3PODResourceNode, loads it from the POD file at the specified resource path, and adds the CC3PODResourceNode instance as a child node to this CC3World instance.
The specified file path is a path relative to the resource directory. Typically this means that the specified path can just be the name of the file, with no path information.
| - (void) drawWorld |
This method is invoked periodically when the objects in the CC3World are to be drawn.
Typcially this method is invoked automatically from the draw method of the CC3Layer instance. This method is invoked asynchronously to the model updating loop, to keep the processing of OpenGL ES drawing separate from model updates.
This implementation invokes drawWithVisitor: with a CC3NodeDrawingVisitor containing the activeCamera's frustum. Does nothing if the visible property of this instance is NO.
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 overriding this method, or any other 3D drawing features, 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.
This method is invoked automatically during each rendering frame. Usually, the application never needs to invoke this method directly.
| - (void) initializeWorld |
This template method is where a subclass should populate the 3D world models.
This can be accomplished through a combination of instantiting model objects directly and loading them from model data files exported from a 3D editor.
This CC3World instance forms the base of a structural tree of nodes. Model objects are added as nodes to this root node instance using the addChild: method.
When loading from files, or adding large node assemblies, you can access individual nodes using the getNodeNamed: method, if you need to set futher initial state.
If you will need to access the same node repeatedly, for example to update it on every frame, it's highly recommended that you retrieve it once in this method, and cache it in an instance variable in your CC3World subclass instance.
You must add at least one CC3Camera to your 3D world to make it viewable. This can be instantiated directly, or loaded from a file as part of a node assembly.
By default, this method does nothing. Subclasses do not need to invoke this default superclass implementation in the overridden method.
| - (void) nodeSelected: | (CC3Node *) | aNode | |
| byTouchEvent: | (uint) | touchType | |
| at: | (CGPoint) | touchPoint | |
This callback template method is invoked when a node has been picked as a result of a touch event.
The specified node will be one of the visible nodes whose isTouchable property returns YES, or will be nil if the touch event occurred in an area under which there is no 3D node that is touch enabled.
For node assemblies, the specified node will be not necessarily be the individual component or leaf node that was touched. The specified node will be the closest structural ancestor of the leaf node that has the isTouchEnabled property set to YES.
For example, if the node representing a wheel of a car is touched, it may be more desireable to identify the car as being the object of interest to be selected, instead of the wheel. In this case, setting the isTouchEnabled property to YES on the car, but to NO on the wheel, will allow the wheel to be touched, but the node received by this callback will be the car structural node.
The touchType is one of the enumerated touch types: kCCTouchBegan, kCCTouchMoved, kCCTouchEnded, or kCCTouchCancelled. The touchPoint is the location in 2D coordinate system of the CC3Layer where the touch occurred.
This callback is received as part of the update processing loop, and is invoked before the invocation of either the updateBeforeTransform: and updateAfterTransform: methods. This callback is invoked only once per event.
To enable touch events, set the isTouchEnabled property of the CC3Layer.
Also, since the touch-move events are both voluminous and seldom used, the implementation of ccTouchMoved:withEvent: has been left out of the default CC3Layer implementation. To receive and handle touch-move events for object picking, copy the commented-out ccTouchMoved:withEvent: template method implementation in CC3Layer to your customized CC3Layer subclass.
To enable a node to be selectable by touching, set the isTouchEnabled property of that node, or an ancestor node to YES.
This implementation does nothing. Subclasses that are interested in node picking will override.
This method is invoked automatically whenever a touch event occurs. Usually, the application never needs to invoke this method directly.
| - (void) pause |
Pauses the dynamics of the 3D world model by setting the isRunning property to NO.
This does not affect the movement of nodes controlled by CCActionIntervals.
| - (void) play |
Starts the dynamics of the 3D world model by setting the isRunning property to YES.
| - (void) touchEvent: | (uint) | touchType | |
| at: | (CGPoint) | touchPoint | |
This method is invoked from the CC3Layer whenever a touch event occurs, if that layer has indicated that it is interested in receiving touch events.
The touchType is one of the enumerated touch types: kCCTouchBegan, kCCTouchMoved, kCCTouchEnded, or kCCTouchCancelled.
This default implementation engages a node picking mechanism, which determines which 3D node is under the touch point. Object picking is handled asynchronously, and once the node is retrieved, the nodeSelected:byTouchEvent:at: callback method will be invoked on this instance.
To enable touch events, set the isTouchEnabled property of the CC3Layer.
This method is invoked automatically whenever a touch event occurs. Usually, the application never needs to invoke this method directly.
| - (void) updateWorld: | (ccTime) | dt |
This method is invoked periodically when the components in the CC3World are to be updated.
Typcially this method is invoked automatically from a CC3Layer instance via a scheduled update, but may also be invoked by some other periodic operation, or even directly by the application.
This method is invoked asynchronously to the frame rendering animation loop, to keep the processing of model updates separate from OpenGL ES drawing.
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. If the maxUpdateInterval property has been set, this method will clamp dt to that limit. See the description of maxUpdateInterval for more information about clamping the update interval.
If this instance is not running, as indicated by the isRunning property, this method does nothing.
As implemented, this method performs the following processing steps, in order:
- Checks isRunning property of this instance, and exits immediately if not running.
- If needed, clamps the dt property to the value in maxUpdateInterval property.
- Invokes updateBeforeTransform: on this instance.
- Triggers recalculation of the transformMatrix on this node.
- Updates each child (including invoking updateBeforeTransform:, recalulating the child node's transformMatrix, and invoking updateAfterTransform: on each descendant, in order).
- Invokes updateAfterTransform: on this instance.
- Updates target tracking in all cameras, lights and billboards.
Sublcasses should not override this updateWorld: method. To customize the behaviour of the 3D model world, sublcasses should override the updateBeforeTransform: or updateAfterTransform: methods. Those two methods are defined and documented in the CC3Node class. Please refer there for more documentation.
This method is invoked automatically at each scheduled update. Usually, the application never needs to invoke this method directly.
| + (id) world |
Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value.
The tag value is generated using a call to nextTag.
Property Documentation
- (CC3Camera *) activeCamera [read, write, retain] |
The 3D camera that is currently displaying the scene of this world.
You can set this property directly, or if this property is not set directly, it will be set automatically to the first CC3Camera added to this world via the addChild: method, including cameras contained somewhere in a structural assembly of nodes whose root node was added to this instance via addChild:. In this way, adding the root node of a node assembly loaded from a file will set the activeCamera property to the first camera found in the assembly, if the property was not already set.
The converse occurs when a camera is removed from the world using the removeChild: method. The camera will be removed as the activeCamera, and the second camera that was previously added (assuming more than one was added) will automatically be set as the activeCamera. Again, this is true even if the root node of a large assembly containing the active camera is removed from the world using the removeChild: method.
The initial value is nil. You must add at least one CC3Camera to your 3D world to make it viewable.
- (ccColor4F) ambientLight [read, write, assign] |
The color of the ambient light of the world.
This is independent of any CC3Light nodes that are added as child nodes. You can use this to provide general flat lighting in your world without having to add light nodes.
The initial value is set to kCC3DefaultLightColorAmbientWorld.
- (CC3NodeSequencer *) drawingSequencer [read, write, retain] |
The node sequencer being used by this instance to order the drawing of child nodes.
During drawing, the nodes can be traversed in the hierarchical order of the node structural assembly, starting at the CC3World instance that forms the root node of the node assembly. Alternately, and preferrably, the CC3World can use a CC3NodeSequencer instance to arrange the nodes into a linear sequence, ordered and grouped based on definable sorting priorities. This is beneficial, because it allows the application to order and group drawing operations in ways that reduce the number and scope of state changes within the GL engine, thereby improving performance and throughput.
For example, when drawing, nodes could be grouped by the drawing sequencer so that opaque objects are drawn prior to blended objects, and an application with many objects that use the same material or mesh can be sorted so that nodes with like materials or meshes are grouped together. It is highly recommended that you use a CC3NodeSequencer.
The default drawing sequencer includes only nodes with local content, and groups them so that opaque nodes are drawn first, then nodes with blending.
- (BOOL) isRunning [read, write, assign] |
Indicates whether the dynamics of this 3D model world are running.
If this property is set to NO, calls to the updateWorld: method will be effectively ignored. The play and pause methods set this property to YES and NO respectively.
This does not affect the movement of nodes controlled by CCActionIntervals. They will continue to move, irrespective of the state of this property.
- (BOOL) isUsingDrawingSequence [read, assign] |
Returns whether this instance is using a drawing sequencer.
- (ccTime) maxUpdateInterval [read, write, assign] |
If the value of this property is greater than zero, it will be used as the upper limit accepted by the updateWorld: method.
Values sent to the updateWorld: method that are larger than this maximum will be clamped to this limit. If the value of this property is zero (or negative), the updateWorld: method will use the value that is passed to it unchanged.
Resource limitations, and activities around start-up and shut-down, can sometimes cause an occasional large interval between consecutive updates. These large intervals can sometimes cause object in the world to appear to jump around, and if you are using physics simulation, might cause collisions to be missed.
Setting a maximum update interval can help eliminate both concerns, but the trade-off may be less realistic real-time behaviour. With a limit in place, larger intervals between updates will make the world appear to run in slow motion, rather than jump around.
The initial value of this property is set to kCC3DefaultMaximumUpdateInterval.
The behaviour described here does not apply to nodes controlled by CCActionIntervals, which are not affected by the time between updates, or the value of this property.
- (CC3PerformanceStatistics *) performanceStatistics [read, write, retain] |
If set, collects statistics about the updating and drawing performance of the 3D world.
By default, this property is nil, and no statistics are accumulated. To accumulate statistics, set this property with an appropriate instance. Subclasses of CC3PerformanceStatistics can customize the statistics that are collected.
To allow flexibility in accumulating statistics, the statistics collector does not automatically clear the accumulated statistics. If you set this property with a statistic collector, it is your responsibility to read the values, and reset the performanceStatistics instance periodically, using the CC3PerformanceStatistics reset method, to ensure that the counters do not overflow. Depending on the complexity and capabilities of your application, you should reset the performance statistics at least every few seconds.
- (CC3ViewportManager *) viewportManager [read, write, retain] |
The viewport manager manages the viewport and device orientation, including handling coordinate rotation based on the device orientation, and conversion of locations and points between the 3D and 2D coordinate systems.
The documentation for this class was generated from the following file:
