Use the new operator to create nodes. For example:

SoSphere *headSphere = new SoSphere;

Do not allocate nodes in arrays. (See “How Nodes Are Deleted”.)

---

Note: Although you create nodes using the new operator, you cannot delete them using delete. See “How Nodes Are Deleted” for a description of how and when nodes are deleted in Inventor. An understanding of reference counting is vital to your use of Inventor, since you must be aware of the conditions under which a node is automatically deleted.

---

Each node is composed of a set of data elements, known as fields, that describe the parameters of the node. For example, a point light-source node (of class SoPointLight) contains four fields: intensity, color, location, and on. The intensity field contains a value from 0.0 (no illumination) to 1.0 (maximum illumination). The color field specifies a Red/Green/Blue illumination color for the light source. The location field specifies the position of the light. The on field specifies whether the light is on.

Inventor defines a number of field types. Each field type has unique methods to get and set its values. Within each node, the fields are named according to their usage. For example, here are a few nodes and their fields:

Note that fields that contain multiple values, such as the point field in SoCoordinate3, have singular names.

Each node implements its own action behavior. When you want to perform a particular action on a scene, you create an instance of the action class (for example, SoGLRenderAction or SoGetBoundingBoxAction) and then apply it to the root node of the scene graph. For each action, the database manages a traversal state, which is a collection of elements or parameters in the action at a given time. Typically, executing an action involves traversing the graph from top to bottom and left to right. During this traversal, nodes can modify the traversal state, depending on their particular behavior for that action.

This chapter focuses on the OpenGL rendering action, since one of the primary reasons for constructing a 3D database is to view and manipulate

objects. The rendering traversal state consists of a set of elements, each of which can be altered by a given class of nodes. When a rendering action is applied, each element is used and interpreted in a specified manner. A few of the elements in the traversal state include the following:

An SoMaterial node, for example, sets the current values in the various material elements of the traversal state. An SoDrawStyle node sets the current value in the drawing-style element of the traversal state. Shape nodes, such as SoSphere, are especially important in rendering traversal, since they cause their shape to be drawn, using the current values in the traversal state.

Shape nodes represent 3D geometric objects. They are unique because they describe physical matter that is affected by property and group nodes, and during a rendering action, they actually cause their shape to be drawn on the screen. Classes of shape nodes include SoSphere, SoIndexedFaceSet, and SoText3. Figure 3-2 shows the portion of the class tree that contains the shape-node classes.

Figure 3-2. Shape-Node Classes

Property nodes represent appearance and qualitative characteristics of the scene, such as surface material, drawing style, or geometric transformation. Figure 3-3 shows the portion of the class tree that contains the property-node classes. Since property nodes fall naturally into several subgroupings, the scene graph diagrams use three different icons for property nodes:

In general, a property node replaces the values in a corresponding element of the traversal state with its own new values. Geometric transformations are one exception to this rule. They concatenate with the current transformation.

Let's take the material node as an example. This node represents the surface and spectral (color) properties of an object. To create a bronze material, first create the material node and then set the field values appropriately:

SoMaterial *bronze = new SoMaterial;

// set field values
bronze->ambientColor.setValue(.33, .22, .27);
bronze->diffuseColor.setValue(.78, .57, .11);
bronze->specularColor.setValue(.99, .94, .81);
bronze->shininess = .28;

If you do not explicitly set the field values for a particular node, Inventor uses the default values for those fields (see the Open Inventor C++ Reference Manual for individual nodes). For example, in the preceding example, transparency remains 0.0.

SoTransform nodes, which produce geometric transformations, include fields for scaling, rotating, and translating. The following code defines a transform node that translates -1 in the y direction:

SoTransform *myXform = new SoTransform;

// set field value
myXform->translation.setValue(0.0, -1.0, 0.0);

In order for this translation to take effect, it must be inserted appropriately into a scene graph (that is, before the shape node to translate).

Figure 3-3. Property-Node Classes

A group node is a container for collecting child objects. Groups collect property, shape, and other group nodes into graphs. Figure 3-4 shows the portion of the class tree that contains the group-node classes. There are a variety of different group-node classes, each with a specialized grouping characteristic.

When a group node is created, it has no children. The base class for all group nodes is SoGroup, and all nodes derived from it have an addChild() method.

Figure 3-4. Group-Node Classes

