Layers

Cocos3D runs within an environment created by Cocos2D. A Cocos3D layer forms the bridge between the 2D environment of Cocos2D, and the 3D environment of Cocos3D.

A Cocos3D layer is represented by the CC3Layer class. CC3Layer is a subclass of the 2D Cocos2D CCNode class, and can therefore be placed within a structural hierarchy of 2D Cocos2D nodes. It has a 2D node as a parent, and can have 2D nodes as child nodes.

Each instance of CC3Layer holds a single 3D scene, as an instance of CC3Scene, in its cc3Scene property, and triggers the rendering of the 3D content within the 3D scene as part of its own rendering, thereby forming the bridge between the 2D content of Cocos2D, and the 3D content of Cocos3D. You can think of a CC3Layer as providing the 2D portal through which you view the 3D scene.

---

####Customizing CC3Layer

As with the CC3Scene class, generally, you create a customized subclass of CC3Layer to define the behaviour of your layer. Most often, you create a custom CC3Layer subclass for each custom CC3Scene subclass, and typically name them in a compatible manner, such as MyLevel2Layer and MyLevel2Scene.

This design pattern is so common, that if you do not explicitly set the cc3Scene property of your customized CC3Layer instance, when that cc3Scene property is first accessed, your customized CC3Layer instance will automatically instantiate a matching CC3Scene instance to populate that property, based on looking for a CC3Scene subclass with a name of the same structure as the CC3Layer subclass name. For example, a layer subclass named MyLevel2Layer will look for a CC3Scene subclass named MyLevel2Scene, MyLevel2, or MyLevel2LayerScene, and a layer subclass named MyLevel2 will look for a CC3Scene subclass named MyLevel2Scene.

You can also modify this pattern in your custom CC3Layer subclass by overriding the cc3SceneClass property accessor method to return a different CC3Scene subclass. And finally, you can always bypass this automation, and instantiate an instance of your own CC3Scene subclass, and set that instance into the cc3Scene property of any instance of your customized CC3Layer subclass.

Using one of these last two techniques allows you to instantiate different instances of the same CC3Layer subclass for use with several different customized CC3Scene subclasses. For example, if you are building a game, and the user interaction is the same for all levels of your game, you may only need a single customized CC3Layer subclass for use with many different CC3Scene subclasses, each customized for a different level in your game.

CC3Layer also provides the bridge between the Cocos2D scheduled update mechanism and the 3D scene. If you want the updateBeforeTransform: and updateAfterTransform: methods of your customized CC3Scene and other 3D nodes to be invoked, be sure to invoke the scheduleUpdate method of your customized CC3Layer subclass during its initialization.

---

####User Interaction

Because CC3Layer is a 2D node, it can participate in the Cocos2D node structural assembly. In particular, you can add other 2D nodes as child nodes to your CC3Layer instance, for use as user interface controls such as buttons, menus, joysticks, labels, and heads-up displays.

Like other 2D nodes, if its userInteractionEnabled property has been set to YES, your CC3Layer instance can interact with user interface events such as touch events or mouse events. Touch events and mouse events within your CC3Layer are automatically passed to the CC3Scene instance for interpretation (typically to select a 3D node under the touch point).

CC3Layer also provides a number of convenience methods to help you use gestures as part of user interaction:

• cc3AddGestureRecognizer:
• cc3ConvertUIPointToNodeSpace:
• cc3ConvertUIMovementToNodeSpace:
• cc3NormalizeUIMovement:
• cc3WillConsumeTouchEventAt:

---

####Layer Configuration and Behaviour

There are several template methods and access points provided by CC3Layer that you can override or access to build the user interface, including:

• initializeControls – This method is invoked automatically when the CC3Layer is instantiated. You can override this method to add user interface controls such as buttons, menus, joysticks, labels, and heads-up displays, as 2D child nodes to your custom CC3Layer instance.

• scheduleUpdate – Invoking this method from the initializeControls method will ensure that the layer, and the 3D scene, receive an update call at the beginning of each rendered frame, to allow you to control the action within your app. Once this method has been invoked, your custom CC3Scene will receive periodic invocations of its updateBeforeTransform: and updateAfterTransform: methods.

• userInteractionEnabled - In the initializeControls method, set this property to YES to allow the layer, and 3D scene, to receive touch events and mouse events. Set this property to NO if you prefer to use gesture handlers to provide user interaction.

• onOpenCC3Layer - This method is invoked just before the layer is first displayed. At this point, the view, on which the layer and 3D scene will be rendered, has been created. You can override this method to add gesture recognizers to your layer, as described above.

• update: – If you have scheduled regular updates using the scheduleUpdate method, this update: method will be invoked on each frame. This is where you can update any of the 2D controls you’ve added, or pass data from dynamic controls such as sliders or joysticks to your custom CC3Scene instance. If you override this method, be sure to invoke the superclass implementation so it can pass the update notice to the CC3Scene instance.

• ccTouchMoved:withEvent: - By default touch-move and mouse-move events are not handled, because they are voluminous and seldom used. You can override this method to handle touch-move and mouse-move events by passing them to the standard touch handler method:

    -(void) ccTouchMoved: (UITouch *)touch withEvent: (UIEvent *)event {
        [self handleTouch: touch ofType: kCCTouchMoved];
    }
  

---

####Adding Your Layer to the Cocos2D Node Environment

As mentioned above, CC3Layer is a subclass of the 2D CCNode, and can therefore be placed within a structural hierarchy of 2D Cocos2D nodes. When you establish your assembly of 2D nodes, you can add one or more CC3Layer instances to the mix, to provide 3D content.

In many apps, the 3D content is all there is (except for 2D controls), and is presented in one large scene (for example, a medical imaging app, or a standard first-person shooter game). In this case, your custom CC3Layer is all you need, and you can add it directly to the CCDirector by wrapping your custom CC3Layer instance in a CCScene instance so that it can be run by the CCDirector.

This is such a common requirement, that CC3Layer supports a convenience method, asCCScene, that wraps the CC3Layer in a CCScene instance, so that your CC3Layer instance is a child node of the CCScene instance, and returns the CCScene instance. This convenience functionality allows you to use the following as your startScene method implementation in your standard Cocos2D CCAppDelegate subclass:

-(CCScene*) startScene {
    return [[MyLevel2Layer layer] asCCScene] ;
}

Note: The CCScene class should not be confused with the CC3Scene class that represents the 3D scene. Both of these classes are used in a Cocos3D app, one above your CC3Layer, and one below, but for very different purposes. The CCScene is a Cocos2D component, and is simply a wrapper to allow your CC3Layer to be used by the CCDirector. Your customized CC3Scene instance, on the other hand, contains all of your 3D content.

In addition to having a single CC3Layer, holding a single CC3Scene containing all of your 3D content, you can also instantiate a number of CC3Layer/CC3Scene pairs, and use them as 3D tiles in your otherwise 2D app. For example, you might have a few 3D characters moving around in an otherwise 2D or 2.5D environment created in Cocos2D. In this case, each of your custom CC3Layer instances is added as a child somewhere in your structure of Cocos2D nodes, and moved around within the 2D environment. Each custom CC3Layer instance displays the 3D scene it contains, at the location that the CC3Layer is positioned. The CC3Demo3DTiles demo app, included with the Cocos3D distribution provides an example of this approach.