SIGGRAPH '97

Course 24: OpenGL and Window System Integration

OpenGL/Mesa Off-screen Rendering

Contents

• 1. Introduction
• 2. Microsoft OpenGL Off-Screen Rendering
• 3. GLX Pixmaps
• 4. SGI pbuffers
• 5. Aux Buffers
• 6. Mesa
• 7. Tiled Rendering

1. Introduction

Some uses of off-screen rendering include:

• Generation of intermediate images such as textures
• Batch rendering of non-interactive animations
• High-resolution image generation for hardcopy

Generaly, off-screen rendering is not a core part of OpenGL; it's provided by an OpenGL window system interface such as GLX or WGL. Some systems have more than one facility for off-screen rendering, each with its own advantages and disadvantages.

The following sections describe the off-screen rendering facilities for WGL, GLX and Mesa with an emphasis on portablity and performance trade-offs.

2. Microsoft OpenGL Off-Screen Rendering

Pros:

• A standard WGL feature

• Only usable with Windows 95/NT OpenGL

3. GLX Pixmaps

Pros:

• Buffer contents are retained; cannot be damaged like on-screen windows
• GLX pixmaps are a standard part of GLX
• GLX pixmaps can sometimes be larger than an on-screen window

• Rendering into GLX pixmaps may not be accelerated with graphics hardware and, in fact, may be rather slow
• Size may be limited to the screen's size
• Connection to X server is required even though rendering is off-screen

1. Call XOpenDisplay to open an X display connection.
2. Select an X visual with glXChooseVisual.
3. Create an X pixmap with XCreatePixmap specifying the depth of the X visual.
4. Create the GLX pixmap with glXCreateGLXPixmap.

The contents of a GLX pixmap may be read back with glReadPixels or XGetImage.

4. SGI pbuffers

Pros:

• Hardware accelerated
• May offer pixel formats not available for ordinary windows

• Currently only available on recent SGI systems
• May require special X server configuration
• pbuffers contents may be arbitrarily lost at any time
• Connection to X server is required even though rendering is off-screen
• More difficult to use than GLX pixmaps
• Maximum size may be contrained to screen size

With that in mind let us consider pbuffers in more detail.

The pbuffers extension name is GLX_SGIX_pbuffers. Prerequisite to the pbuffers extension is the exerimental fbconfig extension (GLX_SGIX_fbconfig).

The fbconfig extension was introduced for several reasons:

• It introduces a new way to describe the capabilities of a GLX drawable, that is, to describe the resolution of color buffer components and the type and size of ancillary buffers by providing a GLXFBConfig construct.
• It relaxes the "similarity" requirement when associating a current context with a drawable.
• It supports RGBA rendering to one- and two-component windows and GLX pixmaps as well as pbuffers.

Pbuffer applications must test for both the GLX_SGIX_pbuffers and GLX_SGIX_fbconfig extensions. See the Using OpenGL Extensions document for details on extension testing. If either extension is not available the application should fall back to using GLX pixmaps.

The basic steps for creating a pbuffer are:

1. Call XOpenDisplay to open an X display connection.
2. Get a GLXFBConfigSGIX handle by calling glXChooseFBConfigSGIX
3. Create a pbuffer by calling glXCreateGLXPbuffer

• glXChooseFBConfigSGIX returns a sorted list of fbconfigs which match your attribute list. However, some or all of the fbconfigs may not be usable for making a pbuffer.
• The glXCreateGLXPbuffer call may fail, generating an X protocol error. You must set up an X error handler to catch this error so your program doesn't exit abnormally.
• You may have to try several different fbconfig attribute lists before you're able to find one which works.

As an example, suppose you need a single-buffered RGB pbuffer with a depth buffer. glXChooseFBConfigSGIX may return a list of several fbconfig candidates. However, there may not be enough memory available in the frame buffer for some or any of those fbconfigs. There may be enough memory for the color buffer but not the depth buffer, for example. Or, it may not be possible to allocate a single buffered pbuffer; only double buffered pbuffers may exist.

