1. Introduction

This document presents information which will help to maximize OpenGL across different computer systems and within different configurations of similar systems.

2.1 Visuals

Mesa, however, may potentially return any X visual type for RGB mode. This is because some X displays on which Mesa may be used do not have TrueColor or DirectColor visuals. Mese prefers visual types in the order TrueColor, DirectColor, PseudoColor, StaticColor, GrayScale, and StaticGray and visuals depths from deepest to shallowest. There is one exception: 8-bit PseudoColor is preferred over 8-bit TrueColor. This is a convention many people prefer for low-end displays which use an 8-bit PseudoColor visual for the default and only have one hardware colormap.

Similarly, Mesa may return a PseudoColor, StaticColor, GrayScale or StaticGray visual if color index mode is requested.

Mesa violates the GLX specification but allows rendering on more types of displays than OpenGL would.

Dealing with Mesa's expanded offering of visuals is mostly just a matter of handling colormaps correctly.

2.2 Colormaps

2.2.1 RGB mode colormaps

The following algorithm should pick a good RGB colormap in most cases:

#include <X11/Xlib.h>
#include <X11/Xutil.h>
#include <X11/Xatom.h>  /* for XA_RGB_DEFAULT_MAP atom */
#if defined(__vms)
#include <X11/StdCmap.h>  /* for XmuLookupStandardColormap */
#else
#include <X11/Xmu/StdCmap.h>  /* for XmuLookupStandardColormap */
#endif
#include <GL/glx.h>
#include <string.h>

/*
 * Return an X colormap to use for OpenGL RGB-mode rendering.
 * Input:  dpy - the X display
 *         scrnum - the X screen number
 *         visinfo - the XVisualInfo as returned by glXChooseVisual()
 * Return:  an X Colormap or 0 if there's a _serious_ error.
 */
Colormap
get_rgb_colormap( Display *dpy, int scrnum, XVisualInfo *visinfo )
{
   Atom hp_cr_maps;
   Status status;
   int numCmaps;
   int i;
   XStandardColormap *standardCmaps;
   Window root = RootWindow(dpy,scrnum);
   int using_mesa;

   /*
    * First check if visinfo's visual matches the default/root visual.
    */
   if (visinfo->visual==DefaultVisual(dpy,scrnum)) {
      /* use the default/root colormap */
      return DefaultColormap( dpy, scrnum );
   }

   /*
    * Check if we're using Mesa.
    */
   if (strstr(glXQueryServerString( dpy, scrnum, GLX_VERSION ), "Mesa")) {
      using_mesa = 1;
   }
   else {
      using_mesa = 0;
   }

   /*
    * Next, if we're using Mesa and displaying on an HP with the "Color
    * Recovery" feature and the visual is 8-bit TrueColor, search for a
    * special colormap initialized for dithering.  Mesa will know how to
    * dither using this colormap.
    */
   if (using_mesa) {
      hp_cr_maps = XInternAtom( dpy, "_HP_RGB_SMOOTH_MAP_LIST", True );
      if (hp_cr_maps
	  && visinfo->visual->class==TrueColor
	  && visinfo->depth==8) {
	 status = XGetRGBColormaps( dpy, root, &standardCmaps,
				    &numCmaps, hp_cr_maps );
	 if (status) {
	    for (i=0; i < numCmaps; i++) {
	       if (standardCmaps[i].visualid==visinfo->visual->visualid) {
		  Colormap cmap = standardCmaps[i].colormap;
                  XFree(standardCmaps);
                  return cmap;
	       }
	    }
            XFree(standardCmaps);
	 }
      }
   }

   /*
    * Next, try to find a standard X colormap.
    */
#ifndef SOLARIS_BUG
   status = XmuLookupStandardColormap( dpy, visinfo->screen,
                                       visinfo->visualid,
                                       visinfo->depth,
				       XA_RGB_DEFAULT_MAP,
				       /* replace */ False,
                                       /* retain */ True);
   if (status == 1) {
      status = XGetRGBColormaps( dpy, root, &standardCmaps,
				 &numCmaps, XA_RGB_DEFAULT_MAP);
      if (status == 1) {
         for (i = 0; i < numCmaps; i++) {
	    if (standardCmaps[i].visualid == visinfo->visualid) {
               Colormap cmap = standardCmaps[i].colormap;
	       XFree(standardCmaps);
	       return cmap;
	    }
	 }
         XFree(standardCmaps);
      }
   }
#endif

   /*
    * If we get here, give up and just allocate a new colormap.
    */
   return XCreateColormap( dpy, root, visinfo->visual, AllocNone );
}

