All nodes have the following attributes:

Only group nodes can have child nodes. Each child node has an index number; the first child added to a group node has an index number of 0, the next child added has an index number of 1, and so on. The group node keeps a list of its child nodes.

A child node may have multiple parent nodes. For example, a node encapsulating a wheel might have four parent nodes, each translating the shape of the wheel to a different place in the scene (on a car), as shown in Figure 6-1.

Figure 6-1. Multiple Parent Nodes

L eaf nodes contain the descriptive values used to render all the visual elements in the virtual world. Leaf nodes cannot have child nodes.

Special leaf nodes in OpenGL Performer include:

The root node, pfScene, is the node at the “top” of the scene graph hierarchy. pfScene is a group node because child nodes must be added to it. When a traversal is applied to it, the traversal is (potentially) passed to all other nodes in the scene graph.

You create a pfScene using the following method:

pfScene* root = pfNewScene();

pfScene nodes are attached to a pfChannel using the following method:

pfChanScene(chan, root);

A pfChannel provides a view of the geometric objects defined in the scene graph. For more information about pfChannel, see Chapter 5, “Creating a Display with pfChannel”.

You can start anywhere in the hierarchy to create the scene graph. To create the hierarchy by follow these steps:

You continue making the hierarchy by repeating these steps.

To remove a node from a scene graph, use the following method:

pfRemoveChild(GroupNode, removeNode)

pfRemoveChild() returns 0 if the node is not a child of the specified group node.

When a child is removed, the index numbers of the remaining children are shifted so there is no discontinuity; all index numbers greater than the index number removed are decremented by one.

To find a specific node in a scene graph based on name and type, use pfFindNode().

The hierarchy of nodes is determined by the order in which you add nodes to one another. For example, if you start with the root node, called the pfScene node, and add a child node to it, it would appear in the scene graph directly below the pfScene node.

There are no rules for grouping nodes. However, there are some important guidelines that affect the performance of an application:

OpenGL Performer automatically looks for the file specified in pfdLoadFile() in the following directories in the following order:

The last valid directory takes precedence over any before it. For example, if you had two versions of mySceneGraph.pif, one in the current directory and another in the directory specified by pfdLoadFile(), the version in pfdLoadFile() would be loaded.

Several standard traversal operations are usually necessary for basic application operation and for the efficient rendering of a scene. OpenGL Performer provides automatic and transparent mechanisms for utilizing pipelined and parallel multiprocessing for handling these different traversals. The following processes can be created by OpenGL Performer for the purpose of handling a specific traversal with its own effective copy of the scene graph nodes.

Each process is allotted its own memory space and acts on the scene graph nodes that reside in the shared memory arena, as shown in Figure 6-3. The scene graph geometry, and most of the actual scene graph data, is by default shared across the different processes and is not set up for multiprocessing. For multiprocessed geometry data, you should use the pfFlux object. See Chapter 14, “Dynamic Data,” in the OpenGL Performer Programmer's Guide.

Figure 6-3. Processes Acting on Scene Graph

Scene graphs are traversed in a depth-first, left-to-right order, as shown in Figure 6-4. At each node, some default behavior occurs. For example, a CULL stage starts a bounding sphere test to see whether the node is within the viewing frustum. Custom user pre and post-traversal callbacks on nodes are called as nodes are entered and exited.

Figure 6-4. Scene Graph Traversal Flow

The following method enables you to set up pre- or post-callback functions for a node, with a given traversal that triggers the callback function.

void pfGetNodeTravFuncs(const pfNode* node, int which,     pfNodeTravFuncType *pre, pfNodeTravFuncType *post);

node is the node for which the callback functions apply.

which is the kind of traversal that triggers the callback function. Possible values include:

pre and post are pointers to callback functions triggered before or after, respectively, a node is traversed. Pre-callback functions completely replace the default behavior of the node; post-callbacks modify the default behavior of the node.

Use NULL as the value when not using a pre- or post-callback function.

You can use * pfGetTravNode() can be used inside the callback function. It returns the node for which a callback function was called.

void pfNodeTravData(pfNode *node, int which, void *data);

You can create your own traversals to accomplish specific tasks, such as:

OpenGL Performer includes in a pfuTraverser utility libpfutil/trav.c to help you write your own traverser. pfuTraverser recursively traverses the nodes in a scene graph database, applying pre- and post-traversal functions to each node.

Also included in trav.c is a series of general user traversers that implement pfuTraverser, as described in Table 6-3.