Brian Paul | fe4b966 | 2004-04-23 13:13:30 +0000 | [diff] [blame] | 1 | |
| 2 | Mesa Cygwin/X11 Information |
| 3 | |
| 4 | |
| 5 | WARNING |
| 6 | ======= |
| 7 | |
| 8 | If you installed X11 (packages xorg-x11-devel and xorg-x11-bin-dlls ) with the |
| 9 | latest setup.exe from Cygwin the GL (Mesa) libraries and include are already |
| 10 | installed in /usr/X11R6. |
| 11 | |
| 12 | The following will explain how to "replace" them. |
| 13 | |
| 14 | Installation |
| 15 | ============ |
| 16 | |
| 17 | How to compile Mesa on Cygwin/X11 systems: |
| 18 | |
| 19 | 1. Shared libs: |
| 20 | type 'make cygwin-sl'. |
| 21 | |
| 22 | When finished, the Mesa DLL will be in the Mesa-x.y/lib/ and |
| 23 | Mesa-x.y/bin directories. |
| 24 | |
| 25 | |
| 26 | 2. Static libs: |
| 27 | type 'make cygwin-static'. |
| 28 | When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory. |
| 29 | |
| 30 | Header and library files: |
| 31 | After you've compiled Mesa and tried the demos I recommend the following |
| 32 | procedure for "installing" Mesa. |
| 33 | |
| 34 | Copy the Mesa include/GL directory to /usr/X11R6/include: |
| 35 | cp -a include/GL /usr/X11R6/include |
| 36 | |
| 37 | Copy the Mesa library files to /usr/X11R6/lib: |
| 38 | cp -a lib/* /usr/X11R6ocal/lib |
| 39 | |
| 40 | Copy the Mesa bin files (used by the DLL stuff) to /usr/X11R6/bin: |
| 41 | cp -a lib/cyg* /usr/X11R6/bin |
| 42 | |
| 43 | Xt/Motif widgets: |
| 44 | If you want to use Mesa or OpenGL in your Xt/Motif program you can build |
| 45 | the widgets found in either the widgets-mesa or widgets-sgi directories. |
| 46 | The former were written for Mesa and the later are the original SGI |
| 47 | widgets. Look in those directories for more information. |
| 48 | For the Motif widgets you must have downloaded the lesstif package. |
| 49 | |
| 50 | |
| 51 | Using the library |
| 52 | ================= |
| 53 | |
| 54 | Configuration options: |
| 55 | The file src/mesa/main/config.h has many parameters which you can adjust |
| 56 | such as maximum number of lights, clipping planes, maximum texture size, |
| 57 | etc. In particular, you may want to change DEPTH_BITS from 16 to 32 |
| 58 | if a 16-bit depth buffer isn't precise enough for your application. |
| 59 | |
| 60 | |
| 61 | Shared libraries: |
| 62 | If you compile shared libraries (Win32 DLLS) you may have to set an |
| 63 | environment variable to specify where the Mesa libraries are located. |
| 64 | Set the PATH variable to include /your-dir/Mesa-2.6/bin. |
| 65 | Otherwise, when you try to run a demo it may fail with a message saying |
| 66 | that one or more DLL couldn't be found. |
| 67 | |
| 68 | |
| 69 | Xt/Motif Widgets: |
| 70 | Two versions of the Xt/Motif OpenGL drawing area widgets are included: |
| 71 | |
| 72 | widgets-sgi/ SGI's stock widgets |
| 73 | widgets-mesa/ Mesa-tuned widgets |
| 74 | |
| 75 | Look in those directories for details |
| 76 | |
| 77 | |
| 78 | Togl: |
| 79 | Togl is an OpenGL/Mesa widget for Tcl/Tk. |
| 80 | See http://togl.sourceforge.net for more information. |
| 81 | |
| 82 | |
| 83 | |
| 84 | X Display Modes: |
| 85 | Mesa supports RGB(A) rendering into almost any X visual type and depth. |
| 86 | |
| 87 | The glXChooseVisual function tries its best to pick an appropriate visual |
| 88 | for the given attribute list. However, if this doesn't suit your needs |
| 89 | you can force Mesa to use any X visual you want (any supported by your |
| 90 | X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL |
| 91 | environment variables. When an RGB visual is requested, glXChooseVisual |
| 92 | will first look if the MESA_RGB_VISUAL variable is defined. If so, it |
| 93 | will try to use the specified visual. Similarly, when a color index |
| 94 | visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL |
| 95 | variable. |
| 96 | |
| 97 | The format of accepted values is: <visual-class> <depth> |
| 98 | Here are some examples: |
| 99 | |
| 100 | using the C-shell: |
| 101 | % setenv MESA_RGB_VISUAL "TrueColor 8" // 8-bit TrueColor |
| 102 | % setenv MESA_CI_VISUAL "PseudoColor 12" // 12-bit PseudoColor |
| 103 | % setenv MESA_RGB_VISUAL "PseudoColor 8" // 8-bit PseudoColor |
| 104 | |
| 105 | using the KornShell: |
| 106 | $ export MESA_RGB_VISUAL="TrueColor 8" |
| 107 | $ export MESA_CI_VISUAL="PseudoColor 12" |
| 108 | $ export MESA_RGB_VISUAL="PseudoColor 8" |
| 109 | |
| 110 | |
| 111 | Double buffering: |
| 112 | Mesa can use either an X Pixmap or XImage as the backbuffer when in |
| 113 | double buffer mode. Using GLX, the default is to use an XImage. The |
| 114 | MESA_BACK_BUFFER environment variable can override this. The valid |
| 115 | values for MESA_BACK_BUFFER are: Pixmap and XImage (only the first |
| 116 | letter is checked, case doesn't matter). |
| 117 | |
| 118 | A pixmap is faster when drawing simple lines and polygons while an |
| 119 | XImage is faster when Mesa has to do pixel-by-pixel rendering. If you |
| 120 | need depth buffering the XImage will almost surely be faster. Exper- |
| 121 | iment with the MESA_BACK_BUFFER variable to see which is faster for |
| 122 | your application. |
| 123 | |
| 124 | |
| 125 | Colormaps: |
| 126 | When using Mesa directly or with GLX, it's up to the application writer |
| 127 | to create a window with an appropriate colormap. The aux, tk, and GLUT |
| 128 | toolkits try to minimize colormap "flashing" by sharing colormaps when |
| 129 | possible. Specifically, if the visual and depth of the window matches |
| 130 | that of the root window, the root window's colormap will be shared by |
| 131 | the Mesa window. Otherwise, a new, private colormap will be allocated. |
| 132 | |
| 133 | When sharing the root colormap, Mesa may be unable to allocate the colors |
| 134 | it needs, resulting in poor color quality. This can happen when a |
| 135 | large number of colorcells in the root colormap are already allocated. |
| 136 | To prevent colormap sharing in aux, tk and GLUT, define the environment |
| 137 | variable MESA_PRIVATE_CMAP. The value isn't significant. |
| 138 | |
| 139 | |
| 140 | Gamma correction: |
| 141 | To compensate for the nonlinear relationship between pixel values |
| 142 | and displayed intensities, there is a gamma correction feature in |
| 143 | Mesa. Some systems, such as Silicon Graphics, support gamma |
| 144 | correction in hardware (man gamma) so you won't need to use Mesa's |
| 145 | gamma facility. Other systems, however, may need gamma adjustment |
| 146 | to produce images which look correct. If in the past you thought |
| 147 | Mesa's images were too dim, read on. |
| 148 | |
| 149 | Gamma correction is controlled with the MESA_GAMMA environment |
| 150 | variable. Its value is of the form "Gr Gg Gb" or just "G" where |
| 151 | Gr is the red gamma value, Gg is the green gamma value, Gb is the |
| 152 | blue gamma value and G is one gamma value to use for all three |
| 153 | channels. Each value is a positive real number typically in the |
| 154 | range 1.0 to 2.5. The defaults are all 1.0, effectively disabling |
| 155 | gamma correction. Examples using csh: |
| 156 | |
| 157 | % setenv MESA_GAMMA "2.3 2.2 2.4" // separate R,G,B values |
| 158 | % setenv MESA_GAMMA "2.0" // same gamma for R,G,B |
| 159 | |
| 160 | The demos/gamma.c program may help you to determine reasonable gamma |
| 161 | value for your display. With correct gamma values, the color intensities |
| 162 | displayed in the top row (drawn by dithering) should nearly match those |
| 163 | in the bottom row (drawn as grays). |
| 164 | |
| 165 | Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well |
| 166 | on HP displays using the HP-ColorRecovery technology. |
| 167 | |
| 168 | Mesa implements gamma correction with a lookup table which translates |
| 169 | a "linear" pixel value to a gamma-corrected pixel value. There is a |
| 170 | small performance penalty. Gamma correction only works in RGB mode. |
| 171 | Also be aware that pixel values read back from the frame buffer will |
| 172 | not be "un-corrected" so glReadPixels may not return the same data |
| 173 | drawn with glDrawPixels. |
| 174 | |
| 175 | For more information about gamma correction see: |
| 176 | http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html |
| 177 | |
| 178 | |
| 179 | Overlay Planes |
| 180 | |
| 181 | Overlay planes in the frame buffer are supported by Mesa but require |
| 182 | hardware and X server support. To determine if your X server has |
| 183 | overlay support you can test for the SERVER_OVERLAY_VISUALS property: |
| 184 | |
| 185 | xprop -root | grep SERVER_OVERLAY_VISUALS |
| 186 | |
| 187 | |
| 188 | HPCR glClear(GL_COLOR_BUFFER_BIT) dithering |
| 189 | |
| 190 | If you set the MESA_HPCR_CLEAR environment variable then dithering |
| 191 | will be used when clearing the color buffer. This is only applicable |
| 192 | to HP systems with the HPCR (Color Recovery) system. |
| 193 | |
| 194 | |
| 195 | Extensions |
| 196 | ========== |
| 197 | There are three Mesa-specific GLX extensions at this time. |
| 198 | |
| 199 | GLX_MESA_pixmap_colormap |
| 200 | |
| 201 | This extension adds the GLX function: |
| 202 | |
| 203 | GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual, |
| 204 | Pixmap pixmap, Colormap cmap ) |
| 205 | |
| 206 | It is an alternative to the standard glXCreateGLXPixmap() function. |
| 207 | Since Mesa supports RGB rendering into any X visual, not just True- |
| 208 | Color or DirectColor, Mesa needs colormap information to convert RGB |
| 209 | values into pixel values. An X window carries this information but a |
| 210 | pixmap does not. This function associates a colormap to a GLX pixmap. |
| 211 | See the xdemos/glxpixmap.c file for an example of how to use this |
| 212 | extension. |
| 213 | |
| 214 | GLX_MESA_release_buffers |
| 215 | |
| 216 | Mesa associates a set of ancillary (depth, accumulation, stencil and |
| 217 | alpha) buffers with each X window it draws into. These ancillary |
| 218 | buffers are allocated for each X window the first time the X window |
| 219 | is passed to glXMakeCurrent(). Mesa, however, can't detect when an |
| 220 | X window has been destroyed in order to free the ancillary buffers. |
| 221 | |
| 222 | The best it can do is to check for recently destroyed windows whenever |
| 223 | the client calls the glXCreateContext() or glXDestroyContext() |
| 224 | functions. This may not be sufficient in all situations though. |
| 225 | |
| 226 | The GLX_MESA_release_buffers extension allows a client to explicitly |
| 227 | deallocate the ancillary buffers by calling glxReleaseBuffersMESA() |
| 228 | just before an X window is destroyed. For example: |
| 229 | |
| 230 | #ifdef GLX_MESA_release_buffers |
| 231 | glXReleaseBuffersMESA( dpy, window ); |
| 232 | #endif |
| 233 | XDestroyWindow( dpy, window ); |
| 234 | |
| 235 | This extension is new in Mesa 2.0. |
| 236 | |
| 237 | GLX_MESA_copy_sub_buffer |
| 238 | |
| 239 | This extension adds the glXCopySubBufferMESA() function. It works |
| 240 | like glXSwapBuffers() but only copies a sub-region of the window |
| 241 | instead of the whole window. |
| 242 | |
| 243 | This extension is new in Mesa version 2.6 |
| 244 | |
| 245 | |
| 246 | |
| 247 | Summary of X-related environment variables: |
| 248 | MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only) |
| 249 | MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only) |
| 250 | MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only) |
| 251 | MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only) |
| 252 | MESA_GAMMA - gamma correction coefficients (X only) |
| 253 | |
| 254 | |
| 255 | ---------------------------------------------------------------------- |
| 256 | README.CYGWIN - lassauge April 2004 - based on README.X11 |