Sophie: libopenrm1-1.5.2-2mdv2007.0 i586

libopenrm1-1.5.2-2mdv2007.0.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmscene.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="rmNodeSetSceneBackgroundColor"> 
<pre><b>
 RMenum rmNodeSetSceneBackgroundColor (RMnode *toModify,
			               const RMcolor4D *newColor)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (input).

 const RMcolor4D *newColor - a handle to the desired background color
   (input).
</pre>
<menu><P>
 Use this routine to set the background color scene parameter.
 Calling this routine with a color argument of NULL disables the
 background color scene parameter.  During rendering, the color planes
 of the framebuffer are cleared to this background color (with a depth
 value of 1.0, see NOTE below).  
</P>
<P>
 Upon success, RM_CHILL is returned and the specified background color
 scene parameter is set.  Otherwise, RM_WHACKED is returned, and the
 background color scene parameter remains unmodified.
</P>
<P>
 Passing in a value of NULL for the RMcolor4D object will effectively
 remove any existing background image color parameter from the RMnode toModify.
</P>
<P>
 NOTE: internal to this routine, a call to rmNodeSetSceneDepthValue is
 performed, effectively coupling framebuffer and depthbuffer clears.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMcolor4D object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P>
<P>
 Related routines: rmNodeSetSceneBackgroundImageTile, rnNodeSetSceneDepthValue.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneBackgroundColor"> 
<pre><b>
 RMenum rmNodeGetSceneBackgroundColor (const RMnode *toQuery,
			               RMcolor4D *returnColor)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMcolor4D *returnColor - a handle to a caller-supplied RMcolor4D
    object (return).
</pre>
<menu><P>
 Use this routine to obtain the background color scene parameter of an
 RMnode, if such a scene parameter exists.  
</P>
<P>
 Upon success, RM_CHILL is returned and the scene background color is
 copied into the caller-supplied RMcolor4D (effectively returning a copy
 of the background color scene parameter to the caller). If no such scene 
 parameter exists, or if there is some error condition detected, RM_WHACKED 
 is returned, and the caller-supplied colorReturn object remains unmodified.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneBackgroundImage"> 
<pre><b>
 RMenum rmNodeSetSceneBackgroundImage (RMnode *toModify,
			               const RMimage *newImageTile)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMimage *newImageTile - a handle to an RMimage (input).
</pre>
<menu><P>
 Sets the background image scene parameter for the RMnode.  When
 rendered, this image is tiled into the viewport at the scene depth
 value (or a default of 1.0) with an orthogonal projection, creating a
 background image. If the image does not fit the display, it will be
 tiled from top to bottom and left to right, so ragged edges fall on
 the bottom and right edges of the viewport.
</P>
<P>
 Passing in a value of NULL for the newImageTile parameter will 
 effectively remove the background image tile scene parameter, if it
 exists.
</P>
<P>
 Upon success, RM_CHILL is returned and the background image scene
 parameter has been modified.  Otherwise, RM_WHACKED is returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMimage object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P>
<P>
 NOTE: internal to this routine, a call to rmNodeSetSceneDepthValue() is
 performed, effectively coupling framebuffer clears (by image tiling) with
 depth buffer clears.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneBackgroundImage"> 
<pre><b>
 RMenum rmNodeGetSceneBackgroundImage (const RMnode *toQuery,
			               RMimage **returnImageTile)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMimage **returnImageTile - a handle to an RMimage handle (return).
</pre>
<menu><P>
 Use this routine to obtain the background image scene parameter of an
 RMnode.  Note that a handle to the RMimage is returned, not a
 copy of the actual pixel data.
</P>
<P>
 Upon success, RM_CHILL is returned and a handle to the scene
 background image is copied into the caller-supplied RMimage handle.
 Otherwise, RM_WHACKED is returned.
</P>
<P>
 Unlike most other rmNodeGetScene*() routines, this routine returns a
 handle to the actual object contained within the scene graph, rather
 than returning a copy. Applications should exercise appropriate
 discretion when using this object.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneCamera2D"> 
