Index of OpenRM - RM Library


  RMpipe * rmPipeNew (void)
  No arguments.

Use this routine to create a new RMpipe object. Upon success, a handle to the new RMpipe object is returned to the caller, or NULL is returned upon failure.

The RMpipe object is initialized with the following:

1. The "swapbuffers" function is set to rmSwapBuffers (rmPipeSetSwapbuffers). We assume by making this the default that the OpenGL context is one which is double-buffered.

2. The "post render barrier function" is set to NULL (see rmPipeSetPostRenderBarrierFunc).

3. The "post render function" is set to NULL (see rmPipeSetPostRenderFunc).

4. Each of the following three passes of the multipass rendering engine is enabled by default: opaque 3D, transparent 3D, opaque 2D. Applications may not change the order of these rendering passes, but may enable or disable a given rendering pass with rmPipeSetRenderPassEnable().

The RMpipe object plays a central role in all applications that use RM for rendering. When fully initialized, it contains a handle to the OpenGL rendering context, a handle to and configuration information about the window used for rendering, a rendering or draw callback, post rendering callbacks (swapbuffers, and two arbitrary post-render functions). The precise contents of the RMpipe object vary depending upon the underlying window system; the contents of X11 and Win32 pipes differ to some degree to reflect that the information needed to render using OpenGL on each of these platforms differs.

The basic sequence of steps needed to enable the use of RM for rendering are:

1. Use rmPipeInit to create and initialize a pipe.

2. Create a window suitable for display. This can be done with either rmauxCreateXWindow() or rmauxCreateW32Window().

3. Assign the window to the RMpipe (rmPipeSetWindow)

4. Make the pipe current (rmPipeMakeCurrent).

librm library source file: rmpipe.c

 RMenum rmPipeDelete (RMpipe *toDelete)
 RMpipe *toDelete - a handle to an RMpipe to be deleted.

Releases resources associated with an RMpipe object. This is the opposite of rmPipeNew(). Returns RM_WHACKED if the input RMpipe is NULL.

librm library source file: rmpipe.c

 RMenum rmPipeMakeCurrent (RMpipe *toUse)
 RMpipe *toUse - a handle to an RMpipe object (input).

Use this routine to make a named RMpipe "active." Inside this routine, the OpenGL rendering context associated with the input RMpipe is made current, and all subsequent OpenGL commands are executed to that context.

All applications will use this routine to make an RMpipe "active."

During the process of making an RMpipe active, this routine will check for the existance of a "context cache," and will create a new one, if one does not exist. If a context cache exists, it will be replaced with a new one.

The context cache is used internally by RM to store retained mode, OpenGL context-specific data, such as display list indices, texture object identifiers, and so forth. The reason for creating/replacing/activating the context cache in this routine, rather than earlier (when the OpenGL context is created) is due to the inconsistencies between X11 and Win32 in how OpenGL is initialized. In X11, the GLX context must be created prior to creating an X11 window (XCreateWindow needs an XVisualInfo structure, which reflects the pixel format chosen with glXChooseVisual). In Win32, the equivalent of an XVisualInfo structure is created using a window handle.

In nearly all applications, this routine will be called only once. It is not an error call it multiple times, but developers must be aware that any existing retained mode structures will be flushed by rmPipeMakeCurrent, and rebuilt during subsequent renderings.

This routine *must* be called by all applications between rmPipeInit() (RMpipe initialization) and rmFrame() (rendering). Note that some applications (CAVELib apps, for example) will *not* call rmPipeInit, but will instead call rmPipeNew, followed by some number of steps to fully specify the rendering context, window parameters, and so forth into the RMpipe. Those apps must call rmPipeMakeCurrent between the time the GLXcontext is assigned to the RMpipe and the first time rendering is performed to the RMpipe.

librm library source file: rmpipe.c

 RMenum rmPipeClose(RMpipe *toClose)
 RMpipe *toClose - a handle to an RMpipe (modified).