Basically, we use the default colormap if the visuals match. Otherwise we look for a standard colormap. If that fails we must allocate a new, private colormap. If using Mesa on an 8-bit TrueColor HP display then we look for a special "Color Recovery" colormap which helps to produce high-quality dithered images.

Caveat: this algorithm may not work on Sun systems due to a bug in the XmuLookupStandardColormap function.

Finally, if one intends to render into several different window with the same RGB context those window should share the same colormap. This is required with Mesa and helps to reduce colormap flashing with OpenGL.

2.2.2 Color index mode colormaps

Otherwise, if your GLX visual type and depth matches the default/root visual then you can probably use the default/root colormap. To allocate a read/write colorcell from the colormap use XAllocColorCells. To allocate read-only cells use XAllocColor. In both cases, X will return to you the index of a colorcell.

If XAllocColor fails then you may have to search the colormap for a close match. The following function will search a colormap for the closest match to your requested color:

#include <X11/Xlib.h>
#include <stdlib.h>

/* A replacement for XAllocColor.
 * This  function should never fail to allocate a color.  When
 * XAllocColor fails, we return the nearest matching color.  If
 * we have to allocate many colors this function isn't a great
 * solution; the XQueryColors() could be done just once.
 */
static void
noFaultXAllocColor(Display * dpy, Colormap cmap, int cmapSize, XColor * color)
{
    XColor *ctable, subColor;
    int i, bestmatch;
    double mindist;       /* 3*2^16^2 exceeds long int precision. */

    /* First try just using XAllocColor. */
    if (XAllocColor(dpy, cmap, color))
        return;

    /* Retrieve color table entries. */
    /* XXX alloca canidate. */
    ctable = (XColor *) malloc(cmapSize * sizeof(XColor));
    for (i = 0; i < cmapSize; i++)
      ctable[i].pixel = i;
    XQueryColors(dpy, cmap, ctable, cmapSize);

    /* Find best match. */
    bestmatch = -1;
    mindist = 0.0;
    for (i = 0; i < cmapSize; i++) {
        double dr = (double) color->red - (double) ctable[i].red;
        double dg = (double) color->green - (double) ctable[i].green;
        double db = (double) color->blue - (double) ctable[i].blue;
        double dist = dr * dr + dg * dg + db * db;
        if (bestmatch < 0 || dist < mindist) {
          bestmatch = i;
          mindist = dist;
        }
    }

    /* Return result. */
    subColor.red = ctable[bestmatch].red;
    subColor.green = ctable[bestmatch].green;
    subColor.blue = ctable[bestmatch].blue;
    free(ctable);
    if (!XAllocColor(dpy, cmap, &subColor)) {
      subColor.pixel = (unsigned long) bestmatch;
   }
   *color = subColor;
}

If your application needs several color index mode windows it's a good idea to try to share one colormap among the windows. Finally, be sure that glXChooseVisual returns a PseudoColor (or for Mesa, GrayScale) visual if a writable colormap is needed.

After the colormap has been selected you can create your window, specifying the colormap in the XSetWindowAttributes structure passed to XCreateWindow.

Furthermore, you should inform the window manager if your top-level window contains children with non-default colormaps. This is done with the XSetWMColormapWindows function:

    XSetWMColormapWindows( display, top_level_window,
                           &window_list, num );

2.3 Double buffering

Be aware that many systems advertised as having 24-bit color, in fact, only offer 12-bit color in double buffer mode. This is because the 24-bit frame buffer is divided into two 12-bit buffers. Dithering may become evident in this situation.

What if you would like both double buffering and full 24-bit color? For example, during animation one may want double buffering but to show a static image a full-color single buffered window would look best.

IRIS GL allowed one to reconfigure a window to single or double buffering on the fly with doublebuffer, singlebuffer and gconfig. This can't be done with OpenGL. Instead, you can create two subwindows contained by a common parent, one window single buffered and the other window double buffered, and use XMapWidnow/XUnmapWindow to display the one you want to use. Remember to use separate contexts for each window since they will have different visuals.

2.4 Alpha planes

2.5 GLX Pixmaps

The usual steps in creating and using a GLX pixmap are:

• Select a visual with glXChooseVisual
• Create an X pixmap with XCreatePixmap using the depth of the visual returned by glXChooseVisual
• Create the GLX pixmap from the X pixmap with glXCreateGLXPixmap.
• Create an OpenGL rendering context with glXCreateContext, usually specifying the indirect option.
• Bind the context to the GLX pixmap with glXMakeCurrent