<pre><b>
 RMenum rmNodeSetSceneCamera2D (RMnode *toModify,
		                const RMcamera2D *newCamera)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMcamera2D *newCamera - a handle to an RMcamera2D object (input).
</pre>
<menu><P>
 Assign a 2D camera as a scene parameter to an RMnode. The 2D camera scene
 parameter defines a rectangular viewing region, and results in the
 render-time modification of the OpenGL view and projection matrices.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned and the RMnode's scene parameters remain unmodified.
</P>
<P>
 Passing in a value of NULL for the RMcamera2D object will effectively
 remove any existing 2D camera scene parameter from the RMnode toModify.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMcamera2D object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneCamera2D"> 
<pre><b>
 RMenum rmNodeGetSceneCamera2D (const RMnode *toQuery,
		                RMcamera2D **returnCamera)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMcamera2D **returnCamera - a handle to anRMcamera2D object (return). 
</pre>
<menu><P>
 If a 2D camera is defined for the RMnode, then a copy of the 2D
 camera is returned in the caller-supplied handle, and RM_CHILL is
 returned. Otherwise, RM_WHACKED is returned, and the caller supplied
 RMcamera2D object handle remains unmodified.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMcamera2D object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmCamera2DDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneCamera3D"> 
<pre><b>
 RMenum rmNodeSetSceneCamera3D (RMnode *toModify,
		                const RMcamera3D *newCamera)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMcamera3D *newCamera - a handle to an RMcamera3D (input).
</pre>
<menu><P>
 Assign a 3D camera as a scene parameter to an RMnode. The 3D camera
 defines a viewing volume in world coordinats. Objects that lie within
 this view volume will be visible when rendered. The 3D camera scene
 parameter will produce a render-time modification of the OpenGL
 modelview and projection matrices. The effect of these matrix stack
 modifications have scope only over the subtree rooted at the RMnode
 toModify.
</P>
<P>
 Passing in a value of NULL for the input RMcamera3D object will effectively
 remove any existing RMcamera3D scene parameter from the RMnode.
</P>
<P>
 Upon success, a copy of the input RMcamera3D object is made (if not NULL), 
 and assigned as a scene parameter to the input RMnode; Otherwise, RM_WHACKED 
 is returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMcamera3D object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneCamera3D"> 
<pre><b>
 RMenum rmNodeGetSceneCamera3D (const RMnode *toQuery,
		                RMcamera3D **returnCamera)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMcamera3D **returnCamera - a handle to a caller-supplied RMcamera3D object
    (modified).
</pre>
<menu><P>
 If a 3D camera is defined for the RMnode, then a copy of the 3D
 camera is created, then returned in the caller-supplied handle, and 
 RM_CHILL is returned. Otherwise, RM_WHACKED is returned and the 
 caller-supplied RMcamera3D handle remains unmodified.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMcamera3D object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmCamera3DDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneClipPlane"> 
<pre><b>
 RMenum rmNodeSetSceneClipPlane (RMnode *toModify,
			         RMenum clipPlaneEnum,
				 const RMclipPlane *newClipPlane)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (input).

 RMenum clipPlaneEnum - an RMenum specifying which clipping plane
    to modify.  Must be one of [RM_SCENE_CLIP_PLANE0..5] (input).

 const RMclipPlane *newClipPlane - a handle to an RMclipPlane handle (input).
</pre>
<menu><P>
 Assigns a clip plane as a scene parameter to an RMnode. This routine will
 make a copy of the input RMclipPlane object, and assign the copy as a
 scene parameter to the input RMnode. See rmClipPlaneNew() for more
 details about how clip planes are specified.
</P>
<P>
 Passing in a value of NULL for the newClipPlane parameter will 
 effectively remove the clip plane scene parameter specified by
 clipPlaneEnum, if it exists.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMclipPlane), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneClipPlane"> 
