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