Scenes

A 3D scene is the top level of a structural node assembly,and forms the realm of everything that is visible to a 3D camera.

A 3D scene is represented by an instance of the CC3Scene class. To manage the content, and control the behaviour, within your 3D scene, you create a subclass of CC3Scene. All 3D activity, from model management to rendering, takes place within, and is the responsibility of, your application’s customized CC3Scene subclass.

Note: The CC3Scene class should not be confused with the CCScene class from Cocos2D. Both of these classes are used in a Cocos3D app, but for very different purposes. You can learn more about CCScene in the discussion about layers.

CC3Scene is a subclass of CC3Node, and supports all of the methods and properties available to CC3Node. You build your 3D scene by adding other structural and mesh nodes to your CC3Scene instance using the same addChild: method that you use to assemble nodes into structural assemblies. And you can use methods like getNodeNamed: on your CC3Scene instance to find a particular node on which you want to perform an operation.

---

####Global Coordinate System

Like all other nodes, the scene has its own local coordinate system. The coordinate system of the scene is special, since, being at the root of all other nodes, the coordinate system of the CC3Scene instance forms the global coordinate system for all of the nodes within the scene. In addition to being the common root coordinate system for all nodes, the global coordinate system also defines the coordinate system in which the camera views the scene content.

CC3Node defines a number of (typically) read-only properties that begin with global..., such as globalLocation, globalBoundingBox, etc. These properties return values that are measured relative to the global coordinate system of the scene.

As an example, the globalLocation property of any node in the scene returns the absolute location of that node, relative to the global coordinate system of the scene. You can therefore perform activities such as measuring the absolute distance between two nodes by comparing the values their respective globalLocation properties.

In the same vein, each node in the scene maintains a globalTransformMatrix property, which returns a matrix that transforms location, rotation or scale values that are measured in the local coordinate system of the node, into the global coordinate system. Conversely, the globalTransformMatrixInverted property of any node returns a matrix that transforms values that are measured in the global coordinate system into the local coordinate system of that node.

You can also use the global coordinate system as a bridge between the local coordinate systems of any two nodes. To transform a value measured in the local coordinate system of one node into the local coordinate system of a another node, you can do so by transforming the value to the global coordinate system, and then from the global coordinate system into the local coordinate system of the second node.

For example, the following code will find the location of one node in the coordinate system of a second node:

CC3Vector nodeALocSeenFromNodeB = [nodeB globalTransformMatrixInverted transformLocation: nodeA.globalLocation];

This code transforms the location property of nodeA into the global coordinate system (via the globalLocation property), and then transforms that global location into the local coordinate system of nodeB. In a sense, this reflects how nodeB sees nodeA, in nodeB's own frame of reference.

---

####Scene Configuration and Behaviour

You create a subclass of CC3Scene in order to customize the action behaviour within your scene. For example, if you are writing a game, your customized CC3Scene subclass is where you would provide most of the game logic, and control the interaction of the nodes within the scene.

There are a number of template methods and access points provided by CC3Scene that you can override or access to provide configuration and operational behaviour. Some of the more useful template methods and access points include:

