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 TrueColor and DirectColor visuals, for 22any depth with a corresponding renderable OpenGL texture format. 23 24The glXChooseVisual function tries to choose the best X visual for the 25given attribute list. However, if this doesn't suit your needs you can 26force Mesa to use any X visual you want (any supported by your X server 27that is) by setting the **MESA_RGB_VISUAL** environment variable. When 28a visual is requested, glXChooseVisual will first look if the 29MESA_RGB_VISUAL variable is defined. If so, it will try to use the 30specified visual. 31 32The format of accepted values is: ``visual-class depth`` 33 34Here are some examples: 35 36:: 37 38 using csh: 39 % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor 40 % setenv MESA_RGB_VISUAL "DirectColor 30" // 30-bit DirectColor 41 42 using bash: 43 $ export MESA_RGB_VISUAL="TrueColor 8" 44 $ export MESA_RGB_VISUAL="DirectColor 30" 45 46Double Buffering 47---------------- 48 49Mesa can use either an X Pixmap or XImage as the back color buffer when 50in double-buffer mode. The default is to use an XImage. The 51**MESA_BACK_BUFFER** environment variable can override this. The valid 52values for **MESA_BACK_BUFFER** are: **Pixmap** and **XImage** (only the 53first letter is checked, case doesn't matter). 54 55Using XImage is almost always faster than a Pixmap since it resides in 56the application's address space. When glXSwapBuffers() is called, 57XPutImage() or XShmPutImage() is used to transfer the XImage to the 58on-screen window. 59 60A Pixmap may be faster when doing remote rendering of a simple scene. 61Some OpenGL features will be very slow with a Pixmap (for example, 62blending will require a round-trip message for pixel readback.) 63 64Experiment with the MESA_BACK_BUFFER variable to see which is faster for 65your application. 66 67Colormaps 68--------- 69 70When using Mesa directly or with GLX, it's up to the application writer 71to create a window with an appropriate colormap. The GLUT toolkit tries 72to minimize colormap *flashing* by sharing colormaps when possible. 73Specifically, if the visual and depth of the window matches that of the 74root window, the root window's colormap will be shared by the Mesa 75window. Otherwise, a new, private colormap will be allocated. 76 77When sharing the root colormap, Mesa may be unable to allocate the 78colors it needs, resulting in poor color quality. This can happen when a 79large number of colorcells in the root colormap are already allocated. 80 81Overlay Planes 82-------------- 83 84Hardware overlay planes are supported by the Xlib driver. To determine 85if your X server has overlay support you can test for the 86SERVER_OVERLAY_VISUALS property: 87 88.. code-block:: console 89 90 xprop -root | grep SERVER_OVERLAY_VISUALS 91 92 93Extensions 94---------- 95 96The following Mesa-specific extensions are implemented in the Xlib 97driver. 98 99GLX_MESA_pixmap_colormap 100~~~~~~~~~~~~~~~~~~~~~~~~ 101 102This extension adds the GLX function: 103 104.. code-block:: c 105 106 GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, 107 Pixmap pixmap, Colormap cmap ) 108 109It is an alternative to the standard glXCreateGLXPixmap() function. 110Since Mesa supports RGB rendering into any X visual, not just True- 111Color or DirectColor, Mesa needs colormap information to convert RGB 112values into pixel values. An X window carries this information but a 113pixmap does not. This function associates a colormap to a GLX pixmap. 114See the xdemos/glxpixmap.c file for an example of how to use this 115extension. 116 117`GLX_MESA_pixmap_colormap 118specification <specs/MESA_pixmap_colormap.spec>`__ 119 120GLX_MESA_release_buffers 121~~~~~~~~~~~~~~~~~~~~~~~~ 122 123Mesa associates a set of ancillary (depth, accumulation, stencil and 124alpha) buffers with each X window it draws into. These ancillary buffers 125are allocated for each X window the first time the X window is passed to 126glXMakeCurrent(). Mesa, however, can't detect when an X window has been 127destroyed in order to free the ancillary buffers. 128 129The best it can do is to check for recently destroyed windows whenever 130the client calls the glXCreateContext() or glXDestroyContext() 131functions. This may not be sufficient in all situations though. 132 133The GLX_MESA_release_buffers extension allows a client to explicitly 134deallocate the ancillary buffers by calling glxReleaseBuffersMESA() just 135before an X window is destroyed. For example: 136 137.. code-block:: c 138 139 #ifdef GLX_MESA_release_buffers 140 glXReleaseBuffersMESA( dpy, window ); 141 #endif 142 XDestroyWindow( dpy, window ); 143 144`GLX_MESA_release_buffers 145specification <specs/MESA_release_buffers.spec>`__ 146 147This extension was added in Mesa 2.0. 148 149GLX_MESA_copy_sub_buffer 150~~~~~~~~~~~~~~~~~~~~~~~~ 151 152This extension adds the glXCopySubBufferMESA() function. It works like 153glXSwapBuffers() but only copies a sub-region of the window instead of 154the whole window. 155 156`GLX_MESA_copy_sub_buffer 157specification <specs/MESA_copy_sub_buffer.spec>`__ 158 159This extension was added in Mesa 2.6 160 161Summary of X-related environment variables 162------------------------------------------ 163 164+-----------------------------+--------------------------------------+ 165| Environment variable | Description | 166+=============================+======================================+ 167| :envvar:`MESA_RGB_VISUAL` | specifies the X visual and depth for | 168| | RGB mode (X only) | 169+-----------------------------+--------------------------------------+ 170| :envvar:`MESA_BACK_BUFFER` | specifies how to implement the back | 171| | color buffer (X only) | 172+-----------------------------+--------------------------------------+ 173