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