<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmnode.c)</title></head>
<body bgcolor=white fgcolor=black>
<table width="100%" border=2 cellspacing=0 cellpadding=0 bgcolor="khaki" valign="center">
<th><img src="./images/ormsg.gif">
</th>
</table>
<spacer type=vertical size=15>
<h2>Index of OpenRM - RM Library</h2>
<spacer type=vertical size=15>
<a name="rmRootNode">
<pre><b>
RMnode * rmRootNode (void)
</b></pre>
<pre>
No arguments.
</pre>
<menu><P>
Returns a handle to the "RM Root Node." The RM Root Node is intended
to be used as the root for all application-built scene graphs,
although this isn't strictly necessary.
</P>
<P>
Some RM routines (notable, rmFrame()) assume that their activities
will commence at the rmRootNode() and proceed downward through all
relative nodes.
</P>
<P>
Applications may modify parameters of the rmRootNode(), but must not
delete it. Parameter modification include setting scene parameters,
such as the background color, etc. as well as assigning RMprimitives.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeNew">
<pre><b>
RMnode * rmNodeNew(char *name,
RMenum dimsTraversalMask,
RMenum opacityTraversalMask)
</b></pre>
<pre>
char *name - a character string, used to set the internal RMnode "name"
attribute (input).
RMenum dimsTraversalMask - an RMenum value, may be either RM_RENDERPASS_3D,
RM_RENDERPASS_2D or RM_RENDERPASS_ALL (input).
RMenum opacityTraversalMask - an RMenum value, may be one of
RM_RENDERPASS_OPAQUE, RM_RENDERPASS_TRANSPARENT or RM_RENDERPASS_ALL (input).
</pre>
<menu><P>
This routine creates a new RMnode, and returns a handle to the caller upon
success, or NULL upon failure.
</P>
<P>
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().
</P>
<P>
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).
</P>
<P>
When created, the RMnode is assigned the following default values:
</P>
<P>
1. The "name" attribute of the RMnode is set to contain a copy of the input
string "name" (rmNodeSetName()).
</P>
<P>
2. The RMnode's bounding box minimum and maximum coordinates are set to
RM_MAXFLOAT and RM_MINFLOAT, respectively.
</P>
<P>
3. The node "traverse enable" flag is set (rmNodeSetTraverseEnable()).
</P>
<P>
4. The node is scheduled for rendering during all passes of a stereo
rendering (rmNodeSetTraversalMaskChannel()).
</P>
<P>
5. The node's transformation attributes, if any, are applied to
the "model-view" matrix stack (as opposed to the texture stack)
(rmNodeSetTransformMode()).
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeDelete">
<pre><b>
RMenum rmNodeDelete (RMnode *toDelete)
</b></pre>
<pre>
RMnode *toDelete - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
This routine deletes only a single RMnode. Use rmSubTreeDelete() to
delete an entire, connected, rooted scene graph.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmSubTreeDelete">
<pre><b>
RMenum rmSubTreeDelete (RMnode *toDelete)
</b></pre>
<pre>
RMnode *toDelete - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetName">
<pre><b>
RMenum rmNodeSetName (RMnode *toModify,
const char *name)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const char *name - a character string (input).
</pre>
<menu><P>
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.
</P>
<P>
RM_CHILL is returned upon success, and RM_WHACKED is returned upon
failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetName">
<pre><b>
char * rmNodeGetName (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode to query (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTraverseEnable">
<pre><b>
RMenum rmNodeSetTraverseEnable (RMnode *toModify,
RMenum newval)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode to modify (modified).
RMenum newval - an RMenum value, may be either RM_TRUE or RM_FALSE
(input).
</pre>
<menu><P>
Use this routine to modify the "traverse enable" attribute of an
RMnode. During a render traversal, it is possible to terminate the
depth traversal at a given RMnode by setting it's "traverse enable"
attribute to RM_FALSE.
</P>
<P>
The pretraversal callback, if any, is processed prior to testing the
"traverse enable" attribute of an RMnode.
</P>
<P>
By default, when an RMnode is created with rmNodeNew, the value of
this attribute is set to RM_TRUE.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTraverseEnable">
<pre><b>
RMenum rmNodeGetTraverseEnable (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode to query (input).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeAddChild">
<pre><b>
RMenum rmNodeAddChild (RMnode *parent,
RMnode *child)
</b></pre>
<pre>
RMnode *parent - a handle to an RMnode (modified).
RMnode *child - a handle to an RMnode (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
There is no limit to the number of children nodes at an RMnode.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeRemoveChild">
<pre><b>
RMenum rmNodeRemoveChild (RMnode *parent,
RMnode *child)
</b></pre>
<pre>
RMnode *parent - a handle to an RMnode (modified).
RMnode *child - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
Consider this example. Upon entry to rmNodeRemoveChild, the array of
children at an RMnode is:
</P>
<P>
[A B C D]
</P>
<P>
and we wish to remove child "B". Upon exit from this routine, the
array of children will look like this:
</P>
<P>
[A C D]
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeRemoveAllChildren">
<pre><b>
RMenum rmNodeRemoveAllChildren (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
RM_CHILL is returned upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetNumChildren">
<pre><b>
int rmNodeGetNumChildren (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
</pre>
<menu><P>
Returns to the caller the number of child nodes registered with the
input node. Upon failure, a value of -1 is returned.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetNumPrims">
<pre><b>
int rmNodeGetNumPrims (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
</pre>
<menu><P>
Returns to the caller the number of RMprimitives owned by an RMnode.
If the input RMnode is NULL, a value of -1 is returned.
</P>
<P>
Related routines: rmNodeGetPrimitive() retrieves the i'th primitive
from an RMnode; rmNodeAddPrimitive() adds a new RMprimitive to an
RMnode.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeRemoveAllPrims">
<pre><b>
RMenum rmNodeRemoveAllPrims (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
If you pass in an RMnode with no RMprimitives, nothing happens to the
RMnode and RM_CHILL will be returned.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetIthChild">
<pre><b>
RMnode * rmNodeGetIthChild (const RMnode *toQuery,
int indx)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
int indx - an integer index value.
</pre>
<menu><P>
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.
</P>
<P>
Use rmNodeGetNumChildren to determine how many children are
registered at a given RMnode.
</P>
<P>
Upon failure, NULL is returned.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmFindNamedNode">
<pre><b>
RMnode * rmFindNamedNode (const RMnode *start,
const char *name)
</b></pre>
<pre>
const RMnode *start - an RMnode handle (input).
const char *name - a search string (input).
</pre>
<menu><P>
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.
</P>
<P>
Aug 2000 - eventually, this routine will be replaced by using a
customizable traverser.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmPrintSceneGraph">
<pre><b>
void rmPrintSceneGraph (const RMnode *root,
RMenum printMode,
const char *fileName)
</b></pre>
<pre>
const RMnode *root - a handle to an RMnode (input).
RMenum printMode - an RMenum value specifying a level of
verbosity. At this time (Feb 2000), this parameter is effectively
ignore. Use RM_CHILL for the time being.
const char *fileName - a character string, or NULL (input).
</pre>
<menu><P>
This routine will print the contents of a scene graph rooted at
"root", performing a depth first, left-to-right traversal.
</P>
<P>
If the fileName parameter is NULL, print occurs to stderr. Otherwise,
printing will be directed to the named file.
</P>
<P>
Feb 2000- this routine is not fully implemented, nor fully
functional. It provides only rudimentary information.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetBoundingBox">
<pre><b>
RMenum rmNodeSetBoundingBox (RMnode *toModify,
const RMvertex3D *vMin,
const RMvertex3D *vMax)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMvertex3D *vMin, *vMax - handles to RMvertex3D objects
(input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetBoundingBox">
<pre><b>
RMenum rmNodeGetBoundingBox (const RMnode *toQuery,
RMvertex3D *vMinReturn,
RMvertex3D *vMaxReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMvertex3D *vMinReturn, *vMaxReturn - handles to RMvertex objects
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeComputeCenterFromBoundingBox">
<pre><b>
RMenum rmNodeComputeCenterFromBoundingBox (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeComputeBoundingBox">
<pre><b>
RMenum rmNodeComputeBoundingBox (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeUnionAllBoxes">
<pre><b>
RMenum rmNodeUnionAllBoxes (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modify).
</pre>
<menu><P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetAmbientColor">
<pre><b>
RMenum rmNodeSetAmbientColor (RMnode *toModify,
const RMcolor4D *newColor)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode to modify (modified).
const RMcolor4D *newColor - a handle to an RMcolor4D object (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetAmbientColor">
<pre><b>
RMenum rmNodeGetAmbientColor (const RMnode *toQuery,
RMcolor4D *ambientReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMcolor4D *ambientReturn - a handle to a caller-supplied RMcolor4D
object (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetDiffuseColor">
<pre><b>
RMenum rmNodeSetDiffuseColor (RMnode *toModify,
const RMcolor4D *newColor)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode to modify (modified).
const RMcolor4D *newColor - a handle to an RMcolor4D object (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetDiffuseColor">
<pre><b>
RMenum rmNodeGetDiffuseColor (const RMnode *toQuery,
RMcolor4D *diffuseReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMcolor4D *diffuseReturn - a handle to a caller-supplied RMcolor4D
object (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetSpecularColor">
<pre><b>
RMenum rmNodeSetSpecularColor (RMnode *toModify,
const RMcolor4D *newColor)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode to modify (modified).
const RMcolor4D *newColor - a handle to an RMcolor4D object (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetSpecularColor">
<pre><b>
RMenum rmNodeGetSpecularColor (const RMnode *toQuery,
RMcolor4D *diffuseReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMcolor4D *specularReturn - a handle to a caller-supplied RMcolor4D
object (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetSpecularExponent">
<pre><b>
RMenum rmNodeSetSpecularExponent (RMnode *toModify,
float newValue)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
float newValue - a floating point value, typically greater than 1.0
(input).
</pre>
<menu><P>
Use this routine to set the specular reflectence exponent surface
reflectance material property. RM_CHILL is returned upon success, or
RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetSpecularExponent">
<pre><b>
RMenum rmNodeGetSpecularExponent (const RMnode *toQuery,
float *retValue)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode to query (input).
float *retValue - a handle to a caller-supplied float (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetUnlitColor">
<pre><b>
RMenum rmNodeSetUnlitColor (RMnode *toModify,
const RMcolor4D *newColor)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMcolor4D *newColor - a handle to an RMcolor4D object (input).
</pre>
<menu><P>
Use this routine to set the "unlit" material color of an RMnode.
RM_CHILL is returned upon success, or RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetUnlitColor">
<pre><b>
RMenum rmNodeGetUnlitColor (const RMnode *toQuery,
RMcolor4D *retColor)
</b></pre>
<pre>
const RMnode *toModify - a handle to an RMnode (input).
RMcolor4D *retColor - a handle to an RMcolor4D object (modified).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetOpacity">
<pre><b>
RMenum rmNodeSetOpacity (RMnode *toModify,
float newValue)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
float newValue - a floating point value between 0.0 and 1.0. A value
of 0.0 means the object is completely transparent, while a value
of 1.0 means the object is completely opaque (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetOpacity">
<pre><b>
RMenum rmNodeGetOpacity (const RMnode *toQuery,
float *retValue)
</b></pre>
<pre>
RMnode *toQuery - a handle to an RMnode (input).
float *retValue - a handle to a caller-supplied float (modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetNormalizeNormals">
<pre><b>
RMenum rmNodeSetNormalizeNormals(RMnode *toModify,
RMenum newValue)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newValue - an RMenum value, may be either RM_TRUE or RM_FALSE (input).
</pre>
<menu><P>
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.
</P>
<P>
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."
</P>
<P>
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.
</P>
<P>
Use rmNodeGetNormalizeNormals to query this parameter.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetNormalizeNormals">
<pre><b>
RMenum rmNodeGetNormalizeNormals(const RMnode *toQuery,
RMenum *valueReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *valueReturn - a handle to a caller-supplied RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
See rmNodeSetNormalizeNormals() for more information.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetLineStyle">
<pre><b>
RMenum rmNodeSetLineStyle(RMnode *toModify,
RMenum newLineStyle)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newLineStyle - an RMenum value, may be one of RM_LINES_SOLID,
RM_LINES_DASHED, RM_LINES_DOTTED, RM_LINES_DOT_DASH or
RM_LINES_DASH_DASH_DOT (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetLineStyle">
<pre><b>
RMenum rmNodeGetLineStyle(const RMnode *toQuery,
RMenum *lineStyleReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *lineStyleReturn - a handle to a caller supplied RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
To obtain the render-time value of the line width parameter of the
RM rendering context, use rmStateGetLineStyle() from inside an application
callback.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetLineWidth">
<pre><b>
RMenum rmNodeSetLineWidth(RMnode *toModify,
RMenum widthEnum)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum widthEnum - an RMenum value. May be one of RM_LINEWIDTH_NARROW,
RM_LINEWIDTH_MEDIUM, RM_LINEWIDTH_HEAVY, or RM_LINEWIDTH_X, where
1 <= X <= 8 (input).
</pre>
<menu><P>
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.
</P>
<P>
<pre>
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
</pre>
</P>
<P>
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.
</P>
<P>
Use rmNodeGetLinewidth to obtain the line width attribute from an RMnode,
or rmStateGetLinewidth to obtain the line width attribute at
render time.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetLineWidth">
<pre><b>
RMenum rmNodeGetLineWidth(const RMnode *toQuery,
RMenum *lineWidthReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *lineWidthReturn - a handle to a caller supplied RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
Note that a linewidth enumerator is returned, not the actual pixel thickness
of the line.
</P>
<P>
To obtain the render-time value of the line width parameter of the
RM rendering context, use rmStateGetLineWidth() from inside an application
callback.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPointSize">
<pre><b>
RMenum rmNodeSetPointSize(RMnode *toModify,
float newSize)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
float newSize - a floating point value, must be greater than zero (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPointSize">
<pre><b>
RMenum rmNodeGetPointSize(const RMnode *toQuery,
float *sizeReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
float *sizeReturn - a handle to a caller-supplied float (result).
</pre>
<menu><P>
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.
</P>
<P>
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().
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPolygonDrawMode">
<pre><b>
RMenum rmNodeSetPolygonDrawMode(RMnode *toModify,
RMenum whichFace,
RMenum newMode)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum whichFace - an RMenum value, may be one of RM_FRONT, RM_BACK,
RM_FRONT_AND_BACK (input).
RMenum newMode - an RMenum value, may be one of RM_LINE, RM_FILL or RM_POINT.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success. Upon failure, the polygon draw mode
remains unmodified, and RM_WHACKED is returned.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPolygonDrawMode">
<pre><b>
RMenum rmNodeGetPolygonDrawMode(const RMnode *toQuery,
RMenum *returnFace,
RMenum *returnMode)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *returnFace, *returnMode - handles to caller-supplied RMenum's
(result).
</pre>
<menu><P>
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."
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPolygonCullMode">
<pre><b>
RMenum rmNodeSetPolygonCullMode(RMnode *toModify,
RMenum newMode)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newMode - an RMenum value. May be one of RM_CULL_NONE, RM_CULL_FRONT,
RM_CULL_BACK, or RM_CULL_FRONT_AND_BACK.
</pre>
<menu><P>
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.
</P>
<P>
By default, no polygon
culling is performed (RM_CULL_NONE is applied to rmRootNode() at
initialization time).
</P>
<P>
Whether or not a polygon is front or back facing is a function of how
vertices are ordered. See rmNodeSetFrontFace() for more information.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPolygonCullMode">
<pre><b>
RMenum rmNodeGetPolygonCullMode(const RMnode *toQuery,
RMenum *modeReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *modeReturn - a handle to a caller-supplied RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetFrontFace">
<pre><b>
RMenum rmNodeSetFrontFace(RMnode *toModify,
RMenum newMode)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newMode - an RMenum value, may be one of RM_CW or RM_CCW (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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).
</P>
<P>
Use rmNodeGetFrontFace() to obtain the front face winding rule parameter
from an RMnode.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetFrontFace">
<pre><b>
RMenum rmNodeGetFrontFace(const RMnode *toQuery,
RMenum *modeReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *modeReturn - a handle to a caller-supplied RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetShader">
<pre><b>
RMenum rmNodeSetShader(RMnode *toModify,
RMenum newMode)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newMode - an RMenum value (input). Must be one of RM_SHADER_SMOOTH,
RM_SHADER_FLAT or RM_SHADER_NOLIGHT.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
By default, rmRootNode() is assigned RM_SHADER_SMOOTH as the default
shader, and will remain in effect unless overridden.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetShader">
<pre><b>
RMenum rmNodeGetShader(const RMnode *toQuery,
RMenum *shaderReturn)
</b></pre>
<pre>
const RMnode *n - a handle to an RMnode (input).
RMenum *shaderReturn - a handle to an RMenum (result).
</pre>
<menu><P>
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.
</P>
<P>
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).
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTraversalMaskOpacity">
<pre><b>
RMenum rmNodeSetTraversalMaskOpacity(RMnode *toModify,
RMenum newVal)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newVal - an RMenum value. May be one of RM_RENDERPASS_TRANSPARENT,
RM_RENDERPASS_OPAQUE or RM_RENDERPASS_ALL.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTraversalMaskOpacity">
<pre><b>
RMenum rmNodeGetTraversalMaskOpacity(const RMnode *toQuery,
RMenum *maskReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *maskReturn - a handle to an RMenum value (result).
</pre>
<menu><P>
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.
</P>
<P>
See rmNodeSetTraversalMaskOpacity for more information about the
opacity traversal mask.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTraversalMaskDims">
<pre><b>
RMenum rmNodeSetTraversalMaskDims(RMnode *toModify,
RMenum newVal)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newVal - an RMenum value. May be one of RM_RENDERPASS_2D,
RM_RENDERPASS_3D or RM_RENDERPASS_ALL.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTraversalMaskDims">
<pre><b>
RMenum rmNodeGetTraversalMaskDims(const RMnode *toQuery,
RMenum *maskReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMenum *maskReturn - a handle to an RMenum value (result).
</pre>
<menu><P>
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.
</P>
<P>
See rmNodeSetTraversalMaskDims for more information about the
dimensions traversal mask.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTraversalMaskChannel">
<pre><b>
RMenum rmNodeSetTraversalMaskChannel(RMnode *toModify,
RMenum newVal)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newVal - an RMenum value. May be one of RM_LEFT_CHANNEL,
RM_RIGHT_CHANNEL or RM_ALL_CHANNELS.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTraversalMaskChannel">
<pre><b>
RMenum rmNodeGetTraversalMaskChannel(const RMnode *toQuery,
RMenum *maskReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode to query (input).
RMenum *maskReturn - a handle to an RMenum value (result).
</pre>
<menu><P>
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.
</P>
<P>
See rmNodeSetTraversalMaskChannel for more information about the
opacity traversal mask.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTransformMode">
<pre><b>
RMenum rmNodeSetTransformMode (RMnode *toModify,
RMenum newMode)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum newMode - an RMenum value. Must be one of
RM_TRANSFORM_GEOMETRY, RM_TRANSFORM_TEXTURE, or
RM_TRANSFORM_IGNORE.
</pre>
<menu><P>
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.
</P>
<P>
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).
</P>
<P>
By default, RMnodes are assigned a transformation mode of
RM_TRANSFORM_GEOMETRY when created by rmNodeNew().
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTransformMode">
<pre><b>
RMenum rmNodeGetTransformMode (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
</pre>
<menu><P>
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.
</P>
<P>
The transformation mode of RMnodes is by default
RM_TRANSFORM_GEOMETRY, as set by rmNodeNew(), but may be later
changed by using rmNodeSetTransformMode.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPreMatrix">
<pre><b>
RMenum rmNodeSetPreMatrix (RMnode *toModify,
const RMmatrix *newMatrix)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMmatrix *newMatrix - a handle to a caller-supplied RMmatrix
(input).
</pre>
<menu><P>
Use this routine to set the "pre matrix" transformation attribute of
an RMnode.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for a discussion of how the
transformation attributes of an RMnode are combined into a single
transformation.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPreMatrix">
<pre><b>
RMenum rmNodeGetPreMatrix (const RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetCenter">
<pre><b>
RMenum rmNodeSetCenter (RMnode *toModify,
const RMvertex3D *newVertex)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode to modify (modified).
const RMvertex3D *newVertex - a handle to an RMvertex3D (input).
</pre>
<menu><P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetCenter">
<pre><b>
RMenum rmNodeGetCenter (const RMnode *toQuery,
RMvertex3D *retVector)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode to query (input).
RMvertex3D *retVector - a handle to a caller-supplied RMvertex3D
object (modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetScaleMatrix">
<pre><b>
RMenum rmNodeSetScaleMatrix (RMnode *toModify,
const RMmatrix *newMatrix)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMmatrix *newMatrix - a handle to a caller-supplied RMmatrix
(input).
</pre>
<menu><P>
Use this routine to set the "pre-rotation scale matrix"
transformation attribute of an RMnode.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for a discussion of how the
transformation attributes of an RMnode are combined into a single
transformation.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetScaleMatrix">
<pre><b>
RMenum rmNodeGetScaleMatrix (const RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetRotateMatrix">
<pre><b>
RMenum rmNodeSetRotateMatrix (RMnode *toModify,
const RMmatrix *newMatrix)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMmatrix *newMatrix - a handle to a caller-supplied RMmatrix
(input).
</pre>
<menu><P>
Use this routine to set the "pre-rotation scale matrix"
transformation attribute of an RMnode.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for a discussion of how the
transformation attributes of an RMnode are combined into a single
transformation.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetRotateMatrix">
<pre><b>
RMenum rmNodeGetRotateMatrix (const RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPostRotateScaleMatrix">
<pre><b>
RMenum rmNodeSetPostRotateScaleMatrix (RMnode *toModify,
const RMmatrix *newMatrix)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMmatrix *newMatrix - a handle to a caller-supplied RMmatrix
(input).
</pre>
<menu><P>
Use this routine to set the "post-rotation scale matrix"
transformation attribute of an RMnode.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for a discussion of how the
transformation attributes of an RMnode are combined into a single
transformation.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPostRotateScaleMatrix">
<pre><b>
RMenum rmNodeGetPostRotateScaleMatrix (const RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetTranslateVector">
<pre><b>
RMenum rmNodeSetTranslateVector (RMnode *toModify,
const RMvertex3D *newVector)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMvertex3D *newVector - a handle to an RMvertex3D object
(input).
</pre>
<menu><P>
Use this routine to set the "translate vector" transformation
attribute in an RMnode. Returns RM_CHILL upon success, or RM_WHACKED
upon failure.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for information concerning how
the composite transformation matrix at an RMnode is derived from the
transformation attributes.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetTranslateVector">
<pre><b>
RMenum rmNodeGetTranslateVector (const RMnode *toQuery,
RMvertex3D *returnVector)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
RMvertex3D *returnVector - a handle to a caller-supplied RMvertex3D
object (modified).
</pre>
<menu><P>
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.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for more details concerning how
the RMnode transformation attributes are combined into a single,
composite transformation.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPostMatrix">
<pre><b>
RMenum rmNodeSetPostMatrix (RMnode *toModify,
const RMmatrix *newMatrix)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
const RMmatrix *newMatrix - a handle to a caller-supplied RMmatrix
(input).
</pre>
<menu><P>
Use this routine to set the "post matrix" transformation attribute of
an RMnode.
</P>
<P>
See rmNodeGetCompositeModelMatrix() for a discussion of how the
transformation attributes of an RMnode are combined into a single
transformation.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetPostMatrix">
<pre><b>
RMenum rmNodeGetPostMatrix (const RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
const RMnode *toQuery - a handle to the RMnode to query (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(modified).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetCompositeModelMatrix">
<pre><b>
RMenum rmNodeGetCompositeModelMatrix (RMnode *toQuery,
RMmatrix *matrixReturn)
</b></pre>
<pre>
RMnode *toQuery - a handle to an RMnode (input).
RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
(return).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
The composite transformation is the matrix product of:
</P>
<P>
[Pre -C S R S2 C T Post]
</P>
<P>
Where:
</P>
<P>
Pre (rmNodeSetPreMatrix, rmNodeGetPreMatrix) is the "pre
transformation" matrix applied prior to any other transformations.
</P>
<P>
-C and C are matrices representing a translation. C represents the
RMnode's "center point" attribute (rmNodeSetCenter, rmNodeGetCenter).
</P>
<P>
S is the "pre rotate" scale matrix (rmNodeSetScaleMatrix,
rmNodeGetScaleMatrix)
</P>
<P>
R is the RMnode's rotation matrix (rmNodeSetRotateMatrix,
rmNodeGetRotateMatrix).
</P>
<P>
S2 is the RMnode's "post rotate" scale matrix
(rmNodeSetPostRotateScaleMatrix, rmNodeGetPostRotateScaleMatrix).
</P>
<P>
T is a translation matrix derived from the RMnode's translation
vector (rmNodeSetTranslateVector, rmNodeGetTranslateVector).
</P>
<P>
Post is a transformation matrix applied after all other
transformations at an RMnode (rmNodeSetPostMatrix,
rmNodeGetPostMatrix).
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetRenderOrderCallback">
<pre><b>
RMenum rmNodeSetRenderOrderCallback (RMnode *toModify,
int (*appFunc)(const RMnode *, const RMstate *, int *orderIndices, int nChildren))
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
int (*appFunc)(const RMnode *, const RMstate *, int *, int) - A handle to an
application callback, or NULL (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
This routine first appeared in v1.4.3.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetSwitchCallback">
<pre><b>
RMenum rmNodeSetSwitchCallback (RMnode *toModify,
int (*appFunc)(const RMnode *, const RMstate *))
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
int (*appFunc)(const RMnode *, const RMstate *) - A handle to an
application callback, or NULL (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Use an RMnode's "pre traversal" callback to inhibit traversal rather
than returning an out-of-bounds index from the switch callback.
</P>
<P>
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.
</P>
<P>
See the rmStateGet*() family of routines for more details about the
type of render state information available to application callbacks.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPreTraversalCallback">
<pre><b>
RMenum rmNodeSetPreTraversalCallback (RMnode *toModify,
RMenum whichPass,
int (*appFunc)(const RMnode *, const RMstate *))
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum whichPass - an RMenum value that specifies during which stage
of multistage rendering the callback should be invoked. Use either
RM_VIEW or RM_RENDER.
int (*appFunc)(const RMnode *, const RMstate *) - A handle to an
application callback, or NULL (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
See the rmStateGet*() family of routines for more details about the
type of render state information available to application callbacks.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeSetPostTraversalCallback">
<pre><b>
RMenum rmNodeSetPostTraversalCallback (RMnode *toModify,
RMenum whichPass,
int (*appFunc)(const RMnode *, const RMstate *))
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
RMenum whichPass - an RMenum value that specifies during which stage
of multistage rendering the callback should be invoked. Use either
RM_VIEW or RM_RENDER.
int (*appFunc)(const RMnode *, const RMstate *) - A handle to an
application callback, or NULL (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
The return value from the post traversal callback is ignored.
</P>
<P>
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.
</P>
<P>
See the rmStateGet*() family of routines for more details about the
type of render state information available to application callbacks.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeMutexInit">
<pre><b>
RMenum rmNodeMutexInit(RMnode *toModify,
RMenum initialLockState)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (input).
RMenum initialLockState - an RMenum value (input). May be either
RM_MUTEX_LOCK or RM_MUTEX_UNLOCK.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeMutexUnlock">
<pre><b>
RMenum rmNodeMutexUnlock (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeMutexLock">
<pre><b>
RMenum rmNodeMutexLock (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeMutexTryLock">
<pre><b>
RMenum rmNodeMutexTryLock (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
int *returnValue - a handle to a caller-supplied int (return).
</pre>
<menu><P>
Performs a non-blocking lock of the RMmutex in the RMnode
toQuery. Return values are the same as those for rmMutexTryLock.
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeGetMutex">
<pre><b>
RMmutex * rmNodeGetMutex (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
</pre>
<menu><P>
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().
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeMutexDelete">
<pre><b>
RMenum rmNodeMutexDelete (RMnode *toModify)
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (input).
</pre>
<menu><P>
Deletes the RMmutex in the RMnode "toModify." Upon success,
RM_CHILL is returned. A return value of RM_WHACKED indicates some
type of error.
</P>
<P>
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.
</P>
<P>
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:
</P>
<P>
- 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.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
<a name="rmNodeFrustumCullCallback">
<pre><b>
int rmNodeFrustumCullCallback(const RMnode *n, const RMstate *s)
</b></pre>
<pre>
const RMnode *n - an RMnode pointer (input).
const RMstate *s - an RMstate pointer (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
When this routine is used as indicated in the code example below, the
result if view frustum culling for RMnodes.
</P>
<P>
Example code:
</P>
<P>
<pre>
</P>
<P>
RMnode *n = rmNodeNew("myNode",RM_RENDERPASS_ALL, RM_RENDERPASS_ALL);
</P>
<P>
... other node config and primitive building omitted ...
</P>
<P>
rmNodeComputeBoundingBox(n);
</P>
<P>
rmNodeSetPretraversalCallback(n, RM_VIEW, rmNodeFrustumCallback);
</P>
<P>
</pre>
</P>
<P>
Caveats:
</P>
<P>
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).
</P>
<P>
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.
</P>
<P>
3. This routine has been tested for perspective projections, but
needs to be tested with orthographic projections.
</P>
<P>
For best results, the size of the bounding box should be < the
size of the frustum.
</P></menu>
<i>librm library source file: rmnode.c </i><hr width="75%">
</body></html>
