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