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