This routine creates a new RMnode, and returns a handle to the caller upon success, or NULL upon failure.

During render-time traversal of the scene graph, render parameters can be compared against certain attributes of the RMnode, thereby terminating depth traversal. Three such traversal masks exist at this time (February 2000): 2D vs. 3D, opaque pass vs. transparent pass, and for stereo rendering, left vs. right channel. The first two attributes, opaque vs. transparent and 2D vs. 3D are specified at the time the RMnode is created. These may be subsequently overridden, if desired, using rmNodeSetTraversalMaskOpacity() or rmNodeSetTraversalMaskDims().

Control over the filter masks used to compare against RMnode attributes is manipulated by the multipass rendering framework. (Feb 2000, this needs to be written).

When created, the RMnode is assigned the following default values:

1. The "name" attribute of the RMnode is set to contain a copy of the input string "name" (rmNodeSetName()).

2. The RMnode's bounding box minimum and maximum coordinates are set to RM_MAXFLOAT and RM_MINFLOAT, respectively.

3. The node's "traverse enable" attribute is set to RM_TRUE. 4. The node's "pick enable" attribute is set to RM_TRUE.

4. The node is scheduled for rendering during all passes of a stereo rendering (rmNodeSetTraversalMaskChannel()).

5. The node's transformation attributes, if any, are applied to the "model-view" matrix stack (as opposed to the texture stack) (rmNodeSetTransformMode()).

This routine is the opposite of rmNodeNew(), and will delete resources associated with an RMnode, including scene parameters, rendering parameters, and all RMprimitives. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

This routine deletes only a single RMnode. Use rmSubTreeDelete() to delete an entire, connected, rooted scene graph.

RMnodes maintain an internal reference count; it is an error to delete an RMnode that has a non-zero reference count. The RMnode reference count is modified by adding nodes into the scene graph (rmNodeAddChild), or by removing them from the scene graph (rmNodeRemoveChild, rmNodeRemoveAllChildren). Attempts to delete RMnodes with a non-zero reference count will not succeed, but will be rewarded with an RM_WHACKED return status.

Use this routine to delete a collection of nodes in a scene graph rooted at "toDelete". RM_CHILL is returned upon success, or RM_WHACKED upon failure. This routine performs a depth-first, left-to-right traversal of the scene graph rooted at "toDelete", and performs an rmNodeDelete operation during the traversal.

Use this routine to set the "name" attribute of an RMnode. The input string is copied into a character string inside the RMnode. The maximum string length allowable is defined by the constant RM_MAX_STRING_LENGTH. The RMnode name attribute is used when searching for a named node.

RM_CHILL is returned upon success, and RM_WHACKED is returned upon failure.

Use this routine to obtain a COPY of the name string attribute of an RMnode. A character string is returned to the caller upon success, otherwise NULL is returned.

Since the return string is a COPY malloc'ed off the heap, the caller should free() the return string when it is no longer needed.

Use this routine to modify the value of the "general traverse enable" attribute of an RMnode. This attribute affects all frame-based traversals: view, render, and pick. A newVal of RM_TRUE specifies that a node will be processed during such traversals. A newVal of RM_FALSE inhibits processing of the node toModify along with all its children.

As of RM version 1.6.0, the point during node processing when RM checks the value of the traversal flag varies between multistage rendering processing, serial rendering processing, and picking varies. This inconsistency will be remedied in a future RM version. For multistage rendering, the traverse enable flag is checked prior to any other node processing. For picking and serial rendering, the traverse enable flag is processed after a node's pretraversal callback.

By default, when an RMnode is created with rmNodeNew, the value of this attribute is set to RM_TRUE.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Returns to the caller the RMnode's "traverse enable" attribute. Upon success, the return value will be either RM_TRUE or RM_FALSE. A return value of RM_WHACKED indicates an error condition.

Returns to the caller the RMnode's "pick enable" attribute. Upon success, the return value will be either RM_TRUE or RM_FALSE. A return value of RM_WHACKED indicates an error condition.

Use this routine to modify the "pick enable" attribute of an RMnode. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The "pick enable" attribute controls whether or not a node is traversed during a pick operation. It is similar to the "traverse enable" attribute, but is used only during picks. The pick enable attribute can be used to accelerate picking operations in complex scenes where only a small subset of the scene is pickable.

By default, when an RMnode is created with rmNodeNew, the value of this attribute is set to RM_TRUE.

Use this routine to establish a parent-child relationship between two RM scene graph nodes. This routine is the fundamental building block used to construct the scene graph. Returns RM_CHILL upon success or RM_WHACKED upon failure.

The node "child" is appended to the list of children at node "parent". It is not possible to insert a child at a specific index within the array of children. This can be done explicitly by calling rmNodeAddChild in order, thereby producing the sequence of children desired at an RMnode.

There is no limit to the number of children nodes at an RMnode.

Feb 2001 - This routine is thread-safe. Multiple application threads may simultaneously call this routine; thread-safety is provided by mutex locks in the component manager.

Will remove the RMnode "child" from the list of children nodes at "parent". If "child" is not a child node of "parent", RM_WHACKED is returned. Otherwise, the reference to "child" is removed from "parent" and the count of children is decremented by one.

Upon successful location of "child" in "parent," the array of children will be modified so that it is contiguous. Otherwise, the metaphor of number of children and child indexing (rmNodeGetIthChild) would break.

Consider this example. Upon entry to rmNodeRemoveChild, the array of children at an RMnode is:

[A B C D]

and we wish to remove child "B". Upon exit from this routine, the array of children will look like this:

[A C D]

Feb 2000 - at this time, RMnodes only know about their children, but not parents. Therefore, the RMnode child is not modified in any way. In the future, RMnodes might know about their parents, in which case "child" would be modified so that it has one fewer parent references.

