Inherits from NSObject
Declared in CC3NodeVisitor.h

Overview

A CC3NodeVisitor is a context object that is passed to a node when it is visited during a traversal of the node hierarchy.

To initiate a visitation run, invoke the visit: method on any CC3Node.

Subclasses will override template methods to customize the behaviour prior to, during, and after the node traversal.

If a node is to be removed from the node structural hierarchy during a visitation run, the requestRemovalOf: method can be used instead of directly invoking the remove method on the node itself. A visitation run involves iterating through collections of child nodes, and removing a node during the iteration of a collection raises an error.

Tasks

Properties

camera

The camera that is viewing the 3D scene.

@property (nonatomic, retain) CC3Camera *camera

Discussion

If this property is not set in advance, it is lazily initialized to the value of the defaultCamera property when first accessed during a visitation run.

The value of this property is not cleared at the end of the visitation run.

Declared In

CC3NodeVisitor.h

currentMaterial

Returns the material of the mesh node that is currently being visited, or returns nil if that mesh node has no material.

@property (nonatomic, readonly) CC3Material *currentMaterial

Discussion

It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

This property is only valid during the traversal of the node returned by the currentMeshNode property, and will be nil both before and after the visit: method is invoked on that node.

Declared In

CC3NodeVisitor.h

currentMesh

Returns the mesh of the mesh node that is currently being visited.

@property (nonatomic, readonly) CC3Mesh *currentMesh

Discussion

It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

This property is only valid during the traversal of the node returned by this property, and will be nil both before and after the visit: method is invoked on the node.

Declared In

CC3NodeVisitor.h

currentMeshNode

Returns the mesh node that is currently being visited.

@property (nonatomic, readonly) CC3MeshNode *currentMeshNode

Discussion

This is a convenience property that returns the value of the currentNode property, cast as a CC3MeshNode. It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

This property is only valid during the traversal of the node returned by this property, and will be nil both before and after the visit: method is invoked on that node.

Declared In

CC3NodeVisitor.h

currentNode

The CC3Node that is currently being visited.

@property (nonatomic, readonly) CC3Node *currentNode

Discussion

This property is only valid during the traversal of the node returned by this property, and will be nil both before and after the visit: method is invoked on the node.

Declared In

CC3NodeVisitor.h

currentShaderProgram

Under OpenGL ES 2.0 & OpenGL, returns the shader program of the mesh node that is currently being visited, or returns nil if that mesh node has no shader program, or when using OpenGL ES 1.1.

@property (nonatomic, readonly) CC3ShaderProgram *currentShaderProgram

Discussion

It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

This property is only valid during the traversal of the node returned by the currentMeshNode property, and will be nil both before and after the visit: method is invoked on that node.

Declared In

CC3NodeVisitor.h

defaultCamera

The default camera to use when visiting a node assembly.

@property (nonatomic, retain, readonly) CC3Camera *defaultCamera

Discussion

This implementation returns the activeCamera property of the starting node. Subclasses may override.

Declared In

CC3NodeVisitor.h

lightCount

Number of lights in the scene.

@property (nonatomic, readonly) GLuint lightCount

Declared In

CC3NodeVisitor.h

lightProbeCount

Min of number of light probes in the scene, and the number used by the shader program.

@property (nonatomic, readonly) GLuint lightProbeCount

Declared In

CC3NodeVisitor.h

performanceStatistics

The performanceStatistics being accumulated during the visitation runs.

@property (nonatomic, readonly) CC3PerformanceStatistics *performanceStatistics

Discussion

This is extracted from the startingNode, and may be nil if that node is not collecting statistics.

Declared In

CC3NodeVisitor.h

scene

Returns the CC3Scene.

@property (nonatomic, readonly) CC3Scene *scene

Discussion

This is a convenience property that returns the scene property of the startingNode property.

Declared In

CC3NodeVisitor.h

shouldVisitChildren

Indicates whether this visitor should traverse the child nodes of any node it visits.

@property (nonatomic, assign) BOOL shouldVisitChildren

Discussion

The initial value of this property is YES.

Declared In

CC3NodeVisitor.h

startingNode

The CC3Node on which this visitation traversal was intitiated. This is the node on which the visit: method was first invoked to begin a traversal of the node structural hierarchy.

@property (nonatomic, readonly) CC3Node *startingNode

Discussion

This property is only valid during the traversal, and will be nil both before and after the visit: method is invoked.

Declared In

CC3NodeVisitor.h

textureCount

Returns the number of textures in the current mesh node.

@property (nonatomic, readonly) GLuint textureCount

Discussion

It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

Declared In

CC3NodeVisitor.h

Class Methods

visitor

Allocates and initializes an autoreleased instance.

+ (id)visitor

Declared In

CC3NodeVisitor.h

Instance Methods

currentTextureUnitAt:

Returns the texture unit at the specified index from the mesh node that is currently being visited, or returns nil if the material covering the node has no corresponding texture unit.

- (CC3TextureUnit *)currentTextureUnitAt:(GLuint)texUnit

Discussion

It is up to the invoker to make sure that the current node actually is a CC3MeshNode.

The value returned by this method is only valid during the traversal of the node returned by the currentMeshNode property, and will be nil both before and after the visit: method is invoked on that node.

Declared In

CC3NodeVisitor.h

fullDescription

Returns a more detailed description of this instance.

- (NSString *)fullDescription

Declared In

CC3NodeVisitor.h

lightAt:

Returns the light indicated by the index, or nil if the specified index is greater than the number of lights currently existing in the scene.

- (CC3Light *)lightAt:(GLuint)index

Discussion

The specified index is an index into the lights array of the scene, and is not necessarily the same as the lightIndex property of the CC3Light.

Declared In

CC3NodeVisitor.h

lightProbeAt:

Returns the light probe indicated by the index, or nil if the specified index is greater than the number of light probes currently existing in the scene.

- (CC3LightProbe *)lightProbeAt:(GLuint)index

Discussion

The specified index is an index into the lightProbes array of the scene.

Declared In

CC3NodeVisitor.h

requestRemovalOf:

Requests the removal of the specfied node.

- (void)requestRemovalOf:(CC3Node *)aNode

Discussion

During a visitation run, to remove a node from the hierarchy, you must use this method instead of directly invoking the remove method on the node itself. Visitation involves iterating through collections of child nodes, and removing a node during the iteration of a collection raises an error.

This method can safely be invoked while a node is being visited. The visitor keeps track of the requests, and safely removes all requested nodes as part of the close method, once the visitation of the full node assembly is finished.

Declared In

CC3NodeVisitor.h

visit:

Visits the specified node, then if the shouldVisitChildren property is set to YES, invokes this visit: method on each child node as well.

- (BOOL)visit:(CC3Node *)aNode

Discussion

Returns whether the visitation run was stopped once a desired result was accomplished. Depending on the type of visitation, this might occur if a particular node was reached, or some other desired result has been accomplished. The purpose of the returned value is not to indicate whether all node have been visited, or even that the visitation was aborted. Instead, you should think of the returned value as a way of indicating that a desired result has been accomplished, and that there is no need to visit further nodes. For visitations that normally visit all nodes, such as drawing, or updating, the return value will generally be NO.

Subclasses will override several template methods to customize node visitation behaviour.

Declared In

CC3NodeVisitor.h