The addChild() method adds the specified node to the end of the list of children in the group, as shown in the preceding code. Each child added to the group has an associated index. The first child in a group has an index of 0, the second child in a group has an index of 1, and so on.

The insertChild() method

void   		insertChild( SoNode *child, int newChildIndex);

inserts a child node into a group at the location specified by newChildIndex. For example,

SoDrawStyle *wireStyle;

wireStyle = new SoDrawStyle;
wireStyle->style = SoDrawStyle::LINES;
// Insert as child 1 (the node right after the first child,
// which is child 0.
body->insertChild(wireStyle, 1);

inserts a wireframe drawing-style node as the second child of the body group.

Other group methods allow you to find out how many children are in a group, to find the index of a particular child, to access the child with a given index, and to remove children.

Each node class has its own way of responding to a given database action. For this discussion, assume you are dealing only with the GL rendering action (here called simply rendering).

During rendering, the scene graph is traversed, starting from the root node, from left to right and from top to bottom. Nodes to the right (and down) in the graph inherit the traversal state set by nodes to the left (and above).

Figure 3-6 shows how nodes inherit state. When the waterMolecule node is rendered, it visits its first child, oxygen. The oxygen group then visits each of its children, as follows:

The graph traversal continues to the next group on the right, hydrogen1, which in turn visits each of its children in order from left to right:

Next, the hydrogen2 group visits its children, from left to right:

Example 3-1 shows the code to create this molecule.

// Construct all parts
SoGroup *waterMolecule = new SoGroup;      // water molecule

SoGroup *oxygen = new SoGroup;             // oxygen atom
SoMaterial *redPlastic = new SoMaterial;
SoSphere *sphere1 = new SoSphere;

SoGroup *hydrogen1 = new SoGroup;          // hydrogen atoms
SoGroup *hydrogen2 = new SoGroup;
SoTransform *hydrogenXform1 = new SoTransform;
SoTransform *hydrogenXform2 = new SoTransform;
SoMaterial *whitePlastic = new SoMaterial;
SoSphere *sphere2 = new SoSphere;
SoSphere *sphere3 = new SoSphere;

// Set all field values for the oxygen atom
redPlastic->ambientColor.setValue(1.0, 0.0, 0.0);  
redPlastic->diffuseColor.setValue(1.0, 0.0, 0.0); 
redPlastic->specularColor.setValue(0.5, 0.5, 0.5);
redPlastic->shininess = 0.5;
   
// Set all field values for the hydrogen atoms
hydrogenXform1->scaleFactor.setValue(0.75, 0.75, 0.75);  
hydrogenXform1->translation.setValue(0.0, -1.2, 0.0);  
hydrogenXform2->translation.setValue(1.1852, 1.3877, 0.0);
whitePlastic->ambientColor.setValue(1.0, 1.0, 1.0);  
whitePlastic->diffuseColor.setValue(1.0, 1.0, 1.0); 
whitePlastic->specularColor.setValue(0.5, 0.5, 0.5);
whitePlastic->shininess = 0.5;

// Create a hierarchy
waterMolecule->addChild(oxygen);   
waterMolecule->addChild(hydrogen1);   
waterMolecule->addChild(hydrogen2);

oxygen->addChild(redPlastic);
oxygen->addChild(sphere1);
hydrogen1->addChild(hydrogenXform1);
hydrogen1->addChild(whitePlastic);
hydrogen1->addChild(sphere2);
hydrogen2->addChild(hydrogenXform2);
hydrogen2->addChild(sphere3);

To isolate the effects of nodes in a group, use an SoSeparator node, which is a subclass of SoGroup. Before traversing its children, an SoSeparator saves the current traversal state. When it has finished traversing its children, the SoSeparator restores the previous traversal state. Nodes within an SoSeparator thus do not affect anything above or to the right in the graph.

Figure 3-7, for example, shows the body and head for a robot. The body group, a separator, contains SoTransform and SoMaterial nodes that affect the traversal state used by the cylinder in that group. These values are restored when all children in the body group have been visited, so the head group is unaffected by the body-group nodes. Because the head group is also a separator group, the traversal state is again saved when group traversal begins and restored when group traversal finishes.

Separators are inexpensive to use and help to structure scene graphs. You will probably use them frequently.

---

Tip: The root node of a scene graph should be a separator if you want the state to be reset between successive renderings.

---

Figure 3-7. Separator Groups

Code for the robot body and head groups is shown below:

