docs/README.CYGWIN

   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