Feb 2001 - this routine is thread-safe: multiple applications threads may safely call this routine simultaneously. Thread-safety is implemented by mutexes in the component manager.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Use this routine to break the parent-child relationship at a given RMnode. This routine will simply remove all nodes from the list of children at an RMnode, and set the count of the number of children to zero. The child nodes are not deleted; only the reference to them is removed from the input node.

RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Returns to the caller the number of child nodes registered with the input node. Upon failure, a value of -1 is returned.

Returns to the caller the number of RMprimitives owned by an RMnode. If the input RMnode is NULL, a value of -1 is returned.

Related routines: rmNodeGetPrimitive() retrieves the i'th primitive from an RMnode; rmNodeAddPrimitive() adds a new RMprimitive to an RMnode.

Use this routine to remove all the RMprimitives associated with an RMnode object. Upon successful completion, RM_CHILL will be returned, and the RMnode will contain no primitives. Failure will occur, and RM_WHACKED will be return, if the input RMnode is NULL.

If you pass in an RMnode with no RMprimitives, nothing happens to the RMnode and RM_CHILL will be returned.

Use this routine to obtain the RMnode handle of a child node. Since the "indx" parameter is a C-style index, an input value of zero refers to the first child, a value of one refers to the second child, an so forth.

Use rmNodeGetNumChildren to determine how many children are registered at a given RMnode.

Upon failure, NULL is returned.

This routine searches for an RMnode in a scene graph rooted at "start" that contains the name attribute that matches the string in the input parameter "name". Upon success, a handle to matching RMnode is returned to the caller, otherwise, NULL is returned.

Aug 2000 - eventually, this routine will be replaced by using a customizable traverser.

This routine will print the contents of a scene graph rooted at "root", performing a depth first, left-to-right traversal.

If the fileName parameter is NULL, print occurs to stderr. Otherwise, printing will be directed to the named file.

Feb 2000- this routine is not fully implemented, nor fully functional. It provides only rudimentary information.

Use this routine to update the bounding box attribute of an RMnode. The bounding box vertices are specified in world coordinates. The bounding box is specified with a minimum and maximum vertex, implying that the bounding box is aligned with the axes of the world coordinate system.

Each of "vMin" and "vMax" are optional - if you do not wish to update either the min or max bounding box coordinate, use a value of NULL.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Use this routine to obtain the bounding box minimum and/or minimum coordinate(s) from an RMnode. Upon success, RM_CHILL is returned, and the RMnode's bounding box coordinates are copied into caller-supplied memory (if non-NULL). Otherwise, RM_WHACKED is returned.

This convenience routine will set the RMnode's "center point" attribute (rmNodeSetCenter()) with the geometric average of the RMnode's bounding box minimum and maximum coordinate.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

This convenience routine will determine the minimum and maximum extents of all geometric primitives owned by an RMnode by performing a "union" of all RMprimitive's bounding boxes. Then, this routine will also set the RMnode's bounding box minimum and maximum coordinate to those minimum and maximum extents.

In addition, this routine will set the RMnode's center point to be the middle of the computed bounding box. Note that setting a center point will have an impact on geometric transformations, such as a rotation, that might be set later at the RMnode toModify.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

rooted at the node toModify, and will perform a "bounding box union". The union of two bounding boxes can be thought of as the smallest 3D box that encloses two sub-boxes.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Use this routine to set the color of the ambient material reflectence property at an RMnode. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if normals are not present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the 4-component ambient reflectance color attribute of an RMnode. Upon success, the ambient reflectance color attribute of an RMnode will be copied into the caller-supplied memory, and RM_CHILL will be returned.

If the input RMnode is NULL, or if the ambient reflectance color is not defined at an RMnode, RM_WHACKED is returned to the caller.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to set the color of the diffuse material reflectence property at an RMnode. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the 4-component diffuse reflectance color attribute of an RMnode. Upon success, the diffuse reflectance color attribute of an RMnode will be copied into the caller-supplied memory, and RM_CHILL will be returned.

If the input RMnode is NULL, or if the diffuse reflectance color is not defined at an RMnode, RM_WHACKED is returned to the caller.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to set the color of the specular material reflectence property at an RMnode. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the 4-component specular reflectance color attribute of an RMnode. Upon success, the specular reflectance color attribute of an RMnode will be copied into the caller-supplied memory, and RM_CHILL will be returned.

If the input RMnode is NULL, or if the specular reflectance color is not defined at an RMnode, RM_WHACKED is returned to the caller.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to set the specular reflectence exponent surface reflectance material property. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The shade of each vertex (OpenGL supports only vertex shading) is a function of the Lambertian diffuse shading model, combined with Phong specular reflection. The weights, or coefficients, applied to each of the ambient, diffuse and specular components of the shading equation are the linear combination of ambient, diffuse and specular coefficients of the surface material properties with the ambient, diffuse and specular color components of the light sources and light models.

The specular exponent controls the appearance of specular highlights. A smaller exponent value produces a larger specular highlight, while a larger exponent value produces a smaller, more focused highlight. The default specular exponent in RM is 10.0.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the specular exponent material reflectance attribute of an RMnode. Upon success, RM_CHILL is returned, and the RMnode's specular exponent is copied into caller-supplied memory.

If the input node is NULL, or if the input node has no surface reflectance properties, or if the specular exponent term has not been defined (through explicit assignment using rmNodeSetSpecularExponent()), RM_WHACKED is returned and caller memory remains undisturbed.

Use this routine to set the "unlit" material color of an RMnode. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The term "unlit color" refers to the color used to draw primitives when lighting is not active. Rather than arbitrarily choose from among diffuse, ambient or specular material colors for use when rendering in the absence of lights, RM provides a node-level attribute for that purpose: unlit color. A newColor value of (0,0,0,1) specifies the color "black," while a newColor value of (1,1,1,1) specifies the color "white."

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the "unlit" material color of an RMnode. Upon success, RM_CHILL is returned and the RMnode's unlit color attribute is copied into caller-supplied memory. If, however, the RMnode has no surface reflectance properties defined, or if the unlit color attribute has not been explicitly set (with rmNodeSetUnlitColor), RM_WHACKED is returned, and caller memory remains unmodified.

