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