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

#import <CC3NodeSequencer.h>

Inheritance diagram for CC3NodeSequencer:
Inheritance graph

Instance Methods

(BOOL) - add:withVisitor:
(NSString *) - fullDescription
(void) - identifyMisplacedNodesWithVisitor:
(id) - initWithEvaluator:
(void) - populateFrom:
(BOOL) - remove:withVisitor:
(BOOL) - updateSequenceWithVisitor:
(void) - visitNodesWithNodeVisitor:

Class Methods

(id) + sequencer
(id) + sequencerWithEvaluator:


BOOL allowSequenceUpdates
NSArray * nodes
BOOL shouldUseOnlyForwardDistance

Detailed Description

A CC3NodeSequencer instance organizes nodes that are added to it.

The node sequencer contains a CC3NodeEvaluator to determine whether it is interested in a node when an attempt is made to add the node. Only nodes that are accepted the evaluator will be added to the sequencer.

The type of sequencing performed is determined by the subclass of CC3NodeSequencer. A wide range of subclasses may be constructed to perform a variety of sequencing techniques.

Method Documentation

- (BOOL) add: (CC3Node *)  aNode
withVisitor: (CC3NodeSequencerVisitor *)  visitor 

Adds the specified node to this sequencer if the node is accepted by the contained evaluator.

If the node is rejected by the evaluator, it is not added. Returns whether the node was added.

- (NSString*) fullDescription

Returns a string containing a more complete description of this object.

- (void) identifyMisplacedNodesWithVisitor: (CC3NodeSequencerVisitor *)  visitor

If the allowSequenceUpdates is set to YES, looks for nodes that are misplaced in this sequencer, and adds them to the misplacedNodes property of the specified visitor.

What it means for a node to be "misplaced" is defined by the sequencer subclass. A sequencer subclass may determine that the node no longer meets the criteria of the sequencer's evaluator, or that the node is now out of order, relative to the sorting or grouping criteria defined by the sequencer.

The default behaviour is to do nothing. Subclasses will override as necessary.

This method is invoked automatically by the updateSequenceWithVisitor: method. The application should never need to invoke this method directly.

- (id) initWithEvaluator: (CC3NodeEvaluator *)  anEvaluator

Initializes this instance with the specified evaluator.

- (void) populateFrom: (CC3NodeSequencer *)  another

Template method that populates this instance from the specified other instance.

This method is invoked automatically during object copying via the copy or copyWithZone: method. In most situations, the application should use the copy method, and should never need to invoke this method directly.

Subclasses that add additional instance state (instance variables) should extend copying by overriding this method to copy that additional state. Superclass that override this method should be sure to invoke the superclass implementation to ensure that superclass state is copied as well.

- (BOOL) remove: (CC3Node *)  aNode
withVisitor: (CC3NodeSequencerVisitor *)  visitor 

Removes the specified node, if it exists within this sequencer, and returns whether it was removed.

+ (id) sequencer

Allocates and initializes an autoreleased instance with no evaluator.

This sequencer will not accept any nodes until an evaluator is attached.

+ (id) sequencerWithEvaluator: (CC3NodeEvaluator *)  anEvaluator

Allocates and initializes an autoreleased instance with the specified evaluator.

- (BOOL) updateSequenceWithVisitor: (CC3NodeSequencerVisitor *)  visitor

Invokes the identifyMisplacedNodesWithVisitor: method on this sequencer to look for nodes that are "misplaced", then removes and re-adds those misplaced nodes back into this sequencer, so that they can be inserted into their correct sequence position.

This method is invoked automatically from the CC3Scene on each drawing frame. The application should never need to invoke this method directly.

- (void) visitNodesWithNodeVisitor: (CC3NodeVisitor *)  aNodeVisitor

Visits the nodes contained in this node sequencer with the specified node visitor.

The nodes are visited in the order that they are sequenced by this node sequencer.

Note that the argument is a CC3NodeVisitor, not a CC3NodeSequencerVisitor as with other methods on this class.

The default implementation does nothing. Subclasses that contain nodes, or contain other sequencers that contain nodes, will override.

Property Documentation

- (BOOL) allowSequenceUpdates

Indicates that the sequencer will run the algorithm to relocate misplaced nodes when the updateSequenceWithVisitor: method is invoked.

Setting this property to NO means that when updateSequenceWithVisitor: is invoked, on this or a parent sequencer, no attempt will be made to move misplaced nodes in this sequencer to their correct drawing sequence position.

Initially, this property is set to YES to ensure nodes are always in their correct drawing sequence position, to avoid unexpected visual artifacts.

However, the updateSequenceWithVisitor: method is invoked on each drawing frame, and checks each drawable node. You may find performance improvements by setting this property to NO on some sequencers, if you know that the nodes contained in a particular sequencer will not be moved out of that sequencer, or re-sorted within that sequencer, and you want to save the overhead of checking each node on each drawing frame.

If you have set this property to NO, you can still force a node to be re-positioned to its correct drawing sequence position by invoking the checkDrawingOrder method on the node.

- (CC3NodeEvaluator*) evaluator

The evaluator that determines whether a node should be added to this sequencer.

If no evaluator is attached to this sequencer, no nodes will be added.

- (NSArray*) nodes

Returns an array of the nodes that have been added to this sequencer, ordered as this sequencer defines.

The returned array is a copy of the any internal arrays. Changing the contents will not change the internal node seqeunce.

- (BOOL) shouldUseOnlyForwardDistance

For sequencers that order nodes based on distance to the camera, indicates whether, when comparing distances from the nodes to the camera, only the distance component that is parallel to the camera's forwardDirection should be considered.

If the value of this property is NO, nodes will be sorted based on the true 3D straight-line distance from each node to the camera, as if drawing a measuring tape from the location of the camera to the location of the center of geometry of the node. This is the most common 3D scenario.

If the value of this property is YES, nodes will be sorted based on the shortest distance from the camera to a plane that is perpendicular to the forwardDirection of the camera and contains the location of the node. This has the effect of sorting nodes based on their distance "straight-out" from the camera, ignoring distance contributed by nodes that are "off to the side" of the camera's view. This option is good for scenes that are built from large planar nodes that move in layers at fixed distances from a fixed camera, similar to cell-animation techniques.

The initial value for this property is NO, indicating that the true 3D distance between the camera and the center of geometry of the node will be used to determine drawing order. Unless your 3D scene is using special cell-animation techniques with large planar nodes, you should not change the value of this property.

In this default abstract implmentation, the value returned is always returned as NO, and values set in this property are ignored. Subclasses that sort based on Z-order, and subclasses that contain such other sequencers will override.

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