The term "unlit color" refers to the color used to draw primitives when lighting is not active. Rather than arbitrarily choose from among diffuse, ambient or specular material colors for use when rendering in the absence of lights, RM provides a node-level attribute for that purpose: unlit color.

For lighting/shading to be active, the following three elements must be present: light sources, light models and surface normals. Light models and light sources are RMnode-level scene parameters (see rmNodeSetSceneLight() and rmNodeSetSceneLightModel()). Surface normals are RMprimitive attributes. Thus, primitives in 3D are not considered to be lit (ie, vertex shade computed using light sources and surface reflectance properties) if no normals are present. When lighting is not active, the RMnode's "unlit color" attribute is used for the vertex color.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to set the opacity level for all RMprimitives in an RMnode. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

In order for objects to be rendered as translucent, a value of opacity other than 1.0 must be specified, either at the RMnode level or at the RMprimitive level. In the former case, the opacity value applies to all RMprimitives in an RMnode (and all descendent primitives, unless subsequently overridden by the presence of the node-level opacity value or RMprimitive level opacities). In the latter case, opacity is specified on a per-vertex level. In addition, the RMnode must be scheduled for traversal during the transparent rendering pass. See rmNodeNew() for more details.

By default, when an RMnode is created with rmNodeNew(), the new node contains no surface properties. Surface properties are inherited along depth in the scene graph. The RM root node has a set of default material reflectance properties, so application nodes that are inserted as children of rmRootNode() will inherit those default material properties.

Use this routine to obtain the opacity attribute of an RMnode. Upon success, RM_CHILL is returned, and the RMnode's opacity attribute is copied into caller-supplied memory. If the RMnode is NULL, or if the RMnode has no surface reflectance properties, or if the opacity attribute is not present (specified with rmNodeSetOpacity()), RM_WHACKED is returned and caller-supplied memory remains undisturbed.

By default, surface normals are not "auto-normalized" during rendering. In some circumstances, it is desireable to ask OpenGL to normalize surface normals prior to rendering, most notably when the governing transformation matrix includes a scaling component. The effect of scaled normals will appear on-screen as objects becoming brigher or dimmer as they are scaled. Enabling auto-normalization will remedy this artifact, but at the expense of speed.

This routine is used to enable or disable auto-normalization of surface normals during rendering. Setting this parameter at an RMnode will either enable or disable normalization of surface normals at render time for the entire scene graph rooted at the RMnode "toModify."

Upon success, this routine will return RM_CHILL, and modify the RMnode's drawing attributes accordingly. Otherwise, RM_WHACKED is returned, and the RMnode's drawing attributes remain unmodified.

Use rmNodeGetNormalizeNormals to query this parameter.

Note that there is not means at this time (3/2000) to obtain from the RM rendering context (RMstate object) any indication of whether or not normals are normalized. This may be added in a future release.

Use this routine to query the "normals are normalized" drawing attribute of an RMnode. If the RMnode has this parameter defined, RM_CHILL is returned, and the parameter is copied into caller supplied memory (if the parameter is non-NULL). Otherwise, RM_WHACKED is returned and caller-supplied memory remains unmodified.

See rmNodeSetNormalizeNormals() for more information.

Line styles in RM control the appearance of lines when rendered. Lines can be rendered as solid lines, or with using a pattern. This routine is used to manipulate the pattern used for line rendering using on of a predefined set of styles. Please refer to the program "lines2d" in the RM demonstration programs for a visual representation of available line styles and widths.

Upon success, the line style attribute is set to the value specified by the "newLineStyle" parameter, and RM_CHILL is returned. Upon failure, RM_WHACKED is returned and the line style attribute of the RMnode "toModify" remains unmodified.

Use rmNodeGetLineStyle() to obtain the line style attribute of an RMnode, or rmStateGetLineStyle() to obtain the current line style attribute from an RM rendering context during a render time traversal of the scene graph.

All RMnode-level drawing properties and modes take effect immediately when the RMnode is is processed during a render time traversal of the scene graph. These settings remain in effect over all children of the RMnode, unless overridden by some child node deeper in the scene graph.

Use this routine to query the line style attribute of an RMnode. If one is defined, RM_CHILL is returned on the stack, and the RMnode's line style attribute will be copied into caller-supplied memory. Otherwise, RM_WHACKED is returned. Please refer to rmNodeSetLineStyle() for details about line style enumerators.

To obtain the render-time value of the line width parameter of the RM rendering context, use rmStateGetLineStyle() from inside an application callback.

Use this routine to change the thickness of lines. Be default, all lines are drawn so they are 1 pixel wide (set on rmRootNode() at the time when RM is initialized). The following table shows the relationship between the linewidth enumerators and the pixel thickness of lines. The column on the left is the actual pixel thickness on the screen, and the second column are the associated RM line width enumerators.

 1  -  RM_LINEWIDTH_NARROW,RM_LINEWIDTH_1
 2  -  RM_LINEWIDTH_MEDIUM, RM_LINEWIDTH_2
 3  -  RM_LINEWIDTH_3
 4  -  RM_LINEWIDTH_HEAVY, RM_LINEWIDTH_4
 5  -  RM_LINEWIDTH_5
 6  -  RM_LINEWIDTH_6
 7  -  RM_LINEWIDTH_7
 8  -  RM_LINEWIDTH_8
 

Upon success, RM_CHILL is returned, and the RMnode's linewidth attribute is set to the value "widthEnum." Upon failure, RM_WHACKED is returned and the RMnode's line width attribute remains unmodified.

Use rmNodeGetLinewidth to obtain the line width attribute from an RMnode, or rmStateGetLinewidth to obtain the line width attribute at render time.

Use this routine to query the line width attribute of an RMnode. If one is defined, RM_CHILL is returned on the stack, and the RMnode's line width attribute will be copied into caller-supplied memory. Otherwise, RM_WHACKED is returned. Please refer to rmNodeSetLineWidth() for details about line width enumerators.