// create body parts
SoTransform *xf1 = new SoTransform;        
xf1->translation.setValue(0.0, 3.0, 0.0);

SoMaterial *bronze = new SoMaterial;
bronze->ambientColor.setValue(.33, .22, .27);
bronze->diffuseColor.setValue(.78, .57, .11);
bronze->specularColor.setValue(.99, .94, .81);
bronze->shininess = .28;

SoCylinder *myCylinder = new SoCylinder;
myCylinder->radius = 2.5;
myCylinder->height = 6;

// construct body out of parts
SoSeparator *body = new SoSeparator;  
body->addChild(xf1);       
body->addChild(bronze);
body->addChild(myCylinder);

// create head parts
SoTransform *xf2 = new SoTransform;   
xf2->translation.setValue(0, 7.5, 0);
xf2->scaleFactor.setValue(1.5, 1.5, 1.5);

SoMaterial *silver = new SoMaterial;
silver->ambientColor.setValue(.2, .2, .2);
silver->diffuseColor.setValue(.6, .6, .6);
silver->specularColor.setValue(.5, .5, .5);
silver->shininess = .5;

SoSphere *mySphere = new SoSphere;

// construct head out of parts
SoSeparator *head = new SoSeparator;  
head->addChild(xf2);       
head->addChild(silver);
head->addChild(mySphere);
   
// add head and body
SoSeparator *robot = new SoSeparator;  
robot->addChild(body);               
robot->addChild(head);

In addition to SoSeparator, other subclasses of SoGroup include the following:

In the robot example, SoSeparator nodes are used to contain the effects of nodes within a particular group in the scene graph; you do not want the head to inherit the transformation or material attributes from the body group. Conversely, the molecule example uses SoGroup nodes to accumulate a set of properties to apply to other nodes later in the graph.

SoSwitch *s = new SoSwitch;
s->addChild(a);							// this child has an index of 0
s->addChild(b);							// this child has an index of 1
s->addChild(c);							// this child has an index of 2
s->addChild(d);							// this child has an index of 3
s->whichChild = 2;							// specifies to visit child(c)

SoLevelOfDetail

The SoLevelOfDetail node allows you to specify the same object with varying levels of detail. The children of this node are arranged from highest to lowest level of detail. The size of the objects when projected into the viewport determines which child to use. This node is very useful for applications requiring the fastest rendering possible. It has one field:

screenArea (SoMFFloat)

areas on the screen to use for comparison with the bounding box of the level-of-detail group. By default, this value is 0.0, so the first child in the group is traversed.

