Index of OpenRM - RM Library


 RMprimitive * rmPrimitiveNew (RMenum primType)

 RMenum primType - an RMenum value specifying the RM primitive type.    See below for more information  (input).

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. at jogoscasinoonline.eu.

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, RM_USERDEFINED_PRIM, RM_APP_DISPLAYLIST. Bonus Fara Depunere

Some of the procedural primitives are assigned default "model flag" attributes (see rmPrimitiveSetModelFlag). These are:

RM_SPHERES: RM_SPHERES_32 produces a 32-faced sphere tesselation.

RM_OCTMESH: RM_OCTMESH_1 produces a "full resolution" octmesh primitive.

RM_CONES: RM_CONES_16 produces a cone consisting of 16 radial subdivisions.

RM_CYLINDERS: RM_CYLINDERS_16 produces a cylinder consisting of 16 radial subdivisions.

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.

 librm library source file: rmprim.c 

 void rmPrimitiveDelete (RMprimitive *toDelete)

 RMprimitive *toDelete - a handle to an RMprimitive to delete
    (modified).

Use this routine to release resources associated with an RMprimitive.

If shared data management was specified (when rmPrimitiveSetVertex3D was called, for example), those application callback functions will be invoked to free large-payload memory.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetRenderFunc (RMprimitive *toModify,
			          void (*drawFunc) OGLPRIMPARMLIST() )

 RMprimitive *toModify - a handle to an RMprimitive (modified). void (*drawFunc) OGLPRIMPARMLIST() - a callback invoked to draw the
    primitive (input).

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.

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:

(RMprimitive *primToDraw, RMnode *owningNode, RMstate *currentRenderState, RMpipe *renderPipe, RMstateCache *internalStateCache)

librm library source file: rmprim.c 

 void * rmPrimitiveGetRenderFunc (const RMprimitive *toQuery)

 const RMprimitive *toQuery - a handle to the RMprimitive object to
    query (input).

Returns to the caller the handle to the draw callback associated with the input RMprimitive.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetModelFlag (RMprimitive *toModify,
			         int newVal)

 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).

Use this routine to modify the "primitive model flag" for an RMprimitive. Returns RM_CHILL upon success or RM_WHACKED upon failure.

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.

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.

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).

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.

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.

 librm library source file: rmprim.c 

 int rmPrimitiveGetModelFlag (const RMprimitive *toQuery)

 const RMprimitive *toQuery - a handle to an RMprimitive to query
    (input).

Returns to the caller the current primitive model flag associated with the RMprimitive object.

RM_WHACKED is returned for RMprimitives that don't know about model flags.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveComputeBoundingBox (RMprimitive *toModify)

 RMprimitive *toModify - a handle to an RMprimitive (modified).

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.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetBoundingBox (RMprimitive *toModify, const RMvertex3D *bmin, const RMvertex3D *bmax)

 RMprimitive *toModify - a handle to an RMprimitive (modified). const RMvertex3D *bmin, *bmax - handles to RMvertex3D's.

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.

The RMprimitive's bounding box is automatically computed by RM in the following circumstances: 1. list them

The relationship between the RMprimitive and RMnode bounding box is ...

 librm library source file: rmprim.c 

 RMenum rmPrimitiveGetBoundingBox (const RMprimitive *toQuery, RMvertex3D *bminReturn, RMvertex3D *bmaxReturn)

 const RMprimitive *toQuery - a handle to an RMprimitive (input). RMvertex3D *bminReturn, *bmaxReturn;

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.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveGetType (const RMprimitive *toQuery)

    (input).

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().

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetClientData (RMprimitive *toModify,
			          void *clientData,
				  void (*cdFreeFunc)(RMprimitive *,void *))

 RMprimitive *toModify - a handle to an RMprimitive (modified). void *clientData - a handle (input). void (*cdFreeFunc)(RMprimitive *, void *) - a handle to an application
    callback (input).

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.

Client data may be stored in both RMprimitives and RMnodes (rmNodeSetClientData).

The "client data" handle may be later accessed using rmPrimitiveGetClientData.

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.

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).

 librm library source file: rmprim.c 

 void * rmPrimitiveGetClientData (const RMprimitive *toQuery)

 const RMprimitive *toQuery - a handle to an RMprimitive (input).

