1Xlib Software Driver 2==================== 3 4Mesa's Xlib driver provides an emulation of the GLX interface so that 5OpenGL programs which use the GLX API can render to any X display, even 6those that don't support the GLX extension. Effectively, the Xlib driver 7converts all OpenGL rendering into Xlib calls. 8 9The Xlib driver is the oldest Mesa driver and the most mature of Mesa's 10software-only drivers. 11 12Since the Xlib driver *emulates* the GLX extension, it's not totally 13conformant with a true GLX implementation. The differences are fairly 14obscure, however. 15 16The unique features of the Xlib driver follows. 17 18X Visual Selection 19------------------ 20 21Mesa supports RGB(A) rendering into almost any X visual type and depth. 22 23The glXChooseVisual function tries to choose the best X visual for the 24given attribute list. However, if this doesn't suit your needs you can 25force Mesa to use any X visual you want (any supported by your X server 26that is) by setting the **MESA_RGB_VISUAL** and **MESA_CI_VISUAL** 27environment variables. When an RGB visual is requested, glXChooseVisual 28will first look if the MESA_RGB_VISUAL variable is defined. If so, it 29will try to use the specified visual. Similarly, when a color index 30visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL 31variable. 32 33The format of accepted values is: ``visual-class depth`` 34 35Here are some examples: 36 37:: 38 39 using csh: 40 % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor 41 % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor 42 % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor 43 44 using bash: 45 $ export MESA_RGB_VISUAL="TrueColor 8" 46 $ export MESA_CI_VISUAL="PseudoColor 12" 47 $ export MESA_RGB_VISUAL="PseudoColor 8" 48 49Double Buffering 50---------------- 51 52Mesa can use either an X Pixmap or XImage as the back color buffer when 53in double-buffer mode. The default is to use an XImage. The 54**MESA_BACK_BUFFER** environment variable can override this. The valid 55values for **MESA_BACK_BUFFER** are: **Pixmap** and **XImage** (only the 56first letter is checked, case doesn't matter). 57 58Using XImage is almost always faster than a Pixmap since it resides in 59the application's address space. When glXSwapBuffers() is called, 60XPutImage() or XShmPutImage() is used to transfer the XImage to the 61on-screen window. 62 63A Pixmap may be faster when doing remote rendering of a simple scene. 64Some OpenGL features will be very slow with a Pixmap (for example, 65blending will require a round-trip message for pixel readback.) 66 67Experiment with the MESA_BACK_BUFFER variable to see which is faster for 68your application. 69 70Colormaps 71--------- 72 73When using Mesa directly or with GLX, it's up to the application writer 74to create a window with an appropriate colormap. The GLUT toolkit tries 75to minimize colormap *flashing* by sharing colormaps when possible. 76Specifically, if the visual and depth of the window matches that of the 77root window, the root window's colormap will be shared by the Mesa 78window. Otherwise, a new, private colormap will be allocated. 79 80When sharing the root colormap, Mesa may be unable to allocate the 81colors it needs, resulting in poor color quality. This can happen when a 82large number of colorcells in the root colormap are already allocated. 83To prevent colormap sharing in GLUT, set the **MESA_PRIVATE_CMAP** 84environment variable. The value isn't significant. 85 86Gamma Correction 87---------------- 88 89To compensate for the nonlinear relationship between pixel values and 90displayed intensities, there is a gamma correction feature in Mesa. Some 91systems, such as Silicon Graphics, support gamma correction in hardware 92(man gamma) so you won't need to use Mesa's gamma facility. Other 93systems, however, may need gamma adjustment to produce images which look 94correct. If you believe that Mesa's images are too dim, read on. 95 96Gamma correction is controlled with the **MESA_GAMMA** environment 97variable. Its value is of the form **Gr Gg Gb** or just **G** where Gr 98is the red gamma value, Gg is the green gamma value, Gb is the blue 99gamma value and G is one gamma value to use for all three channels. Each 100value is a positive real number typically in the range 1.0 to 2.5. The 101defaults are all 1.0, effectively disabling gamma correction. Examples: 102 103:: 104 105 % export MESA_GAMMA="2.3 2.2 2.4" // separate R,G,B values 106 % export MESA_GAMMA="2.0" // same gamma for R,G,B 107 108The ``demos/gamma.c`` program in mesa/demos repository may help you to 109determine reasonable gamma value for your display. With correct gamma 110values, the color intensities displayed in the top row (drawn by 111dithering) should nearly match those in the bottom row (drawn as grays). 112 113Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well on 114HP displays using the HP-ColorRecovery technology. 115 116Mesa implements gamma correction with a lookup table which translates a 117"linear" pixel value to a gamma-corrected pixel value. There is a small 118performance penalty. Gamma correction only works in RGB mode. Also be 119aware that pixel values read back from the frame buffer will not be 120"un-corrected" so glReadPixels may not return the same data drawn with 121glDrawPixels. 122 123For more information about gamma correction, see the `Wikipedia 124article <https://en.wikipedia.org/wiki/Gamma_correction>`__ 125 126Overlay Planes 127-------------- 128 129Hardware overlay planes are supported by the Xlib driver. To determine 130if your X server has overlay support you can test for the 131SERVER_OVERLAY_VISUALS property: 132 133:: 134 135 xprop -root | grep SERVER_OVERLAY_VISUALS 136 137HPCR Dithering 138-------------- 139 140If you set the **MESA_HPCR_CLEAR** environment variable then dithering 141will be used when clearing the color buffer. This is only applicable to 142HP systems with the HPCR (Color Recovery) feature. This incurs a small 143performance penalty. 144 145Extensions 146---------- 147 148The following Mesa-specific extensions are implemented in the Xlib 149driver. 150 151GLX_MESA_pixmap_colormap 152~~~~~~~~~~~~~~~~~~~~~~~~ 153 154This extension adds the GLX function: 155 156:: 157 158 GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, 159 Pixmap pixmap, Colormap cmap ) 160 161It is an alternative to the standard glXCreateGLXPixmap() function. 162Since Mesa supports RGB rendering into any X visual, not just True- 163Color or DirectColor, Mesa needs colormap information to convert RGB 164values into pixel values. An X window carries this information but a 165pixmap does not. This function associates a colormap to a GLX pixmap. 166See the xdemos/glxpixmap.c file for an example of how to use this 167extension. 168 169`GLX_MESA_pixmap_colormap 170specification <specs/MESA_pixmap_colormap.spec>`__ 171 172GLX_MESA_release_buffers 173~~~~~~~~~~~~~~~~~~~~~~~~ 174 175Mesa associates a set of ancillary (depth, accumulation, stencil and 176alpha) buffers with each X window it draws into. These ancillary buffers 177are allocated for each X window the first time the X window is passed to 178glXMakeCurrent(). Mesa, however, can't detect when an X window has been 179destroyed in order to free the ancillary buffers. 180 181The best it can do is to check for recently destroyed windows whenever 182the client calls the glXCreateContext() or glXDestroyContext() 183functions. This may not be sufficient in all situations though. 184 185The GLX_MESA_release_buffers extension allows a client to explicitly 186deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just 187before an X window is destroyed. For example: 188 189:: 190 191 #ifdef GLX_MESA_release_buffers 192 glXReleaseBuffersMESA( dpy, window ); 193 #endif 194 XDestroyWindow( dpy, window ); 195 196`GLX_MESA_release_buffers 197specification <specs/MESA_release_buffers.spec>`__ 198 199This extension was added in Mesa 2.0. 200 201GLX_MESA_copy_sub_buffer 202~~~~~~~~~~~~~~~~~~~~~~~~ 203 204This extension adds the glXCopySubBufferMESA() function. It works like 205glXSwapBuffers() but only copies a sub-region of the window instead of 206the whole window. 207 208`GLX_MESA_copy_sub_buffer 209specification <specs/MESA_copy_sub_buffer.spec>`__ 210 211This extension was added in Mesa 2.6 212 213Summary of X-related environment variables 214------------------------------------------ 215 216:: 217 218 MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only) 219 MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only) 220 MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only) 221 MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only) 222 MESA_GAMMA - gamma correction coefficients (X only) 223