<pre><b>
 RMenum rmNodeGetSceneClipPlane (const RMnode *toQuery,
			         RMenum clipPlaneEnum,
				 RMclipPlane **returnClipPlane)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMenum clipPlaneEnum - an RMenum indicating which clip plane is
    being modified.  Must be one of RM_SCENE_CLIP_PLANE[0-5] (input).

 RMclipPlane **returnClipPlane - a caller-supplied handle to an RMclipPlane 
    handle (return).
</pre>
<menu><P>
 Use this routine to obtain one of six possible clip planes from an
 RMnode's scene parameters. 
</P>
<P>
 Upon success, a copy of the requested clip plane is created and returned to
 the caller via the returnClipPlane handle, and RM_CHILL is returned.
 Otherwise, RM_WHACKED is returned, and the caller supplied RMclipPlane
 handle remains unmodified.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMclipPlane object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmClipPlaneDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneDepthImage"> 
<pre><b>
 RMenum rmNodeSetSceneDepthImage (RMnode *toModify,
			          const RMimage *newDepthImage)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMimage *newDepthImage - a handle to a depth image (input)
</pre>
<menu><P>
 Assigns a depth image as a scene parameter for the RMnode. The 
 depth image is similar to the background image tile, but is applied to the
 depth buffer, rather than the color planes of the framebuffer. Like the 
 background image tile, the depth image scene parameter is tiled to fill
 the framebuffer, starting from the upper left-hand corner of the viewport. 
 If the size of the depth buffer image and viewport do not match exactly,
 the "ragged edges" or on the right and the bottom of the viewport.
</P>
<P>
 Passing in a value of NULL for the RMimage object will have the effect
 of removing the background depth image scene parameter, if one exists,
 from the RMnode.
</P>
<P>
 Upon success, a copy of the caller's RMimage object is made, and the
 copy is assigned as a scene parameter (or, if the input RMimage object is
 NULL, the NULL is assigned as a depth image scene parameter, effectively
 turning off that scene parameter), and RM_CHILL is returned; 
 otherwise, RM_WHACKED is returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMimage), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P>
<P>
 Note: as a practical matter, it is suggested that the pixel format
 of input RMimage objects should be of type RM_FLOAT, and in the
 range 0..1. By default, depth buffer Pixels in OpenGL range from
 0..1 (or perhaps 0..0.9999, depending upon your interpretation), but
 this range may be manipulated with glPixelTransferf(). As of the time
 of this writing (May 2000), we have tested background depth images
 only with RMimage's consisting of RM_FLOAT pixels in the range 0..1
 (and they work - refer to the demonstration program "pdb" included with
 the openrm-demo distribution).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneDepthImage"> 
<pre><b>
 RMenum rmNodeGetSceneDepthImage (const RMnode *toQuery,
			          RMimage **returnDepthImage)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMimage **returnDepthImage - a handle to a depth image handle
    (return). 
</pre>
<menu><P>
 Use this routine to obtain the RMnode's depth image scene parameter. If
 such a scene parameter exists, the handle of the RMimage (depth image)
 scene parameter is copied into caller-supplied memory, and RM_CHILL is
 returned. Otherwise, in the event of an error or the absence of the
 depth image scene parameter, RM_WHACKED is returned and caller supplied
 memory remains unmodified.
</P>
<P>
 Unlike most other rmNodeGetScene*() routines, this routine returns a
 handle to the actual RMimage object contained within the scene graph, rather
 than returning a copy. Applications should exercise appropriate
 discretion when using this object.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneDepthValue"> 
<pre><b>
 RMenum rmNodeSetSceneDepthValue (RMnode *toModify,
			          const float *newDepthValue)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const float *newDepthValue - a handle to the new depth value for the
    node (input).
</pre>
<menu><P>
 Use this routine to set the scene depth value parameter for an
 RMnode. The presence of the scene depth value has the effect of
 clearing the depth buffer to the value of newDepthValue.
</P>
<P>
 Passing in a value of NULL for newDepthValue has the effect of disabling
 depth buffer clears.