Use this routine to obtain the client data handle stored in an RMprimitive.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetVertex2D (RMprimitive *toModify,
		                int nVertices,
			        RMvertex2D *vertexData,
			        RMenum copyEnum,
			        void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get vertex" routine. Primitive vertex data should be considered write-only by the application.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetVertex3D (RMprimitive *toModify,
		                int nVertices,
			        RMvertex3D *vertexData,
			        RMenum copyEnum,
			        void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get vertex" routine. Primitive vertex data should be considered write-only by the application.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetColor3D (RMprimitive *toModify,
		               int nColors,
			       RMcolor3D *colorData,
			       RMenum copyEnum,
			       void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get colors" routine. Primitive color data should be considered write-only by the application.

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.

In RM, 3-component color data is RGB. 4-component colors are RGBA.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetColor4D (RMprimitive *toModify,
		               int nColors,
			       RMcolor4D *colorData,
			       RMenum copyEnum,
			       void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get colors" routine. Primitive color data should be considered write-only by the application.

In RM, 3-component color data is RGB. 4-component colors are RGBA.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetRadii (RMprimitive *toModify,
		             int nRadii,
			     float *radii,
			     RMenum copyEnum,
			     void (*freeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get radii" routine. Primitive radius data should be considered write-only by the application.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetNormal3D (RMprimitive *toModify,
		                int nNormals,
			        RMvertex3D *normalsData,
			        RMenum copyEnum,
			        void (*freeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get normals" routine. Primitive normal data should be considered write-only by the application.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetTexcoord1D (RMprimitive *toModify,
		                  int nTexCoords,
				  float *texCoordData,
				  RMenum copyEnum,
				  void (*appFreeFunc)(void *))

 RMprimitive *toModify - a handle to an RMprimitive (modified). int nTexCoords - an integer value, specifies the number of 1D texture
    coordinates that will be assigned to the RMprimitive (input). float *texCoordData - a handle to a flat array of float (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).

rmPrimitiveSetTexcoord1D is one of a family of routines used to assign data to RMprimitives. This routine assigns 1D texture coordinates to an RMprimitive, returning RM_CHILL upon success or RM_WHACKED upon failure.

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 float data, but instead will simply copy the handle "texCoordData" into the RMprimitive, and refer to the caller-supplied memory directly in later operations.

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.

There is no corresponding "get texture coordinate" routine. Primitive vertex data should be considered write-only by the application.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetTexcoord2D (RMprimitive *toModify,
		                  int nTexCoords,
				  RMvertex2D *texCoordData,
				  RMenum copyEnum,
				  void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get texture coordinate" routine. Primitive vertex data should be considered write-only by the application.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetTexcoord3D (RMprimitive *toModify,
		                  int nTexcoords,
				  RMvertex3D *texCoordData,
				  RMenum copyEnum,
				  void (*appFreeFunc)(void *))

 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).

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.

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.

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.

There is no corresponding "get texture coordinate" routine. Primitive vertex data should be considered write-only by the application.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetMultiTexcoord1D (RMprimitive *toModify,
		                       int nTexCoords,
				       float *texCoordData,
				       RMenum copyEnum,
				       void (*appFreeFunc)(void *),
				       int textureUnit)

 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). float *texCoordData - a handle to a flat array of floats (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). int textureUnit - an integer value specifying with which multitexturing
    unit the texture coordinates will be used. Valid values are in the
    range zero through RM_MAX_MULTITEXTURES-1.

rmPrimitiveSetMultiTexcoord1D is nearly identical in function and return values to rmPrimitiveSetTexcoord1D. The difference is the ability to assign texture coordinates to a specific texturing unit in a multitexturing environment.

Note that while valid values for the input textureUnit parameter are in the range zero through RM_MAX_MULTITEXTURES-1, this routine performs no error checking to verify that the textureUnit input value is valid for a particular OpenGL implementation. The constant RM_MAX_MULTITEXTURES is independent of the actual number of texture units supported by an OpenGL implementation. When multitexturing is supported (use the routine rmPipeGetNumMultitextureUnits to check for the availability on a given OpenGL implementation), the minimum number of texture units to be supported is two; our Quadro4 cards have four texture units; Mesa provides eight texture units.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetMultiTexcoord2D (RMprimitive *toModify,
		                       int nTexCoords,
				       RMvertex2D *texCoordData,
				       RMenum copyEnum,
				       void (*appFreeFunc)(void *),
				       int textureUnit)

 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). int textureUnit - an integer value specifying with which multitexturing
    unit the texture coordinates will be used. Valid values are in the
    range zero through RM_MAX_MULTITEXTURES-1.

rmPrimitiveSetMultiTexcoord2D is nearly identical in function and return values to rmPrimitiveSetTexcoord2D. The difference is the ability to assign texture coordinates to a specific texturing unit in a multitexturing environment.

Note that while valid values for the input textureUnit parameter are in the range zero through RM_MAX_MULTITEXTURES-1, this routine performs no error checking to verify that the textureUnit input value is valid for a particular OpenGL implementation. The constant RM_MAX_MULTITEXTURES is independent of the actual number of texture units supported by an OpenGL implementation. When multitexturing is supported (use the routine rmPipeGetNumMultitextureUnits to check for the availability on a given OpenGL implementation), the minimum number of texture units to be supported is two; our Quadro4 cards have four texture units; Mesa provides eight texture units.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetMultiTexcoord3D (RMprimitive *toModify,
		                       int nTexCoords,
				       RMvertex3D *texCoordData,
				       RMenum copyEnum,
				       void (*appFreeFunc)(void *),
				       int textureUnit)

 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). RMvertex3D *texCoordData - a handle to a flat array of RMvertex3D's. (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). int textureUnit - an integer value specifying with which multitexturing
    unit the texture coordinates will be used. Valid values are in the
    range zero through RM_MAX_MULTITEXTURES-1.

