OpenRM - RM Library (rmx.c)

## Index of OpenRM - RM Library

     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

     RMenum rmPipeSetContext (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).

Use this routine to assign an X11 OpenGL rendering context to an RMpipe. Inside this routine, the input context "theContext" is copied into a field internal to the RMpipe object. This routine would be used, for example, to obtain an OpenGL context from your application (e.g., some FLTK infrastructure) and to tell OpenRM to use it for subsequent rendering.

Since this routine only makes a copy of the context, you need to "make it current" with a call to rmPipeMakeCurrent *after* you call rmPipeSetContext.

This routine will return RM_WHACKED if the input RMpipe is NULL. Otherwise, it returns RM_CHILL. No error checking is performed on the input X11 OpenGL context.

librm library source file: rmx.c

     GLXContext rmPipeGetContext (const RMpipe *toQuery)

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

Returns the current GLXContext associated with an RMpipe object upon success. A return 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 rmPipeMakeCurrent.

librm library source file: rmx.c

     RMenum rmPipeSetWindow (RMpipe *toUse,
    	  	         Window theWindow,
    			 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, the RMpipe's window attribute is set to the value specified by theWindow parameter, and the RMpipe's window pixel dimension attributes are set.

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.

To assign an offscreen rendering area to the RMpipe, use the routine rmPipeSetOffscreenWindow() rather than rmPipeSetWindow().

librm library source file: rmx.c

     int rmPipeSetOffscreenWindow (RMpipe *toUse,
    		               GLXPixmap glxp,
    		               int windowWidth,
    		               int windowHeight)

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

     GLXPixmap - a valid GLXPixmap handle (input).

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

Use this routine to "bind" an offscreen X11 rendering area, a GLXPixmap, 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 an offscreen rendering areaw 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.

To bind a displayable window to an RMpipe, use rmPipeSetWindow().

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

     RMenum rmPipeSwapBuffersX11 (RMpipe *p)

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

librm library source file: rmx.c

     RMenum rmxPipeCreateContext (RMpipe *toModify)

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

This routine will create a GLX OpenGL rendering context that matches the channel characteristics set in the RMpipe toModify. If successful, this routine returns RM_CHILL, and sets the RMpipe's context variable, along with the RMpipe's XVisual structure.

If unsucessful, RM_WHACKED is returned, and no modifications to the RMpipe will occur.

Failure can occur if (1) there is no GLX extension on the X Server; (2) the OpenGL implementation does not support the desired channel characteristics (e.g., if RM_MBUF_STEREO_CHANNEL is requested, but there is no stereo visual available).

This routine is invoked only from within rmauxCreateXWindow(). Applications that want to create their own windows will need to call this routine prior to creating windows in X, and then use rmxPipeGetVisual() to obtain the appropriate XVisual structure to use when creating a window.

librm library source file: rmx.c