Note that a linewidth enumerator is returned, not the actual pixel thickness of the line.

To obtain the render-time value of the line width parameter of the RM rendering context, use rmStateGetLineWidth() from inside an application callback.

By default, a point primitive is drawn as a single pixel on the screen. This routine is used to change the the number of pixels used when drawing a point primitive. For non antialiased points (3/2000, currently the only option), the point primitive is rendered as a square consisting of "newSize" pixels on each edge of the square. Non-integer values are rounded to the nearest integer.

Upon success, RM_CHILL is returned, and the new point size value is copied into the RMnode. Otherwise, RM_WHACKED is returned, and the RMnode remains unmodified.

Use rmNodeGetPointSize() to obtain the point size attribute from an RMnode, or rmStateGetPointSize() from within an application callback to query the current point size from the RM rendering context.

Use this routine to obtain the "point size" attribute from an RMnode. If it exists, RM_CHILL is returned, and the point size attribute is copied into caller-supplied memory (if it is not NULL). Otherwise, RM_WHACKED is returned.

Note this routine queries an RMnode. To obtain the current point size attribute of the RM rendering context from within an application callback, use rmStateGetPointSize().

This routine maps directly to glPolygonMode() - a polygon has two sides, a front and back, and might be rendered differently depending upon which side is facing the viewer. By default, both front and back are drawn the same way: as filled polygons. This routine allows you to change how polygons are drawn. There are three options for the parameter "newMode" which specifies a new polygon rendering mode. RM_FILL, the default polygon mode, specifies that polygons will be drawn as filled areas. RM_LINE specifies that only polygon edges will be drawn. RM_POINT will cause only polygon vertices to be rendered.

For the "whichFace" parameter, RM_FRONT means that front-facing polygons will be drawn using the new mode. RM_BACK means that back-facing polygons will be drawn using the new mode. Use RM_FRONT_AND_BACK to apply the new mode to both front- and back-facing polygons.

Note the OpenRM limitation that it is not possible at this time (3/2000) to specify one mode for the front-facing polygons and a different mode for back-facing polygons.

Whether or not a polygon is front- or back-facing is determined by the "winding rule." See rmNodeSetFrontFace() for more information. Polygons may be culled based upon whether or not they are front- or back-facing. See rmNodeSetPolygonCullMode() for more information.

Returns RM_CHILL upon success. Upon failure, the polygon draw mode remains unmodified, and RM_WHACKED is returned.

Use this routine to obtain the polygon rendering mode specified at an RMnode. Upon success, RM_CHILL is returned on the stack, and the RMnode's polygon rendering mode and face are copied into caller-supplied memory. If the polygon rendering mode is not defined at the RMnode "toQuery," RM_WHACKED is returned and caller-supplied memory remains unmodified. See rmNodeSetPolygonDrawMode() for more details about the return values for "returnFace" and "returnMode."

Note this routine queries the polygon mode at a specific node. During rendering, a given RMnode may not have a polygon mode defined at the RMnode level, but the polygon mode, and other drawing attributes, are always defined in the RMstate object. Use the routine rmStateGetPolygonDrawMode() from within an application callback to obtain the current render-time values for the polygon draw mode.

Culling refers to the process of rejecting polygons from the rendering process based upon some criteria. rmNodeSetPolygonCullMode() is used to control whether or not polygons are culled based upon whether or not they are front- or back-facing. This type of culling is performed late in the rendering pipeline - polygon vertices are first transformed to eye coordinates, then the polygon cull test is applied to accept or reject the polygon. Higher level culling, such as view frustum culling, occurs much earlier in the pipeline. Face level culling can improve performance in many cases, but frustum culling prior to drawing will result in better performance.

By default, no polygon culling is performed (RM_CULL_NONE is applied to rmRootNode() at initialization time).

Whether or not a polygon is front or back facing is a function of how vertices are ordered. See rmNodeSetFrontFace() for more information.

When the input value for "newMode" is RM_CULL_NONE, no polygon culling is performed. When set to RM_CULL_FRONT, front-facing polygons will be culled after transformation to eye coordinates, but prior to drawing. When RM_CULL_BACK is specified, only back-facing polygons are culled prior to rasterization. When RM_CULL_FRONT_AND_BACK is specified, all polygons are culled.

Use this routine to obtain polygon cull settings at an RMnode. Upon success, RM_CHILL is returned, and the polygon cull mode from the RMnode "toQuery" is copied into caller-supplied memory. Upon failure, RM_WHACKED is returned, and caller-supplied memory remains unmodified.

Note that this routine obtains the polygon cull settings from an RMnode. Not all RMnode's have this attribute defined. During a render-time traversal of the scene graph, the current rendering context may be queried using rmStateGetPolygonCullMode() from an application callback.

This routine is used to control how OpenGL determines which faces are front--facing. The basic idea is that the ordering of vertices in projected screen coordinates determines if a polygon is front-facing. Two choices are possible: either a clockwise orientation, specified with RM_CW, or a counter-clockwise orientation, RM_CCW.

Whether or not a polygon is front- or back-facing as computed by this winding rule is relevant only in the context of face-level culling. Lighting calculations, in contrast, are a function of the dot product of the surface normal with the direction to the light source.

By default, front faces in OpenRM are specified with RM_CCW, so polygon vertices that have a counterclockwise winding are front-facing. This is accomplished by setting rmNodeSetFrontFace(rmRootNode(), RM_CCW) at the time RM is initialized (this is performed internal to RM - applications need not perform this task).

Use rmNodeGetFrontFace() to obtain the front face winding rule parameter from an RMnode.

Use this routine to obtain the "front face" parameter from an RMnode. Upon success, RM_CHILL is returned, and the front face attribute from the RMnode "toQuery" is copied into caller-supplied memory. Upon failure, RM_WHACKED is returned, and caller-supplied memory remains unmodified.