rmPrimitiveSetMultiTexcoord3D is nearly identical in function and return values to rmPrimitiveSetTexcoord3D. The difference is the ability to assign texture coordinates to a specific texturing unit in a multitexturing environment.

Note that while valid values for the input textureUnit parameter are in the range zero through RM_MAX_MULTITEXTURES-1, this routine performs no error checking to verify that the textureUnit input value is valid for a particular OpenGL implementation. The constant RM_MAX_MULTITEXTURES is independent of the actual number of texture units supported by an OpenGL implementation. When multitexturing is supported (use the routine rmPipeGetNumMultitextureUnits to check for the availability on a given OpenGL implementation), the minimum number of texture units to be supported is two; our Quadro4 cards have four texture units; Mesa provides eight texture units.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetIndices (RMprimitive *toModify,
		               int numIndices,
			       int *indicesArray,
			       RMenum copyEnum,
			       void (*appFreeFunc)(void *))

 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).

Use this routine to set "index values" in an RMprimitive. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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).

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).

Each entry in the index array is an index into another array.

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.

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.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetSprites (RMprimitive *toModify,
		               int nSprites,
			       RMimage **spriteArray)

 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).

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.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetBitmaps (RMprimitive *toModify,
		               int nBitmaps,
			       RMbitmap **bmapArray)

 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).

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.

There is no shared data management of RMbitmap data since these objects are small.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetQmeshDims (RMprimitive *toModify,
			         int uSize,
				 int vSize)

 RMprimitive *toModify - a handle to an RMprimitive (modified). int uSize, vSize - integer values specifying the dimensions of a
    lattice defining a quadmesh (input).

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.

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.

The routines rmPrimitiveSetQmeshDims and rmPrimitiveSetVertex3D/2D may be called in any order, but both must be called before a quadmesh primitive is rendered.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetOmeshDims (RMprimitive *toModify,
			         int isize,
				 int jsize,
				 int ksize)

 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).

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.

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.

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.

(Jan 2000) - use rmPrimitiveSetOmeshMinMaxGrid() to specify the corners of the 3D lattice. Use of rmPrimitiveSetVertex3D on octmesh primitives is not yet implemented.

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).

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetOmeshMinMaxGrid (RMprimitive *toModify,
			               const RMvertex3D *gridMin,
				       const RMvertex3D *gridMax)

 RMprimitive *p - a handle to an RMprimitive (modified). const RMvertex3D *gridMin, *gridMax - handles to RMvertex3D objects
    (input).

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().

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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).

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetMarkerScale (RMprimitive *toModify,
			           int npts,
				   float *scales,
				   RMenum copyEnum,
				   void (*appFreeFunc)(void *))

 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).

