docs/README.X11

   1
   2                           Mesa Unix/X11 Information
   3
   4
   5
   6 Installation
   7 ============
   8
   9 There are two ways to compile Mesa on Unix/X11 systems:
  10
  11 1. The old way:
  12     First type 'make' alone to see the list of system
  13     configurations currently supported.  If you see your configuration on the
  14     list, type 'make <config>'.  Most popular Unix/X workstations are currently
  15     supported.
  16
  17     If your system configuration is not listed by 'make', you'll have to modify
  18     the top-level Makefile and Make-config files.  There are instructions in
  19     each file.
  20
  21     When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory.
  22
  23
  24 2. The new way:
  25     Type './configure' and then 'make'.  This uses GNU autoconfig.
  26     Run 'make check' to build the demos.
  27     See docs/INSTALL for more details.
  28     When finished, the Mesa libraries will be in the Mesa-x.y/src/.libs/,
  29     Mesa-x.y/si-glu/.libs, etc directories.
  30
  31
  32 Notes on assembly language optimizations:
  33
  34    When using the old-style Makefiles, you can specify a configuration
  35    that uses X86 assembly language optimizations (linux-3dnow for example).
  36
  37    The detection of MMX, 3DNow!, PIII/SSE, etc capability is done at
  38    runtime.  That means you can compile Mesa for 3DNow! optimizations
  39    even if you don't have an AMD CPU.
  40
  41    However, your Linux binutils and assembler must understand the
  42    special instructions in order to compile them.  If you have
  43    compilation problems, try upgrading your binutils.
  44
  45
  46 Header and library files:
  47    After you've compiled Mesa and tried the demos I recommend the following
  48    procedure for "installing" Mesa.
  49
  50    Copy the Mesa include/GL directory to /usr/local/include:
  51         cp -r include/GL /usr/local/include
  52
  53    Copy the Mesa library files to /usr/local/lib:
  54         cp lib/* /usr/local/lib
  55
  56         (actually, use "cp -d" on Linux to preserve symbolic links)
  57
  58
  59 Xt/Motif widgets:
  60    If you want to use Mesa or OpenGL in your Xt/Motif program you can build
  61    the widgets found in either the widgets-mesa or widgets-sgi directories.
  62    The former were written for Mesa and the later are the original SGI
  63    widgets.  Look in those directories for more information.
  64
  65
  66 Notes:
  67    HP users:  a Mesa user reports that the HP-UX 10.01 C compiler has
  68    a bug which effects glReadPixels.  A patch for the compiler (PHSS_5743) is
  69    available.  Otherwise be sure your compiler is version 10.13 or later.
  70
  71    QNX users:  if you have problems running the demos try setting the
  72    stack size to 200K or larger with -N200K, for example.
  73
  74    SunOS 5.x users:  The X shared memory extension may not work
  75    correctly.  If Mesa prints an error message to the effect of "Shared memory
  76    error" then you'll have to append the following three lines to the end of
  77    your /etc/system file then reboot:
  78       set shmsys:shminfo_shmmax = 0x2000000
  79       set shmsys:shminfo_shmmni = 0x1000
  80       set shmsys:shminfo_shmseg = 0x100
  81
  82
  83
  84 Using the library
  85 =================
  86
  87 Configuration options:
  88    The file src/mesa/main/config.h has many parameters which you can adjust
  89    such as maximum number of lights, clipping planes, maximum texture size,
  90    etc.  In particular, you may want to change DEPTH_BITS from 16 to 32
  91    if a 16-bit depth buffer isn't precise enough for your application.
  92
  93
  94 Shared libraries:
  95    If you compile shared libraries you may have to set an environment
  96    variable to specify where the Mesa libraries are located.  On Linux and
  97    Sun systems for example, set the LD_LIBRARY_PATH variable to include
  98    /your-dir/Mesa-2.6/lib.   Otherwise, when you try to run a demo it
  99    may fail with a message saying that one or more libraries couldn't be
 100    found.
 101
 102
 103 Remote display of OpenGL/GLX programs:
 104    As of version 1.2.3, Mesa's header files use the same GLenum and GLUenum
 105    values as SGI's (and most/all other vendor's) OpenGL headers.  This means
 106    you can freely mix object files compiled with OpenGL or Mesa headers.
 107    In fact, on systems with dynamic runtime linkers it's possible to dynam-
 108    ically link with Mesa or OpenGL shared libraries at runtime, without
 109    recompiling or relinking anything!
 110
 111    Using IRIX 5.x as an example, you can run SGI's OpenGL demos with the
 112    Mesa shared libraries as follows.  Let's assume you're installing Mesa
 113    in /usr/local/Mesa and using the C-shell:
 114        % cd /usr/local/Mesa
 115        % make irix5-dso
 116        % setenv _RLD_LIST "/usr/local/Mesa/lib/libGL.so:DEFAULT"
 117        % /usr/demos/bin/ideas_ogl      // this is a test
 118
 119    You can now run OpenGL executables on almost any X display!  There may
 120    be some problems from the fact that Mesa supports many X visual types
 121    that an OpenGL client may not expect (grayscale for example).  In this
 122    case the application may abort, print error messages, or just behave
 123    strangely.  You may have to experiment with the MESA_RGB_VISUAL envi-
 124    ronment variable.
 125
 126
 127 Xt/Motif Widgets:
 128    Two versions of the Xt/Motif OpenGL drawing area widgets are included:
 129
 130       widgets-sgi/      SGI's stock widgets
 131       widgets-mesa/     Mesa-tuned widgets
 132
 133    Look in those directories for details
 134
 135
 136 Togl:
 137    Togl is an OpenGL/Mesa widget for Tcl/Tk.
 138    See http://togl.sourceforge.net for more information.
 139
 140
 141
 142 X Display Modes:
 143    Mesa supports RGB(A) rendering into almost any X visual type and depth.
 144
 145    The glXChooseVisual function tries its best to pick an appropriate visual
 146    for the given attribute list.  However, if this doesn't suit your needs
 147    you can force Mesa to use any X visual you want (any supported by your
 148    X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL
 149    environment variables.  When an RGB visual is requested, glXChooseVisual
 150    will first look if the MESA_RGB_VISUAL variable is defined.  If so, it
 151    will try to use the specified visual.  Similarly, when a color index
 152    visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
 153    variable.
 154
 155    The format of accepted values is:  <visual-class> <depth>
 156    Here are some examples:
 157
 158    using the C-shell:
 159         % setenv MESA_RGB_VISUAL "TrueColor 8"          // 8-bit TrueColor
 160         % setenv MESA_CI_VISUAL "PseudoColor 12"        // 12-bit PseudoColor
 161         % setenv MESA_RGB_VISUAL "PseudoColor 8"        // 8-bit PseudoColor
 162
 163    using the KornShell:
 164         $ export MESA_RGB_VISUAL="TrueColor 8"
 165         $ export MESA_CI_VISUAL="PseudoColor 12"
 166         $ export MESA_RGB_VISUAL="PseudoColor 8"
 167
 168
 169 Double buffering:
 170    Mesa can use either an X Pixmap or XImage as the backbuffer when in
 171    double buffer mode.  Using GLX, the default is to use an XImage.  The
 172    MESA_BACK_BUFFER environment variable can override this.  The valid
 173    values for MESA_BACK_BUFFER are:  Pixmap and XImage (only the first
 174    letter is checked, case doesn't matter).
 175
 176    A pixmap is faster when drawing simple lines and polygons while an
 177    XImage is faster when Mesa has to do pixel-by-pixel rendering.  If you
 178    need depth buffering the XImage will almost surely be faster.  Exper-
 179    iment with the MESA_BACK_BUFFER variable to see which is faster for
 180    your application.
 181
 182
 183 Colormaps:
 184    When using Mesa directly or with GLX, it's up to the application writer
 185    to create a window with an appropriate colormap.  The aux, tk, and GLUT
 186    toolkits try to minimize colormap "flashing" by sharing colormaps when
 187    possible.  Specifically, if the visual and depth of the window matches
 188    that of the root window, the root window's colormap will be shared by
 189    the Mesa window.  Otherwise, a new, private colormap will be allocated.
 190
 191    When sharing the root colormap, Mesa may be unable to allocate the colors
 192    it needs, resulting in poor color quality.  This can happen when a
 193    large number of colorcells in the root colormap are already allocated.
 194    To prevent colormap sharing in aux, tk and GLUT, define the environment
 195    variable MESA_PRIVATE_CMAP.  The value isn't significant.
 196
 197
 198 Gamma correction:
 199    To compensate for the nonlinear relationship between pixel values
 200    and displayed intensities, there is a gamma correction feature in
 201    Mesa.  Some systems, such as Silicon Graphics, support gamma
 202    correction in hardware (man gamma) so you won't need to use Mesa's
 203    gamma facility.  Other systems, however, may need gamma adjustment
 204    to produce images which look correct.  If in the past you thought
 205    Mesa's images were too dim, read on.
 206
 207    Gamma correction is controlled with the MESA_GAMMA environment
 208    variable.  Its value is of the form "Gr Gg Gb" or just "G" where
 209    Gr is the red gamma value, Gg is the green gamma value, Gb is the
 210    blue gamma value and G is one gamma value to use for all three
 211    channels.  Each value is a positive real number typically in the
 212    range 1.0 to 2.5.  The defaults are all 1.0, effectively disabling
 213    gamma correction.  Examples using csh:
 214
 215         % setenv MESA_GAMMA "2.3 2.2 2.4"       // separate R,G,B values
 216         % setenv MESA_GAMMA "2.0"               // same gamma for R,G,B
 217
 218    The demos/gamma.c program may help you to determine reasonable gamma
 219    value for your display.  With correct gamma values, the color intensities
 220    displayed in the top row (drawn by dithering) should nearly match those
 221    in the bottom row (drawn as grays).
 222
 223    Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
 224    on HP displays using the HP-ColorRecovery technology.
 225
 226    Mesa implements gamma correction with a lookup table which translates
 227    a "linear" pixel value to a gamma-corrected pixel value.  There is a
 228    small performance penalty.  Gamma correction only works in RGB mode.
 229    Also be aware that pixel values read back from the frame buffer will
 230    not be "un-corrected" so glReadPixels may not return the same data
 231    drawn with glDrawPixels.
 232
 233    For more information about gamma correction see:
 234    http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html
 235
 236
 237 Overlay Planes
 238
 239    Overlay planes in the frame buffer are supported by Mesa but require
 240    hardware and X server support.  To determine if your X server has
 241    overlay support you can test for the SERVER_OVERLAY_VISUALS property:
 242
 243         xprop -root | grep SERVER_OVERLAY_VISUALS
 244
 245
 246 HPCR glClear(GL_COLOR_BUFFER_BIT) dithering
 247
 248    If you set the MESA_HPCR_CLEAR environment variable then dithering
 249    will be used when clearing the color buffer.  This is only applicable
 250    to HP systems with the HPCR (Color Recovery) system.
 251
 252
 253 Extensions
 254 ==========
 255    There are three Mesa-specific GLX extensions at this time.
 256
 257    GLX_MESA_pixmap_colormap
 258
 259       This extension adds the GLX function:
 260
 261          GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
 262                                            Pixmap pixmap, Colormap cmap )
 263
 264       It is an alternative to the standard glXCreateGLXPixmap() function.
 265       Since Mesa supports RGB rendering into any X visual, not just True-
 266       Color or DirectColor, Mesa needs colormap information to convert RGB
 267       values into pixel values.  An X window carries this information but a
 268       pixmap does not.  This function associates a colormap to a GLX pixmap.
 269       See the xdemos/glxpixmap.c file for an example of how to use this
 270       extension.
 271
 272    GLX_MESA_release_buffers
 273
 274       Mesa associates a set of ancillary (depth, accumulation, stencil and
 275       alpha) buffers with each X window it draws into.  These ancillary
 276       buffers are allocated for each X window the first time the X window
 277       is passed to glXMakeCurrent().  Mesa, however, can't detect when an
 278       X window has been destroyed in order to free the ancillary buffers.
 279
 280       The best it can do is to check for recently destroyed windows whenever
 281       the client calls the glXCreateContext() or glXDestroyContext()
 282       functions.  This may not be sufficient in all situations though.
 283
 284       The GLX_MESA_release_buffers extension allows a client to explicitly
 285       deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
 286       just before an X window is destroyed.  For example:
 287
 288          #ifdef GLX_MESA_release_buffers
 289             glXReleaseBuffersMESA( dpy, window );
 290          #endif
 291          XDestroyWindow( dpy, window );
 292
 293       This extension is new in Mesa 2.0.
 294
 295    GLX_MESA_copy_sub_buffer
 296
 297       This extension adds the glXCopySubBufferMESA() function.  It works
 298       like glXSwapBuffers() but only copies a sub-region of the window
 299       instead of the whole window.
 300
 301       This extension is new in Mesa version 2.6
 302
 303
 304
 305 Summary of X-related environment variables:
 306    MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
 307    MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
 308    MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
 309    MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
 310    MESA_GAMMA - gamma correction coefficients (X only)
 311
 312
 313 ----------------------------------------------------------------------
 314 $Id: README.X11,v 3.11 2003/12/17 15:14:31 brianp Exp $