OpenRM - RM Library (rmx.c)

Index of OpenRM - RM Library


 RMenum rmPipeInit (const char *displayName,
	            RMenum channelFormat,
		    RMpipe **pipeReturn)

 const char *displayName - a character string containing an X
    resolvable display name. Typically, this is of the form
    "myhost.myplace.com:0" (input).

 RMenum channelFormat - an RMenum value specifying the display format
    requested on the new RMpipe. May be one of RM_MONO_CHANNEL,
    RM_REDBLUE_STEREO_CHANNEL, RM_BLUERED_STEREO_CHANNEL or
    RM_MBUF_STEREO_CHANNEL (input).

 RMpipe **pipeReturn - a handle to an RMpipe * (return).

Use this routine to create and initialize an RMpipe object on the named X display using the specified channelFormat. Upon success, RM_NATIVE_OPENGL or RM_MESA_OPENGL is returned (indicating whether the underlying OpenGL/GLX mechanism is "native" or "Mesa"), and the pipeReturn parameter contains a handle to a newly created and initialized RMpipe object. Upon failure, RM_WHACKED is returned and the pipeReturn parameter remains unmodified.

RM_MONO_CHANNEL produces a monocular image.

RM_REDBLUE_STEREO_CHANNEL and RM_BLUERED_STEREO_CHANNEL produce anaglyph-style stereograms. The former uses a red passthrough filter for the left eye, the latter uses red for the right eye. You can use inexpensive red-blue glasses with this stereo format.

RM_MBUF_STEREO_CHANNEL uses a so-called multi-buffered or quad-buffered OpenGL framebuffer format to produce stereo. You will need special hardware in conjunction with this stereo format, such as the CrystalEyes active or passive stereo viewing system.

The stereo formats will produce 3D stereo images if and only if the underlying 3D camera is a stereo camera. See rmCamera3DSetStereo. There is no equivalent for 2D cameras. It is also possible to schedule a node for rendering during the left or right stereo rendering passes. See rmNodeSetChannel().

librm library source file: rmx.c


 RMenum rmxInitPipes (int npipes,
	              char *display_names[],
		      const int *channel_formats,
		      RMpipe ***pipes)

 int npipes - integer count of the number of RMpipes to initialize
    (input).

 char *display_names[] - array of character strings containing
    resolvable X display names, like "myhost.myplace.com:0",
    etc. There should be "npipes" of these strings.

 const int *channel_formats - an array of integer values, "npipes" in
    length, that specify the channel format for each of the new
    RMpipes. These values should be one of RM_MONO_CHANNEL,
    RM_REDBLUE_STEREO_CHANNEL, RM_BLUERED_STEREO_CHANNEL or
    RM_MBUF_STEREO_CHANNEL.

 RMpipe ***pipes - a handle to an RMpipe * array. Must be "npipes" in
    length.

January 2000 - this routine is still under development. It has not been extensively tested.

Use this routine to initialize a number of RMpipe objects, where all RMpipes share a common OpenGL rendering context. The pipes may all have unique display formats, with some being mono and others being stereo.

There is no corresponding Win32 version of this routine at this time (January 2000).

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmx.c


 RMenum rmxInitPipeUsingDisplay (Display *d,
			         RMenum channelFormat,
				 RMpipe **pipeReturn)

 Display *d - a handle to an already opened X display (input).

 int channelFormat - an RMenum value requesting a specific display
    format for the display. May be one of RM_MONO_CHANNEL,
    RM_REDBLUE_STEREO_CHANNEL, RM_BLUERED_STEREO_CHANNEL or
    RM_MBUF_STEREO_CHANNEL (input).

 RMpipe **pipeReturn - a handle to an RMpipe * (modified, return).

This is an X-specific version of rmPipeInit, but allows the caller to use an already-opened X display as input rather than asking RM to open the X display. Those applications that manage their own X displays and other resources will want to use this routine to avoid the added startup cost associated with XOpenDisplay.

Upon success, an RMpipe object is created, initialized and returned to the caller through the pipeReturn parameter. A return value of RM_WHACKED indicates an error of some type, otherwise RM_NATIVE_OPENGL or RM_MESA_GL indicates whether or not the underlying OpenGL support is natively supported or the Mesa software OpenGL implementation.

See rmPipeInit for more information concerning the channelFormat parameter.

librm library source file: rmx.c


 RMenum rmxPipeSetDisplay (RMpipe *toModify,
		           Display *display)

 RMpipe *toModify - a handle to an RMpipe that will be modified by
    this routine (modified).

 Display *display - a handle to an opened X display (input).

This routine assigns an X display handle to an RMpipe, returning RM_CHILL upon success, or RM_WHACKED upon failure.

Only those applications that want to do their own XOpenDisplay calls will make use of this routine.

librm library source file: rmx.c


 Display * rmxPipeGetDisplay (const RMpipe *toQuery)

 const RMpipe *toQuery - a handle to an RMpipe object that will be
    queried (input).

Returns to the caller the X Display handle associated with an RMpipe.

librm library source file: rmx.c


 RMenum rmxPipeSetColormap (RMpipe *toModify,
		            const Colormap newCmap)

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

 Colormap newCmap - an X colormap handle.

Directly assigns an X Colormap to an RMpipe object. This routine allows applications that require specific and precise control to modify the X Colormap within an RMpipe.

The only time that the X Colormap is ever used inside an RMpipe is when rmauxCreateWindow is used to create a new X window.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmx.c


 Colormap rmxPipeGetColormap (const RMpipe *toQuery)

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

Returns to the caller the X Colormap handle attribute of an RMpipe object. If the input RMpipe is NULL, a value of zero is returned.