To determine which child to traverse, Inventor computes the 3D bounding box of all children in the level-of-detail group. It projects that bounding box onto the viewport and then computes the area of the screen-aligned rectangle that surrounds the bounding box. This area is then compared to the areas stored in the screenArea field. For example, Figure 3-8 shows a level-of-detail node with three children. Suppose the screenArea field contains the values [400.0, 100.0]. If the bounding-box projection of the group is 390.0 square pixels (that is, less than 400.0 but greater than 100.0), then childB is traversed. If the bounding-box projection of the group is 450.0 pixels (that is, greater than 400.0, then childA is traversed. If the bounding-box projection is less than 100.0, childC is traversed.

The SoComplexity node, discussed in Chapter 5, “Shapes, Properties, and Binding”, also affects the child selection for the level-of-detail node. If complexity is 0.0 or is of type BOUNDING_BOX, the last child in SoLevelOfDetail is always traversed. If complexity is 1.0, the first child is always used. If the complexity value is greater than 0.0 and less than 0.5, the computed size of the bounding rectangle is scaled down appropriately to use a less detailed representation. If the complexity value is greater than 0.5, the size of the bounding rectangle is scaled up appropriately. If the complexity is 0.5, Inventor uses the computed size of the bounding rectangle as is.

Figure 3-9 shows an object modeled with different levels of detail. Each group of candlesticks is arranged with the most detailed model at the left, a medium level of detail in the middle, and the least detailed model at the right. When the candlestick is close to the camera (as in the first group at the left of Figure 3-9), the most detailed model would be used. This model uses a texture on the base of the candlestick and has a detailed candle with a wick. When the object is farthest away, the least detailed model can be used since the details are not visible anyway. When the object is mid-range (the center group of Figure 3-9), the middle model would be used.

Figure 3-8. Scene Graph with Level-of-Detail Node

Figure 3-9. Different Levels of Detail for an Object

Paths are returned by a picking or search action, and you can construct your own path. (See Chapter 9, “Applying Actions,” for a detailed description of interactive picking.) The user of an interactive application might click the mouse over an object on the screen, causing the object to be picked, and then perform an operation on that object—for example, moving it, changing its color, or deleting it. The selection node manages a list of paths as the currently selected objects.

All actions that can be performed on a node can also be performed on a path. These actions include calculating a bounding box and origin for the path, accumulating a transformation matrix for it, and writing the path to a file.

How you use the information included in a path depends on your application. You may use the whole path, or only part of the path. If your user clicks the mouse on the robot's left foot, is the user selecting the whole robot, the left leg, or just the left foot? (Perhaps one click selects the whole robot, and subsequent clicks select parts of the robot that are lower in the graph, such as the left leg and foot.)

You may be wondering why Inventor nodes have fields instead of simple member variables. This section outlines a few of the mechanisms provided by fields. The Inventor Toolmaker provides additional background on these topics.

First, fields provide consistent methods for setting and inquiring values, as described in the following sections and in the Open Inventor C++ Reference Manual. Second, fields provide a mechanism for Inventor to detect changes to the database. Third, you can connect fields in one node to fields in another node, as described in Chapter 13, “Engines,”. Finally, fields provide a consistent and automatic way to read and write node values.

A single-value field has one value of a given type. Single-value fields include the letters SF in their class name. For example:

Single-value fields are used for nodes that have no use for arrays of values, such as a line pattern, a translation value, a rotation value, or a camera aspect ratio.

A multiple-value field contains an array of values. Multiple-value fields include the letters MF in their class name—for example, SoMFBool, SoMFFloat, SoMFVec3f, and SoMFColor. Multiple-value fields are used for coordinate points and normal vectors. They are also used for materials, so that you can assign different colors to different vertices. Most fields have both SF and MF forms. See the Open Inventor C++ Reference Manual for descriptions of fields within each node class.

The examples earlier in this chapter show how to declare and create nodes. This section provides additional examples of the syntax for setting and getting values for single-value fields within the nodes. (Most fields have a setValue() and getValue() method and can also use the = operator to set values.)

SoOrthographicCamera *cam = new SoOrthographicCamera;
cam->height.setValue(1.);

cam->height = 1.; // = operator has been defined for this field

float result = cam->height.getValue();

SoTransform *xform = new SoTransform;

//(1) Setting the field from a vector

	SbVec3f vector;
	vector.setValue(2.5, 3.5, 0.0);
xform->translation.setValue(vector);
	// or: xform->translation = vector;
	
	
//(2a) Setting the field from a vector of three floats
 	
	xform->translation.setValue(SbVec3f(2.5, 3.5, 0.0));
	// or: xform->translation = SbVec3f(2.5, 3.5, 0.0);
	
	
//(2b) Setting the field from three floats
	
	float x = 2.5, y = 3.5, z = 0.0;
xform->translation.setValue(x, y, z);
	
	
	//(3) Setting the field from an array of three floats
	
	float floatArray[3];
floatArray[0] = 2.5;
floatArray[1] = 3.5;
floatArray[2] = 0.0;
xform->translation.setValue(floatArray);

SbVec3f t = xform->translation.getValue();

t[0] += 1.0;
xform->translation.setValue(t);
// or: xform->translation = t;

Rotations

A rotation field specifies a rotation in 3D space. Since an SbRotation represents rotation around an axis by an angle, you can set its value by specifying the axis and angle:

SbRotation r; SbVec3f axis(0., 1., 0.); float angle = M_PI; //from math.h r.setvalue(axis, angle); // or SbRotation r(SbVec3f(0., 1., 1.), M_PI);

You can also define a rotation to rotate one direction vector into another, as follows:

SbRotation r(SbVec3f(0.0, 0.0, 1.0), SbVec3f(0.0, 1.0, 0.0));

To set the value of the rotation field of an SoTransform node:

SoTransform *xform = new SoTransform; xform ->rotation = r;

You can also use setValue() to set the value of a rotation field and supply an axis and angle, a quaternion, or two vectors.

The = (assignment) operator can be used to set a field's value from another field of the same type. As with vectors, getValue() returns the value of the field.

---

Tip: If you want to specify a rotation as an axis/angle, you must pass an SbVec3f and a float. Passing four floats specifies a quaternion.

---

The SoMaterial node contains the following fields:

These examples show different styles for setting the fields of an SoMaterial node. The transparency field is of type SoMFFloat, so it contains one or more values of type float. The diffuseColor field is of type SoMFColor, so it contains one or more values of type SbColor. The syntax for setting multiple values in an SoMFFloat field is as follows:

nodeName->fieldName.setValues(starting index, number of values, pointer 							   	to array of values);

For example:

SoMaterial *mtl;
float vals[3];
vals[0] = 0.2;
vals[1] = 0.5;
vals[2] = 0.9;
mtl->transparency.setValues(0, 3, vals);

Space for the array is reallocated when necessary. The values are copied in from the array. An example of setting a multiple-value field that uses an Sb type is as follows:

SoMaterial *mtl;
SbVec3f vals[3];

vals[0].setValue(1.0, 0.0, 0.0);
vals[1].setValue(0.0, 1.0, 0.0);
vals[2].setValue(0.0, 0.0, 1.0);
mtl->diffuseColor.setValues(0, 3, vals);

If you want to set only one value in an SoMFFloat field, you can use the following shorthand method:

nodeName->fieldName.setValue(value1);

For example:

mtl->transparency.setValue(.25); 
//or mtl->transparency = .25;

This short method sets the number of values equal to 1 and sets the field to the specified value. However, it also throws away any subsequent values that were previously set in the array, so you should use it only to set the field to have one value. Use the longer method (setValues) or the set1Value() method if you want to change one value in the array and preserve the rest of the values.

You can use the [ ] operator to get a particular value within a multiple-value field as follows:

f = myMtl->transparency[13]; // get 14th value of array

You can also create loops to access all values in the field:

for (i = 0; i < myMtl->transparency.getNum(); i++) {
      printf("transparency value %d is %g\n", i, 
               myMtl->transparency[i]);
}

To insert values in the middle of a field:

float newValues[2];
newValues[0] = 0.1;
newValues[1] = 0.2;

// First, make space; after this, myMtl->transparency[10] 
// and myMtl->transparency[11] will have arbitrary values:

myMtl->transparency.insertSpace(10, 2);

// Set the space created to the right values:

myMtl->transparency.setValues(10, 2, newValues);

To delete values from a field:

// Delete myMtl->transparency[8] and myMtl->transparency[9];
// the values in myMtl->transparency[10] on up will be moved
// down to fill in the missing space, and the transparency
// array will have two fewer values.

myMtl->transparency.deleteValues(8, 2);

See the Open Inventor C++ Reference Manual for additional methods used to edit MF fields.

Every field has an Ignore flag associated with it. Use the setIgnored() method to set or reset the Ignore flag. When this flag is set, the field is disregarded. This flag enables you to ignore certain fields in a node and to use others. For example, to ignore the specular color field in a material node so the value is inherited from the previous material:

SoMaterial *bronze = new SoMaterial;

bronze->ambientColor.setValue(.33, .22, .27);
bronze->diffuseColor.setValue(.78, .57, .11);
bronze->specularColor.setIgnored(TRUE);
bronze->shininess = .28;

To turn the Ignore flag off:

bronze->specularColor.setIgnored(FALSE);

The isIgnored() method returns TRUE if the Ignore flag for this field is set:

if (bronze->specularColor.isIgnored()) {
   printf("Yes, specular is ignored\n");
}

Some fields are not inherited and are thus not affected by the Ignore flag. Examples of fields that are not inherited are the fields of shape nodes, light-source nodes, some groups, and cameras, as well as the fields in the SoEnvironment node. If you set the Ignore flag for a field whose values are not inherited, Inventor simply uses the field's default values.

Each node stores the number of references made to that node within the database. There are several different types of references for nodes:

Engines also store a reference count (see Chapter 13, “Engines,”). This count is incremented when the output of an engine is connected to a field. You can also increment or decrement the reference count manually, by calling ref() or unref().

Figure 3-13 shows the reference counts for nodes in a small subgraph. Whenever you create a reference to a node, you increment its count. The action

A->addChild(B)

adds node B to node A and also increments the reference count for node B by 1. In Figure 3-13 node C has a reference count of 2 because it has been added to two different parent groups. At this point, nodes A and D contain 0 references.

Figure 3-13. Reference Counts

Referencing a node in a path also increments the node's reference count, as shown in Figure 3-14. The reference count for node A now becomes 1, and the reference count for node B becomes 2.

Figure 3-14. Incrementing the Reference Count

---

Tip: Be sure to reference the root of the scene graph: root->ref(). This node is not referenced by being a child of anything else.

---

Inventor uses a reference-counting mechanism to delete nodes and subgraphs of nodes. To understand how nodes are deleted, you need to know how a node's reference count is incremented and decremented, as detailed in this section.

When you remove a reference to a node, its reference count is decremented. Removing a child decrements the reference count. When a node's count returns to 0, it is deleted from the database. Consider the following cases, however, where deleting a node causes problems (refer to Figure 3-13 for this discussion):

The solution to these problems is that when you want to prevent a node from being deleted, you reference it:

B->ref();

Referencing a node increments its count by 1 and ensures that the node is not accidentally deleted. After you have explicitly referenced node B, you can safely remove it as a child of A without fear of deleting node B
(Problem 1).

Similarly, to prevent node A from being deleted (Problem 3), you
reference it:

A->ref();

If you want to delete A (Problem 2), you can unreference it, which decrements the reference count. Node A is now deleted, since you were the only one with a reference to it:

A->unref();

When a group is deleted, all of its children are removed and their reference counts are decremented by 1. In Figure 3-15, for example, if you specify

P->unref(); // reference count for P goes to 0

the reference counts for the child nodes are decremented as follows:

1. Q goes to 0

2. S goes to 1

3. R goes to 0

4. S goes to 0

Since all reference counts now equal 0, all nodes are deleted.

Figure 3-15. Decrementing the Reference Count

---

Tip: Do not allocate nodes, paths, or engines in arrays. This creates problems when one reference count goes to 0 and Inventor tries to free the space allocated for one object in the array.

---

When you apply an action to a node, the action automatically creates a path that references the node. When the action finishes, it automatically removes the path, and thus decrements the node's reference count. Here again, if the node originally has a reference count of 0, it is deleted when the action finishes.

---

Tip: Random memory errors are often caused by unreferenced nodes that have been deleted. If such errors occur, check your program to be sure that it is not trying to use nodes that have been deleted. The debugging version of the Inventor library catches many common reference- counting mistakes.

---

A node, path, or engine should be created only with new and never declared on the stack. These objects should be freed only when their reference count goes to 0, not when they go out of scope.

A newly created node has a reference count of 0. This does not mean that it immediately disappears, since a node is deleted only when the reference count is decremented to 0. Sometimes it is important to be able to restore a

node to its original state (that is, reference count equals 0, but it still exists). For example:

// Create a sphere of a certain radius and returns its bounding
// box. NOTE: BUGGY VERSION; provided for discussion only!

SoSphere *makeSphere(float radius, SbBox3f &box)
{
   sphere = new SoSphere;	// reference count of 0
   sphere->radius.setValue(radius);

   ba = new SoGetBoundingBoxAction;
   ba->apply(sphere);	// does a ref/unref
   box = ba->getBoundingBox();

   return  sphere;	 // ERROR! returning node that
	       // was deleted when ref count
	       // went back to zero!
}

In this example, the sphere node is referenced and unreferenced by SoGetBoundingBoxAction. When unreferenced, the sphere's reference count goes to 0, and it is deleted. The sphere needs to be referenced before the action is applied.

You can use the unrefNoDelete() method in cases such as this one, where you want to return the sphere to its original “fresh” state, with a reference count of 0 (but not deleted). Here is an example of using unrefNoDelete():

// Create a sphere of a certain radius and returns its bounding
// box. NOTE: CORRECT VERSION

SoSphere *makeSphere(float radius, SbBox3f &box)
{
   sphere = new SoSphere;	// reference count of 0
   sphere->ref();	// we want it to stay around
   sphere->radius.setValue(radius);

   ba = new SoGetBoundingBoxAction;
   ba->apply(sphere);	// does a ref/unref
   box = ba->getBoundingBox();

   sphere->unrefNoDelete();	// ref count goes to zero,
	// but sphere stays around
   return  sphere;	// returns sphere with ref
	// count of zero
}

Table 3-1 summarizes the occurrences that increment and decrement reference counts of nodes and engines. Note that connecting an engine to a field in a node does not increment the node's reference count. (Engines are discussed in Chapter 13.)