This routine will destroy the OpenGL rendering context associated with the input RMpipe object, and delete all resources associated with the RMpipe's context cache, including all OpenGL display lists and texture object id's.

On X11, this routine will also close the X Display associated with the RMpipe.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmpipe.c

 RMenum rmPipeSetChannelFormat (RMpipe *toModify,
		                RMenum channelFormat)
 RMpipe *toModify - a handle to an RMpipe object (modified).

 RMenum channelFormat - an RMenum value specifying a display
    format. May be one of RM_MONO_CHANNEL, RM_REDBLUE_STEREO_CHANNEL,

Use this routine to set the "channel format" of an RMpipe object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The RMpipe channel format serves two purposes. First, when multibuffered stereo is requested, this information must be known prior to creating an OpenGL rendering context. So, the channel format provides hints about the type of OpenGL capabilities that are needed by the application. As such, it is likely that the channel format interface will evolve over time to include more access to additional OpenGL capabilities.

Second, when a channel format is specified, internal to rmPipeSetChannelFormat(), an RM rendering callback is assigned to the pipe. The rendering callback knows about multipass rendering as well as how to instruct the underlying rendering engine in the details of managing stereo rendering.

In most cases, applications will not need to call this routine directly. Instead, the preferred interface is through rmPipeInit(), which takes a channel format parameter.

librm library source file: rmpipe.c

 RMenum rmPipeGetChannelFormat (const RMpipe *toQuery)
 const RMpipe *toQuery - a handle to an RMpipe object (input).

Returns to the caller the current channel format of an RMpipe object. A successful return value will be one of RM_MONO_CHANNEL, RM_REDBLUE_STEREO_CHANNEL, RM_BLUERED_STEREO_CHANNEL or RM_MBUF_STEREO_CHANNEL. A return value of RM_WHACKED indicates an error of some type.

librm library source file: rmpipe.c

 RMenum rmPipeSetInitMatrixStackMode(RMpipe *toModify,
			             RMenum newMode)
 RMpipe *toModify - a handle to an RMpipe object (modified).
 RMenum newMode - an RMenum value, either RM_TRUE or RM_FALSE, that
    controls how matrix transformations are applied to the OpenGL
    matrix stack.

By default, OpenRM will initialize the OpenGL matrix stack during a frame rendering operation by setting GL_MODELVIEW, GL_PROJECTION and GL_TEXTURE matrices to the Identity matrix. This behavior may be overridden, so that OpenRM will honor any existing matrices in the matrix stacks while accumulating nested transformations. This is helpful in some deployment environments, such as combining OpenRM with CAVElib (www.vrco.com).

When the input enumerator is set to RM_TRUE (the default), OpenRM will initialize the OpenGL matrix stack to the identity matrix prior to accumulating transformations during rendering. When the input enum is set to RM_FALSE, OpenRM will NOT initialize the matrix stack, and any existing transformations within the scene graph will be accumulated with the contents of the matrix stack at render time.

More precisely, if the GL_MODELVIEW matrix stack has the matrix M, and the scene graph defines a matrix transformation S, the combined transformation will be S*M (left multiplication), so that the scene graph transformation S is effectively applied prior to the outer transformation M when vertex data moves down the OpenGL transformation pipeline.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmpipe.c

 RMenum rmPipeGetInitMatrixStackMode(const RMpipe *toQuery)
 const RMpipe *toQuery - a handle to an RMpipe object (queried).

This routine will return the "init matrix stack" attribute of an RMpipe object. A return value of RM_TRUE means the OpenGL matrix stack will be initialized by OpenRM during frame rendering, while a value of RM_FALSE means that any existing values in the OpenGL matrix stack will be honored during rendering.

A return value of RM_WHACKED indicates an error condition.

