OpenRM - RM Library (rmscene.c)

## Index of OpenRM - RM Library

     RMenum rmNodeSetSceneBackgroundColor (RMnode *toModify,
    			               const RMcolor4D *newColor)

     RMnode *toModify - a handle to an RMnode (input).

     const RMcolor4D *newColor - a handle to the desired background color
       (input).

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

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.

Passing in a value of NULL for the RMcolor4D object will effectively remove any existing background image color parameter from the RMnode toModify.

NOTE: internal to this routine, a call to rmNodeSetSceneDepthValue is performed, effectively coupling framebuffer and depthbuffer clears.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

Related routines: rmNodeSetSceneBackgroundImageTile, rnNodeSetSceneDepthValue.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneBackgroundColor (const RMnode *toQuery,
    			               RMcolor4D *returnColor)

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

     RMcolor4D *returnColor - a handle to a caller-supplied RMcolor4D
        object (return).

Use this routine to obtain the background color scene parameter of an RMnode, if such a scene parameter exists.

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.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneBackgroundImage (RMnode *toModify,
    			               const RMimage *newImageTile)

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

     const RMimage *newImageTile - a handle to an RMimage (input).

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.

Passing in a value of NULL for the newImageTile parameter will effectively remove the background image tile scene parameter, if it exists.

Upon success, RM_CHILL is returned and the background image scene parameter has been modified. Otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

NOTE: internal to this routine, a call to rmNodeSetSceneDepthValue() is performed, effectively coupling framebuffer clears (by image tiling) with depth buffer clears.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneBackgroundImage (const RMnode *toQuery,
    			               RMimage **returnImageTile)

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

     RMimage **returnImageTile - a handle to an RMimage handle (return).

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.

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.

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.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneCamera2D (RMnode *toModify,
    		                const RMcamera2D *newCamera)

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

     const RMcamera2D *newCamera - a handle to an RMcamera2D object (input).

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.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned and the RMnode's scene parameters remain unmodified.

Passing in a value of NULL for the RMcamera2D object will effectively remove any existing 2D camera scene parameter from the RMnode toModify.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneCamera2D (const RMnode *toQuery,
    		                RMcamera2D **returnCamera)

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

     RMcamera2D **returnCamera - a handle to anRMcamera2D object (return).

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.

Because this routine returns a COPY of the RMnode's scene parameter (an RMcamera2D object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmCamera2DDelete the object when it is no longer needed).

librm library source file: rmscene.c

     RMenum rmNodeSetSceneCamera3D (RMnode *toModify,
    		                const RMcamera3D *newCamera)

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

     const RMcamera3D *newCamera - a handle to an RMcamera3D (input).

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.

Passing in a value of NULL for the input RMcamera3D object will effectively remove any existing RMcamera3D scene parameter from the RMnode.

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.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneCamera3D (const RMnode *toQuery,
    		                RMcamera3D **returnCamera)

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

     RMcamera3D **returnCamera - a handle to a caller-supplied RMcamera3D object
        (modified).

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.

Because this routine returns a COPY of the RMnode's scene parameter (an RMcamera3D object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmCamera3DDelete the object when it is no longer needed).

librm library source file: rmscene.c

     RMenum rmNodeSetSceneClipPlane (RMnode *toModify,
    			         RMenum clipPlaneEnum,
    				 const RMclipPlane *newClipPlane)

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

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.

Passing in a value of NULL for the newClipPlane parameter will effectively remove the clip plane scene parameter specified by clipPlaneEnum, if it exists.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneClipPlane (const RMnode *toQuery,
    			         RMenum clipPlaneEnum,
    				 RMclipPlane **returnClipPlane)

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

Use this routine to obtain one of six possible clip planes from an RMnode's scene parameters.

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.

Because this routine returns a COPY of the RMnode's scene parameter (an RMclipPlane object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmClipPlaneDelete the object when it is no longer needed).

librm library source file: rmscene.c

     RMenum rmNodeSetSceneDepthImage (RMnode *toModify,
    			          const RMimage *newDepthImage)

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

     const RMimage *newDepthImage - a handle to a depth image (input)

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.

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.

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.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

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

librm library source file: rmscene.c

     RMenum rmNodeGetSceneDepthImage (const RMnode *toQuery,
    			          RMimage **returnDepthImage)

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

     RMimage **returnDepthImage - a handle to a depth image handle
        (return).

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.

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.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneDepthValue (RMnode *toModify,
    			          const float *newDepthValue)

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

     const float *newDepthValue - a handle to the new depth value for the
        node (input).

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.

Passing in a value of NULL for newDepthValue has the effect of disabling depth buffer clears.

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.

Upon success, RM_CHILL is returned and the node's depth value is set. Otherwise, RM_WHACKED is returned.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneDepthValue (const RMnode *toQuery,
       			          float *returnDepthValue)

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

     float *returnDepthValue - a handle to a caller-supplied float for the
        queried depth value (return).

