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