• Since one often wants to render into a GLX pixmap and later copy it to an on-screen window, the X window should have the same depth as the pixmap.
• If one wants to use one context for both GLX pixmap rendering and rendering into a window, the GLX pixmap and window must be created with the same XVisualInfo.
• Direct rendering contexts are usually not supported for pixmap rendering. The only way to determine if direct rendering into GLX pixmaps works is to create a direct context then test if glXMakeCurrent succeeds.

Mesa (version 1.2.8 and later) has a GLX extension which lets the user specify the colormap associated with a GLX pixmap. The extension provides a new function very similar to glXCreateGLXPixmap:

GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
                                  Pixmap pixmap, Colormap cmap )

The proper way to use this function is:

    Pixmap p;
    GLXPixmap q;
    ...
    #ifdef GLX_MESA_pixmap_colormap
        q = glXCreateGLXPixmapMESA( display, visual, p, colormap );
    #else
        q = glXCreateGLXPixmap( display, visual, p );
    #endif

Why would we want to do this? One, we may want our application to work on both X and Windows platforms. Two, we may want to support both OpenGL and IRIS GL (or PEX) during a transition period.

The basics:

• isolate window system-dependent code (including GLX, GLW code) in separate modules.
• isolate OpenGL code, and other graphics library code, in separate modules

• Create user interface
• Setup callback functions
• Enter event loop

On the other hand, a complex application may be so tightly integrated with a user interface toolkit or graphics library that it's impractical to support alternative interfaces or libraries.

3.1 An example: Vis5D

OpenGL, IRIS GL and PEX code is isolated into separate source files:

• graphics.ogl.c
• graphics.gl.c
• graphics.pex.c

• create_3d_window()
• clear_3d_window()
• swap_3d_window()
• draw_isosurface()
• draw_trajectory()
• draw_contour_slice()

The core of Vis5Ds functionality is isolated from the user interface by an internal API. Everything "below" the API is GUI independent. Everything "above" the API is considered user interface code. While Vis5D's user interface code is substantial, it could be replaced by an alternative toolkit with minimal impact on the rest of the system.

3.2 Graphics library functionality

The simplest solution to this problem is to only use functionality which is common to all libraries. This can actually be quite practical in simple applications which don't require elaborate renderering techniques.

The other solution is to poll the graphics system to determine its capabilities and work around those it doesn't support. Vis5D, for example, offers volume rendering only on systems with alpha blending capability.

3.3 Multi- window system applications

A small application using GLUT or Tcl/Tk is potentially portable to many systems because GLUT and Tcl/Tk are available on most platforms.

Larger applications which use native window system toolkits will have to be partitioned into modules which isolate window and operating system- specific code.

The OpenGL window system interface call should be considered window system code and not be put in the OpenGL modules. This includes the swapbuffers operation.

• To take advantage of new graphics hardware
• To keep up with evolving operating systems
• To broaden the range of system supported

4.1 PEX to OpenGL

Here are the highlights of PEX vs OpenGL and porting:

• PEX is more of a protocol specification than API specification. That is, there are several interfaces to PEX functionality. OpenGL on the other hand, is defined in terms of an API and not a protocol.

• Since PEX relies on the same Xlib window management and event handling code as OpenGL for X (GLX), much of the user interface code may be quite portable.

• PEX's data structures for describing geometry are of coarse granularity while OpenGL geometry is described in in fine granularity. That is, the data structures for PEX can be easily rendered by OpenGL since OpenGL specifies primitives a vertex at a time rather than as large arrays or structures.

  One may be able to continue using PEX-style data structures in your application and render them using OpenGL commands.

• PEX's notion of attribute "bundles" can be replaced with OpenGL display lists.

• The problem of dealing with PEX subsetting largly disappears with since the OpenGL specification mandates full implementation.

• A PEX application which uses multiple rendering contexts may be especially difficult to port to OpenGL since most PEX API functions explicitly specify the context while in OpenGL the context is implicit. Context switching in OpenGL may be considerably more expensive than it is with PEX.

• PEX has a lot of support for fonts and text drawing which may be difficult to translate to OpenGL.

• PEX has several primitive such as quadrilateral meshes which aren't directly offered by OpenGL but can be implemented without too much trouble.

• PEX supports editable display lists while OpenGL doesn't. Nested OpenGL display lists may be a suitable work around.

• Though PEX and GLX both are built on Xlib, visual selection and window creation code will have to be reimplemented for OpenGL.

4.2 IRIS GL to OpenGL