docs/xlibdriver.html

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