librm library source file: rmpipe.c

 RMenum rmPipeSetRenderPassEnable(RMpipe *toModify,
			          RMenum opaque3DEnable,
				  RMenum transparent3DEnable,
				  RMenum opaque2DEnable)
 RMpipe *toModify - a handle to an RMpipe (modified).

 RMenum opaque3DEnable,transparent3DEnable, opaque2DEnable - RMenum
    values, may be either RM_TRUE or RM_FALSE. 

This routine is used to selectely enable or disable one of the rendering passes of the RM multipass rendering engine. Applications may not change the order of the rendering passes, but may selectively enable or disable a given pass. The order of the passes is:

1. 3D Opaque

2. 3D Transparent

3. 2D Opaque

(There may be a 2D transparent pass in a later release.)

During each of these passes, traversal filters are applied at each node of the RM scene graph. If, at any stage during the traversal, the scene graph node does not pass the traversal filter test, that node, and any descendents, are not processed.

For this reason, developers should carefully consider scene graph design such that 3D opaque, 3D transparent and 2D objects are appropriately partitioned within the scene graph itself.

Background scene operations (background clear color, background image tile, background depth value, background depth image) are performed during rendering passes 1 and 3. A common RM error is to place a background scene operation at a node that is processed during multiple rendering passes.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmpipe.c

 RMenum rmPipeGetRenderPassEnable(const RMpipe *t,
			          RMenum *opaque3DEnableReturn,
				  RMenum *transparent3DEnableReturn,
				  RMenum *opaque2DEnableReturn)

 const RMpipe *t - a handle to an RMpipe (input).

 RMenum *opaque3DEnableReturn, *transparent3DEnableReturn,
    *opaque2DEnableReturn - handles to RMenum values (result). 

This routine is used to obtain the boolean values that indicate if a particular rendering pass is enabled in the RMpipe.

Each of the return parameters is optional - a value of NULL will skip reporting of that particular rendering pass.

Upon success, RM_CHILL is returned, and RM_TRUE or RM_FALSE is copied into non-NULL caller-supplied memory for each of the RMpipe rendering passes. Otherwise, RM_WHACKED is returned, and caller-supplied memory remains unmodified.

librm library source file: rmpipe.c

 RMenum rmPipeSetWindowSize (RMpipe *toModify,
		             int newWidth,
			     int newHeight)
 RMpipe *toModify - a handle to an RMpipe (modified).

 int newWidth, newHeight - integer values specifing the pixel width
    and height of the window associated with an RMpipe (input). 

This routine sets the RMpipe's notion of pixel width and height of it's associated display window. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

The most typical use of this routine will be when an application detects, through an event loop, that the window geometry has changed. The application is reponsible for notifying RM of such changes; RM doesn't manage events and doesn't keep track of the size of the display window.

This routine is called by rmPipeSetWindow().

librm library source file: rmpipe.c

 RMenum rmPipeGetWindowSize (const RMpipe *toQuery,
		             int *widthReturn,
			     int *heightReturn)
 const RMpipe *toQuery - a handle to an RMpipe (input).

 int *widthReturn, *heightReturn - pointers to integers (return).
    Values of NULL are acceptable.

This routine returns via caller-supplied memory the named RMpipe's notion of the current window width and height. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Callers interested in only width or height may specify NULL for the parameter for which information is not requested.

librm library source file: rmpipe.c

 RMenum rmPipeSetSwapbuffersFunc (RMpipe *toModify,
			          void (newFunc)(RMpipe *))
 RMpipe *toModify - a handle to an RMpipe (modified).

 void (newFunc)(RMpipe *) - a handle to an application callback
    (input). 

Use this routine to set the "swapbuffers" callback function associated with an RMpipe object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The swapbuffers function is invoked after rendering has completed, and after the post-render barrier function, and the post-render framebuffer and depthbuffer grab callbacks, if any. By default, rmSwapBuffers() is assigned to all RMpipe objects' swapbuffers callback functions at the time the RMpipe is created with RMpipe new. The function rmSwapBuffers() calls the native window-system procedure that causes front and back buffers to be swapped.