</P>
<P>
 The input newDepthValue should have the magnitude specified by
 glPixelTransferf(GL_DEPTH_SCALE,X) and range specified by
 glPixelTransferf(GL_DEPTH_BIAS,X). In OpenGL, the default depth
 bias is 0.0 and range/scale is 1.0.
</P>
<P>
 Upon success, RM_CHILL is returned and the node's depth value is set.
 Otherwise, RM_WHACKED is returned.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneDepthValue"> 
<pre><b>
 RMenum rmNodeGetSceneDepthValue (const RMnode *toQuery,
   			          float *returnDepthValue)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 float *returnDepthValue - a handle to a caller-supplied float for the 
    queried depth value (return). 
</pre>
<menu><P>
 Use this routine to query the scene depth value for a given RMnode.
</P>
<P>
 Upon success, RM_CHILL is returned and the node's depth value is
 copied into the caller-supplied float.  If the specified pointers are
 NULL, or no valid scene depth parameter exists, RM_WHACKED is
 returned.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneFog"> 
<pre><b>
 RMenum rmNodeSetSceneFog (RMnode *toModify,
		           const RMfog *newFog)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMfog *newFog - a handle to the new fog scene parameters
    (input).
</pre>
<menu><P>
 Use this routine to set the fog scene parameters for an RMnode.  If
 no scene parameters have been defined, then the RMfog object is
 duplicated into the RMnode.  Existing fog parameters are first deleted,
 thenn replaced with the new fog parameters.  Calling this routine with a
 an argument of NULL for the RMfog object disables the fog scene parameters.
</P>
<P>
 When a non-NULL RMfog object is added as a scene parameter to an
 RMnode, fogging will become enabled. The fogging will have scope only
 over the subtree rooted at the RMnode toModify. When the RMfog object
 is NULL, fogging is disabled (unless fogging is enabled at an
 anscestor node in the scene graph).
</P>
<P>
 Upon success, RM_CHILL is returned and the node's fog parameters are
 set.  Otherwise, RM_WHACKED is returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMfog object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneFog"> 
<pre><b>
 RMenum rmNodeGetSceneFog (const RMnode *toQuery,
	 	           RMfog **returnFog)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMfog **returnFog - a pointer to an RMfog handle (return).
</pre>
<menu><P>
 Use this routine to query the fog scene parameters for an RMnode.  If
 no fog scene parameters exists for the RMnode, then NULL is returned
 via the returnFog parameter, and RM_WHACKED is returned on the stack.
</P>
<P>
 Upon success, RM_CHILL is returned and a handle to the node's fog
 scene parameters are copied into the caller-supplied handle.
</P>
<P>
 Unlike most other rmNodeGetScene*() routines, this routine returns a
 handle to the actual RMfog object contained within the scene graph, rather
 than returning a copy. Applications should exercise appropriate
 discretion when using this object.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneLight"> 
<pre><b>
 RMenum rmNodeSetSceneLight (RMnode *toModify,
		             RMenum whichLightEnum,
			     const RMlight *newLight)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 RMenum whichLightEnum - an RMenum specifying which light tp modify.
    Must be one of [RM_LIGHT0..7] (input).

 const RMlight *newLight - a handle to an RMlight handle (input).
</pre>
<menu><P>
 Use this routine to assign a light source as a scene parameter to
 an RMnode. The light source is specified with an RMlight object
 (see rmLightNew for more information). Up to eight light sources
 may be simultaneously active, or specified at an RMnode by the
 RMenum values RM_LIGHT0, RM_LIGHT1, ... , RM_LIGHT7.
</P>
<P>
 When a non-NULL light source is assigned as a scene parameter, that
 light source becomes active, and has scope over the subtree rooted
 at the RMnode toModify within the scene graph. Assinging a NULL
 light source to one of the eight potential light source scene
 parameters will deactivate that particular light source.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMlight object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneLight"> 