librm library source file: rmx.c


 Colormap rmxGetSharableColormap (Display *d,
		                  XVisualInfo *v)

 Display *d - a handle to an opened X Display (input).

 XVisualInfo *v - a handle to a valid XVisualInfo structure (input).

Obtains a standard, sharable colormap suitable for use by XCreateWindow. Returns a handle to a valid X Colormap upon success, otherwise zero is returned.

Only those applications that create their own windows will need to use this routine. When using OpenGL, a sharable Colormap that is compatible with the OpenGL-compatible XVisual must be specified to XCreateWindow, otherwise a BadMatch error will be generated when the window is mapped.

librm library source file: rmx.c


 RMenum rmxPipeSetVisual(RMpipe *toModify,
		         XVisualInfo *visual)

 RMpipe *toModify - a handle to an RMpipe object (modified).

 XVisualInfo *visual - a handle to an XVisualInfo structure (input).

This routine will assign the specified X Visual to the RMpipe object, returning RM_CHILL upon success or RM_WHACKED upon failure.

Under usual circumstances, the XVisual inside an RMpipe is discovered and assigned by RM when rmPipeInit is called. The RM-discovered visual will be suitable for OpenGL rendering. This routine may be used by applications that wish to discover their own visual and assign that to an RMpipe.

The X visual structure is used at the time that an OpenGL rendering context is created. When rmPipeInit is called, an OpenGL rendering context is created automatically.

It will be a rare occurance when an application will call this routine. Usually, applications that create their own X windows will use rmxPipeGetVisual to obtain the X Visual that is compatible with OpenGL for use in creating an X window.

This routine may be removed in a future version of RM (January 2000).

librm library source file: rmx.c


 XVisualInfo * rmxPipeGetVisual (const RMpipe *toQuery)

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

Use this routine to obtain the handle of the XVisualInfo struct associated with an RMpipe object. This attribute will be valid only after the RMpipe has been initialized with rmPipeInit.

Upon success, returns the handle to an XVisualInfo structure, or NULL upon failure.

At this time (January 2000), no check is made to determine if the XVisualInfo structure inside the RMpipe is valid at the time when this routine is called.

librm library source file: rmx.c


 XVisualInfo * rmxVisualGetBest (Display *d)

 Display *d - a handle to an already opened X Display (input).

This routine obtains an X11 XVisualInfo (X visual) suitable for use with OpenGL, returning a handle to the caller. RM is conservative in it's request, asking first for a visual that is double buffered, has a depth buffer and RGB color planes. If that request fails, we fall back to a request for a single-buffered visual with a depth buffer and RGB color planes. Alpha color planes are not implemented on all platforms.

(need to try adding alpha planes back in and testing on current systems)

RM uses GL_RGBA color mode in OpenGL, and never uses the index-color model.

Returns a handle to the new XVisualInfo X11 struct to the caller upon success, or NULL upon failure.

librm library source file: rmx.c


 RMenum rmxPipeSetContext (RMpipe *toModify,
		           GLXContext context)

 RMpipe *toModify - a handle to an RMpipe object (modified).

 GLXContext context - a handle to a valid GLXContext (an OpenGL
    rendering context) (input).

Assigns an OpenGL rendering context (a GLXContext in the X11 world) to an RMpipe. The assignment does not make the context current (see rmUsePipe).

At this time (January 2000), the only RM routine that will create an OpenGL rendering context is rmPipeInit. When created, it is automatically assigned to the RMpipe. Therefore, it is expected that this routine will rarely be used by applications and may be removed in future releases. Also, this routine does not perform any validity checking on the input GLXContext.

Upon success, returns RM_CHILL, otherwise, returns RM_WHACKED.

librm library source file: rmx.c


 GLXContext rmxPipeGetContext (RMpipe *toQuery)

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

Returns the current GLXContext associated with an RMpipe object upon success. A value of zero is returned if there is a problem.

Note that the GLXContext returned by this routine is not necessarily "active" unless this call is made after the RMpipe is "made current" by using rmUsePipe.

librm library source file: rmx.c


 int rmPipeSetWindow (RMpipe *toUse,
		      Window w,
		      int windowWidth,
		      int windowHeight)

 RMpipe *toUse - a handle to an RMpipe object (input, but not const).

 Window w - a valid X window handle (input).

 int windowWidth, int windowHeight - integer values specifying the
    pixel width & height of the window "w".

Use this routine to "bind" an X11 Window to an RMpipe. When this routine is called, a number of things happen:

1. The RMpipe's notion of the window size is set (rmPipeSetWindowSize).

2. The GLXContext contained within the RMpipe is made current.

3. Final internal initialization within RM on the RMpipe's GLXContext is performed, readying both RM and OpenGL for use.

After this call succeeds, on X11 systems is is safe to begin making raw OpenGL calls. Note that things work a bit differently in Win32. See rmauxSetInitFunc().

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

This routine should be used by all applications to activate an OpenGL context and to bind a window to the RMpipe.

Note that there are no event callbacks associated with the RMpipe: when the window geometry changes (size, etc) it is the responsibility of the application to inform RM that the window geometry has changed (rmPipeSetWindowSize). There are separate versions of this routine for Win32 and X.

librm library source file: rmx.c


 Window rmPipeGetWindow (const RMpipe *toQuery)

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

Returns the window handle associated with an RMpipe object, or zero upon failure. Note there are separate versions of this routine for Win32 and X11.

librm library source file: rmx.c


 void rmSwapBuffers (RMpipe *p)

 RMpipe *p - a handle to an RMpipe (input).

This routine will cause a buffer-swap on the display and window specified by the input RMpipe.

In the interest of speed, no error checking is performed inside this routine.

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.

There are X11 and Win32 versions of rmSwapBuffers().

librm library source file: rmx.c