<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmpipe.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="rmPipeCreateContext">
<pre><b>
RMenum rmPipeCreateContext (RMpipe *toUse)
</b></pre>
<pre>
RMpipe *toUse - a handle to an RMpipe (modified).
</pre>
<menu><P>
This routine will create a platform-specific OpenGL context that honors
the display format attributes contained in the RMpipe. Use
rmPipeSetChannelFormat() to set such parameters prior to creating the context.
Changing the channel format parameters after the context has been created
with this routine will have no effect.
</P>
<P>
After the context has been created with this routine, be sure to call
rmPipeMakeCurrent() to perform final intialization steps needed to ready
the context for use in rendering.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeNew">
<pre><b>
RMpipe * rmPipeNew (RMenum targetPlatform)
</b></pre>
<pre>
RMenum targetPlatform - select the appropriate platform. This parameter
must be one of RM_PIPE_GLX, RM_PIPE_WGL or RM_PIPE_CR.
</pre>
<menu><P>
Use this routine to create a new RMpipe object for use with a specified
display platform. Upon success, a handle to the new RMpipe object is
returned to the caller, or NULL is returned upon failure.
</P>
<P>
The input parameter must be one of RM_PIPE_GLX, RM_PIPE_WGL or RM_PIPE_CR.
RM_PIPE_GLX specifies use on any X-based system that has the GLX extension
(supports OpenGL through the server). RM_PIPE_WGL specifies use on a
Win32 platform. RM_PIPE_CR specifies use only on a Chromium-enabled system.
</P>
<P>
Note that RM_PIPE_GLX and RM_PIPE_WGL platforms can make use of Chromium
as well for doing single application to one or more crservers. However,
an RM_PIPE_CR platform is highly Chromium-specific. Refer to the RM
Programming Guide for more details.
</P>
<P>
During rmPipeNew(), the RMpipe object is initialized with the following
platform-specific and platform-neutral settings:
</P>
<P>
1. The "swapbuffers" function is set to a platform-appropriate value. The
application may later override this setting using rmPipeSetSwapBuffersFunc().
By assigning a default swapbuffers function, we are assuming that the
OpenGL context (created later) will be double buffered.
</P>
<P>
2. The default channel format is RM_MONO_CHANNEL, which corresponds to
an OpenGL visual that has RGBA color buffers, a depth buffer, and which
is double-buffered. The channel format can be set using
rmPipeSetChannelFormat() after rmPipeNew() returns, and before a window
is created (or before drawing occurs in the case of RM_PIPE_CR).
</P>
<P>
3. The default processing mode is RM_PIPE_MULTISTAGE. This mode corresponds
to serial rendering using a two-stage pipeline. You can set the processing
mode after rmPipeNew() returns (see rmPipeSetProcessingMode), but before
rmPipeMakeCurrent().
</P>
<P>
4. The "post render barrier function" is set to NULL (see
rmPipeSetPostRenderBarrierFunc).
</P>
<P>
5. The "post render function" is set to NULL (see
rmPipeSetPostRenderFunc).
</P>
<P>
6. 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().
</P>
<P>
The basic sequence of steps needed to fully initialize RM for rendering are:
</P>
<P>
1. Use rmPipeNew(yourPlatform) to create the RMpipe object specific
for your platform.
</P>
<P>
2. Set any optional parameters on the RMpipe: processing mode (see
rmPipeSetProcessingMode), channel format (see rmPipeSetChannelFormat),
XDisplay on X systems (see rmxPipeSetDisplay).
</P>
<P>
X11 note: if you want to display somewhere other than getenv($DISPLAY),
you will need to make an explicit call to rmxPipeSetDisplay() using
an appropriate XDisplay structure. By default, rmPipeNew(RM_PIPE_GLX)
will perform XOpenDisplay(getenv("$DISPLAY")), and assign the
resulting XDisplay structure to the RMpipe.
</P>
<P>
3. Create a window suitable for display. This can be done with
either rmauxCreateXWindow() or rmauxCreateW32Window(), or a suitable
drawable can be provided by an external source (for more details, see
the RM Programming Guide).
</P>
<P>
4. Assign the window to the RMpipe (see rmPipeSetWindow)
</P>
<P>
5. Make the pipe current (rmPipeMakeCurrent).
</P>
<P>
Note: the routine rmPipeInit() was deprecated after 1.4.3 and is
no longer a part of the API.
1. Use rmPipeInit to create and initialize a pipe.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeDelete">
<pre><b>
RMenum rmPipeDelete (RMpipe *toDelete)
</b></pre>
<pre>
RMpipe *toDelete - a handle to an RMpipe to be deleted.
</pre>
<menu><P>
Releases resources associated with an RMpipe object. This is the
opposite of rmPipeNew(). Returns RM_WHACKED if the input RMpipe is
NULL.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeMakeCurrent">
<pre><b>
RMenum rmPipeMakeCurrent (RMpipe *toUse)
</b></pre>
<pre>
RMpipe *toUse - a handle to an RMpipe object (input).
</pre>
<menu><P>
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.
</P>
<P>
All applications will use this routine to make an RMpipe "active."
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeClose">
<pre><b>
RMenum rmPipeClose(RMpipe *toClose)
</b></pre>
<pre>
RMpipe *toClose - a handle to an RMpipe (modified).
</pre>
<menu><P>
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.
</P>
<P>
On X11, this routine will also close the X Display associated with
the RMpipe.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSwapBuffers">
<pre><b>
RMenum rmPipeSwapBuffers (RMpipe *p)
</b></pre>
<pre>
RMpipe *p - a handle to an RMpipe (input).
</pre>
<menu><P>
This routine will cause a buffer-swap on the display and window
specified by the input RMpipe.
</P>
<P>
In the interest of speed, no error checking is performed inside this
routine.
</P>
<P>
This routine is most typically called from within a rendering manager
routine, and not directly from the application. There is nothing that
precludes it's use directly by applications, if so desired.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetChannelFormat">
<pre><b>
RMenum rmPipeSetChannelFormat (RMpipe *toModify,
RMenum channelFormat)
</b></pre>
<pre>
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,
</pre>
<menu><P>
Use this routine to set the "channel format" of an RMpipe object.
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
This routine must be called between the time you create the RMpipe with
rmPipeNew(), and before an OpenGL rendering context is created with
rmPipeCreateContext(). It is a logic error to change an RMpipe's channel
format after the OpenGL context has been created.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetChannelFormat">
<pre><b>
RMenum rmPipeGetChannelFormat (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetInitMatrixStackMode">
<pre><b>
RMenum rmPipeSetInitMatrixStackMode(RMpipe *toModify,
RMenum newMode)
</b></pre>
<pre>
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.
</pre>
<menu><P>
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).
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetInitMatrixStackMode">
<pre><b>
RMenum rmPipeGetInitMatrixStackMode(const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (queried).
</pre>
<menu><P>
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.
</P>
<P>
A return value of RM_WHACKED indicates an error condition.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetRenderPassEnable">
<pre><b>
RMenum rmPipeSetRenderPassEnable(RMpipe *toModify,
RMenum opaque3DEnable,
RMenum transparent3DEnable,
RMenum opaque2DEnable)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe (modified).
RMenum opaque3DEnable,transparent3DEnable, opaque2DEnable - RMenum
values, may be either RM_TRUE or RM_FALSE.
</pre>
<menu><P>
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:
</P>
<P>
1. 3D Opaque
</P>
<P>
2. 3D Transparent
</P>
<P>
3. 2D Opaque
</P>
<P>
(There may be a 2D transparent pass in a later release.)
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetRenderPassEnable">
<pre><b>
RMenum rmPipeGetRenderPassEnable(const RMpipe *t,
RMenum *opaque3DEnableReturn,
RMenum *transparent3DEnableReturn,
RMenum *opaque2DEnableReturn)
</b></pre>
<pre>
const RMpipe *t - a handle to an RMpipe (input).
RMenum *opaque3DEnableReturn, *transparent3DEnableReturn,
*opaque2DEnableReturn - handles to RMenum values (result).
</pre>
<menu><P>
This routine is used to obtain the boolean values that indicate if
a particular rendering pass is enabled in the RMpipe.
</P>
<P>
Each of the return parameters is optional - a value of NULL will skip
reporting of that particular rendering pass.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetWindowSize">
<pre><b>
RMenum rmPipeSetWindowSize (RMpipe *toModify,
int newWidth,
int newHeight)
</b></pre>
<pre>
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).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
This routine is called by rmPipeSetWindow().
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetWindowSize">
<pre><b>
RMenum rmPipeGetWindowSize (const RMpipe *toQuery,
int *widthReturn,
int *heightReturn)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe (input).
int *widthReturn, *heightReturn - pointers to integers (return).
Values of NULL are acceptable.
</pre>
<menu><P>
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.
</P>
<P>
Callers interested in only width or height may specify NULL for the
parameter for which information is not requested.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetSwapBuffersFunc">
<pre><b>
RMenum rmPipeSetSwapBuffersFunc (RMpipe *toModify,
void (newFunc)(RMpipe *))
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe (modified).
void (newFunc)(RMpipe *) - a handle to an application callback
(input).
</pre>
<menu><P>
Use this routine to set the "swapbuffers" callback function
associated with an RMpipe object. Returns RM_CHILL upon success, or
RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetPostRenderFunc">
<pre><b>
RMenum rmPipeSetPostRenderFunc (RMpipe *toModify,
void (*postRenderFunc)(const RMimage *, RMenum))
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe (modified).
void (*postRenderFunc)(RMimage *, RMenum) - a handle to an
application callback.
</pre>
<menu><P>
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.
</P>
<P>
Use a value of NULL for the postRenderFunc to effectively disable
post rendering callbacks.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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).
</P>
<P>
The RMimage object provided to applications is managed by RM.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetPostRenderDepthFunc">
<pre><b>
RMenum rmPipeSetPostRenderDepthFunc (RMpipe *toModify,
void (*postRenderDepthFunc)(const RMimage *, RMenum))
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMimage object (modified).
void (*postRenderDepthFunc)(RMimage *, RMenum) - a handle to an
application callback (input).
</pre>
<menu><P>
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.
</P>
<P>
Use a value of NULL for the postRenderDepthFunc to effectively
disable this post rendering callback.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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).
</P>
<P>
The RMimage object provided to applications is managed by RM.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetPostRenderBarrierFunc">
<pre><b>
RMenum rmPipeSetPostRenderBarrierFunc (RMpipe *toModify,
void (*barrierFunc)(RMpipe *))
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe object (modified).
void (*barrierFunc)(RMpipe *) - a handle to an application callback
(input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
The application callback will be provided a single parameter, an
RMpipe.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeProcessingModeIsMultithreaded">
<pre><b>
RMenum rmPipeProcessingModeIsMultithreaded (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe (input).
</pre>
<menu><P>
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.
</P>
<P>
See also rmPipeGetProcessingMode().
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetProcessingMode">
<pre><b>
RMenum rmPipeGetProcessingMode (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
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.
</P>
<P>
Upon failure, RM_WHACKED is returned to the caller.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetProcessingMode">
<pre><b>
RMenum rmPipeSetProcessingMode (RMpipe *toModify,
RMenum newMode)
</b></pre>
<pre>
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.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
The following processing modes are supported:
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.).
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetDisplayListEnable">
<pre><b>
RMenum rmPipeGetDisplayListEnable (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
This routine will return the RMpipe's notion of whether or not it will use
OpenGL display lists when rendering primitives. The returned value will be
either RM_TRUE, which indicates that display lists will be used when
rendering primitives on the RMpipe, or RM_FALSE, which indicates that no
RMprimitives will be drawn using display lists.
</P>
<P>
See also: rmPipeSetDisplayListEnable, rmPrimitiveSetDisplayListEnable.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetDisplayListEnable">
<pre><b>
RMenum rmPipeSetDisplayListEnable (RMpipe *toModify,
RMenum newMode)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe (modified).
RMenum newMode - a RMenum specifying whether or not RMprimitives rendered on
the RMpipe toModify will use display lists. The input value should be
either RM_TRUE or RM_FALSE.
</pre>
<menu><P>
Set's the RMpipe's policy on the use of display lists. When the value
of newMode is set to RM_TRUE, use of display lists on the RMpipe toModify
is enabled. When set to RM_FALSE, use of display lists on the RMpipe is
disabled. The default policy for use of display lists is RM_TRUE, and this
value is set at the time the RMpipe is created. You can override the
default behavior by calling rmPipeSetDisplayListEnable() with a value
of RM_FALSE.
</P>
<P>
Use of display lists can greatly accelerate rendering performance on
many platforms. By default, RM will attempt to create display lists for
RMprimitives during rendering, and reuse them in subsequent renderings.
</P>
<P>
Applications can control use of display lists in two ways: at the RMpipe
level, and at the RMprimitive level. At the RMpipe level, you can
enable or disable use of display lists for all RMprimitives drawn on RMpipe
using the routine rmPipeSetDisplayListEnable. At the RMprimitive level,
you can enable or disable the use of display lists for a single primitive
using rmPrimitiveSetDisplayListEnable().
</P>
<P>
The RMprimitive display list policy does not override the display list
policy set at the RMpipe level. In other words, if the policy at the RMpipe
level is set to RM_FALSE, then no display lists will be used, even if the
policy at the RMprimitive level is set to RM_TRUE. On the other hand, if
the policy at the RMpipe level is set to RM_TRUE, a policy at the RMprimitive
level of RM_FALSE will result on no display lists being used for the
one RMprimitive. In order for display lists to be used at any given
RMprimitive, the logical AND of RMpipe and RMprimitive display list
policies must be RM_TRUE.
</P>
<P>
To obtain the current display list use policy at an RMpipe, use the routine
rmPipeGetDisplayListEnable().
</P>
<P>
See also rmPrimitiveSetDisplayListEnable().
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetCommSize">
<pre><b>
RMenum rmPipeSetCommSize (RMpipe *toModify)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe object (modified).
</pre>
<menu><P>
Sets the global number of PEs in an MPI-parallel application.
Docs need to be better written.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetCommSize">
<pre><b>
int rmPipeSetCommSize (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
Returns the global number of PEs in an MPI-parallel application.
Docs need to be better written.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetRank">
<pre><b>
RMenum rmPipeSetRank (RMpipe *toModify)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe object (modified).
</pre>
<menu><P>
Sets the rank value of one RMpipe in an MPI-parallel application.
Docs need to be better written.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetRank">
<pre><b>
int rmPipeGetRank (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
Obtains the rank value of one RMpipe in an MPI-parallel application.
Docs need to be better written.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetDisplayName">
<pre><b>
const char * rmPipeGetDisplayName (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object (input).
</pre>
<menu><P>
Returns to the caller a character string defining $DISPLAY, the display
name. $DISPLAY has an effect only on GL_PIPE_GLX platforms.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetDisplayName">
<pre><b>
RMenum rmPipeSetDisplayName (RMpipe *toModify, const char *displayName)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe object (modified).
const char *displayName - character string defining name of the $DISPLAY
to use in subsequent window system operations.
</pre>
<menu><P>
Use this routine to set the $DISPLAY variable in an RMpipe. This
variable is used only on RM_PIPE_GLX platforms, and only when a
Returns to the caller a character string defining $DISPLAY, the display
name. $DISPLAY has an effect only on GL_PIPE_GLX platforms.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetDisplay">
<pre><b>
void * rmPipeGetDisplay (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - a handle to an RMpipe object that will be
queried (input).
</pre>
<menu><P>
Returns to the caller the X Display handle, cast to void *, associated
with an RMpipe.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeSetFrameRate">
<pre><b>
RMenum rmPipeSetFrameRate (RMpipe *toModify, int newFPS)
</b></pre>
<pre>
RMpipe *toModify - a handle to an RMpipe (modified).
int newFPS - an integer value indicating the target frames-per-second
renderering rate when rendering on the RMpipe toModify.
</pre>
<menu><P>
This routine is used to specify the desired frame rate when rendering
on the RMpipe toModify. The caller provides an integer value, newFPS,
that indicates the desired number of frames per second. A value of 30
will result in 30 frames per second being rendered, etc. A value of -1
will disable constant-rate rendering: OpenRM will not "watch the clock"
if you specify a value of -1 frames per second as the desired target
rate. The value for newFPS should be a positive integer. Note that not
all values of newFPS make sense on all platforms for reasons related
to how OpenGL is implemented on your machine.
</P>
<P>
Constant-rate rendering is really a misnomer : what the contstant-rate
rendering capability in OpenRM really does is to use a high precision
timer and sleep function to ensure that *no more than a given number
of frames per second are rendered*. In this way, you can be assured that
your application will not be rendering more than newFPS per second. If
your application produces a heavy graphics load, the actual rendering
rate may fall well short of newFPS frames per second. Rather than
calling this capability "constant frame rate" rendering, it is more
accurately called "bounded frame rate" rendering.
</P>
<P>
Future work in this area will result in the ability for the application
to query the rendering "load" or "stress" values. This way, you'll be
able to obtain a quantitative value that indicates how far "over budget"
your rendering is, and take action accordingly. One remedial action
will be for the application to use switch nodes and render lower-resolution
models as a way to reduce graphics rendering load.
</P>
<P>
From the newFPS parameter, a value of milliseconds-per-frame is computed.
When your application calls rmFrame() for the first time, OpenRM makes
note of the current time. It then proceeds with rendering without delay,
and then returns control to the application after rendering is
complete. The second time your application calls rmFrame(), OpenRM
will delay rendering so that the time taken by rendering during the
previous frame along with the time taken by the application for processing
inbetween frames does not exceed the occur before the milliseconds-per-frame
amount of time has passed. In other words, the period of timing is from
the start of rendering to the start of rendering.
</P>
<P>
The bounded-frame-rendering capability works on both Unix/Linux and Win32
platforms subject to caveats that are described in the OpenRM Programming
Guide. Additional caveats not specific to a platform are also discussed
in the OpenRM Progamming Guide.
</P>
<P>
Use the routine rmPipeGetFrameRate() to query the frames-per-second
parameter of an RMpipe.
</P>
<P>
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetFrameRate">
<pre><b>
int rmPipeGetFrameRate (constRMpipe *toQuery)
</b></pre>
<pre>
RMpipe *toQuery - a handle to an RMpipe (queried).
</pre>
<menu><P>
Use this routine to obtain the RMpipe's notion of how many frames per
second it is supposed to render. For a more meaningful discussion of
what the frames-per-second RMpipe attribute means, refer to the
discussion for rmPipeSetFrameRate() as well as the OpenRM Programming
Guide.
</P>
<P>
Returns either -1 or a positive integer on success, or zero on failure.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
<a name="rmPipeGetFrameNumber">
<pre><b>
int rmPipeGetFrameNumber (const RMpipe *toQuery)
</b></pre>
<pre>
const RMpipe *toQuery - (input) a handle to an RMpipe.
</pre>
<menu><P>
Use this routine to obtain the RMpipe's notion of the current frame
number. Upon success, a non-negative integer is returned. Upon failure,
a value of -1 is returned.
</P>
<P>
The RMpipe's frame number is initialized to zero when the RMpipe is
created with rmPipeNew(). Upon each call to rmFrame(), the the
frame number is incremented by one. There is no mechanism for applications
to set the frame number, or for applications to reset the frame number
to zero.
</P></menu>
<i>librm library source file: rmpipe.c </i><hr width="75%">
</body></html>
distrib
>
Mandriva
>
2007.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
8079d983ecf371717db799dd75bd56c2
>
files
>
33