<pre><b>
 RMenum rmNodeGetSceneLight (const RMnode *toQuery,
		             RMenum whichLightEnum,
			     RMlight **returnLightCopy)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMenum whichLightEnum - an RMenum indicating which RMlight to query.  
    Must be one of RM_LIGHT0, RM_LIGHT1, ... , RM_LIGHT7 (input).

 RMlight **returnLightCopy - a caller-supplied handle to an RMlight handle
    (return).
</pre>
<menu><P>
 Use this routine to obtain one of eight possible lights defined as
 scene parameters for an RMnode.  If no such scene parameter is
 defined, RM_WHACKED is returned, and the caller-supplied pointer to
 an RMlight pointer remains unmodified. 
</P>
<P>
 Upon success, RM_CHILL is returned, and a copy of the specified
 RMlight object is created, and the handle to the new copy is
 returned via the caller-supplied handle. Applications 
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMlight object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmLightDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneLightModel"> 
<pre><b>
 RMenum rmNodeSetSceneLightModel (RMnode *toModify,
			          const RMlightModel *newLightModel)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMlightModel *newLightModel - a handle to an RMlightModel (input).
</pre>
<menu><P>
 Set the light model used by an RMnode.  The RMlightmodel controls the
 ambient light color, whether two-sided lighting is enabled, and
 whether the local viewer is enabled for specular calculations.  If no
 light model has been defined, then the RMlightModel object is
 duplicated into the RMnode.  An existing light model is deleted and
 overwritten with the new light model.
</P>
<P>
 Calling this routine with an RMlightModel argument of NULL has the
 effect of removing any existing light model specification from the
 input RMnode. A light model that is specified at an ancestor
 node in the scene graph, if any, will be used to control light
 model parameters.
</P>
<P>
 See rmLightModelNew for details of the RMlightModel parameters.
</P>
<P>
 Upon success, RM_CHILL is returned and the RMnode contains the new
 light model.  Otherwise, RM_WHACKED is returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMlightModel object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneLightModel"> 
<pre><b>
 RMenum rmNodeGetSceneLightModel (const RMnode *toQuery,
			          RMlightModel **lightModelReturn)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMlightModel **returnLightModel - a caller-supplied handle to an RMlightModel
    handle (return).
</pre>
<menu><P>
 Obtains a copy of the light model scene parameter for an RMnode. If no
 such scene parameter exists, RM_WHACKED is returned, and the pointer to the
 caller-supplied RMlightModel pointer remains unmodified.
</P>
<P>
 Otherwise, a copy of the RMnode's RMlightModel parameter is created,
 the pointer to this new object is copied into caller-supplied memory,
 and RM_CHILL is returned.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMlightModel object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmLightModelDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmTextPropsNew"> 
<pre><b>
 RMtextProps * rmTextPropsNew (void)
</b></pre>
<pre>
 No arguments.
</pre>
<menu><P>
 Creates a new RMtextProps object and returns a handle to the caller.
</P>
<P>
 Upon success, the returned handle points to a new RMtextProps object.
 If resources cannot be allocated, then a NULL handle is returned.
</P>
<P>
 The RMtextProps object may be assigned as a scene parameter to RMnodes,
 where it will control text rendering properties, such as font family,
 size, italizication, etc. These text properties may be thought of in
 the same way as other drawing parameters, such as material properties,
 current color, and so forth.
</P>
<P>
 The defaults text rendering properties set by rmTextPropsNew() are
 controlled by definitions in rmglobals.c, and are:
</P>
<P>
 <pre>
RMenum RM_DEFAULT_HJUSTIFY    = RM_LEFT;
RMenum RM_DEFAULT_VJUSTIFY    = RM_BOTTOM;
RMenum RM_DEFAULT_FONT_FAMILY = RM_FONT_SANS;
RMenum RM_DEFAULT_FONT_SIZE   = RM_FONT_M;
RMenum RM_DEFAULT_FONT_BOLD   = RM_FALSE;
RMenum RM_DEFAULT_FONT_ITALIC = RM_FALSE;
</pre>
</P>
<P>
 Use rmTextPropsSetAttribs() to set the attributes of an RMtextProps
 object, or rmTextPropsGetAttribs() to query attributes.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmTextPropsDelete"> 