The best approach is a nested loop:

    let fbAttribs = list of fbconfig attribute lists
    foreach fbAttrib in fbAttribs do
        let fbConfigs = list returned by glXChooseFBConfigSGIX(fbAttrib)
        foreach fbConfig in fbConfigs do
	    let pBuffer = glXCreateGLXPbufferSGIX(fbConfig)
            if pBuffer then
                SUCCESS!
            endif
        endfor
    endfor

The pbutil.c file contains several pbuffer utility functions. The CreatePbuffer handles the X protocol error problem.

The pbinfo.c program is similar to glxinfo. It prints a list of fbconfigs available on your system and whether or not a pbuffer of that config can be created.

System Configuration

On SGI Impact systems, for example, if you look in the /usr/gfx/ucode/MGRAS/vof/ directory you will find a list of video output formats supported by the Impact architecture. Look for ones with the _pbuf suffix. Use the setmon -x utility to configure your X server to use a pbuffer-enabled video format.

5. Auxiliary Buffers

Pros:

• A simple off-screen facility standard to OpenGL.

• Aux buffers are optional and few implementations of OpenGL support them.

6. Mesa

Pros:

• No window system or operating system dependencies

• Only available in Mesa
• Probably no chance of hardware accelerated rendering

7. Tiled Rendering

OpenGL and/or window systems limit the size of rendered imagery in several ways:

• The window system may not allow one to create windows, pixmaps or pbuffers which larger than the screen's size. Typical limits are 1280 by 1024 pixels.
• glViewport's width and height parameters are silently clamped to an implementation-dependant limit. These limits can be queried via glGetIntegerv with the argument GL_MAX_VIEWPORT_DIMS. Typical limits are 2048 by 2048 pixels.

Here is a modified excerpt of the trdemo1.c example program which demonstrates how to use the tr (tile rendering) library:

static void Display(void)
{
   GLubyte *image;
   TRcontext *tr;

   /* allocate final image buffer */
   image = malloc(WindowWidth * WindowHeight * 4 * sizeof(GLubyte));
   if (!image) {
      printf("Malloc failed!\n");
      return;
   }

   /* Setup tiled rendering.  Each tile is TILESIZE x TILESIZE pixels. */
   tr = trNew();
   trTileSize(tr, TILESIZE, TILESIZE);
   trImageSize(tr, WindowWidth, WindowHeight);
   trImageBuffer(tr, GL_RGBA, GL_UNSIGNED_BYTE, image);
 	   
   if (Perspective)
      trFrustum(tr, -1.0, 1.0, -1.0, 1.0, 5.0, 25.0);
   else
      trOrtho(tr, -3.0, 3.0, -3.0, 3.0, -3.0, 3.0);

   /* Draw tiles */
   do {
      trBeginTile(tr);
      DrawScene();
   } while (trEndTile(tr));

   trDelete(tr);

   /* 'image' buffer now contains the final image.
    * You could now print it, write it to a file, etc.
    */
}

1. Allocate memory for the final image.
2. Create a tile rendering context with trNew.
3. Call trTileSize to specify the tile size.
4. Call trImageSize to specify the final image size.
5. Call trImageBuffer to specify where the final image is to be stored.
6. Setup a perspective or orthographic projection with trFrustum or trOrtho.
7. Call the trBeginTile and trEndTile functions inside a loop which surrounds your scene drawing function until trEndTile returns zero.
8. Free the tile rendering context with trDelete.

There is one caveat to this utility library: glRasterPos, glDrawPixels and glBitmap may be troublesome. The problem is that if glRasterPos specifies a coordinate which falls outside the current viewport, the current raster position becomes invalid. If the current raster position is invalid subsequent calls to glDrawPixels or glBitmap will have no consequence.

The solution to this problem is the trRasterPos3f function. It works just like glRasterPos3f but doesn't suffer from the invalid raster position problem. See the trdemo1.c program for example usage.

The trdemo2.c example demonstrates how to generate very large image files without allocating a full-size image buffer.