If the application overrides the default swapbuffers function, the application callback will be provided a single input parameter: a handle to an RMpipe object. The RMpipe object contains enough information to enable application code to do the swapbuffers call.

librm library source file: rmpipe.c

 RMenum rmPipeSetPostRenderFunc (RMpipe *toModify,
			         void (*postRenderFunc)(const RMimage *, RMenum))
 RMpipe *toModify - a handle to an RMpipe (modified).

 void (*postRenderFunc)(RMimage *, RMenum) - a handle to an
    application callback.

This routine assigns a "post render" application callback to the RMpipe. The post render callback is invoked after rendering has occured, and after the "post render barrier function" has been called (if any), but before the "post render depthbuffer function" (if any) and before the swapbuffers function. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Use a value of NULL for the postRenderFunc to effectively disable post rendering callbacks.

The purpose of the post render function is to allow applications to grab a copy of the color planes of the framebuffer after rendering has occured. If you want the raw image data produced by the rendering, this is the path to use.

When the application callback is invoked, the callback is invoked with two parameters. The first is a handle to an RMimage object. Use rmImageGetPixelData() to obtain the raw pixel data from this image. At this time (Jan 2000) the image provided to the app callback is in GL_RGBA, GL_UNSIGNED_BYTE format. Applications are advised to use the rmImageGet*() series of routines to obtain RMimage configuration information. In particular, pay close attention to scanline-padding issues.

The second parameter provided to the application callback is an RMenum value that is one of RM_ALL_CHANNELS, RM_LEFT_CHANNEL or RM_RIGHT_CHANNEL. Multibuffered stereo channels will invoke the application callback twice, once for each channel. Anaglyph stereo formats (RM_REDBLUE_STEREO_CHANNEL and RM_BLUERED_STEREO_CHANNEL) will trigger the callback just once. This may change in the future (Jan 2000).

The RMimage object provided to applications is managed by RM.

librm library source file: rmpipe.c

 RMenum rmPipeSetPostRenderDepthFunc (RMpipe *toModify,
			              void (*postRenderDepthFunc)(const RMimage *, RMenum))
 RMpipe *toModify - a handle to an RMimage object (modified).

 void (*postRenderDepthFunc)(RMimage *, RMenum) - a handle to an
    application callback (input). 

Use this routine to assign a "post render depth buffer" callback to an RMpipe object. RM_CHILL is returned upon success, or RM_WHACKED upon failure.

Use a value of NULL for the postRenderDepthFunc to effectively disable this post rendering callback.

Whereas the "post render callback" gives applications access to the color planes of the framebuffer after rendering, the purpose of this callback is to give applications access to the depth buffer after rendering has completed. Assigning a "post render depth buffer callback" will cause the application callback to be invoked after rendering, and after the post-render barrier function, after the post render callback (the color planes) but before the swapbuffers function.

The pixel data of the RMimage object provided to the application, the first application callback parameter, contains the contents of the depth buffer of the scene just rendered. The pixel data in the RMimage object is in RM_FLOAT format. Applications should use the rmImageGet*() series of routines to query specific RMimage attributes.

The second parameter provided to the application callback is an RMenum value that is one of RM_ALL_CHANNELS, RM_LEFT_CHANNEL or RM_RIGHT_CHANNEL. Multibuffered stereo channels will invoke the application callback twice, once for each channel. Anaglyph stereo formats (RM_REDBLUE_STEREO_CHANNEL and RM_BLUERED_STEREO_CHANNEL) will trigger the callback just once. This may change in the future (Jan 2000).

The RMimage object provided to applications is managed by RM.

librm library source file: rmpipe.c

 RMenum rmPipeSetPostRenderBarrierFunc (RMpipe *toModify,
			                void (*barrierFunc)(RMpipe *))
 RMpipe *toModify - a handle to an RMpipe object (modified).

 void (*barrierFunc)(RMpipe *) - a handle to an application callback
    (input).

