Xlib Software Driver — The Mesa 3D Graphics Library latest documentation

# Xlib Software Driver

Mesa’s Xlib driver provides an emulation of the GLX interface so that OpenGL programs which use the GLX API can render to any X display, even those that don’t support the GLX extension. Effectively, the Xlib driver converts all OpenGL rendering into Xlib calls.

Since the Xlib driver emulates the GLX extension, it’s not totally conformant with a true GLX implementation. The differences are fairly obscure, however.

The unique features of the Xlib driver follows.

## X Visual Selection

Mesa supports RGB(A) rendering into TrueColor and DirectColor visuals, for any depth with a corresponding renderable OpenGL texture format.

The glXChooseVisual function tries to choose the best X visual for the given attribute list. However, if this doesn’t suit your needs you can force Mesa to use any X visual you want (any supported by your X server that is) by setting the MESA_RGB_VISUAL environment variable. When a visual is requested, glXChooseVisual will first look if the MESA_RGB_VISUAL variable is defined. If so, it will try to use the specified visual.

The format of accepted values is: `visual-class depth`

Here are some examples:

    using csh:
        % setenv MESA_RGB_VISUAL "TrueColor 8"      // 8-bit TrueColor
        % setenv MESA_RGB_VISUAL "DirectColor 30"   // 30-bit DirectColor

    using bash:
        $ export MESA_RGB_VISUAL="TrueColor 8"
        $ export MESA_RGB_VISUAL="DirectColor 30"

## Double Buffering

Mesa can use either an X Pixmap or XImage as the back color buffer when in double-buffer mode. The default is to use an XImage. The MESA_BACK_BUFFER environment variable can override this. The valid values for MESA_BACK_BUFFER are: Pixmap and XImage (only the first letter is checked, case doesn’t matter).

Using XImage is almost always faster than a Pixmap since it resides in the application’s address space. When glXSwapBuffers() is called, XPutImage() or XShmPutImage() is used to transfer the XImage to the on-screen window.

A Pixmap may be faster when doing remote rendering of a simple scene. Some OpenGL features will be very slow with a Pixmap (for example, blending will require a round-trip message for pixel readback.)

Experiment with the MESA_BACK_BUFFER variable to see which is faster for your application.

## Extensions

The following Mesa-specific extensions are implemented in the Xlib driver.

### GLX_MESA_pixmap_colormap

This extension adds the GLX function:

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

It is an alternative to the standard glXCreateGLXPixmap() function. Since Mesa supports RGB rendering into any X visual, not just True- Color or DirectColor, Mesa needs colormap information to convert RGB values into pixel values. An X window carries this information but a pixmap does not. This function associates a colormap to a GLX pixmap. See the xdemos/glxpixmap.c file for an example of how to use this extension.

GLX_MESA_pixmap_colormap specification

### GLX_MESA_release_buffers

Mesa associates a set of ancillary (depth, accumulation, stencil and alpha) buffers with each X window it draws into. These ancillary buffers are allocated for each X window the first time the X window is passed to glXMakeCurrent(). Mesa, however, can’t detect when an X window has been destroyed in order to free the ancillary buffers.

The best it can do is to check for recently destroyed windows whenever the client calls the glXCreateContext() or glXDestroyContext() functions. This may not be sufficient in all situations though.

The GLX_MESA_release_buffers extension allows a client to explicitly deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just before an X window is destroyed. For example:

    #ifdef GLX_MESA_release_buffers
       glXReleaseBuffersMESA( dpy, window );
    #endif
    XDestroyWindow( dpy, window );

GLX_MESA_release_buffers specification

This extension was added in Mesa 2.0.

### GLX_MESA_copy_sub_buffer

This extension adds the glXCopySubBufferMESA() function. It works like glXSwapBuffers() but only copies a sub-region of the window instead of the whole window.

GLX_MESA_copy_sub_buffer specification

This extension was added in Mesa 2.6

## Summary of X-related environment variables

Environment variable | Description
--- | ---
`MESA_RGB_VISUAL` | specifies the X visual and depth for RGB mode (X only)
`MESA_BACK_BUFFER` | specifies how to implement the back color buffer (X only)