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 almost any X visual type and depth.
  22
  23 The glXChooseVisual function tries to choose the best X visual for the
  24 given attribute list. However, if this doesn't suit your needs you can
  25 force Mesa to use any X visual you want (any supported by your X server
  26 that is) by setting the **MESA_RGB_VISUAL** and **MESA_CI_VISUAL**
  27 environment variables. When an RGB visual is requested, glXChooseVisual
  28 will first look if the MESA_RGB_VISUAL variable is defined. If so, it
  29 will try to use the specified visual. Similarly, when a color index
  30 visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
  31 variable.
  32
  33 The format of accepted values is: ``visual-class depth``
  34
  35 Here are some examples:
  36
  37 ::
  38
  39    using csh:
  40        % setenv MESA_RGB_VISUAL "TrueColor 8"      // 8-bit TrueColor
  41        % setenv MESA_CI_VISUAL "PseudoColor 12"    // 12-bit PseudoColor
  42        % setenv MESA_RGB_VISUAL "PseudoColor 8"    // 8-bit PseudoColor
  43
  44    using bash:
  45        $ export MESA_RGB_VISUAL="TrueColor 8"
  46        $ export MESA_CI_VISUAL="PseudoColor 12"
  47        $ export MESA_RGB_VISUAL="PseudoColor 8"
  48
  49 Double Buffering
  50 ----------------
  51
  52 Mesa can use either an X Pixmap or XImage as the back color buffer when
  53 in double-buffer mode. The default is to use an XImage. The
  54 **MESA_BACK_BUFFER** environment variable can override this. The valid
  55 values for **MESA_BACK_BUFFER** are: **Pixmap** and **XImage** (only the
  56 first letter is checked, case doesn't matter).
  57
  58 Using XImage is almost always faster than a Pixmap since it resides in
  59 the application's address space. When glXSwapBuffers() is called,
  60 XPutImage() or XShmPutImage() is used to transfer the XImage to the
  61 on-screen window.
  62
  63 A Pixmap may be faster when doing remote rendering of a simple scene.
  64 Some OpenGL features will be very slow with a Pixmap (for example,
  65 blending will require a round-trip message for pixel readback.)
  66
  67 Experiment with the MESA_BACK_BUFFER variable to see which is faster for
  68 your application.
  69
  70 Colormaps
  71 ---------
  72
  73 When using Mesa directly or with GLX, it's up to the application writer
  74 to create a window with an appropriate colormap. The GLUT toolkit tries
  75 to minimize colormap *flashing* by sharing colormaps when possible.
  76 Specifically, if the visual and depth of the window matches that of the
  77 root window, the root window's colormap will be shared by the Mesa
  78 window. Otherwise, a new, private colormap will be allocated.
  79
  80 When sharing the root colormap, Mesa may be unable to allocate the
  81 colors it needs, resulting in poor color quality. This can happen when a
  82 large number of colorcells in the root colormap are already allocated.
  83 To prevent colormap sharing in GLUT, set the **MESA_PRIVATE_CMAP**
  84 environment variable. The value isn't significant.
  85
  86 Gamma Correction
  87 ----------------
  88
  89 To compensate for the nonlinear relationship between pixel values and
  90 displayed intensities, there is a gamma correction feature in Mesa. Some
  91 systems, such as Silicon Graphics, support gamma correction in hardware
  92 (man gamma) so you won't need to use Mesa's gamma facility. Other
  93 systems, however, may need gamma adjustment to produce images which look
  94 correct. If you believe that Mesa's images are too dim, read on.
  95
  96 Gamma correction is controlled with the **MESA_GAMMA** environment
  97 variable. Its value is of the form **Gr Gg Gb** or just **G** where Gr
  98 is the red gamma value, Gg is the green gamma value, Gb is the blue
  99 gamma value and G is one gamma value to use for all three channels. Each
 100 value is a positive real number typically in the range 1.0 to 2.5. The
 101 defaults are all 1.0, effectively disabling gamma correction. Examples:
 102
 103 ::
 104
 105    % export MESA_GAMMA="2.3 2.2 2.4"  // separate R,G,B values
 106    % export MESA_GAMMA="2.0"       // same gamma for R,G,B
 107
 108 The ``demos/gamma.c`` program in mesa/demos repository may help you to
 109 determine reasonable gamma value for your display. With correct gamma
 110 values, the color intensities displayed in the top row (drawn by
 111 dithering) should nearly match those in the bottom row (drawn as grays).
 112
 113 Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well on
 114 HP displays using the HP-ColorRecovery technology.
 115
 116 Mesa implements gamma correction with a lookup table which translates a
 117 "linear" pixel value to a gamma-corrected pixel value. There is a small
 118 performance penalty. Gamma correction only works in RGB mode. Also be
 119 aware that pixel values read back from the frame buffer will not be
 120 "un-corrected" so glReadPixels may not return the same data drawn with
 121 glDrawPixels.
 122
 123 For more information about gamma correction, see the `Wikipedia
 124 article <https://en.wikipedia.org/wiki/Gamma_correction>`__
 125
 126 Overlay Planes
 127 --------------
 128
 129 Hardware overlay planes are supported by the Xlib driver. To determine
 130 if your X server has overlay support you can test for the
 131 SERVER_OVERLAY_VISUALS property:
 132
 133 ::
 134
 135    xprop -root | grep SERVER_OVERLAY_VISUALS
 136
 137 HPCR Dithering
 138 --------------
 139
 140 If you set the **MESA_HPCR_CLEAR** environment variable then dithering
 141 will be used when clearing the color buffer. This is only applicable to
 142 HP systems with the HPCR (Color Recovery) feature. This incurs a small
 143 performance penalty.
 144
 145 Extensions
 146 ----------
 147
 148 The following Mesa-specific extensions are implemented in the Xlib
 149 driver.
 150
 151 GLX_MESA_pixmap_colormap
 152 ~~~~~~~~~~~~~~~~~~~~~~~~
 153
 154 This extension adds the GLX function:
 155
 156 ::
 157
 158    GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
 159                                      Pixmap pixmap, Colormap cmap )
 160
 161 It is an alternative to the standard glXCreateGLXPixmap() function.
 162 Since Mesa supports RGB rendering into any X visual, not just True-
 163 Color or DirectColor, Mesa needs colormap information to convert RGB
 164 values into pixel values. An X window carries this information but a
 165 pixmap does not. This function associates a colormap to a GLX pixmap.
 166 See the xdemos/glxpixmap.c file for an example of how to use this
 167 extension.
 168
 169 `GLX_MESA_pixmap_colormap
 170 specification <specs/MESA_pixmap_colormap.spec>`__
 171
 172 GLX_MESA_release_buffers
 173 ~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 Mesa associates a set of ancillary (depth, accumulation, stencil and
 176 alpha) buffers with each X window it draws into. These ancillary buffers
 177 are allocated for each X window the first time the X window is passed to
 178 glXMakeCurrent(). Mesa, however, can't detect when an X window has been
 179 destroyed in order to free the ancillary buffers.
 180
 181 The best it can do is to check for recently destroyed windows whenever
 182 the client calls the glXCreateContext() or glXDestroyContext()
 183 functions. This may not be sufficient in all situations though.
 184
 185 The GLX_MESA_release_buffers extension allows a client to explicitly
 186 deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just
 187 before an X window is destroyed. For example:
 188
 189 ::
 190
 191    #ifdef GLX_MESA_release_buffers
 192       glXReleaseBuffersMESA( dpy, window );
 193    #endif
 194    XDestroyWindow( dpy, window );
 195
 196 `GLX_MESA_release_buffers
 197 specification <specs/MESA_release_buffers.spec>`__
 198
 199 This extension was added in Mesa 2.0.
 200
 201 GLX_MESA_copy_sub_buffer
 202 ~~~~~~~~~~~~~~~~~~~~~~~~
 203
 204 This extension adds the glXCopySubBufferMESA() function. It works like
 205 glXSwapBuffers() but only copies a sub-region of the window instead of
 206 the whole window.
 207
 208 `GLX_MESA_copy_sub_buffer
 209 specification <specs/MESA_copy_sub_buffer.spec>`__
 210
 211 This extension was added in Mesa 2.6
 212
 213 Summary of X-related environment variables
 214 ------------------------------------------
 215
 216 ::
 217
 218    MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
 219    MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
 220    MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
 221    MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
 222    MESA_GAMMA - gamma correction coefficients (X only)