Brian Paul | 12ad488 | 2006-04-19 03:25:06 +0000 | [diff] [blame^] | 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 conformance 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 Display Modes</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 backbuffer when in |
| 74 | double 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 |
| 76 | values 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> |
| 81 | A pixmap is faster when drawing simple lines and polygons while an |
| 82 | XImage is faster when Mesa has to do pixel-by-pixel rendering. If you |
| 83 | need depth buffering the XImage will almost surely be faster. |
| 84 | Experiment with the MESA_BACK_BUFFER variable to see which is faster |
| 85 | for your application. |
| 86 | </p> |
| 87 | |
| 88 | |
| 89 | <H2>Colormaps</H2> |
| 90 | <p> |
| 91 | When using Mesa directly or with GLX, it's up to the application |
| 92 | writer to create a window with an appropriate colormap. The GLUT |
| 93 | toolkit tris to minimize colormap <em>flashing</em> by sharing |
| 94 | colormaps when possible. Specifically, if the visual and depth of the |
| 95 | window matches that of the root window, the root window's colormap |
| 96 | will be shared by the Mesa window. Otherwise, a new, private colormap |
| 97 | will be allocated. |
| 98 | </p> |
| 99 | |
| 100 | <p> |
| 101 | When sharing the root colormap, Mesa may be unable to allocate the colors |
| 102 | it needs, resulting in poor color quality. This can happen when a |
| 103 | large number of colorcells in the root colormap are already allocated. |
| 104 | To prevent colormap sharing in GLUT, set the |
| 105 | <b>MESA_PRIVATE_CMAP</b> environment variable. The value isn't |
| 106 | significant. |
| 107 | </p> |
| 108 | |
| 109 | |
| 110 | <H2>Gamma correction</H2> |
| 111 | <p> |
| 112 | To compensate for the nonlinear relationship between pixel values |
| 113 | and displayed intensities, there is a gamma correction feature in |
| 114 | Mesa. Some systems, such as Silicon Graphics, support gamma |
| 115 | correction in hardware (man gamma) so you won't need to use Mesa's |
| 116 | gamma facility. Other systems, however, may need gamma adjustment |
| 117 | to produce images which look correct. If you believe that |
| 118 | Mesa's images are too dim, read on. |
| 119 | </p> |
| 120 | |
| 121 | <p> |
| 122 | Gamma correction is controlled with the <b>MESA_GAMMA</b> environment |
| 123 | variable. Its value is of the form <b>Gr Gg Gb</b> or just <b>G</b> where |
| 124 | Gr is the red gamma value, Gg is the green gamma value, Gb is the |
| 125 | blue gamma value and G is one gamma value to use for all three |
| 126 | channels. Each value is a positive real number typically in the |
| 127 | range 1.0 to 2.5. |
| 128 | The defaults are all 1.0, effectively disabling gamma correction. |
| 129 | Examples: |
| 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> |
| 136 | The progs/demos/gamma.c program may help you to determine reasonable gamma |
| 137 | value for your display. With correct gamma values, the color intensities |
| 138 | displayed in the top row (drawn by dithering) should nearly match those |
| 139 | in the bottom row (drawn as grays). |
| 140 | </p> |
| 141 | |
| 142 | <p> |
| 143 | Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well |
| 144 | on HP displays using the HP-ColorRecovery technology. |
| 145 | </p> |
| 146 | |
| 147 | <p> |
| 148 | Mesa implements gamma correction with a lookup table which translates |
| 149 | a "linear" pixel value to a gamma-corrected pixel value. There is a |
| 150 | small performance penalty. Gamma correction only works in RGB mode. |
| 151 | Also be aware that pixel values read back from the frame buffer will |
| 152 | not be "un-corrected" so glReadPixels may not return the same data |
| 153 | drawn with glDrawPixels. |
| 154 | </p> |
| 155 | |
| 156 | <p> |
| 157 | For more information about gamma correction see: |
| 158 | <a href="http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html" |
| 159 | the Gamma FAQ</a> |
| 160 | </p> |
| 161 | |
| 162 | |
| 163 | <H2>Overlay Planes</H2> |
| 164 | <p> |
| 165 | Hardware overlay planes are supported by the Xlib driver. To |
| 166 | determine if your X server has overlay support you can test for the |
| 167 | SERVER_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> |
| 176 | If you set the <b>MESA_HPCR_CLEAR</b> environment variable then dithering |
| 177 | will be used when clearing the color buffer. This is only applicable |
| 178 | to HP systems with the HPCR (Color Recovery) feature. |
| 179 | </p> |
| 180 | |
| 181 | |
| 182 | <H2>Extensions</H2> |
| 183 | <p> |
| 184 | The following MESA-specific extensions are implemented in the Xlib driver. |
| 185 | </p> |
| 186 | |
| 187 | <h3>GLX_MESA_pixmap_colormap</h3> |
| 188 | |
| 189 | <p> |
| 190 | This 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> |
| 197 | It is an alternative to the standard glXCreateGLXPixmap() function. |
| 198 | Since Mesa supports RGB rendering into any X visual, not just True- |
| 199 | Color or DirectColor, Mesa needs colormap information to convert RGB |
| 200 | values into pixel values. An X window carries this information but a |
| 201 | pixmap does not. This function associates a colormap to a GLX pixmap. |
| 202 | See the xdemos/glxpixmap.c file for an example of how to use this |
| 203 | extension. |
| 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> |
| 212 | Mesa associates a set of ancillary (depth, accumulation, stencil and |
| 213 | alpha) buffers with each X window it draws into. These ancillary |
| 214 | buffers are allocated for each X window the first time the X window |
| 215 | is passed to glXMakeCurrent(). Mesa, however, can't detect when an |
| 216 | X window has been destroyed in order to free the ancillary buffers. |
| 217 | </p> |
| 218 | <p> |
| 219 | The best it can do is to check for recently destroyed windows whenever |
| 220 | the client calls the glXCreateContext() or glXDestroyContext() |
| 221 | functions. This may not be sufficient in all situations though. |
| 222 | </p> |
| 223 | <p> |
| 224 | The GLX_MESA_release_buffers extension allows a client to explicitly |
| 225 | deallocate the ancillary buffers by calling glxReleaseBuffersMESA() |
| 226 | just 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> |
| 238 | This extension was added in Mesa 2.0. |
| 239 | </p> |
| 240 | |
| 241 | <H3>GLX_MESA_copy_sub_buffer</H3> |
| 242 | <p> |
| 243 | This extension adds the glXCopySubBufferMESA() function. It works |
| 244 | like glXSwapBuffers() but only copies a sub-region of the window |
| 245 | instead 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> |
| 251 | This 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> |