<pre><b>
 RMenum rmTextPropsDelete (RMtextProps *toDelet)
</b></pre>
<pre>
 RMtextProps *toDelete - a handle to an RMtextProps object (deleted).
</pre>
<menu><P>
 Deletes the resources associated with an RMtextProps object.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneTextProps"> 
<pre><b>
 RMenum rmNodeSetSceneTextProps (RMnode *toModify,
			         const RMtextProps *newTextProps)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const RMtextProps *newTextProps - a handle to an RMtextProps object (input).
</pre>
<menu><P>
 Assigns an RMtextProps object as a scene parameter for an RMnode. These
 text properties will control how strings are rendered within the
 subtree rooted at the RMnode toModify, unless subsequently overridden
 at a descendent RMnode. The text properties specify a font family,
 point size, horizontal and vertical justification control,  and
 emboldening and italicization parameters.
</P>
<P>
 If the input RMtextProps object is NULL, any existing RMtextProps
 scene parameter is deleted.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 RMtextProps object), callers do not need to manage the input object after a
 successful return from this routine. This has important ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneTextProps"> 
<pre><b>
 RMenum rmNodeGetSceneTextProps (const RMnode *toQuery,
                                 RMtextProps **returnTextProps)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMtextProps **returnTextProps - a caller-supplied handle to an
   RMtextProps handle (return).
</pre>
<menu><P>
 Obtains a copy of the RMtextProps object scene parameter for the
 RMnode, and returns a handle to the copy in the parameter returnTextProps,
 and RM_CHILL is returned on the stack.
</P>
<P>
 If no such scene parameter exists, or if there is some other error
 condition encountered, RM_WHACKED is returned on the stack, and
 the caller-supplied parameter returnTextProps remains unmodified.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 RMtextProps object), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmTextProps the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneTexture"> 
<pre><b>
 RMenum rmNodeSetSceneTexture (RMnode *toModify,
		               const RMtexture *newTexture)
</b></pre>
<pre>
 RMnode *n - a handle to an RMnode (modified).

 RMtexture *t - a handle to an RMtexture (input).
</pre>
<menu><P>
 Assigns an RMtexture object as a scene parameter to the RMnode.
 The presence of a texture scene parameter will cause texture mapping
 to become active at the RMnode toModify, and will remain active
 using the supplied texture newTexture over the entire subtree
 rooted at the RMnode toModify, unless overridden by a different
 texture at a descendent node within the scene graph.
</P>
<P>
 In order for texture mapping to occur at the pixel fragment level,
 primitives need to have texture coordinates (as well as vertex data).
</P>
<P>
 Specifying a value of NULL for the input texture will remove
 any existing texture scene parameter from the RMnode, effectively
 disabling texture mapping within the scene graph subtree rooted
 at toModify.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P>
<P>
 Starting with OpenRM version 1.5.1 and later, when you assign an
 RMtexture as a scene parameter to an RMnode, only a reference to the
 source RMtexture is copied. In this way, you can use a single RMtexture
 object as a source texture for an arbitrary number of scene graph nodes
 without incurring additional memory storage overhead for each instance
 of the texture. The caveat from an application developer's perspective
 is that you must treat RMtextures like RMnodes - don't delete them
 until they are really no longer needed.
</P>
<P>
 If you try to rmTextureDelete a texture that has been assigned as a
 scene parameter, rmTextureDelete will fail - the RMtexture has a
 reference counter that is incremented or decremented when it is assigned
 or removed as a scene parameter at the scene graph node level. The
 simplest way to delete the RMtexture assigned to one or more nodes
 as a scene parameter is to simply delete the node or tree of nodes.
 All associated scene parameters will be deleted when their reference
 counters reach a value of zero.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneTexture"> 