• initializeScene – This method is invoked automatically when the CC3Scene is instantiated. You can override this method to populate your scene with its initial contents, by [loading models] (Adding-Scene-Content#PODLoading) from resource files exported from a 3D editor, or by creating simple models (eg - spheres, boxes, etc), cameras or lights [programmatically] (Adding-Scene-Content#Parametric). Either way, you use the addChild: method to add content nodes to the scene.

• activeCamera - This property contains the camera that is currently used to view your scene. To be visible, every scene must contain a camera. When you add a camera to your scene (either programmatically via the addChild: method, or by loading a resource model that includes a camera), the camera will automatically appear in this property. If your scene contains multiple cameras, the first camera that is added to the scene will appear in this property initially. You can change the camera used to view the scene by setting this property to another camera within your scene.

• backdrop - This property can contain an optional static backdrop to your 3D scene. It consists of an instance of CC3Backdrop, and can display either a solid color or a texture.

• onOpen - This method is invoked just before the scene is first displayed. At this point, the camera is available and configured, and the view, on which the scene will be rendered, has been created. This is the earliest point at which you can initiate [background loading] (Adding-Scene-Content#BackgroundLoading) of additional scene content. The onOpen method is also a good place to use one of the CC3Camera move...ToShowAllOf: family of methods to automatically move the camera to view all or part of your scene. This can be very useful during initial development, when a model does not appear where you think it should.

• updateBeforeTransform: and updateAfterTransform: – If you have scheduled regular updates through your [layer] (Layers), these methods will be invoked automatically on your CC3Scene subclass as part of the scheduled update. These methods are depth-first recursively invoked on all nodes in your scene during an update. The updateBeforeTransform: method is invoked on each parent node before the same method is invoked on its children. Then the updateAfterTransform: method is invoked on each child before its parent. The combination of these two methods allows you to update a node both before and after its children may have been updated. You do not need to override these methods for nodes that are controlled by [animation or actions] (Animation).

• drawSceneContentWithVisitor: - This method renders the 3D scene content. The default implementation establishes scene lighting, renders the scene content in a single pass, and then renders shadows. You can override this method to perform more complicated rendering, such as multi-pass rendering or post-processing effects (blur, etc). This method is invoked automatically once the 3D environment has been established. Once this method is complete, the 2D rendering environment used by Cocos2D will be re-established automatically.

• touchEvent:at: - This method is invoked from your [layer] (Layers) whenever a touch event occurs, if your layer has indicated that it is interested in user interaction. The default implementation selects the 3D node that is visible under the touch point on each touch-down event, and presents that node to the nodeSelected:byTouchEvent:at: method (see below). You can modify this touchEvent:at: method to perform more sophisticated touch handling. This method is not invoked when gestures are used for user interaction. When gestures are used, your layer subclass should process the gestures and invoke higher-level application-defined behaviour on your CC3Scene subclass.

• pickNodeFromTapAt: - If your app is using gestures for user interaction, you can invoke this method from your gesture handler to cause the node under the current touch point to be selected, and presented to the nodeSelected:byTouchEvent:at: method.

• nodeSelected:byTouchEvent:at: - This method is automatically invoked when a [node has been selected] (User-Interaction) by a touch event or gesture handler (via the touchEvent:at: or pickNodeFromTapAt: methods previously mentioned. Node selection occurs asynchronously. The touchEvent:at: or pickNodeFromTapAt: methods queue the node selection for processing, and once the node has been selected, it is presented to this callback method. The default implementation of this method does nothing. You can override this method to handle the selected node.

To be visible, every scene must contain a camera, and usually at least one light. As an example of a configured scene, the following is a snapshot of the 3D scene from the CC3HelloWorld template app in the Cocos3D distribution:

The 3D scene from the CC3HelloWorld template app.

This scene contains a textured backdrop, and a single mesh node illuminated by a light, and viewed by a camera. As loaded into Cocos3D, the following is a listing of the contents of this 3D scene:

CC3HelloWorldScene 'CC3HelloWorldScene':1
  CC3Camera 'Camera':3
    CC3Light 'Lamp':4 light index: 0
  CC3PODResourceNode 'hello-world.pod':5
    CC3PODMeshNode 'Hello':6 (POD index: 0)

This listing shows the custom CC3Scene class instance at the root of the node assembly for the scene. The scene node itself has two child nodes: the camera, and a resource node that was loaded from a POD file. As a result of the POD file loading, that resource node has a single child, the visible mesh node. The scene also contains a light node that is actually mounted as a child of the camera node, so that it will follow along if if the camera is moved around the scene. The static textured backdrop is not a child node of the scene because it exists outside of the 3D scene, and never moves.

You can generate a listing like that shown above for any CC3Node instance and its descendants by retrieving the value of the structureDescription property of the base node in the assembly. Or, as shown here, you can retrieve this property from your custom CC3Scene instance, to get a description of the node assembly structure of the entire 3D scene.