docs/xlibdriver.rst

   1 Xlib Software Driver
   2 ====================
   3
   4 Mesa's Xlib driver provides an emulation of the GLX interface so that
   5 OpenGL programs which use the GLX API can render to any X display, even
   6 those that don't support the GLX extension. Effectively, the Xlib driver
   7 converts all OpenGL rendering into Xlib calls.
   8
   9 The Xlib driver is the oldest Mesa driver and the most mature of Mesa's
  10 software-only drivers.
  11
  12 Since the Xlib driver *emulates* the GLX extension, it's not totally
  13 conformant with a true GLX implementation. The differences are fairly
  14 obscure, however.
  15
  16 The unique features of the Xlib driver follows.
  17
  18 X Visual Selection
  19 ------------------
  20
  21 Mesa supports RGB(A) rendering into TrueColor and DirectColor visuals, for
  22 any depth with a corresponding renderable OpenGL texture format.
  23
  24 The glXChooseVisual function tries to choose the best X visual for the
  25 given attribute list. However, if this doesn't suit your needs you can
  26 force Mesa to use any X visual you want (any supported by your X server
  27 that is) by setting the **MESA_RGB_VISUAL** environment variable. When
  28 a visual is requested, glXChooseVisual will first look if the
  29 MESA_RGB_VISUAL variable is defined. If so, it will try to use the
  30 specified visual.
  31
  32 The format of accepted values is: ``visual-class depth``
  33
  34 Here are some examples:
  35
  36 ::
  37
  38    using csh:
  39        % setenv MESA_RGB_VISUAL "TrueColor 8"      // 8-bit TrueColor
  40        % setenv MESA_RGB_VISUAL "DirectColor 30"   // 30-bit DirectColor
  41
  42    using bash:
  43        $ export MESA_RGB_VISUAL="TrueColor 8"
  44        $ export MESA_RGB_VISUAL="DirectColor 30"
  45
  46 Double Buffering
  47 ----------------
  48
  49 Mesa can use either an X Pixmap or XImage as the back color buffer when
  50 in double-buffer mode. The default is to use an XImage. The
  51 **MESA_BACK_BUFFER** environment variable can override this. The valid
  52 values for **MESA_BACK_BUFFER** are: **Pixmap** and **XImage** (only the
  53 first letter is checked, case doesn't matter).
  54
  55 Using XImage is almost always faster than a Pixmap since it resides in
  56 the application's address space. When glXSwapBuffers() is called,
  57 XPutImage() or XShmPutImage() is used to transfer the XImage to the
  58 on-screen window.
  59
  60 A Pixmap may be faster when doing remote rendering of a simple scene.
  61 Some OpenGL features will be very slow with a Pixmap (for example,
  62 blending will require a round-trip message for pixel readback.)
  63
  64 Experiment with the MESA_BACK_BUFFER variable to see which is faster for
  65 your application.
  66
  67 Colormaps
  68 ---------
  69
  70 When using Mesa directly or with GLX, it's up to the application writer
  71 to create a window with an appropriate colormap. The GLUT toolkit tries
  72 to minimize colormap *flashing* by sharing colormaps when possible.
  73 Specifically, if the visual and depth of the window matches that of the
  74 root window, the root window's colormap will be shared by the Mesa
  75 window. Otherwise, a new, private colormap will be allocated.
  76
  77 When sharing the root colormap, Mesa may be unable to allocate the
  78 colors it needs, resulting in poor color quality. This can happen when a
  79 large number of colorcells in the root colormap are already allocated.
  80
  81 Overlay Planes
  82 --------------
  83
  84 Hardware overlay planes are supported by the Xlib driver. To determine
  85 if your X server has overlay support you can test for the
  86 SERVER_OVERLAY_VISUALS property:
  87
  88 .. code-block:: console
  89
  90    xprop -root | grep SERVER_OVERLAY_VISUALS
  91
  92
  93 Extensions
  94 ----------
  95
  96 The following Mesa-specific extensions are implemented in the Xlib
  97 driver.
  98
  99 GLX_MESA_pixmap_colormap
 100 ~~~~~~~~~~~~~~~~~~~~~~~~
 101
 102 This extension adds the GLX function:
 103
 104 .. code-block:: c
 105
 106    GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
 107                                      Pixmap pixmap, Colormap cmap )
 108
 109 It is an alternative to the standard glXCreateGLXPixmap() function.
 110 Since Mesa supports RGB rendering into any X visual, not just True-
 111 Color or DirectColor, Mesa needs colormap information to convert RGB
 112 values into pixel values. An X window carries this information but a
 113 pixmap does not. This function associates a colormap to a GLX pixmap.
 114 See the xdemos/glxpixmap.c file for an example of how to use this
 115 extension.
 116
 117 `GLX_MESA_pixmap_colormap
 118 specification <specs/MESA_pixmap_colormap.spec>`__
 119
 120 GLX_MESA_release_buffers
 121 ~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 Mesa associates a set of ancillary (depth, accumulation, stencil and
 124 alpha) buffers with each X window it draws into. These ancillary buffers
 125 are allocated for each X window the first time the X window is passed to
 126 glXMakeCurrent(). Mesa, however, can't detect when an X window has been
 127 destroyed in order to free the ancillary buffers.
 128
 129 The best it can do is to check for recently destroyed windows whenever
 130 the client calls the glXCreateContext() or glXDestroyContext()
 131 functions. This may not be sufficient in all situations though.
 132
 133 The GLX_MESA_release_buffers extension allows a client to explicitly
 134 deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just
 135 before an X window is destroyed. For example:
 136
 137 .. code-block:: c
 138
 139    #ifdef GLX_MESA_release_buffers
 140       glXReleaseBuffersMESA( dpy, window );
 141    #endif
 142    XDestroyWindow( dpy, window );
 143
 144 `GLX_MESA_release_buffers
 145 specification <specs/MESA_release_buffers.spec>`__
 146
 147 This extension was added in Mesa 2.0.
 148
 149 GLX_MESA_copy_sub_buffer
 150 ~~~~~~~~~~~~~~~~~~~~~~~~
 151
 152 This extension adds the glXCopySubBufferMESA() function. It works like
 153 glXSwapBuffers() but only copies a sub-region of the window instead of
 154 the whole window.
 155
 156 `GLX_MESA_copy_sub_buffer
 157 specification <specs/MESA_copy_sub_buffer.spec>`__
 158
 159 This extension was added in Mesa 2.6
 160
 161 Summary of X-related environment variables
 162 ------------------------------------------
 163
 164 +-----------------------------+--------------------------------------+
 165 | Environment variable        | Description                          |
 166 +=============================+======================================+
 167 | :envvar:`MESA_RGB_VISUAL`   | specifies the X visual and depth for |
 168 |                             | RGB mode (X only)                    |
 169 +-----------------------------+--------------------------------------+
 170 | :envvar:`MESA_BACK_BUFFER`  | specifies how to implement the back  |
 171 |                             | color buffer (X only)                |
 172 +-----------------------------+--------------------------------------+