xlibdriver.html revision 848b8605
1848b8605Smrg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2848b8605Smrg<html lang="en"> 3848b8605Smrg<head> 4848b8605Smrg <meta http-equiv="content-type" content="text/html; charset=utf-8"> 5848b8605Smrg <title>Xlib Software Driver</title> 6848b8605Smrg <link rel="stylesheet" type="text/css" href="mesa.css"> 7848b8605Smrg</head> 8848b8605Smrg<body> 9848b8605Smrg 10848b8605Smrg<div class="header"> 11848b8605Smrg <h1>The Mesa 3D Graphics Library</h1> 12848b8605Smrg</div> 13848b8605Smrg 14848b8605Smrg<iframe src="contents.html"></iframe> 15848b8605Smrg<div class="content"> 16848b8605Smrg 17848b8605Smrg<h1>Xlib Software Driver</h1> 18848b8605Smrg 19848b8605Smrg<p> 20848b8605SmrgMesa's Xlib driver provides an emulation of the GLX interface so that 21848b8605SmrgOpenGL programs which use the GLX API can render to any X display, even 22848b8605Smrgthose that don't support the GLX extension. 23848b8605SmrgEffectively, the Xlib driver converts all OpenGL rendering into Xlib calls. 24848b8605Smrg</p> 25848b8605Smrg 26848b8605Smrg<p> 27848b8605SmrgThe Xlib driver is the oldest Mesa driver and the most mature of Mesa's 28848b8605Smrgsoftware-only drivers. 29848b8605Smrg</p> 30848b8605Smrg 31848b8605Smrg<p> 32848b8605SmrgSince the Xlib driver <em>emulates</em> the GLX extension, it's not 33848b8605Smrgtotally conformant with a true GLX implementation. 34848b8605SmrgThe differences are fairly obscure, however. 35848b8605Smrg</p> 36848b8605Smrg 37848b8605Smrg<p> 38848b8605SmrgThe unique features of the Xlib driver follows. 39848b8605Smrg</p> 40848b8605Smrg 41848b8605Smrg 42848b8605Smrg<h2>X Visual Selection</h2> 43848b8605Smrg<p> 44848b8605SmrgMesa supports RGB(A) rendering into almost any X visual type and depth. 45848b8605Smrg</p> 46848b8605Smrg<p> 47848b8605SmrgThe glXChooseVisual function tries to choose the best X visual 48848b8605Smrgfor the given attribute list. However, if this doesn't suit your needs 49848b8605Smrgyou can force Mesa to use any X visual you want (any supported by your 50848b8605SmrgX server that is) by setting the <b>MESA_RGB_VISUAL</b> and 51848b8605Smrg<b>MESA_CI_VISUAL</b> 52848b8605Smrgenvironment variables. 53848b8605SmrgWhen an RGB visual is requested, glXChooseVisual 54848b8605Smrgwill first look if the MESA_RGB_VISUAL variable is defined. 55848b8605SmrgIf so, it will try to use the specified visual. 56848b8605SmrgSimilarly, when a color index visual is requested, glXChooseVisual will 57848b8605Smrglook for the MESA_CI_VISUAL variable. 58848b8605Smrg</p> 59848b8605Smrg 60848b8605Smrg<p> 61848b8605SmrgThe format of accepted values is: <code>visual-class depth</code> 62848b8605Smrg</p> 63848b8605Smrg<p> 64848b8605SmrgHere are some examples: 65848b8605Smrg</p> 66848b8605Smrg<pre> 67848b8605Smrg using csh: 68848b8605Smrg % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor 69848b8605Smrg % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor 70848b8605Smrg % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor 71848b8605Smrg 72848b8605Smrg using bash: 73848b8605Smrg $ export MESA_RGB_VISUAL="TrueColor 8" 74848b8605Smrg $ export MESA_CI_VISUAL="PseudoColor 12" 75848b8605Smrg $ export MESA_RGB_VISUAL="PseudoColor 8" 76848b8605Smrg</pre> 77848b8605Smrg 78848b8605Smrg 79848b8605Smrg<h2>Double Buffering</h2> 80848b8605Smrg<p> 81848b8605SmrgMesa can use either an X Pixmap or XImage as the back color buffer when in 82848b8605Smrgdouble-buffer mode. 83848b8605SmrgThe default is to use an XImage. 84848b8605SmrgThe <b>MESA_BACK_BUFFER</b> environment variable can override this. 85848b8605SmrgThe valid values for <b>MESA_BACK_BUFFER</b> are: <b>Pixmap</b> and 86848b8605Smrg<b>XImage</b> (only the first letter is checked, case doesn't matter). 87848b8605Smrg</p> 88848b8605Smrg 89848b8605Smrg<p> 90848b8605SmrgUsing XImage is almost always faster than a Pixmap since it resides in 91848b8605Smrgthe application's address space. 92848b8605SmrgWhen glXSwapBuffers() is called, XPutImage() or XShmPutImage() is used 93848b8605Smrgto transfer the XImage to the on-screen window. 94848b8605Smrg</p> 95848b8605Smrg<p> 96848b8605SmrgA Pixmap may be faster when doing remote rendering of a simple scene. 97848b8605SmrgSome OpenGL features will be very slow with a Pixmap (for example, blending 98848b8605Smrgwill require a round-trip message for pixel readback.) 99848b8605Smrg</p> 100848b8605Smrg<p> 101848b8605SmrgExperiment with the MESA_BACK_BUFFER variable to see which is faster 102848b8605Smrgfor your application. 103848b8605Smrg</p> 104848b8605Smrg 105848b8605Smrg 106848b8605Smrg<h2>Colormaps</h2> 107848b8605Smrg<p> 108848b8605SmrgWhen using Mesa directly or with GLX, it's up to the application 109848b8605Smrgwriter to create a window with an appropriate colormap. The GLUT 110848b8605Smrgtoolkit tries to minimize colormap <em>flashing</em> by sharing 111848b8605Smrgcolormaps when possible. Specifically, if the visual and depth of the 112848b8605Smrgwindow matches that of the root window, the root window's colormap 113848b8605Smrgwill be shared by the Mesa window. Otherwise, a new, private colormap 114848b8605Smrgwill be allocated. 115848b8605Smrg</p> 116848b8605Smrg 117848b8605Smrg<p> 118848b8605SmrgWhen sharing the root colormap, Mesa may be unable to allocate the colors 119848b8605Smrgit needs, resulting in poor color quality. This can happen when a 120848b8605Smrglarge number of colorcells in the root colormap are already allocated. 121848b8605SmrgTo prevent colormap sharing in GLUT, set the 122848b8605Smrg<b>MESA_PRIVATE_CMAP</b> environment variable. The value isn't 123848b8605Smrgsignificant. 124848b8605Smrg</p> 125848b8605Smrg 126848b8605Smrg 127848b8605Smrg<h2>Gamma Correction</h2> 128848b8605Smrg<p> 129848b8605SmrgTo compensate for the nonlinear relationship between pixel values 130848b8605Smrgand displayed intensities, there is a gamma correction feature in 131848b8605SmrgMesa. Some systems, such as Silicon Graphics, support gamma 132848b8605Smrgcorrection in hardware (man gamma) so you won't need to use Mesa's 133848b8605Smrggamma facility. Other systems, however, may need gamma adjustment 134848b8605Smrgto produce images which look correct. If you believe that 135848b8605SmrgMesa's images are too dim, read on. 136848b8605Smrg</p> 137848b8605Smrg 138848b8605Smrg<p> 139848b8605SmrgGamma correction is controlled with the <b>MESA_GAMMA</b> environment 140848b8605Smrgvariable. Its value is of the form <b>Gr Gg Gb</b> or just <b>G</b> where 141848b8605SmrgGr is the red gamma value, Gg is the green gamma value, Gb is the 142848b8605Smrgblue gamma value and G is one gamma value to use for all three 143848b8605Smrgchannels. Each value is a positive real number typically in the 144848b8605Smrgrange 1.0 to 2.5. 145848b8605SmrgThe defaults are all 1.0, effectively disabling gamma correction. 146848b8605SmrgExamples: 147848b8605Smrg</p> 148848b8605Smrg<pre> 149848b8605Smrg % export MESA_GAMMA="2.3 2.2 2.4" // separate R,G,B values 150848b8605Smrg % export MESA_GAMMA="2.0" // same gamma for R,G,B 151848b8605Smrg</pre> 152848b8605Smrg<p> 153848b8605SmrgThe <code>demos/gamma.c</code> program in mesa/demos repository may help 154848b8605Smrgyou to determine reasonable gamma value for your display. With correct 155848b8605Smrggamma values, the color intensities displayed in the top row (drawn by 156848b8605Smrgdithering) should nearly match those in the bottom row (drawn as grays). 157848b8605Smrg</p> 158848b8605Smrg 159848b8605Smrg<p> 160848b8605SmrgAlex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well 161848b8605Smrgon HP displays using the HP-ColorRecovery technology. 162848b8605Smrg</p> 163848b8605Smrg 164848b8605Smrg<p> 165848b8605SmrgMesa implements gamma correction with a lookup table which translates 166848b8605Smrga "linear" pixel value to a gamma-corrected pixel value. There is a 167848b8605Smrgsmall performance penalty. Gamma correction only works in RGB mode. 168848b8605SmrgAlso be aware that pixel values read back from the frame buffer will 169848b8605Smrgnot be "un-corrected" so glReadPixels may not return the same data 170848b8605Smrgdrawn with glDrawPixels. 171848b8605Smrg</p> 172848b8605Smrg 173848b8605Smrg<p> 174848b8605SmrgFor more information about gamma correction see: 175848b8605Smrg<a href="http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html"> 176848b8605Smrgthe Gamma FAQ</a> 177848b8605Smrg</p> 178848b8605Smrg 179848b8605Smrg 180848b8605Smrg<h2>Overlay Planes</h2> 181848b8605Smrg<p> 182848b8605SmrgHardware overlay planes are supported by the Xlib driver. To 183848b8605Smrgdetermine if your X server has overlay support you can test for the 184848b8605SmrgSERVER_OVERLAY_VISUALS property: 185848b8605Smrg</p> 186848b8605Smrg<pre> 187848b8605Smrg xprop -root | grep SERVER_OVERLAY_VISUALS 188848b8605Smrg</pre> 189848b8605Smrg 190848b8605Smrg 191848b8605Smrg<h2>HPCR Dithering</h2> 192848b8605Smrg<p> 193848b8605SmrgIf you set the <b>MESA_HPCR_CLEAR</b> environment variable then dithering 194848b8605Smrgwill be used when clearing the color buffer. This is only applicable 195848b8605Smrgto HP systems with the HPCR (Color Recovery) feature. 196848b8605SmrgThis incurs a small performance penalty. 197848b8605Smrg</p> 198848b8605Smrg 199848b8605Smrg 200848b8605Smrg<h2>Extensions</h2> 201848b8605Smrg<p> 202848b8605SmrgThe following MESA-specific extensions are implemented in the Xlib driver. 203848b8605Smrg</p> 204848b8605Smrg 205848b8605Smrg<h3>GLX_MESA_pixmap_colormap</h3> 206848b8605Smrg 207848b8605Smrg<p> 208848b8605SmrgThis extension adds the GLX function: 209848b8605Smrg</p> 210848b8605Smrg<pre> 211848b8605Smrg GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, 212848b8605Smrg Pixmap pixmap, Colormap cmap ) 213848b8605Smrg</pre> 214848b8605Smrg<p> 215848b8605SmrgIt is an alternative to the standard glXCreateGLXPixmap() function. 216848b8605SmrgSince Mesa supports RGB rendering into any X visual, not just True- 217848b8605SmrgColor or DirectColor, Mesa needs colormap information to convert RGB 218848b8605Smrgvalues into pixel values. An X window carries this information but a 219848b8605Smrgpixmap does not. This function associates a colormap to a GLX pixmap. 220848b8605SmrgSee the xdemos/glxpixmap.c file for an example of how to use this 221848b8605Smrgextension. 222848b8605Smrg</p> 223848b8605Smrg<p> 224848b8605Smrg<a href="specs/MESA_pixmap_colormap.spec">GLX_MESA_pixmap_colormap specification</a> 225848b8605Smrg</p> 226848b8605Smrg 227848b8605Smrg 228848b8605Smrg<h3>GLX_MESA_release_buffers</h3> 229848b8605Smrg<p> 230848b8605SmrgMesa associates a set of ancillary (depth, accumulation, stencil and 231848b8605Smrgalpha) buffers with each X window it draws into. These ancillary 232848b8605Smrgbuffers are allocated for each X window the first time the X window 233848b8605Smrgis passed to glXMakeCurrent(). Mesa, however, can't detect when an 234848b8605SmrgX window has been destroyed in order to free the ancillary buffers. 235848b8605Smrg</p> 236848b8605Smrg<p> 237848b8605SmrgThe best it can do is to check for recently destroyed windows whenever 238848b8605Smrgthe client calls the glXCreateContext() or glXDestroyContext() 239848b8605Smrgfunctions. This may not be sufficient in all situations though. 240848b8605Smrg</p> 241848b8605Smrg<p> 242848b8605SmrgThe GLX_MESA_release_buffers extension allows a client to explicitly 243848b8605Smrgdeallocate the ancillary buffers by calling glxReleaseBuffersMESA() 244848b8605Smrgjust before an X window is destroyed. For example: 245848b8605Smrg</p> 246848b8605Smrg<pre> 247848b8605Smrg #ifdef GLX_MESA_release_buffers 248848b8605Smrg glXReleaseBuffersMESA( dpy, window ); 249848b8605Smrg #endif 250848b8605Smrg XDestroyWindow( dpy, window ); 251848b8605Smrg</pre> 252848b8605Smrg<p> 253848b8605Smrg<a href="specs/MESA_release_buffers.spec">GLX_MESA_release_buffers specification</a> 254848b8605Smrg</p> 255848b8605Smrg<p> 256848b8605SmrgThis extension was added in Mesa 2.0. 257848b8605Smrg</p> 258848b8605Smrg 259848b8605Smrg<h3>GLX_MESA_copy_sub_buffer</h3> 260848b8605Smrg<p> 261848b8605SmrgThis extension adds the glXCopySubBufferMESA() function. It works 262848b8605Smrglike glXSwapBuffers() but only copies a sub-region of the window 263848b8605Smrginstead of the whole window. 264848b8605Smrg</p> 265848b8605Smrg<p> 266848b8605Smrg<a href="specs/MESA_copy_sub_buffer.spec">GLX_MESA_copy_sub_buffer specification</a> 267848b8605Smrg</p> 268848b8605Smrg<p> 269848b8605SmrgThis extension was added in Mesa 2.6 270848b8605Smrg</p> 271848b8605Smrg 272848b8605Smrg<h2>Summary of X-related environment variables</h2> 273848b8605Smrg<pre> 274848b8605Smrg MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only) 275848b8605Smrg MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only) 276848b8605Smrg MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only) 277848b8605Smrg MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only) 278848b8605Smrg MESA_GAMMA - gamma correction coefficients (X only) 279848b8605Smrg</pre> 280848b8605Smrg 281848b8605Smrg</div> 282848b8605Smrg</body> 283848b8605Smrg</html> 284