Note that this routine obtains the front face attribute from an RMnode. Use the routine rmStateGetFrontFace() to obtain the front face attribute from the render state from inside an application callback during a render-time traversal of the scene graph.

Use this routine to set the shading model used for rendering primitives. The new shader, specified by newMode, takes effect at the RMnode "toModify" and has scope of control over all descendent nodes in the scene graph, unless overridden by a new shader value specified at some child node. The permissible values for "newMode" are RM_SHADER_SMOOTH, RM_SHADER_FLAT or RM_SHADER_NOLIGHT. RM_SHADER_SMOOTH corresponds to glShadeModel(GL_SMOOTH); RM_SHADER_FLAT corresponds to glShadeModel(GL_FLAT) and RM_SHADER_NOLIGHT is a combination of glShadeModel(GL_FLAT) with lighting disabled.

RM_SHADER_SMOOTH causes OpenGL's "smooth shading" model to be used. In most implementations, this is a Gouroud shader. RM_SHADER_FLAT uses a single color for each polygon or line segment. Some implementations will average all vertex colors, within the polygon or line segment, to produce an average color for the entire polygon or line segment. Other implementations use, instead, the last color value specified. RM_SHADER_NOLIGHT is the same as RM_SHADER_FLAT, but with lighting disabled.

Upon success, the shade model of the input RMnode is modified to contain the value specified by "newMode," and RM_CHILL is returned. Upon failure, caused by a NULL input RMnode or an out-of-range shade model enumerator, RM_WHACKED is returned and the RMnode "toModify" remains unmodified.

By default, rmRootNode() is assigned RM_SHADER_SMOOTH as the default shader, and will remain in effect unless overridden.

Use this routine to obtain the shader parameter associated with an RMnode. If no shader parameter is present in the RMnode "toQuery," or if "toQuery" or "shaderReturn" are NULL, RM_WHACKED is returned and "shaderReturn" remains unmodified. Otherwise, the shader parameter of "toQuery" is copied into caller-supplied memory and RM_CHILL is returned to the caller.

