docs/xlibdriver.html

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