Use this routine to query the scene depth value for a given RMnode.

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.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneFog (RMnode *toModify,
    		           const RMfog *newFog)

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

     const RMfog *newFog - a handle to the new fog scene parameters
        (input).

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.

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

Upon success, RM_CHILL is returned and the node's fog parameters are set. Otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneFog (const RMnode *toQuery,
    	 	           RMfog **returnFog)

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

     RMfog **returnFog - a pointer to an RMfog handle (return).

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.

Upon success, RM_CHILL is returned and a handle to the node's fog scene parameters are copied into the caller-supplied handle.

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.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneLight (RMnode *toModify,
    		             RMenum whichLightEnum,
    			     const RMlight *newLight)

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

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.

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.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneLight (const RMnode *toQuery,
    		             RMenum whichLightEnum,
    			     RMlight **returnLightCopy)

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

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.

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

Because this routine returns a COPY of the RMnode's scene parameter (an RMlight object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmLightDelete the object when it is no longer needed).

librm library source file: rmscene.c

     RMenum rmNodeSetSceneLightModel (RMnode *toModify,
    			          const RMlightModel *newLightModel)

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

     const RMlightModel *newLightModel - a handle to an RMlightModel (input).

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.

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.

See rmLightModelNew for details of the RMlightModel parameters.

Upon success, RM_CHILL is returned and the RMnode contains the new light model. Otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneLightModel (const RMnode *toQuery,
    			          RMlightModel **lightModelReturn)

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

     RMlightModel **returnLightModel - a caller-supplied handle to an RMlightModel
        handle (return).

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.

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.

Because this routine returns a COPY of the RMnode's scene parameter (an RMlightModel object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmLightModelDelete the object when it is no longer needed).

librm library source file: rmscene.c

     RMtextProps * rmTextPropsNew (void)

     No arguments.

Creates a new RMtextProps object and returns a handle to the caller.

Upon success, the returned handle points to a new RMtextProps object. If resources cannot be allocated, then a NULL handle is returned.

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.

The defaults text rendering properties set by rmTextPropsNew() are controlled by definitions in rmglobals.c, and are:

    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;

Use rmTextPropsSetAttribs() to set the attributes of an RMtextProps object, or rmTextPropsGetAttribs() to query attributes.

librm library source file: rmscene.c

     RMenum rmTextPropsDelete (RMtextProps *toDelet)

     RMtextProps *toDelete - a handle to an RMtextProps object (deleted).

Deletes the resources associated with an RMtextProps object.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneTextProps (RMnode *toModify,
    			         const RMtextProps *newTextProps)

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

     const RMtextProps *newTextProps - a handle to an RMtextProps object (input).

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.

If the input RMtextProps object is NULL, any existing RMtextProps scene parameter is deleted.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneTextProps (const RMnode *toQuery,
                                     RMtextProps **returnTextProps)

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

     RMtextProps **returnTextProps - a caller-supplied handle to an
       RMtextProps handle (return).

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.

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.

Because this routine returns a COPY of the RMnode's scene parameter (an RMtextProps object), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmTextProps the object when it is no longer needed).

librm library source file: rmscene.c

     RMenum rmNodeSetSceneTexture (RMnode *toModify,
    		               const RMtexture *newTexture)

     RMnode *n - a handle to an RMnode (modified).

     RMtexture *t - a handle to an RMtexture (input).

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.

In order for texture mapping to occur at the pixel fragment level, primitives need to have texture coordinates (as well as vertex data).

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.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

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.

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.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneTexture (const RMnode *toQuery,
    		               RMtexture **returnTexture)

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

     RMtexture **returnTexture - a handle to an RMtexture handle (return).

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.

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.

librm library source file: rmscene.c

     RMenum rmNodeUpdateSceneTexture (const RMnode *toUpdate)

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

This routine will cause texture data contained within an RMtexture scene parameter to be downloaded to OpenGL texture memory.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

librm library source file: rmscene.c

     RMenum rmNodeSetSceneViewport (RMnode *toModify,
    			        const float *newViewport)

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

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.

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.

Use input values of {0.0, 0.0, 1.0, 1.0} to consume the entire window.

Upon success, RM_CHILL is returned; otherwise, RM_WHACKED is returned.

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:

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;

2. Callers may safely delete their copy of the input object after a successful return from this routine.

librm library source file: rmscene.c

     RMenum rmNodeGetSceneViewport (const RMnode *toQuery,
    			        float **returnViewport)

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

     float **returnViewport - a handle to an array of float (returned).

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.

Otherwise, RM_WHACKED is returned and the caller supplied return parameter returnViewport remains unmodified.

Because this routine returns a COPY of the RMnode's scene parameter (an array of floats), two important ramifications should be noted:

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;

2. Callers are responsible for managing the returned object (rmFloatDelete the object when it is no longer needed).

librm library source file: rmscene.c