1 2 Mesa Cygwin/X11 Information 3 4 5WARNING 6======= 7 8If you installed X11 (packages xorg-x11-devel and xorg-x11-bin-dlls ) with the 9latest setup.exe from Cygwin the GL (Mesa) libraries and include are already 10installed in /usr/X11R6. 11 12The following will explain how to "replace" them. 13 14Installation 15============ 16 17How to compile Mesa on Cygwin/X11 systems: 18 191. 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 262. Static libs: 27 type 'make cygwin-static'. 28 When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory. 29 30Header 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 43Xt/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 51Using the library 52================= 53 54Configuration 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 61Shared 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 69Xt/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 78Togl: 79 Togl is an OpenGL/Mesa widget for Tcl/Tk. 80 See http://togl.sourceforge.net for more information. 81 82 83 84X 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 111Double 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 125Colormaps: 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 140Gamma 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 179Overlay 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 188HPCR 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 195Extensions 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 247Summary 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---------------------------------------------------------------------- 256README.CYGWIN - lassauge April 2004 - based on README.X11 257