Use this routine to set the "post render barrier function" on an RMpipe object. Use a value of NULL for barrierFunc to disable this callback, or remove a previously installed callback. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The "post render barrier" callback, if present, will be invoked immediately after rendering, but prior to any other callbacks (post render color planes callback, post render depth buffer callback or swapbuffers). This routine is intended for use by parallel rendering applications.

The application callback will be provided a single parameter, an RMpipe.

librm library source file: rmpipe.c

 RMenum rmPipeProcessingModeIsMultithreaded (const RMpipe *toQuery)
 const RMpipe *toQuery - a handle to an RMpipe (input).

This routine can be used to determine if the processing mode of the RMpipe toQuery is a multithreaded format. If toQuery's processing mode is either RM_PIPE_MULTISTAGE_VIEW_PARALLEL or RM_PIPE_MULTISTAGE_PARALLEL, this routine will return RM_TRUE. Otherwise, RM_FALSE is returned.

See also rmPipeGetProcessingMode().

librm library source file: rmpipe.c

 RMenum rmPipeGetProcessingMode (const RMpipe *toQuery)
 const RMpipe *toQuery - a handle to an RMpipe object (input).

This routine will return the processing mode of the RMpipe toQuery. Upon success, one of the following is returned to the caller: RM_PIPE_SERIAL, RM_PIPE_MULTISTAGE, RM_PIPE_MULTISTAGE_PARALLEL or RM_PIPE_MULTISTAGE_VIEW_PARALLEL.

Upon failure, RM_WHACKED is returned to the caller.

librm library source file: rmpipe.c

 RMenum rmPipeSetProcessingMode (RMpipe *toModify,
			         RMenum newMode)
 RMpipe *toModify - a handle to an RMpipe (modified).
 RMenum newMode - a RMenum specifying a processing mode. This value must
 be one of:  RM_PIPE_SERIAL, RM_PIPE_MULTISTAGE, RM_PIPE_MULTISTAGE_PARALLEL
 or RM_PIPE_MULTISTAGE_VIEW_PARALLEL.

This routine will select the "processing mode" for an RMpipe object. The processing mode assigns a rendering engine to the RMpipe for use in subsequent rendering operations. Upon success, RM_CHILL is returned to the caller; upon failure, RM_WHACKED is returned.

Applications may set the processing mode on an RMpipe any time between when it is created (using either rmPipeNew or rmPipeInit) and the first time a frame is rendered. As of this time (June 2001), it is not possible to change the processing mode of an RMpipe, and this routine will not detect this error condition. Your application will likely crash if you attempt to alter the processing mode of an RMpipe after the first frame has been drawn.

OpenRM uses a two-stage rendering pipeline: a view traversal of the scene graph prepares a list of things to be drawn during a rendering traversal.

The following processing modes are supported:

RM_PIPE_MULTISTAGE - uses a two-stage rendering traversal (view, render), and both stages are called sequentially within the same process/thread as the caller. There is no parallelization in this processing mode.

RM_PIPE_MULTISTAGE_PARALLEL - each of the two rendering stages are called from detached Posix threads. The render thread will assume ownership of the OpenGL context (applications should NOT make any OpenGL calls except from within node callbacks invoked by the OpenRM renderer). This mode is fully parallelized.

RM_PIPE_MULTISTAGE_VIEW_PARALLEL - the view traversal is assigned to a detached thread, while the render traversal remains in the same execution process/thread as the caller (and does not attempt to exert ownership of the OpenGL rendering context). This mode is also fully parallelized, and is quite useful when combining OpenRM with other toolkits that provide device and event management and which make assumptions about ownership of the OpenGL rendering context (e.g., CAVELibrary, VRJuggler, FLTK, etc.).

librm library source file: rmpipe.c