Chapter 7. Traversing the Scene Graph

Once you create a scene graph, you apply an action to the root node to trigger the events prescribed in the scene graph nodes. Most nodes include an overwritten apply() method that triggers an appropriate response when a specific action is applied to the node. Actions include rendering the scene (draw action) and playing sound files (sound action).

This chapter describes how an action traverses a scene graph and the actions available in Cosmo 3D.

This chapter has the following sections:

Scene Graph Actions

An action is an operation that is carried out on one or more nodes in a scene graph. In response to actions,

  • csLeaf nodes set values.

  • csGroup nodes pass actions from one child node to another.

For example, when a csDrawAction is applied to the root node of a scene graph, the action operates on (potentially) all of the nodes in the scene graph so that all of the csShape nodes in it are rendered.

The action-specific responses taken by a node are implemented in the following node functions:

  • draw()—for csDrawAction

  • isect()—for csIsectAction

  • compile()—for csCompileAction

  • sound()—for csSoundAction

When an action operates on one node after another, the action is said to be traversing the scene graph.

Action Types

In Cosmo 3D, there are four kinds of actions:

  • csDrawAction—Renders a scene graph.

  • csIsectAction—Selects objects intersecting a ray.

  • csCompileAction—Compiles a subgraph.

  • csSoundAction—Plays spatialized (3D) sounds in a scene graph.

All of the actions are derived from csAction.

For more information about


csAction is a virtual class from which all actions are derived. An action is an operation that is performed on some or all of the nodes in a scene graph, for example, a csDrawAction, when applied to the root node, renders a scene graph.

csAction contains the following method:

virtual void  apply(csNode *node) = 0;

You invoke an action by creating an instance of an action class and applying it to a node (commonly the root node), for example:

csGroup* rootNode = new csGroup;
csDrawAction* renderAction = new csDrawAction;

In this example, a draw action, renderAction, is applied to the root node, rootNode, of a scene graph.

When an action is applied to a node, each kind of node responds in its own way. When a draw action is invoked on a leaf node, for example, it sets the values that describe a shape. When a draw action is invoked on a group node, it applies the action to some or all of its children.

Rendering the Scene

A csDrawAction causes leaf nodes to set the variables that affect the rendering of the shapes in a scene graph and causes the shapes to be rendered.

A csDrawAction has the following get and set methods:

void reset();
virtual csTravDirective apply(csNode *node);

reset() resets the cull stack and transformation stack.

The virtual function apply() is the method you use to apply the draw action on a node in a scene graph, for example:


where renderAction is a csDrawAction instance and rootNode is the root node of a scene graph. A draw action can be applied to any node in a scene graph. If you apply a draw action to a leaf node, the node may set a value but the action does not spread to any other nodes.

Playing Sound Files

csSoundAction plays sound files. The csSound node indirectly specifies—through csAudioClip and csAudioSamples nodes—the sound file to play. The csSoundAction places the listener (referred to as the microphone in Cosmo 3D) relative to the sound source for spatial effects, such as volume based on the proximity of the listener to the sound source.

void        setMicrophone(Microphone mic);
Microphone  getMicrophone();

When the csSoundAction traverses a scene graph, it creates a list of active sounds in the scene graph and supplies that information to csContext internally. If any sounds are active, csContext sends instructions to play the associated sound files for a specific duration.

For more information about sounds, see Chapter 15, “Adding Sounds To Virtual Worlds.”

The Order In Which Actions Are Passed Between Nodes

In a scene graph, group nodes are acted upon in a top-to-bottom sequence. Leaf nodes under any one group node are acted upon in an unspecified order. While not every child node may be visited, for example, under a csSwitch node, it is guaranteed that all parent nodes are visited before their children nodes.

Top-Down Traversals

In diagrams of scene graphs, this order of node evaluation, called an in-order traversal, is represented by the layout of the nodes so that actions traverse from the top to bottom of the scene graph. For example, the numbers in Figure 7-1 show one order in which an action might traverse the nodes in a scene graph.

Figure 7-1. The Flow of an Action Through A Scene Graph

Figure 7-1 The Flow of an Action Through A Scene Graph

A top-down traversal means that a node can never affect a node “above” it. For example, node 3 in Figure 7-1 cannot affect nodes 4 and 5, however, node 4 can affect node 5. So, that branch of the scene graph is traversed in the following way when an action is applied to the root node:

  1. The action traverses from node 1 to any of its children.

  2. When the action visits node 2, node 2 propagates the action to one of its children.

  3. If the action propagates to node 3, the action takes effect and the attribute variables are reset to their values prior to node 3 after which the action visits node four.

  4. The action then traverses nodes 4 and 5 at which point the traversal state is reset to its state prior to node 2.

  5. The action then traverses to any of the other child nodes of node 1.

Each node can immediately change the image in the frame buffer according to the content to the node.

Whether all of the children of a group node are evaluated depends on the group node type. For example, in Figure 7-1, if the number 1 node is of type csSwitch, the traversal may visit all, one, or none of nodes 2, 6, 7, 9, and 10.