Use this routine to set the scale values applied to RM "marker primitives." Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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.

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().

The number of scale values may be either 1, or the same as the number of vertices specified with rmPrimitiveSetVertex2D/3D.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetMarkerPrims (RMprimitive *toModify,
			           int nMarkerPrims,
				   RMinternalMarker2D **mArray)

 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).

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.

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.

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().

The number of scale values may be either 1, or the same as the number of vertices specified with rmPrimitiveSetVertex2D/3D.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetEllipse2DRotate (RMprimitive *toModify,
			               int nVals,
				       float *rotationValues,
				       RMenum copyEnum,
				       void (*appFreeFunc)(void *))

 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).

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.

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.

At render time, for each input vertex, or ellipse center, an idealized ellipse is first scaled, rotated, then translated to the desired location.

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.

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.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetText (RMprimitive *toModify,
		            int nStrings,
			    char *strings[])

 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).

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.

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.

The appearance of the text string, such as typeface, size, italicization and so forth are manipulated through the RMnode scene parameter RMtextProps (see rmTextPropsSetAttribs).

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetDisplayListEnable (RMprimitive *toModify,
				         RMenum newMode)

 RMprimitive *toModify - a handle to an RMprimitive (modified). RMenum newMode - an RMenum value, may be either RM_TRUE or RM_FALSE
    (input).

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.

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.

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().

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.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

(Jan 2000) At this time, there is no corresponding "get display list enable" routine.

See also rmPipeSetDisplayListEnable().

 librm library source file: rmprim.c 

 RMenum rmNodeAddPrimitive (RMnode *addTo,
		            RMprimitive *src)

 RMnode *addTo - a handle to an RMnode (modified). RMprimitive *src - a handle to an RMprimitive (input).

This routine adds an RMprimitive to an RMnode. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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.

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.

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.

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.

 librm library source file: rmprim.c 

 RMprimitive * rmNodeGetPrimitive (const RMnode *toQuery,
		                   int indx)

 const RMnode *toQuery - a handle to an RMnode (input). int indx - an integer value interpreted as an index (input).

Returns to the caller the RMprimitive handle of the i'th primitive in an RMnode.

 librm library source file: rmprim.c 

 RMenum rmNodeSetClientData (RMnode *toModify,
		             void *clientData,
			     void (*cdFreeFunc)(RMnode *,void *))

 RMnode *toModify - a handle to an RMnode (modified). void *clientData - a handle (input). void (*cdFreeFunc)(RMnode *,void *) - a handle to an application
   callback (input).

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.

Client data may be stored in both RMprimitives and RMnodes (rmNodeSetClientData).

The "client data" handle may be later accessed using rmNodeGetClientData.

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.

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).

 librm library source file: rmprim.c 

 void * rmNodeGetClientData (const RMnode *toQuery)

 const RMnode *toQuery - a handle to an RMnode (input).

Use this routine to obtain the client data handle stored in an RMnode.

 librm library source file: rmprim.c 

 RMenum rmPrimitiveSetAppDisplayList (RMprimitive *toModify, GLuint appDisplayList)

 RMprimitive *toModify - a handle to an RMprimitive object (input). GLuint appDisplayList - a GLuint value (input).

Use this routine to assign a GL display list ID to an RMprimitive of type RM_APP_DISPLAYLIST. This type of RMprimitive is intended to be used by applications that need to create an OpenGL display list, perhaps using third-party modeling tools, and then have the display list contents rendered within an RM Scene Graph. Upon success, RM_CHILL is returned, while RM_WHACKED is returned upon failure.

Restrictions apply when using application-defined display lists: (1) Applications are completely responsible for ensuring that the GLuint assigned as a display list ID is indeed valid. (2) After invoking the application-supplied display list, the the OpenGL state must be in exactly the same condition as it was before the display list was invoked. Failure to adhere to this rule will likely cause rendering errors that result from RM's inability to know about state changes made by the application display list.

 librm library source file: rmprim.c