third_party_mesa3d/docs/xlibdriver.rst

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.

The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
software-only drivers.

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.

Colormaps
---------

When using Mesa directly or with GLX, it's up to the application writer
to create a window with an appropriate colormap. The GLUT toolkit tries
to minimize colormap *flashing* by sharing colormaps when possible.
Specifically, if the visual and depth of the window matches that of the
root window, the root window's colormap will be shared by the Mesa
window. Otherwise, a new, private colormap will be allocated.

When sharing the root colormap, Mesa may be unable to allocate the
colors it needs, resulting in poor color quality. This can happen when a
large number of colorcells in the root colormap are already allocated.

Overlay Planes
--------------

Hardware overlay planes are supported by the Xlib driver. To determine
if your X server has overlay support you can test for the
SERVER_OVERLAY_VISUALS property:

.. code-block:: console

   xprop -root | grep SERVER_OVERLAY_VISUALS


Extensions
----------

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

GLX_MESA_pixmap_colormap
~~~~~~~~~~~~~~~~~~~~~~~~

This extension adds the GLX function:

.. code-block:: c

   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 <specs/MESA_pixmap_colormap.spec>`__

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:

.. code-block:: c

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

`GLX_MESA_release_buffers
specification <specs/MESA_release_buffers.spec>`__

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 <specs/MESA_copy_sub_buffer.spec>`__

This extension was added in Mesa 2.6

Summary of X-related environment variables
------------------------------------------

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