<pre><b>
 RMenum rmNodeGetSceneTexture (const RMnode *toQuery,
		               RMtexture **returnTexture)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 RMtexture **returnTexture - a handle to an RMtexture handle (return).
</pre>
<menu><P>
 Use this routine to obtain the handle of the RMtexture scene parameter
 at an RMnode. If such a scene parameter is present, a handle to the
 internal RMtexture object is copied into caller-supplied memory
 (returnTexture), and RM_CHILL is returned on the stack. Otherwise,
 RM_WHACKED is returned, and caller-supplied memory remains unmodified.
</P>
<P>
 This routine will be useful for applications that will use the
 routine rmNodeUpdateSceneTexture to replace the contents of a
 particular texture, perhaps on a time-varying basis.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeUpdateSceneTexture"> 
<pre><b>
 RMenum rmNodeUpdateSceneTexture (const RMnode *toUpdate)
</b></pre>
<pre>
 const RMnode *toUpdate - a handle to an RMnode (input).
</pre>
<menu><P>
 This routine will cause texture data contained within an RMtexture
 scene parameter to be downloaded to OpenGL texture memory.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeSetSceneViewport"> 
<pre><b>
 RMenum rmNodeSetSceneViewport (RMnode *toModify,
			        const float *newViewport)
</b></pre>
<pre>
 RMnode *toModify - a handle to an RMnode (modified).

 const float *newViewport - a handle to an array of four floats, defining a
    viewport (input) [x, y, w, h].
</pre>
<menu><P>
 The viewport scene parameter defines a pixel rectangle in the window
 into which the final image is mapped. The four viewport parameters,
 (x, y, width, height), are passed in as a single array of floats.
 The (x,y) coordinate specifies the lower left corner of the viewport
 rectangle.  Width and height are the size of the viewport.
</P>
<P>
 Use this routine to specify a viewport as a scene parameter at an
 RMnode. Upon success, any existing viewport at the RMnode is removed,
 then a copy of the input viewport parameters are made, then assigned
 to the RMnode toModify. Passing in a value of NULL for the viewport
 parameter will result in the removal of any existing viewport
 scene parameter from the RMnode.
</P>
<P>
 Use input values of {0.0, 0.0, 1.0, 1.0} to consume the entire window.
</P>
<P>
 Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is
 returned.
</P>
<P>
 Because this routine makes a copy of the input scene parameter (an
 viewport specification), callers do not need to manage the input object
 after a successful return from this routine. This has important
 ramificiations:
</P>
<P>
 1. Since a copy is made, any changes made to the caller's object will have
 no effect upon the scene graph, unless this routine is called again to
 update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers may safely delete their copy of the input object after a 
 successful return from this routine.
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
<a name="rmNodeGetSceneViewport"> 
<pre><b>
 RMenum rmNodeGetSceneViewport (const RMnode *toQuery,
			        float **returnViewport)
</b></pre>
<pre>
 const RMnode *toQuery - a handle to an RMnode (input).

 float **returnViewport - a handle to an array of float (returned).
</pre>
<menu><P>
 This routine is used to query the viewport scene parameters at an
 RMnode. If the input RMnode toQuery has a viewport scene parameter,
 a copy of the viewport is created, then the handle to the copy returned
 to the caller through the parameter returnViewport, and RM_CHILL is
 returned on the stack.
</P>
<P>
 Otherwise, RM_WHACKED is returned and the caller supplied return
 parameter returnViewport remains unmodified.
</P>
<P>
 Because this routine returns a COPY of the RMnode's scene parameter (an
 array of floats), two important ramifications should be noted:
</P>
<P>
 1. Since a copy is returned, any changes made to the caller's object will have
 no effect upon the scene graph, unless the appropriate routine is called 
 again to update the scene parameter inside the scene graph;
</P>
<P>
 2. Callers are responsible for managing the returned object 
 (rmFloatDelete the object when it is no longer needed).
</P></menu>
<i>librm library source file: rmscene.c </i><hr width="75%">
</body></html>