Note that this routine does not return the shader that would be active at "toQuery" during a render-time traversal of the scene graph. If an RMnode does not have a shading parameter, the shader is inherited from ancestor nodes. The only means at this time (March 2000) to obtain the shader that would be active during a render-time traversal of the scene graph is to attach a switch or post-traversal callback to an RMnode, then query the RMstate using rmStateGetShader()) (a pre-traversal callback won't work because all rendering parameters are processed after the pre-traversal callback).

This routine is used to update one of the traversal masks of the RMnode "toModify." Upon success, the "opacity" traversal mask is modified to contain the value "newVal", and RM_CHILL is returned to the caller. Upon failure, RM_WHACKED is returned and the RMnode's opacity traversal mask remains unmodified.

The RMnode traversal mask is used to control whether or not a RMnode, and its descendents in the scene graph, are processed during a scene graph traversal. Three types of traversal masks are supported: opacity (rmNodeSetTraversalMaskOpacity), dimensions (rmNodeSetTraversalMaskDims), and stereo channel (rmNodeSetTraversalMaskChannel), although more may be added in the future. Currently, the traversal masks of RMnodes are tested only during a render-time traversal of the scene graph. The traversal masks provide a way for nodes to be processed during one or multiple passes of multipass rendering.

In this routine, the permissible values of "newVal" are RM_RENDERPASS_OPAQUE, RM_RENDERPASS_TRANSPARENT or RM_RENDERPASS_ALL. Setting the value to RM_RENDERPASS_OPAQUE will cause nodes, and their descendents, to be processed only during an "opaque" rendering pass; a traversal mask value of RM_RENDERPASS_TRANSPARENT will result in nodes and their descendents being processed only during a "transparent" rendering pass, and RM_RENDERPASS_ALL will cause nodes and their descendents to be processed during both opaque and transparent rendering passes.

Use this routine to obtain the opacity traversal mask from an RMnode. Upon success, the opacity traversal mask from the RMnode "toQuery" is copied into caller-supplied memory, and RM_CHILL is returned. Otherwise, RM_WHACKED is returned, and the caller-supplied memory is not modified.

See rmNodeSetTraversalMaskOpacity for more information about the opacity traversal mask.

This routine is used to update one of the traversal masks of the RMnode "toModify." Upon success, the "dimensions" traversal mask is modified to contain the value "newVal", and RM_CHILL is returned to the caller. Upon failure, RM_WHACKED is returned and the RMnode's opacity traversal mask remains unmodified.

The RMnode traversal mask is used to control whether or not a RMnode, and its descendents in the scene graph, are processed during a scene graph traversal. Three types of traversal masks are supported: opacity (rmNodeSetTraversalMaskOpacity), dimensions (rmNodeSetTraversalMaskDims), and stereo channel (rmNodeSetTraversalMaskChannel), although more may be added in the future. Currently, the traversal masks of RMnodes are tested only during a render-time traversal of the scene graph. The traversal masks provide a way for nodes to be processed during one or multiple passes of multipass rendering.

In this routine, the permissible values of "newVal" are RM_RENDERPASS_2D, RM_RENDERPASS_3D or RM_RENDERPASS_ALL. Setting the value to RM_RENDERPASS_3D will cause nodes, and their descendents, to be processed only during "3D" rendering passes; a traversal mask value of RM_RENDERPASS_2D will result in nodes and their descendents being processed only during a "2D" rendering pass, and RM_RENDERPASS_ALL will cause nodes and their descendents to be processed during both 2D and 3D rendering passes.

Use this routine to obtain the "dimensions" traversal mask from an RMnode. Upon success, the dimensions traversal mask from the RMnode "toQuery" is copied into caller-supplied memory, and RM_CHILL is returned. Otherwise, RM_WHACKED is returned, and the caller-supplied memory is not modified.

See rmNodeSetTraversalMaskDims for more information about the dimensions traversal mask.

This routine is used to update one of the traversal masks of the RMnode "toModify." Upon success, the "channel" traversal mask is modified to contain the value "newVal", and RM_CHILL is returned to the caller. Upon failure, RM_WHACKED is returned and the RMnode's channel traversal mask remains unmodified.

The RMnode traversal mask is used to control whether or not a RMnode, and its descendents in the scene graph, are processed during a scene graph traversal. Three types of traversal masks are supported: opacity (rmNodeSetTraversalMaskOpacity), dimensions (rmNodeSetTraversalMaskDims), and stereo channel (rmNodeSetTraversalMaskChannel), although more may be added in the future. Currently, the traversal masks of RMnodes are tested only during a render-time traversal of the scene graph. The traversal masks provide a way for nodes to be processed during one or multiple passes of multipass rendering.

In this routine, the permissible values of "newVal" are RM_LEFT_CHANNEL, RM_RIGHT_CHANNEL or RM_ALL_CHANNELS. Setting the value to RM_LEFT_CHANNEL will cause nodes, and their descendents, to be processed only during the left-channel rendering pass of a multipass stereo rendering; a traversal mask value of RM_RIGHT_CHANNEL will result in nodes and their descendents being processed only during the right-channel rendering pass of a multipass stereo rendering, and RM_ALL_CHANNELS will cause nodes and their descendents to be processed during any rendering pass of a multipass stereo or mono channel rendering.

Use this routine to obtain the channel traversal mask from an RMnode. Upon success, the channel traversal mask from the RMnode "toQuery" is copied into caller-supplied memory, and RM_CHILL is returned. The return value copied into maskReturn will be one of RM_LEFT_CHANNEL, RM_RIGHT_CHANNEL or RM_ALL_CHANNELS. Otherwise, RM_WHACKED is returned, and the caller-supplied memory is not modified.

See rmNodeSetTraversalMaskChannel for more information about the opacity traversal mask.

Use this routine to set the transformation mode attribute in an RMnode. This attribute controls how the transformation matrix information is applied to the scene graph. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The mode RM_TRANSFORM_GEOMETRY causes transformation attributes within an RMnode to be applied to the GL_MODELVIEW matrix stack. RM_TRANSFORM_TEXTURE results in modification of the GL_TEXTURE matrix stack. RM_TRANSFORM_IGNORE will disable the application of an RMnode's transformation attributes without requiring transformation attributes to be neutralized (zero vectors and Identity matrices).

By default, RMnodes are assigned a transformation mode of RM_TRANSFORM_GEOMETRY when created by rmNodeNew().

Note that RMnode transformations are ALWAYS applied prior to scene parameter processing within an RMnode. This means that any lights, cameras, etc. that are part of an RMnode's scene parameters will be affected by transformations within the node.

Upon success, the transform mode of the input RMnode is returned to the caller, and the return value will be one of RM_TRANSFORM_GEOMETRY, RM_TRANSFORM_TEXTURE or RM_TRANSFORM_IGNORE. Upon failure, RM_WHACKED is returned. Failure is defined as a NULL input RMnode, or if the input RMnode has no transformation attributes.

The transformation mode of RMnodes is by default RM_TRANSFORM_GEOMETRY, as set by rmNodeNew(), but may be later changed by using rmNodeSetTransformMode.

Use this routine to set the "pre matrix" transformation attribute of an RMnode.

See rmNodeGetCompositeModelMatrix() for a discussion of how the transformation attributes of an RMnode are combined into a single transformation.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

If the RMnode toQuery has transformation attributes defined, the "pre matrix" is copied into caller-supplied memory, and RM_CHILL is returned to the caller. Otherwise, RM_WHACKED is returned and the caller-supplied memory remains undisturbed.

Use this routine to set the "center point" of an RMnode. The "center point" attribute defines the a local origin about which rotation and scaling occur for any transformations at this RMnode. See rmNodeGetCompositeModelMatrix() for a discussion of how the RMnode transformation attributes are combined into a single, composite transformation matrix.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Use this routine to obtain the RMnode's "center point." If the input RMnode and RMvertex3D objects are NOT NULL, then RM_CHILL is returned, and the RMnode's center point attribute is copied into caller-supplied memory. Otherwise, RM_WHACKED is returned, and the caller-supplied memory remains undisturbed.

Use this routine to set the "pre-rotation scale matrix" transformation attribute of an RMnode.

See rmNodeGetCompositeModelMatrix() for a discussion of how the transformation attributes of an RMnode are combined into a single transformation.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

If the RMnode toQuery has transformation attributes defined, the "pre-rotate scale matrix" is copied into caller-supplied memory, and RM_CHILL is returned to the caller. Otherwise, RM_WHACKED is returned and the caller-supplied memory remains undisturbed.

Use this routine to set the "pre-rotation scale matrix" transformation attribute of an RMnode.

See rmNodeGetCompositeModelMatrix() for a discussion of how the transformation attributes of an RMnode are combined into a single transformation.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

If the RMnode toQuery has transformation attributes defined, the RMnode's rotation matrix transformation attribute is copied into caller-supplied memory, and RM_CHILL is returned to the caller. Otherwise, RM_WHACKED is returned and the caller-supplied memory remains undisturbed.

Use this routine to set the "post-rotation scale matrix" transformation attribute of an RMnode.

See rmNodeGetCompositeModelMatrix() for a discussion of how the transformation attributes of an RMnode are combined into a single transformation.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

If the RMnode toQuery has transformation attributes defined, the "post rotate scale matrix" is copied into caller-supplied memory, and RM_CHILL is returned to the caller. Otherwise, RM_WHACKED is returned and the caller-supplied memory remains undisturbed.

Use this routine to set the "translate vector" transformation attribute in an RMnode. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

See rmNodeGetCompositeModelMatrix() for information concerning how the composite transformation matrix at an RMnode is derived from the transformation attributes.

Use this routine to obtain the translation vector transformation attribute from an RMnode. If the RMnode has no transformation attributes, or if the input RMnode or RMvertex3D objects are NULL, RM_WHACKED is returned. Otherwise, RM_CHILL is returned, and the translation vector is copied into caller supplied memory.

See rmNodeGetCompositeModelMatrix() for more details concerning how the RMnode transformation attributes are combined into a single, composite transformation.

Use this routine to set the "post matrix" transformation attribute of an RMnode.

See rmNodeGetCompositeModelMatrix() for a discussion of how the transformation attributes of an RMnode are combined into a single transformation.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

If the RMnode toQuery has transformation attributes defined, the "post matrix" is copied into caller-supplied memory, and RM_CHILL is returned to the caller. Otherwise, RM_WHACKED is returned and the caller-supplied memory remains undisturbed.

Use this routine to obtain the composite transformation of all transformation matrices in an RMnode. Since transformations are optional node attributes, if no transformation attributes are present in an RMnode, the matrixReturn parameter is set to the Identity matrix.

Upon success, RM_CHILL is returned and the node's composite transformation matrix is copied into caller-supplied memory (or the identity matrix is copied into caller-supplied memory if no transformation attributes are present in the input RMnode). Otherwise, RM_WHACKED is returned.

The composite transformation is the matrix product of:

[Pre -C S R S2 C T Post]

Where:

Pre (rmNodeSetPreMatrix, rmNodeGetPreMatrix) is the "pre transformation" matrix applied prior to any other transformations.

-C and C are matrices representing a translation. C represents the RMnode's "center point" attribute (rmNodeSetCenter, rmNodeGetCenter).

S is the "pre rotate" scale matrix (rmNodeSetScaleMatrix, rmNodeGetScaleMatrix)

R is the RMnode's rotation matrix (rmNodeSetRotateMatrix, rmNodeGetRotateMatrix).

S2 is the RMnode's "post rotate" scale matrix (rmNodeSetPostRotateScaleMatrix, rmNodeGetPostRotateScaleMatrix).

T is a translation matrix derived from the RMnode's translation vector (rmNodeSetTranslateVector, rmNodeGetTranslateVector).

Post is a transformation matrix applied after all other transformations at an RMnode (rmNodeSetPostMatrix, rmNodeGetPostMatrix).

Use this routine to assign a "render order callback" at an RMnode. To remove a switch callback from an RMnode, call this routine with a value of NULL for the appFunc parameter.

This callback, if present, is invoked ONLY from within the RM_VIEW stage of multistage rendering. There is no equivalent routine for the RM_DRAW stage of multistage rendering.

During normal traversal, all children of an RMnodes are traversed. The render order callback is used to alter this behavior: the presence of a render order callback means that the application has the opportunity to alter the order in which the children of the node are renderered. Usually, children are rendered in the order they were added to the RMnode.

The render order callback provided by the application will be passed an array of integers that contain the values of 0, 1, ... n-1 where n is the number of children at the RMnode toModify. These values represent the indices arranged in the order the children will be rendered. The application may modify the placement of these indices so that children need not be rendered in index-order.

In addition to modifying the indices contained in the orderIndices array, the application should also return an integer value that specifies how many of the children will be rendered. This value should be in the range zero through nchildren-1. A value of zero means that no children will be rendered, and a value of nchildren-1 means that all children will be rendered, but using the index order defined in the array orderIndices.

Note that RM will process the indices in the orderIndices array in increasing order. In other words, RM will render the child referenced by orderIndices[0] first, then orderIndices[1] next, and so on, until the application-specified number of children have been processed.

This routine first appeared in v1.4.3.

Use this routine to assign a "switch callback" at an RMnode. To remove a switch callback from an RMnode, call this routine with a value of NULL for the appFunc parameter.

This callback, if present, is invoked ONLY from within the RM_VIEW stage of multistage rendering. There is no equivalent routine for the RM_DRAW stage of multistage rendering.

During normal traversal, all children of an RMnodes are traversed. The switch callback is used to alter this behavior: the presence of a switch callback means that one, and only one of the child nodes will be traversed. The switch callback returns an integer value that is interpreted as an index, indicating which of an RMnode's children to traverse. Should the returned index be "out of range" (less than zero or greater than or equal to the number of children nodes), no children nodes will be processed. However, such a condition is indicative of an application error.

Use an RMnode's "pre traversal" callback to inhibit traversal rather than returning an out-of-bounds index from the switch callback.

The most common use for the switch callback is to perform level-of-detail (LOD) model switching based upon view dependent operations. The application callback is provided two parameters: a handle to the RMnode owning the switch callback, and an RMstate object. The RMstate object contains the current model-view and projection matrices, their inverses, and all other rendering parameters current at the RMnode "toModify" during a render time traversal of the scene graph.

See the rmStateGet*() family of routines for more details about the type of render state information available to application callbacks.

Use this routine to assign a "pre-traversal callback" at an RMnode. To remove a pre-traversal callback from an RMnode, call this routine with a value of NULL for the appFunc parameter.

The callback will be invoked during the view pass if RM_VIEW is specified for the "whichPass", or during the rendering pass if RM_RENDER is specified. The view pass precedes the rendering pass, and is where all view-dependent operations should be performed (distance-based model switching, frustum culling, etc). Only drawing should be performed during the rendering pass.

During normal scene graph traversal, all children of an RMnodes are traversed. The pre-traversal callback is used to possibly alter this behavior: upon entry to an RMnode, the pre-traversal callback is invoked prior to any other RMnode processing. If the pre-traversal callback returns a positive value (greater than zero), the RMnode is processed "as usual." However, if the pre-traversal callback returns a value that is less than or equal to zero, processing of the RMnode terminates; no children will be processed, and any other callbacks in the RMnode (switch, post-traversal) will NOT be invoked.

The application callback is provided two parameters: a handle to the RMnode owning the switch callback, and an RMstate object. The RMstate object contains the current model-view and projection matrices, their inverses, and all other rendering parameters current at the RMnode "toModify" during a render time traversal of the scene graph.

The pretraversal callback is invoked *before* any scene parameters are processed at the given node. Applications that use the pretraversal callback to implement direct OpenGL rendering need to be aware that no scene parameters contained in the node will be processed. An alternate way to accomplish implementation of application rendering code that takes advantage of any scene parameters contained in the node along with the application callback is to use the post-traversal callback.

Important note about RM_RENDER pre traversal callbacks: the return value provided by the application-supplied render-stage pre-traversal callback is ignored as of the time of this writing (8/11/02). This means that the render-stage traversal callback will be invoked during the render stage, but will not alter the scene graph traversal algorithm. This incorrect behavior will be fixed in a later release.

See the rmStateGet*() family of routines for more details about the type of render state information available to application callbacks.

Use this routine to assign a "post-traversal callback" at an RMnode. To remove a post-traversal callback from an RMnode, call this routine with a value of NULL for the appFunc parameter.

The callback will be invoked during the view pass if RM_VIEW is specified for the "whichPass", or during the rendering pass if RM_RENDER is specified. The view pass precedes the rendering pass, and is where all view-dependent operations should be performed (distance-based model switching, frustum culling, etc). Only drawing should be performed during the rendering pass.

The post-traversal callback does not affect processing of children nodes. It is simply a hook provided to applications that is invoked after all other processing at an RMnode is complete, including traversal of all an RMnode's children.

The return value from the post traversal callback is ignored.

The application callback is provided two parameters: a handle to the RMnode owning the switch callback, and an RMstate object. The RMstate object contains the current model-view and projection matrices, their inverses, and all other rendering parameters current at the RMnode "toModify" during a render time traversal of the scene graph.

See the rmStateGet*() family of routines for more details about the type of render state information available to application callbacks.

Creates a new RMmutex object, and assigns it to the RMnode "toModify." The initial state of the mutex lock is set to the value "initialLockState." Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and destroyed by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

Performs an atomic "unlock" operation to the RMmutex object in an RMnode. This operation is non-blocking, and is async-safe. If no RMmutex exists in the RMnode, or if there is some other type of error encountered, RM_WHACKED is returned. Otherwise, RM_CHILL indicates successful completion of the post operation.

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and destroyed by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

Performs a blocking lock operation: execution will be suspended until the RMmutex of the RMnode "toModify" becomes unlocked. When the RMmutex becomes unlocked, this routine will lock the RMmutex, then return. Upon successful completion of the wait operation, RM_CHILL is returned. Otherwise, RM_WHACKED indicates an error of some type.

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and destroyed by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

Performs a non-blocking lock of the RMmutex in the RMnode toQuery. Return values are the same as those for rmMutexTryLock.

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and destroyed by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

Returns to the caller the handle of the RMmutex at the RMnode. If no RMmutex is present in the RMnode, NULL is returned. Callers may perform any valid operation upon the RMmutex (rmMutexLock, rmMutexUnlock or rmMutexTryLock), with one exception: callers may not destroy the RMnode mutex directly. To destroy the RMnode mutex, use the routine rmNodeMutexDestroy().

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and destroyed by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

Deletes the RMmutex in the RMnode "toModify." Upon success, RM_CHILL is returned. A return value of RM_WHACKED indicates some type of error.

Mutexes are control mechanisms used to synchronize access to "critical" resources, and are most often used to serialize access to variables between multiple, concurrent execution threads. Mutexes are an optional field in an RM scene graph node that are explicitly created, manipulated and deleted by applications. The behavior of the mutex synchronization tools in OpenRM is modeled closely after that of POSIX threads/semaphores/mutexes.

In OpenRM, the RMmutex is an abstraction layer that uses POSIX mutex in Unix implementations, and native Win32 methods under windows. Like the POSIX model, the following guidelines apply:

- Mutexes are created and assigned an initial value. - Unlocking the mutex is an atomic, async-safe operation. - Mutex locking is a blocking operation that will suspend the caller until the mutex is unlocked. - A non-blocking lock operation is provided via rmNodeMutexTryLock.

This routine implements a view frustum cull test, and is not intended to be called directly by applications. Developers should use this routine as a parameter to rmNodeSetPretraversalCallback using RM_VIEW to implement view frustum calling during the view stage of multistage rendering.

rmNodeFrustumCallback will transform the corners of the RMnode's bounding box through the composite viewing matrix (model+view+projection) active at this node during the view traversal (transformations accumulate!) and will compare the visibility of each of these eight transformed vertices. If any are visible (lie within the view frustum), a value of 1 is returned. Otherwise, all vertices lie outside the view frustum, and a value of zero is returned.

During a view traversal, if a node is culled by this test, this node and any children will not be further processed - and won't be rendered during the rendering stage. This type of frustum culling is an excellent way to reduce load on the graphics engine by performing view-dependent, model-level simplification.

When this routine is used as indicated in the code example below, the result if view frustum culling for RMnodes.

Example code:

 RMnode *n = rmNodeNew("myNode",RM_RENDERPASS_ALL, RM_RENDERPASS_ALL);


 ... other node config and primitive building omitted ...

 rmNodeComputeBoundingBox(n);


 rmNodeSetPretraversalCallback(n, RM_VIEW, rmNodeFrustumCallback);


 

Caveats:

1. There are some circumstances in which if all bounding box vertices lie outside the view frustum, that the interior of the box lies inside the view frustum. One example is when the frustum is completely contained within the bounding box. This routine needs to be modified to account for these types of conditions (using a method similar to the Cohen-Sutherland polygon clipping algorithm).

2. In order for this routine to be effective, nodes need to have bounding boxes. It is up to the application to ensure that bounding boxes are present at RMnodes for which frustum culling is used. See rmNodeComputeBoundingBox, rmNodeSetBoundingBox and rmNodeUnionAllBoxes.

3. This routine has been tested for perspective projections, but needs to be tested with orthographic projections.

For best results, the size of the bounding box should be < the size of the frustum.