Instance Methods | Class Methods | Properties | List of all members
CC3TouchedNodePicker Class Reference

#import <CC3Scene.h>

Inheritance diagram for CC3TouchedNodePicker:
Inheritance graph

Instance Methods

(void) - dispatchPickedNode
(id) - initOnScene:
(void) - pickNodeFromTouchEvent:at:
(void) - pickTouchedNodeWithVisitor:

Class Methods

(id) + pickerOnScene:


CGPoint touchPoint

Detailed Description

A CC3TouchedNodePicker instance handles picking nodes from touch events in a CC3Scene.

This handler maintains a queue of touch types, to ensure than none are missed. However, it does not keep a queue of touch points. Instead, it uses the most recent touch point to determine the 3D object under the touch point.

This handler picks 3D nodes using a color picking algorithm. When a touch event occurs, its type is added to the queue, and the touch position is updated. On the next rendering pass, the 3D scene is rendered so that each 3D node has a unique color. The color of the pixel under the touch point then identifies the node that was touched. The scene is then re-rendered in true colors in the same rendering pass, so the user never sees the unique-color rendering that was used to pick the node.

Once the node is picked, it is cached. On the next update pass, the node is picked up and all touch events that occured since the previous update pass are dispatched to the CC3Scene in sequence.

This asychronous design keeps the update and rendering loops from interfering with each other. The rendering loop only has to pick the object that is under the touch point that was most recently recorded. And if the dispatching of events takes time, only the update loop will be affected. The rendering loop can continue unhindered.

For rapid finger movements, it is quite likely that more than one touch event could arrive before the next rendering pass picks a 3D node. For this reason, no attempt is made to find the node for each and every touch location. In addition, the touch type is only added to the queue if it is different than the previous touch type. For example, a rapid inflow of kCCTouchMoved events will only result in a single kCCTouchMoved event being picked and dispatched to the CC3Scene on each pair of rendering and updating passes.

Method Documentation

- (void) dispatchPickedNode

Invoked by the CC3Scene during update operations, in the update loop that occurs occurs just after a touch event has been received by the touchEvent:at: method, and after a node has been picked as a result, by the pickTouchedNodeWithVisitor: method.

This implementation invokes the nodeSelected:byTouchEvent:at: method on the CC3Scene instance.

This method is invoked automatically whenever a touch event occurs. Usually, the application never needs to invoke this method directly.

- (id) initOnScene: (CC3Scene *)  aCC3Scene

Initializes this instance on the specified CC3Scene.

+ (id) pickerOnScene: (CC3Scene *)  aCC3Scene

Allocates and initializes an autoreleased instance on the specified CC3Scene.

- (void) pickNodeFromTouchEvent: (uint)  tType
at: (CGPoint)  tPoint 

Indicates that a node should be picked for the touch event of the specified type that occurred at the specified point, which is the location in the 2D coordinate system of the CC3Layer where the touch occurred.

The tType is one of the enumerated touch types: kCCTouchBegan, kCCTouchMoved, kCCTouchEnded, or kCCTouchCancelled.

The event is queued internally, and the node is picked asychronously during the next rendering frame when the pickTouchedNodeWithVisitor: method is automatically invoked.

- (void) pickTouchedNodeWithVisitor: (CC3NodeDrawingVisitor *)  visitor

Invoked by the CC3Scene during drawing operations in the rendering frame that occurs just after a touch event has been received by the touchEvent:at: method.

The picking algorithm runs a specialized drawing routine that paints each node with a unique color. The algorithm then reads the color of the pixel under the touch point from the GL color buffer. The received color is then mapped back to the node that was painted with that color.

This specialized coloring algorithm is inserted into normal drawing operations when (and only when) a touch event has been received. Once the node has been picked, the drawing operations are re-run in normal fashion prior to the final posting of the frame to the display.

The coloring-and-picking algorithm is run only once per touch event, and is not run during rendering frames when there has been no touch event received.

Rendering for node picking uses a specialized internal drawing visitor. The specified visitor is not used to render the scene for node picking. Instead, the internal drawing visitor is aligned with the specified visitor, and is then used to render the scene.

This method is invoked automatically whenever a touch event occurs. Usually, the application never needs to invoke this method directly.

Property Documentation

- (CC3Node*) pickedNode

The currently picked node.

The value of this property is ephemeral, and contains a non-nil value only during node picking from touch handling. The value is set by the pickTouchedNodeWithVisitor: method, and is cleared by the dispatchPickedNode method.

- (CC3NodePickingVisitor*) pickVisitor

The visitor that is used to visit the nodes to draw them when picking a node from touch selection.

This property defaults to an instance of the class returned by the pickVisitorClass method of the CC3Scene. The application can set a different visitor if desired.

- (CGPoint) touchPoint

The most recent touch point in Cocos2D coordinates.

The documentation for this class was generated from the following file: