<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmprim.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="rmPrimitiveNew">
<pre><b>
RMprimitive * rmPrimitiveNew (RMenum primType)
</b></pre>
<pre>
RMenum primType - an RMenum value specifying the RM primitive type.
See below for more information (input).
</pre>
<menu><P>
Use this routine to create a new RMprimitive object of a specified
type. Returns a handle to the new RMprimitive upon success, or NULL
upon failure.
</P>
<P>
The current list of valid RMenum values for the primType parameter
are: RM_LINES, RM_LINE_STRIP, RM_TRIANGLES, RM_TRIANGLE_STRIP,
RM_SPHERES, RM_QUADMESH, RM_OCTMESH, RM_TEXT, RM_POINTS, RM_CONES,
RM_CYLINDERS, RM_INDEXED_TEXT, RM_QUADS, RM_MARKERS2D, RM_BOX3D_WIRE,
RM_CIRCLE2D, RM_ELLIPSE2D, RM_SPRITE, RM_TRIANGLE_FAN,
RM_INDEXED_TFAN, RM_POLYS, RM_QUAD_STRIP, RM_INDEXED_QUADS,
RM_INDEXED_TRIANGLES, RM_INDEXED_TRIANGLE_STRIP and RM_USERDEFINED_PRIM.
</P>
<P>
Some of the procedural primitives are assigned default "model flag"
attributes (see rmPrimitiveSetModelFlag). These are:
</P>
<P>
RM_SPHERES: RM_SPHERES_32 produces a 32-faced sphere tesselation.
</P>
<P>
RM_OCTMESH: RM_OCTMESH_1 produces a "full resolution" octmesh
primitive.
</P>
<P>
RM_CONES: RM_CONES_16 produces a cone consisting of 16 radial
subdivisions.
</P>
<P>
RM_CYLINDERS: RM_CYLINDERS_16 produces a cylinder consisting of 16
radial subdivisions.
</P>
<P>
When the RMprimitive is created, it has no vertices, normals,
etc. and it is not associated with any scene graph node. Use
rmNodeAddPrimitive() to add an RMprimitive to a node.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveDelete">
<pre><b>
void rmPrimitiveDelete (RMprimitive *toDelete)
</b></pre>
<pre>
RMprimitive *toDelete - a handle to an RMprimitive to delete
(modified).
</pre>
<menu><P>
Use this routine to release resources associated with an RMprimitive.
</P>
<P>
If shared data management was specified (when rmPrimitiveSetVertex3D
was called, for example), those application callback functions will
be invoked to free large-payload memory.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetRenderFunc">
<pre><b>
RMenum rmPrimitiveSetRenderFunc (RMprimitive *toModify,
void (*drawFunc) OGLPRIMPARMLIST() )
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
void (*drawFunc) OGLPRIMPARMLIST() - a callback invoked to draw the
primitive (input).
</pre>
<menu><P>
This routine assigns the draw callback to an RMprimitive. When an
RMprimitive is created with rmPrimitiveNew(), the draw callback is
automatically assigned except when rmPrimitiveNew is invoked with
RM_USERDEFINED_PRIM. Applications that want to assign a draw function
to an RMprimitive should use this function. This routine returns
RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
The draw callback contains raw OpenGL code that performs the
rendering. The parameter list to the draw callback is represented
with the macro OGLPRIMPARMLIST(). At this time (June 2002), that macro
expands to:
</P>
<P>
(RMprimitive *primToDraw, RMnode *owningNode, RMstate *currentRenderState, RMpipe *renderPipe, RMstateCache *internalStateCache)
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveGetRenderFunc">
<pre><b>
void * rmPrimitiveGetRenderFunc (const RMprimitive *toQuery)
</b></pre>
<pre>
const RMprimitive *toQuery - a handle to the RMprimitive object to
query (input).
</pre>
<menu><P>
Returns to the caller the handle to the draw callback associated with
the input RMprimitive.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetModelFlag">
<pre><b>
RMenum rmPrimitiveSetModelFlag (RMprimitive *toModify,
int newVal)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int newVal - an integer value specifying a new RMprimitive model flag
(see below for more info) (input).
</pre>
<menu><P>
Use this routine to modify the "primitive model flag" for an
RMprimitive. Returns RM_CHILL upon success or RM_WHACKED upon
failure.
</P>
<P>
The RMprimitive model flag is used to control the rendering
resolution of primitives. Only a few RMprimitive types are eligible
for this kind of resolution control: RM_SPHERES, RM_CONES,
RM_CYLINDERS and RM_OCTMESH.
</P>
<P>
RM_SPHERES model flags: RM_SPHERES_8, RM_SPHERES_32, RM_SPHERES_128,
and RM_SPHERES_512. These flags affect the tesselation resolution
used when rendering spheres. RM_SPHERES_8 produces an octahedron, and
each of the other model flags is a midpoint-subdivision refinement
refinement of the octahedron. The RM sphere tesselation model is
superior to the one in GLU for two reasons. First, the faces of the
tesselation are all equal in area. Second, the faces of the
tesselation are triangles, so there are no non-planar faces;
gluSphere tesselates a sphere into non-planar quads. Internally, RM
builds OpenGL display lists for each sphere tesselation then invokes
that display list at render time, positioned and scaled to the
specifications of the RMprimitive.
</P>
<P>
RM_CONES and RM_CYLINDERS use the following set: RM_CONES_4,
RM_CONES_8, RM_CONES_12, RM_CONES_16, RM_CONES_32, RM_CONES_64, and
RM_CONES_128; RM_CYLINDERS_4, RM_CYLINDERS_8, RM_CYLINDERS_12,
RM_CYLINDERS_16, RM_CYLINDERS_32, RM_CYLINDERS_64, and
RM_CYLINDERS_128. The tesselation of cones and cylinders is nearly
identical: the ideal circle (at the base of the cone, and at each end
of the cylinder) is discretized with 4, 8, 12, 16, 32, 64 or 128
points, respectively. In the case of cones, a single triangle joints
each adjacent pair of sample points with the cone apex, while a
cylinder uses a pair of triangles to join each pair of sample points
between ends of the cylinder. Internally, RM builds OpenGL display
lists (t-fans for cones and t-strips for cylinders).
</P>
<P>
RM_OCTMESH: RM_OCTMESH_1, RM_OCTMESH_2, RM_OCTMESH_4, RM_OCTMESH_8,
RM_OCTMESH_16. The octmesh primitive model flag can be considered a
"divide by" constant. In other words, if the base resolution of the
octmesh grid is 64x64x64 and RM_OCTMESH_2 is used, then the
resolution of the polygonalized model will be 32x32x32, but will be
fill the space (volume) specified by the octmesh grid. This model
flag can accelerate rendering of volume data on pixel-fill limited
systems.
</P>
<P>
Note: the model flag values are not RMenum's - they are in fact
indices into internal tables. Please don't change the #defines for
the the model flags.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveGetModelFlag">
<pre><b>
int rmPrimitiveGetModelFlag (const RMprimitive *toQuery)
</b></pre>
<pre>
const RMprimitive *toQuery - a handle to an RMprimitive to query
(input).
</pre>
<menu><P>
Returns to the caller the current primitive model flag associated
with the RMprimitive object.
</P>
<P>
RM_WHACKED is returned for RMprimitives that don't know about model
flags.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveComputeBoundingBox">
<pre><b>
RMenum rmPrimitiveComputeBoundingBox (RMprimitive *toModify)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
</pre>
<menu><P>
Use this routine to automatically compute an RMprimitive's bounding box.
This routine returns RM_CHILL upon success, or RM_WHACKED upon failure.
Failure will occur if the input RMprimitive is NULL.
</P>
<P>
See the description of rmPrimitiveSetBoundingBox for more details about
when an RMprimitive's bounding box should be set, or computed, as well
as discussion about the relationship between the RMprimitive and RMnode
bounding boxes. Use rmPrimitiveGetBoundingBox() to obtain an RMprimitive's
bounding box.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetBoundingBox">
<pre><b>
RMenum rmPrimitiveSetBoundingBox (RMprimitive *toModify, const RMvertex3D *bmin, const RMvertex3D *bmax)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
const RMvertex3D *bmin, *bmax - handles to RMvertex3D's.
</pre>
<menu><P>
Use this routine to explicitly set the bounding box at an RMprimitive. The
bounding box of the RMprimitive toModify will be set to the RMvertex3D
values specified in the input parameters bmin and bmax. Returns RM_CHILL
upon success, or RM_WHACKED upon failure. If bmin or bmax are NULL, those
portions of the RMprimitive's bounding box are removed, leaving the
bounding box in an undefined and uninitialized state.
</P>
<P>
The RMprimitive's bounding box is automatically computed by RM in the
following circumstances:
1. list them
</P>
<P>
The relationship between the RMprimitive and RMnode bounding box is ...
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveGetBoundingBox">
<pre><b>
RMenum rmPrimitiveGetBoundingBox (const RMprimitive *toQuery, RMvertex3D *bminReturn, RMvertex3D *bmaxReturn)
</b></pre>
<pre>
const RMprimitive *toQuery - a handle to an RMprimitive (input).
RMvertex3D *bminReturn, *bmaxReturn;
</pre>
<menu><P>
Use this routine to obtain an RMprimitive's bounding box. Upon success,
RM_CHILL is returned, and the bounding box minimum and maximum are copied
into the application-supplied RMvertex3D parameters. If either of the
RMprimitive's minimum or maximum bounding box parameters are NULL (i.e.,
they have not been initialized), this routine will return RM_WHACKED.
</P>
<P>
The application can request one, or both, of the bounding box minimum or
maximum values. In other words, the application may specify NULL for
either of the minimum or maximum bounding box return parameters.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveGetType">
<pre><b>
RMenum rmPrimitiveGetType (const RMprimitive *toQuery)
</b></pre>
<pre>
(input).
</pre>
<menu><P>
Returns to the caller the input RMprimitive's "type" RMenum
attribute. RM_WHACKED is returned if the input RMprimitive is
NULL. For a list of RMprimitive type enums, please see
rmPrimitiveNew().
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetClientData">
<pre><b>
RMenum rmPrimitiveSetClientData (RMprimitive *toModify,
void *clientData,
void (*cdFreeFunc)(RMprimitive *,void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
void *clientData - a handle (input).
void (*cdFreeFunc)(RMprimitive *, void *) - a handle to an application
callback (input).
</pre>
<menu><P>
This routine stores a memory handle (pointer) in an RMprimitive,
returning RM_CHILL upon success or RM_WHACKED upon failure. RM
basically ignores this handle; it's use, management and so forth is
entirely under control of the application. This is a simple mechanism
for applications to store a memory handle in an RMprimitive for
subsequent use in an application-specific manner.
</P>
<P>
Client data may be stored in both RMprimitives and RMnodes
(rmNodeSetClientData).
</P>
<P>
The "client data" handle may be later accessed using
rmPrimitiveGetClientData.
</P>
<P>
The callback function will be invoked when the RMprimitive is
deleted. The callback takes two parameters, a handle to the
RMprimitive containing the client data handle, and the client data
handle itself. The callback is provided so that applications may
delete the data referenced by the client data handle stored in the
RMprimitive.
</P>
<P>
When the input client data handle is NULL, the old handle value is
effectively overwritten. Any memory pointed to by the old client data
handle will be lost (a potential memory leak).
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveGetClientData">
<pre><b>
void * rmPrimitiveGetClientData (const RMprimitive *toQuery)
</b></pre>
<pre>
const RMprimitive *toQuery - a handle to an RMprimitive (input).
</pre>
<menu><P>
Use this routine to obtain the client data handle stored in an
RMprimitive.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetVertex2D">
<pre><b>
RMenum rmPrimitiveSetVertex2D (RMprimitive *toModify,
int nVertices,
RMvertex2D *vertexData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nVertices - an integer value, specifies the number of vertices
that will be assigned to the RMprimitive (input).
RMvertex2D *vertexData - a handle to a flat array of RMvertex2D
objects (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetVertex2D is one of a family of routines used to assign
data to RMprimitives. This routine assigns raw 2D vertex data to an
RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon
failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw vertex data provided in "vertexData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMvertex2D data,
but instead will simply copy the handle "vertexData" into the
RMprimitive, and refer to the caller-supplied memory directly in
later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMvertex2D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMvertex2D is assigned (more precisely, if new vertex data
is assigned, regardless of whether or not it is 3D or 2D). The
application callback takes a single parameter: a handle to the
underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get vertex" routine. Primitive vertex data
should be considered write-only by the application.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetVertex3D">
<pre><b>
RMenum rmPrimitiveSetVertex3D (RMprimitive *toModify,
int nVertices,
RMvertex3D *vertexData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nVertices - an integer value, specifies the number of vertices
that will be assigned to the RMprimitive (input).
RMvertex3D *vertexData - a handle to a flat array of RMvertex3D
objects (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetVertex3D is one of a family of routines used to assign
data to RMprimitives. This routine assigns raw 3D vertex data to an
RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon
failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw vertex data provided in "vertexData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMvertex3D data,
but instead will simply copy the handle "vertexData" into the
RMprimitive, and refer to the caller-supplied memory directly in
later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMvertex3D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMvertex3D is assigned (more precisely, if new vertex data
is assigned, regardless of whether or not it is 3D or 2D). The
application callback takes a single parameter: a handle to the
underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get vertex" routine. Primitive vertex data
should be considered write-only by the application.
</P>
<P>
NOTE: some compilers enforce 8-byte alignment/padding of C
structures. Since the RMvertex3D object consists of 3 floats, some
compilers will pad memory to produce 8-byte alignment. The underlying
RM data management infrastructure accomodates this added
complexity. However, on such systems, callers that pass in a flat
array of floats cast to RMvertex3D * should be aware that the data is
considered to be a flat array of RMvertex3D objects inside this
routine, not a flat array of floats.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetColor3D">
<pre><b>
RMenum rmPrimitiveSetColor3D (RMprimitive *toModify,
int nColors,
RMcolor3D *colorData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nColors - an integer value, specifies the number of 3-component
colors that will be assigned to the RMprimitive (input).
RMcolor3D *vertexData - a handle to a flat array of RMcolor3D objects
(input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetColor3D is one of a family of routines used to assign
data to RMprimitives. This routine assigns raw 3-component color data
to an RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon
failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw color data provided in "colorData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMcolor3D data, but
instead will simply copy the handle "colorData" into the RMprimitive,
and refer to the caller-supplied memory directly in later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMcolor3D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMcolor3D is assigned (more precisely, if new color data is
assigned, regardless of whether or not it is 3D or 4D). The
application callback takes a single parameter: a handle to the
underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get colors" routine. Primitive color data
should be considered write-only by the application.
</P>
<P>
NOTE: some compilers enforce 8-byte alignment/padding of C
structures. Since the RMcolor3D object consists of 3 floats, some
compilers will pad memory to produce 8-byte alignment. The underlying
RM data management infrastructure accomodates this added
complexity. However, on such systems, callers that pass in a flat
array of floats cast to RMcolor3D * should be aware that the data is
considered to be a flat array of RMcolor3D objects inside this
routine, not a flat array of floats.
</P>
<P>
In RM, 3-component color data is RGB. 4-component colors are RGBA.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetColor4D">
<pre><b>
RMenum rmPrimitiveSetColor4D (RMprimitive *toModify,
int nColors,
RMcolor4D *colorData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nColors - an integer value, specifies the number of 3-component
colors that will be assigned to the RMprimitive (input).
RMvertex4D *vertexData - a handle to a flat array of RMcolor4D
objects (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetColor4D is one of a family of routines used to assign
data to RMprimitives. This routine assigns raw 4-component color data
to an RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon
failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw color data provided in "colorData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMcolor4D data, but
instead will simply copy the handle "colorData" into the RMprimitive,
and refer to the caller-supplied memory directly in later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMcolor4D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMcolor4D is assigned (more precisely, if new color data is
assigned, regardless of whether or not it is 3D or 4D). The
application callback takes a single parameter: a handle to the
underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get colors" routine. Primitive color data
should be considered write-only by the application.
</P>
<P>
In RM, 3-component color data is RGB. 4-component colors are RGBA.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetRadii">
<pre><b>
RMenum rmPrimitiveSetRadii (RMprimitive *toModify,
int nRadii,
float *radii,
RMenum copyEnum,
void (*freeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nRadii - an integer values specifying the number of input radius
values, the length of the radii[] array (input).
float *radii - a flat array of floating point values (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*freeFunc)(void *) - a handle to an application callback,
required when copyEnum is RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
Use this routine to assign radius values to RMprimitives. Radius
values are used by sphere, cone and cylinder primitives. Returns
RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw radius data provided in "radii." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the radius data, but
instead will simply copy the handle "colorData" into the RMprimitive,
and refer to the caller-supplied memory directly in later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the radius data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new radius is assigned. The application callback takes a
single parameter: a handle to the underlying data array that is
managed by the application.
</P>
<P>
There is no corresponding "get radii" routine. Primitive radius data
should be considered write-only by the application.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetNormal3D">
<pre><b>
RMenum rmPrimitiveSetNormal3D (RMprimitive *toModify,
int nNormals,
RMvertex3D *normalsData,
RMenum copyEnum,
void (*freeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive to modify
(modified).
int nNormals - an integer value specifying the number of input
normals in the normals[] array (input).
RMvertex3D *normalsData - a handle to an RMvertex3D array (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*freeFunc)(void *) - a handle to an application callback,
required when copyEnum is RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
This routine is used to assign a flat array of normals to an
RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon
failure. In most instances, per-vertex normals are required. Quads
and disjoint triangle primitives allow per-face normals.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw normals data provided in "normalsData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMvertex3D data,
but instead will simply copy the handle "normalsData" into the
RMprimitive, and refer to the caller-supplied memory directly in
later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMvertex3D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMvertex3D is assigned. The application callback takes a
single parameter: a handle to the underlying data array that is
managed by the application.
</P>
<P>
There is no corresponding "get normals" routine. Primitive normal
data should be considered write-only by the application.
</P>
<P>
NOTE: some compilers enforce 8-byte alignment/padding of C
structures. Since the RMvertex3D object consists of 3 floats, some
compilers will pad memory to produce 8-byte alignment. The underlying
RM data management infrastructure accomodates this added
complexity. However, on such systems, callers that pass in a flat
array of floats cast to RMvertex3D * should be aware that the data is
considered to be a flat array of RMvertex3D objects inside this
routine, not a flat array of floats.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetTexcoord2D">
<pre><b>
RMenum rmPrimitiveSetTexcoord2D (RMprimitive *toModify,
int nTexCoords,
RMvertex2D *texCoordData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nTexCoords - an integer value, specifies the number of 2D texture
coordinates that will be assigned to the RMprimitive (input).
RMvertex2D *texCoordData - a handle to a flat array of RMvertex2D
objects (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetTexcoord2D is one of a family of routines used to
assign data to RMprimitives. This routine assigns 2D texture
coordinates to an RMprimitive, returning RM_CHILL upon success or
RM_WHACKED upon failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw vertex data provided in "texCoordData." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the RMvertex2D data,
but instead will simply copy the handle "texCoordData" into the
RMprimitive, and refer to the caller-supplied memory directly in
later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the texture coordinate
data in an RMprimitive is deleted. Such deletion occurs when the
RMprimitive itself is deleted, the RMnode containing the RMprimitive
is deleted (if the RMprimitive was assigned to an RMnode with
rmNodeAddChild()), or if new texture coordinate data is assigned.
The application callback takes a single parameter: a handle to the
underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get texture coordinate" routine. Primitive
vertex data should be considered write-only by the application.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetTexcoord3D">
<pre><b>
RMenum rmPrimitiveSetTexcoord3D (RMprimitive *toModify,
int nTexcoords,
RMvertex3D *texCoordData,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nTexcoords - an integer value, specifies the number of texture
coordinates that will be assigned to the RMprimitive (input).
RMvertex3D *texCoordData - a handle to a flat array of RMvertex3D
objects (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application
callback. When "copyEnum" is RM_DONT_COPY_DATA, the application
must provide a callback used to release memory when the
RMprimitive is delete (input).
</pre>
<menu><P>
rmPrimitiveSetTexcoord3D is one of a family of routines used to
assign data to RMprimitives. This routine assigns raw 3D texture
coordinate data to an RMprimitive, returning RM_CHILL upon success or
RM_WHACKED upon failure.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw texture coordinate data provided in "texCoordData." When
"copyEnum" is set to RM_DONT_COPY_DATA, RM will not make a copy of
the RMvertex3D data, but instead will simply copy the handle
"texCoordData" into the RMprimitive, and refer to the caller-supplied
memory directly in later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the RMvertex3D data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new RMvertex3D is assigned (more precisely, if new texture
coordinate data is assigned, regardless of whether or not it is 3D or
2D). The application callback takes a single parameter: a handle to
the underlying data array that is managed by the application.
</P>
<P>
There is no corresponding "get texture coordinate" routine. Primitive
vertex data should be considered write-only by the application.
</P>
<P>
NOTE: some compilers enforce 8-byte alignment/padding of C
structures. Since the RMvertex3D object consists of 3 floats, some
compilers will pad memory to produce 8-byte alignment. The underlying
RM data management infrastructure accomodates this added
complexity. However, on such systems, callers that pass in a flat
array of floats cast to RMvertex3D * should be aware that the data is
considered to be a flat array of RMvertex3D objects inside this
routine, not a flat array of floats.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetIndices">
<pre><b>
RMenum rmPrimitiveSetIndices (RMprimitive *toModify,
int numIndices,
int *indicesArray,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int numIndices - an integer value specifying the length of the
indicesArray[] array (input).
int *indicesArray - a flat array of integer indices (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application callback,
required when copyEnum is RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
Use this routine to set "index values" in an RMprimitive. Returns
RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
Some RMprimitive objects allow the use of "indexed" vertices. At this
time (Feb 2004), these include RM_INDEXED_TFAN, RM_INDEXED_TEXT, and
RM_INDEXED_BITMAP, RM_INDEXED_QUADS, RM_INDEXED_TRIANGLES,
and RM_INDEXED_TRIANGLE_STRIP. (Plans
are underway to grow the number of indexed primitives).
</P>
<P>
In non-indexed primitives, the number of objects drawn on screen is a
function of the number of vertices in the RMprimitive and the
primitive type itself. For example, in RM_TRIANGLES primitives
(disjoint triangles), the number of triangles that are drawn is the
number of vertices divided by 3. For RM_INDEXED_TRIANGLES, the number
of triangles that will be drawn is instead the number of indices
divided by 3. For RM_INDEXED_QUADS, the number of quads drawn is the
number of indices divided by 4. For RM_INDEXED_TRIANGLE_STRIP, the
number of triangles draw is the number of indices-2 (e.g, four
indices produces 2 triangles).
</P>
<P>
Each entry in the index array is an index into another array.
</P>
<P>
Index values in the RM_INDEXED_TEXT are offsets into an array of text
strings. Index values in RM_INDEXED_BITMAP primitives are offsets
into an array of RMbitmap objects. Index values in RM_INDEXED_TFAN
are offsets into a vertex array.
</P>
<P>
When "copyEnum" is set to RM_COPY_DATA, RM will make a copy of the
raw index data provided in "indexArray." When "copyEnum" is set to
RM_DONT_COPY_DATA, RM will not make a copy of the index data, but
instead will simply copy the handle "indexArray" into the
RMprimitive, and refer to the caller-supplied memory directly in
later operations.
</P>
<P>
When RM_DONT_COPY_DATA is specified, applications must supply a
callback function that will be invoked when the index data in an
RMprimitive is deleted. Such deletion occurs when the RMprimitive
itself is deleted, the RMnode containing the RMprimitive is deleted
(if the RMprimitive was assigned to an RMnode with rmNodeAddChild()),
or if new index is assigned. The application callback takes a single
parameter: a handle to the underlying data array that is managed by
the application.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetSprites">
<pre><b>
RMenum rmPrimitiveSetSprites (RMprimitive *toModify,
int nSprites,
RMimage **spriteArray)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nSprites - an integer value specifying the number of sprites that
will be assigned to an RM_SPRITE primitive (input).
RMimage **spriteArray - an array of RMimage handles (input).
</pre>
<menu><P>
RM_SPRITE primitives are image-based primitives consisting of vertex
and image data. rmPrimitiveSetSprites is used to assign the image
data to the RM_SPRITE primitive.
</P>
<P>
Shared data management of the raw pixel data is specified as an
interface to the RMimage object, hence specification of
RM_COPY_DATA/RM_DONT_COPY_DATA is not necessary at the RMprimitive
level for RM_SPRITES. Inside this routine, all the images in the
spriteArray are duplicated with rmImageDup(). Please refer to
rmImageDup() for more details about shared data management of pixel
data in RMimage objects.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetBitmaps">
<pre><b>
RMenum rmPrimitiveSetBitmaps (RMprimitive *toModify,
int nBitmaps,
RMbitmap **bmapArray)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nBitmaps - an integer value specifying the number of RMbitmap
objects to assign to an RMprimitive (input).
RMbitmap **bmapArray - an array of RMbitmap handles (input).
</pre>
<menu><P>
Primitives of the type RM_BITMAP or RM_INDEXED_BITMAP consist of
vertex data and RMbitmap objects (the indexed form also takes
indices). Use this routine to assign RMbitmap data to the
RMprimitive. It returns RM_CHILL upon success, or RM_WHACKED upon
failure.
</P>
<P>
There is no shared data management of RMbitmap data since these
objects are small.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetQmeshDims">
<pre><b>
RMenum rmPrimitiveSetQmeshDims (RMprimitive *toModify,
int uSize,
int vSize)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int uSize, vSize - integer values specifying the dimensions of a
lattice defining a quadmesh (input).
</pre>
<menu><P>
A quadmesh primitive may be considered as a two-dimensional lattice
of points. The points themselves may be specified with two or three
dimensional coordinate values. This routine is used to specify the
number of points in each of the two dimensions of the lattice, and
returns RM_CHILL upon success or RM_WHACKED upon failure.
</P>
<P>
Quadmesh primitives require, in addition to a grid size set with
rmPrimitiveSetQmeshDims, vertex data set with rmPrimitiveSetVertex3D
or rmPrimitiveSetVertex2D. Colors, normals and texture coordinates
are all optional.
</P>
<P>
The routines rmPrimitiveSetQmeshDims and rmPrimitiveSetVertex3D/2D
may be called in any order, but both must be called before a quadmesh
primitive is rendered.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetOmeshDims">
<pre><b>
RMenum rmPrimitiveSetOmeshDims (RMprimitive *toModify,
int isize,
int jsize,
int ksize)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int isize, jsize, ksize - integer values specifying the number of
points in a three dimensional hexahedral lattice (input).
</pre>
<menu><P>
The OpenRM Octmesh primitive is logically a three-dimensional,
hexahedral lattice. Use this routine to set the dimensions of the
lattice. In most cases, "isize" will correspond to the x-axis,
"jsize" to the y-axis and "ksize" to the z-axis.
</P>
<P>
In OpenRM, direct volume rendering is achieved with a combination of
an octmesh primitive and a 3D texture. The 3D texture provides color
and opacity information, while the octmesh primitive specifies the
geometric placement and resolution of the underlying 3D lattice.
</P>
<P>
The octmesh primitive is procedural in that texture coordinates are
automatically generated at render time. Use rmPrimitiveSetModelFlag
to coarsen or refine render-time sampling of the underlying Octmesh
grid.
</P>
<P>
(Jan 2000) - use rmPrimitiveSetOmeshMinMaxGrid() to specify the
corners of the 3D lattice. Use of rmPrimitiveSetVertex3D on octmesh
primitives is not yet implemented.
</P>
<P>
Note: the dimensions of the Octmesh lattice must be specified prior
(using this routine, rmPrimitiveSetOmeshDims) prior to the
specification of the corners of the lattice (using
rmPrimitiveSetOmeshMinMaxGrid).
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetOmeshMinMaxGrid">
<pre><b>
RMenum rmPrimitiveSetOmeshMinMaxGrid (RMprimitive *toModify,
const RMvertex3D *gridMin,
const RMvertex3D *gridMax)
</b></pre>
<pre>
RMprimitive *p - a handle to an RMprimitive (modified).
const RMvertex3D *gridMin, *gridMax - handles to RMvertex3D objects
(input).
</pre>
<menu><P>
Use this routine to set the minimum and maximum coordinates for the
3D lattice that defines an octmesh primitive. The spatial extents of
the lattice are specified with this routine, whereas the resolution
of the lattice is specified with rmPrimitiveSetOmeshDims().
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
Note: the dimensions of the Octmesh lattice must be specified prior
(using rmPrimitiveSetOmeshDims) prior to the specification of the
corners of the lattice (using rmPrimitiveSetOmeshMinMaxGrid).
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetMarkerScale">
<pre><b>
RMenum rmPrimitiveSetMarkerScale (RMprimitive *toModify,
int npts,
float *scales,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int npts - an integer value specifying the length of the "scales"
array (input).
float *scales - a flat array of floats, expected to be "npts" in
length (input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application callback,
required when copyEnum is RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
Use this routine to set the scale values applied to RM "marker
primitives." Returns RM_CHILL upon success, or RM_WHACKED upon
failure.
</P>
<P>
The "marker primitive" in RM is a procedural primitive built from a
number of predefined shapes, such as a triangles, squares, and so
forth (see rmv.h). A fully populated marker primitive will consist of
some number of vertices (each vertex defines the center point for the
procedural marker), optional scale values used to isometrically
shrink or expand the underlying marker geometric model, and optional
color values. The number of vertices defined by
rmPrimitiveSetVertex2D/3D defines the number of marker primitives
that will be drawn.
</P>
<P>
The number of marker shapes that are drawn by a given RMprimitive
object is either 1 (drawn at many places in the scene, defined by
rmPrimitiveSetVertex2D/3D), or the same as the number of vertices
defined by rmPrimitiveSetVertex2D/3D. The marker primitives
themselves are created by rmInternalMarker2DNew() and assigned to the
RMprimitive with rmPrimitiveSetMarkerPrims().
</P>
<P>
The number of scale values may be either 1, or the same as the number
of vertices specified with rmPrimitiveSetVertex2D/3D.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetMarkerPrims">
<pre><b>
RMenum rmPrimitiveSetMarkerPrims (RMprimitive *toModify,
int nMarkerPrims,
RMinternalMarker2D **mArray)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nMarkerPrims - an integer value specifying the number of input
"marker primitives" in the mArray parameter (input).
RMinternalMarker2D **mArray - a handle to a flat array of
RMinternalMarker2D handles (input).
</pre>
<menu><P>
Use this routine to assign some number of procedural marker
primitives (RMinternalMarker2D) to an RMprimitive. Returns RM_CHILL
upon success, or RM_WHACKED upon failure. Use
rmInternalMarker2DNew() to create the marker primitives.
</P>
<P>
The "marker primitive" in RM is a procedural primitive built from a
number of predefined shapes, such as a triangles, squares, and so
forth (see rmv.h). A fully populated marker primitive will consist of
some number of vertices (each vertex defines the center point for the
procedural marker), optional scale values used to isometrically
shrink or expand the underlying marker geometric model, and optional
color values. The number of vertices defined by
rmPrimitiveSetVertex2D/3D defines the number of marker primitives
that will be drawn.
</P>
<P>
The number of marker shapes that are drawn by a given RMprimitive
object is either 1 (drawn at many places in the scene, defined by
rmPrimitiveSetVertex2D/3D), or the same as the number of vertices
defined by rmPrimitiveSetVertex2D/3D. The marker primitives
themselves are created by rmInternalMarker2DNew() and assigned to the
RMprimitive with rmPrimitiveSetMarkerPrims().
</P>
<P>
The number of scale values may be either 1, or the same as the number
of vertices specified with rmPrimitiveSetVertex2D/3D.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetEllipse2DRotate">
<pre><b>
RMenum rmPrimitiveSetEllipse2DRotate (RMprimitive *toModify,
int nVals,
float *rotationValues,
RMenum copyEnum,
void (*appFreeFunc)(void *))
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nVals - an integer value specifying the length of the
rotationValues[] array (input).
float *rotationValues - an array of floats, must be nVals in length
(input).
RMenum copyEnum - an RMenum value, may be either RM_COPY_DATA or
RM_DONT_COPY_DATA (input).
void (*appFreeFunc)(void *) - a handle to an application callback,
required when copyEnum is RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
Use this routine to set the rotation angles for some number of
ellipses in an RM_ELLIPSE2D primitive. Returns RM_CHILL upon success,
or RM_WHACKED upon failure.
</P>
<P>
RM ellipse primitives consist of vertices that define the center of
each ellipse (rmPrimitiveSetVertex2D), optional per-ellipse color
data, optional per-ellipse scale values (2 radius values per ellipse)
and an optional per-ellipse rotation value.
</P>
<P>
At render time, for each input vertex, or ellipse center, an
idealized ellipse is first scaled, rotated, then translated to the
desired location.
</P>
<P>
The per-ellipse rotation value defines a counterclockwise rotation
about the Z-axis, where it is assumed that the ellipse is defined in
the x/y plane. The rotation values are specified in degrees (not
radians). A input rotation value of 90 will cause the ellipse to be
rotated 90 degrees counterclockwise.
</P>
<P>
When copyEnum is set to RM_COPY_DATA, the rotation values provided by
the caller will be copied. When copyEnum is set to RM_DONT_COPY_DATA,
the handle "rotationValues" will be used directly by the RMprimitive.
The caller must provide a callback in conjunction with
RM_DONT_COPY_DATA that will be invoked when the RMprimitive is
deleted.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetText">
<pre><b>
RMenum rmPrimitiveSetText (RMprimitive *toModify,
int nStrings,
char *strings[])
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
int nStrings - an integer value specifying the number of text strings
in the strings[] array (input).
char *strings[] - an array of character strings (input).
</pre>
<menu><P>
Use this routine to assign some number of text strings to an
RMprimitive of type RM_TEXT or RM_INDEXED_TEXT. The input text
strings are duplicated in the RMprimitive; there is no shared data
management. Returns RM_CHILL upon success, or RM_WHACKED upon
failure.
</P>
<P>
Text rendering in RM is achieved by creating an RMprimitive of type
RM_TEXT or RM_INDEXED_TEXT, supplying text strings and vertex
locations to the RMprimitive (colors are optional, but indices are
required for the RM_INDEXED_TEXT primitive). This RMprimitive data
specifies the location of the text string, along with the text to be
rendered.
</P>
<P>
The appearance of the text string, such as typeface, size,
italicization and so forth are manipulated through the RMnode scene
parameter RMtextProps (see rmTextPropsSetAttribs).
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmPrimitiveSetDisplayListEnable">
<pre><b>
RMenum rmPrimitiveSetDisplayListEnable (RMprimitive *toModify,
RMenum newMode)
</b></pre>
<pre>
RMprimitive *toModify - a handle to an RMprimitive (modified).
RMenum newMode - an RMenum value, may be either RM_TRUE or RM_FALSE
(input).
</pre>
<menu><P>
In RM, OpenGL display lists are automatically built and cached on a
per-primitive basis. In some cases, the application may wish to
override this behavior, and inhibit the automatic construction of
display lists. Primitive which are dynamic, such as those that have
geometry, colors, etc. that change often (like every frame) should
not be display-listed. The cost of building and storing the display
list will not be recouped by the shortened rendering time unless the
display list is used in many frames.
</P>
<P>
Specify RM_TRUE for newMode to enable display lists for the
RMprimitive toModify, otherwise, specify RM_FALSE to disable display
list building for the RMprimitive.
</P>
<P>
Applications can control use of display lists in two ways: at the RMpipe
level, and at the RMprimitive level. At the RMpipe level, you can
enable or disable use of display lists for all RMprimitives drawn on RMpipe
using the routine rmPipeSetDisplayListEnable. At the RMprimitive level,
you can enable or disable the use of display lists for a single primitive
using rmPrimitiveSetDisplayListEnable().
</P>
<P>
The RMprimitive display list policy does not override the display list
policy set at the RMpipe level. In other words, if the policy at the RMpipe
level is set to RM_FALSE, then no display lists will be used, even if the
policy at the RMprimitive level is set to RM_TRUE. On the other hand, if
the policy at the RMpipe level is set to RM_TRUE, a policy at the RMprimitive
level of RM_FALSE will result on no display lists being used for the
one RMprimitive. In order for display lists to be used at any given
RMprimitive, the logical AND of RMpipe and RMprimitive display list
policies must be RM_TRUE.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
(Jan 2000) At this time, there is no corresponding "get display list
enable" routine.
</P>
<P>
See also rmPipeSetDisplayListEnable().
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmNodeAddPrimitive">
<pre><b>
RMenum rmNodeAddPrimitive (RMnode *addTo,
RMprimitive *src)
</b></pre>
<pre>
RMnode *addTo - a handle to an RMnode (modified).
RMprimitive *src - a handle to an RMprimitive (input).
</pre>
<menu><P>
This routine adds an RMprimitive to an RMnode. Returns RM_CHILL upon
success, or RM_WHACKED upon failure.
</P>
<P>
Each RMnode may contain an arbitrary number of RMprimitive objects.
Each of the RMprimitive objects is added to the RMnode using
rmNodeAddPrimitive. The list of RMprimitives in an RMnode is a flat
array, and this array grows to accomodate new RMprimitives as they
are added.
</P>
<P>
January 2000 - at this time, there is no corresponding "delete
primitive from an RMnode" operation. The closest equivalent is
rmNodeDelete(). Applications that anticipate the need to delete
RMprimitives should carefully consider the subject of scene graph
design, and use RMnodes that contain just a single primitive; the
delete operations should be performed at the RMnode level, not the
RMprimitive level.
</P>
<P>
February 2001 - this routine is thread safe: multiple application threads
may simultaneously call this routine to add primitives to the same node.
Thread safety is provided by mutex locks in the component manager.
</P>
<P>
NOTE: Applications SHOULD NOT use an RMprimitive in multiple RMnodes
in order to accomplish instancing. Instancing is properly achieved in
RM by instancing at the RMnode level, not the RMprimitive level.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmNodeGetPrimitive">
<pre><b>
RMprimitive * rmNodeGetPrimitive (const RMnode *toQuery,
int indx)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
int indx - an integer value interpreted as an index (input).
</pre>
<menu><P>
Returns to the caller the RMprimitive handle of the i'th primitive in
an RMnode.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmNodeSetClientData">
<pre><b>
RMenum rmNodeSetClientData (RMnode *toModify,
void *clientData,
void (*cdFreeFunc)(RMnode *,void *))
</b></pre>
<pre>
RMnode *toModify - a handle to an RMnode (modified).
void *clientData - a handle (input).
void (*cdFreeFunc)(RMnode *,void *) - a handle to an application
callback (input).
</pre>
<menu><P>
Applications may store a handle to arbitrary memory in RMnodes or
RMprimitives. This routine is used to place a handle to arbitrary
memory in an RMnode, and returns RM_CHILL upon success or RM_WHACKED
upon failure.
</P>
<P>
Client data may be stored in both RMprimitives and RMnodes
(rmNodeSetClientData).
</P>
<P>
The "client data" handle may be later accessed using
rmNodeGetClientData.
</P>
<P>
The callback function will be invoked when the RMnode is deleted.
The callback takes two parameters, a handle to the RMnode containing
the client data handle, and the client data handle itself. The
callback is provided so that applications may delete the data
referenced by the client data handle stored in the RMnode.
</P>
<P>
When the input client data handle is NULL, the old handle value is
effectively overwritten. Any memory pointed to by the old client data
handle will be lost (a potential memory leak).
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
<a name="rmNodeGetClientData">
<pre><b>
void * rmNodeGetClientData (const RMnode *toQuery)
</b></pre>
<pre>
const RMnode *toQuery - a handle to an RMnode (input).
</pre>
<menu><P>
Use this routine to obtain the client data handle stored in an
RMnode.
</P></menu>
<i>librm library source file: rmprim.c </i><hr width="75%">
</body></html>
distrib
>
Mandriva
>
2007.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
8079d983ecf371717db799dd75bd56c2
>
files
>
35
