Magazyn Amiga 5/MA_Cover_5.iso/ppc/mesa/readme

Text File | 1998-01-31 | 38.1 KB | 1,009 lines

                                 Mesa 2.5

                     Copyright (C) 1995-1997  Brian Paul



Disclaimer
==========

Mesa is a 3-D graphics library with an API which is very similar to that
of OpenGL*.  To the extent that Mesa utilizes the OpenGL command syntax
or state machine, it is being used with authorization from Silicon Graphics,
Inc.  However, the author makes no claim that Mesa is in any way a
compatible replacement for OpenGL or associated with Silicon Graphics, Inc.
Those who want a licensed implementation of OpenGL should contact a licensed
vendor.  This software is distributed under the terms of the GNU Library
General Public License, see the LICENSE file for details.

* OpenGL(R) is a registered trademark of Silicon Graphics, Inc.



Author
======

Brian Paul
Avid Technology
6400 EnterPrise Lane, Suite 201
Madison, WI  53719

[e-mail]

Formerly employed at the Space Science and Engineering Center at the
University of Wisconsin - Madison.



Introduction
============

While Mesa uses the OpenGL API and mimics its semantics, it is
important to understand that Mesa is not a real implementation of OpenGL
since it is not licensed and has not been tested by the OpenGL conformance
tests.  That said, Mesa is still a viable alternative to OpenGL.

Since version 2.0 Mesa implements the OpenGL 1.1 API specification.
Only a few features are not yet implemented:

    trimmed NURBS
    line and polygon antialiasing
    glGetPolygonStipple function
    glGetTexImage


The primary design goal of this library has been correctness.  Common
code paths are optimized for speed.  If you find that a particular
rendering operation is slow let me know about it.  It may be a simple
matter to optimize the operation in question.

I've been working on this library in my spare time since August, 1993.
The core library was originally written on an Amiga using the DCC compiler.
Later, development was moved to an SGI workstation.  Current development
is done on SGI and PC/Linux systems.

Mesa works on most Unix workstations with ANSI C and X11.  There are also
drivers for Amiga, Microsoft Windows, Macintosh, MS DOS, NeXT, and BeOS
systems.  Look below for more information.

Since the OpenGL API is used, OpenGL documentation can serve as the
documentation for Mesa's core functions.  Here are a few sources:

  WWW Center:   http://www.sgi.com/Technology/openGL/
  Man pages:    http://www.digital.com:80/pub/doc/opengl/
  Spec doc:     http://www.sgi.com/Technology/openGL/glspec/glspec.html



Getting the software
====================

The primary Mesa ftp site is iris.ssec.wisc.edu in the pub/Mesa directory.
Mesa is also mirrored on sunsite in the directory pub/packages/development
/graphics/mesa.

As of version 2.3, Mesa is distributed in two pieces:  main library code
and demos.  If you're upgrading from a previous version of Mesa or you're not
interested in the demos you can just download the core Mesa archive file.

Mesa is available in three archive formats:

1. GNU zip/tar

    Download MesaLib-2.5.tar.gz and optionally MesaDemos-2.5.tar.gz
    Unpack with:
        gzcat MesaLib-2.5.tar.gz | tar xf -
        gzcat MesaDemos-2.5.tar.gz | tar xf -

2. Unix compressed/tar

    Download MesaLib-2.5.tar.Z and optionally MesaDemos-2.5.tar.Z
    Unpack with:
        zcat MesaLib-2.5.tar.Z | tar xf -
        zcat MesaDemos-2.5.tar.Z | tar xf -

3. ZIP format

    Download MesaLib-2.5.zip and optionally MesaDemos-2.5.zip
    Unpack with:
        unzip MesaLib-2.5.zip
        unzip MesaDemos-2.5.zip


After unpacking you should have the following files in the new Mesa-2.5
directory:

README        - this file
README.3DFX    - instructions for using Mesa with 3Dfx Glide library
README.AMIWIN    - instructions for using Mesa on Amigas with AmiWin (X11)
README.BEOS    - instructions for using Mesa with BeOS
README.DOS    - instructions for using Mesa with MS-DOS
README.LYNXOS    - instructions for using Mesa with LynxOS
README.MGL    - instructions for using Mesa with SciTech's MGL library
README.NEXT    - instructions for using Mesa with NeXT
README.OS2    - instructions for using Mesa with OS/2 and XFree86
README.VIRGE    - instructions for using Mesa with S3/Virge w/ Windows 95
README.VMS    - instructions for using Mesa with VMS
README.WIN    - instructions for using Mesa with Microsoft Windows 95/NT
LICENSE        - the GNU library license
IAFA-PACKAGE    - description file
VERSIONS    - version history
RELNOTES    - version-specific release notes
FUTURE        - future development plans/ideas
Makefile    - top-level Makefile
Make-config    - system configurations used by the Makefiles
Imakefile    - for OS/2
mklib.*        - shell scripts for making shared libraries for some systems
include/    - client include files
lib/        - client libraries, created during installation
src/        - source code for core library
src-glu/    - source code for utility library
src-glut/    - source code for GLUT toolkit
util/        - handly utility functions
widgets-mesa/    - Mesa widgets for Xt/Motif
widgets-sgi/    - SGI OpenGL widgets for Xt/Motif
windows/    - Microsoft Windows driver stuff, from Mesa 1.2.x
gdemos/        - GLUT demos
NeXT/        - NeXT demo programs
BeOS/        - BeOS demo programs
mondello/    - Cirrus Logic Mondello 3-D accelerator code
*mms*        - makefiles for VMS
OpenStep/    - OpenStep files

and if you downloaded and unpacked the demos:

src-tk/        - source code for tk library
src-aux/    - source code for aux library
demos/        - demo programs
samples/    - sample OpenGL programs from SGI
book/        - example programs from the OpenGL Programming Guide
3Dfx/        - 3Dfx demos and GLUT


Other Mesa-related stuff is at  ftp://iris.ssec.wisc.edu/pub/Mesa/contrib/



GLUT
====

Mesa 2.5 and later includes Mark Kilgard's GLUT library (GL Utility Toolkit).
GLUT is built automatically on systems which support it.

The GLUT tests, demos, examples, etc are not included, just the main library.
To obtain the latest complete release of GLUT please visit
http://reality.sgi.com/employees/mjk_asd/glut3/glut3.html



Installation for Unix/X11
=========================

To compile the library, first type 'make' alone to see the list of system
configurations currently supported.  If you see your configuration on the
list, type 'make <config>'.  Most popular Unix/X workstations are currently
supported.

The top-level makefile will execute the makefiles in a number of sub-
directories.  When finished, the Mesa libraries will be in the Mesa-2.5/lib/
directory.  A few GLUT demos in the gdemos/ directory should be ready to run.

If you also downloaded and unpacked the demos there should be executables
in the "demos/", "samples/", and "book/" directories for you to try out.
If you only want to compile the contents of one subdirectory you can 'cd'
to that directory and type 'make <config>' there.

If your system configuration is not listed by 'make', you'll have to modify
the top-level Makefile and Make-config files.  There are instructions in
each file.

If you have compilation problems you should try to fix them and return the
patches to the author.


Header and library files:
   After you've compiled Mesa and tried the demos I recommend the following
   procedure for "installing" Mesa.

   Copy the Mesa include/GL directory to /usr/local/include:
    cp -r include/GL /usr/local/include

   Copy the Mesa library files to /usr/local/lib:
    cp lib/* /usr/local/lib

    (actually, use "cp -d" on Linux to preserve symbolic links)

   Create a few symbolic links so that compiling OpenGL applications is easy:
    cd /usr/local/lib
    IF USING STATIC (lib*.a) FILES THEN
        ln -s libMesaGL.a libGL.a
        ln -s libMesaGLU.a libGLU.a
    ELSE
        ln -s libMesaGL.so libGL.so
        ln -s libMesaGLU.so libGLU.so
    ENDIF


Xt/Motif widgets:
   If you want to use Mesa or OpenGL in your Xt/Motif program you can build
   the widgets found in either the widgets-mesa or widgets-sgi directories.
   The former were written for Mesa and the later are the original SGI
   widgets.  Look in those directories for more information.


Notes:
   HP users:  a Mesa user reports that the HP-UX 10.01 C compiler has
   a bug which effects glReadPixels.  A patch for the compiler (PHSS_5743) is
   available.  Otherwise be sure your compiler is version 10.13 or later.

   QNX users:  if you have problems running the demos try setting the
   stack size to 200K or larger with -N200K, for example.

   SunOS 5.x users:  The X shared memory extension may not work
   correctly.  If Mesa prints an error message to the effect of "Shared memory
   error" then you'll have to append the following three lines to the end of
   your /etc/system file then reboot:
      set shmsys:shminfo_shmmax = 0x2000000
      set shmsys:shminfo_shmmni = 0x1000
      set shmsys:shminfo_shmseg = 0x100



Installation for Amigas
=======================

See http://www.efd.lth.se/~d94sz/amesa for the latest version of the Amiga
driver.



Installation for Microsoft Windows
==================================

See the windows/README file for more information.



Installation for Macintosh
==========================

See http://www.elte.hu/~boga/Mesa.html for the latest info.



Installation for NeXT
=====================

Simply typing "make next" should compile Mesa and a number of NeXT demo
programs found in the NeXT/ directory.  The NeXT driver is implemented
through Mesa's Off-Screen rendering interface.



Installation for BeOS
=====================

Simply typing "make beos" should compile Mesa and a number of BeOS demo
programs found in the BeOS/ directory.  The BeOS driver is implemented
through Mesa's Off-Screen rendering interface.



Installation for OS/2
=====================

*** Mesa 2.x does not currently work on OS/2 ***

See the README.OS2 file for details.



Installation for VMS
====================

See the README.VMS file for more information.



Installation for MS-DOS (optionally with DJGPP)
===============================================

See the README.DOS file for more information.



Installation for OpenStep
=========================

See the OpenStep/README file for more information.



Installation for 3Dfx VooDoo/Rush hardware
==========================================

See the README.3DFX file and look in the 3Dfx/ subdirectory.


Installation for S3/Virge driver on Windows 95
==============================================

See the README.VIRGE file.



Using the library
=================

Configuration options:
   The file src/config.h has many parameters which you can adjust such
   as maximum number of lights, clipping planes, maximum texture size,
   etc.  In particular, you may want to change DEPTH_BITS from 16 to 32
   if a 16-bit depth buffer isn't precise enough for your application.


Shared libraries:
   If you compile shared libraries you may have to set an environment
   variable to specify where the Mesa libraries are located.  On Linux and
   Sun systems for example, set the LD_LIBRARY_PATH variable to include
   /your-dir/Mesa-2.5/lib.   Otherwise, when you try to run a demo it
   may fail with a message saying that one or more libraries couldn't be
   found.


Remote display of OpenGL/GLX programs:
   As of version 1.2.3, Mesa's header files use the same GLenum and GLUenum
   values as SGI's (and most/all other vendor's) OpenGL headers.  This means
   you can freely mix object files compiled with OpenGL or Mesa headers.
   In fact, on systems with dynamic runtime linkers it's possible to dynam-
   ically link with Mesa or OpenGL shared libraries at runtime, without
   recompiling or relinking anything!

   Using IRIX 5.x as an example, you can run SGI's OpenGL demos with the
   Mesa shared libraries as follows.  Let's assume you're installing Mesa
   in /usr/local/Mesa and using the C-shell:
       % cd /usr/local/Mesa
       % make irix5-dso
       % cd lib
       % ln -s libMesaGL.so libGL.so
       % setenv _RLD_LIST "/usr/local/Mesa/lib/libGL.so:DEFAULT"
       % /usr/demos/bin/ideas_ogl      // this is a test

   You can now run OpenGL executables on almost any X display!  There may
   be some problems from the fact that Mesa supports many X visual types
   that an OpenGL client may not expect (grayscale for example).  In this
   case the application may abort, print error messages, or just behave
   strangely.  You may have to experiment with the MESA_RGB_VISUAL envi-
   ronment variable.


Toolkits (X11 only):
   Mesa includes the glaux and gltk libraries from SGI.  Their only real
   use is for writing simple demo programs.  It is highly recommended that
   you do _not_ use these libraries for your own programs.  There are
   several alternatives:

      1. GLUT (OpenGL Utility Toolkit) was written by Mark Kilgard of SGI
      as a replacement for glaux and gltk.  It provides a simple, portable,
      window-system independent interface allowing you to write OpenGL
      applications quickly and easily.  GLUT isn't included with Mesa but
      you'll find instructions on how to get and build GLUT in the file
      README.GLUT.  The second edition of the OpenGL Programming Guide,
      published by Addison Wesley uses GLUT instead of the glaux library.

      2. Use an Xt/Motif widget.  Look in the widgets-old/ or widgets-sgi
      directories for more info.

      3. If you use Tcl/Tk you should consider Togl.  See
      http://www.ssec.wisc.edu/~brianp/Togl.html for more information.

      4. Use the GLX (simulated since Mesa doesn't implement the GLX proto-
      col) functions.  These functions look like, and try to act like, the
      real GLX functions used by OpenGL in conjunction with the X window
      system.


Performance tips:
   1. Turn off smooth shading when you don't need it (glShadeModel)
   2. Turn off depth buffering when you don't need it.
   3. Turn off dithering when not needed.
   4. Use double buffering as it's often faster than single buffering
   5. Compile in the X Shared Memory extension option if it's supported
      on your system by adding -DSHM to CFLAGS and -lXext to XLIBS for
      your system in the Make-config file.
   6. Recompile Mesa with more optimization if possible.
   7. Try to maximize the amount of drawing done between glBegin/glEnd pairs.
   8. Use the MESA_BACK_BUFFER variable to find best performance in double
      buffered mode.  (X users only)
   9. Optimized polygon rasterizers are employed when:
         rendering into back buffer which is an XImage
         RGB mode, not grayscale, not monochrome
         depth buffering is GL_LESS, or disabled
         flat or smooth shading
         dithered or non-dithered
         no other rasterization operations enabled (blending, stencil, etc)
  10. Optimized line drawing is employed when:
         rendering into back buffer which is an XImage
         RGB mode, not grayscale, not monochrome
         depth buffering is GL_LESS or disabled
         flat shading
         dithered or non-dithered
         no other rasterization operations enabled (blending, stencil, etc)
  11. Textured polygons are fastest when:
         using a 3-component (RGB), 2-D texture
         minification and magnification filters are GL_NEAREST
         texture coordinate wrap modes for S and T are GL_REPEAT
         GL_DECAL environment mode
         glHint( GL_PERSPECTIVE_CORRECTION_HINT, GL_FASTEST )
         depth buffering is GL_LESS or disabled
  12. Lighting is fastest when:
         Two-sided lighting is disabled
         GL_LIGHT_MODEL_LOCAL_VIEWER is false
         GL_COLOR_MATERIAL is disabled
         No spot lights are used (all GL_SPOT_CUTOFFs are 180.0)
         No local lights are used (all position W's are 0.0)
         All material and light coefficients are >= zero
  13. XFree86 users:  if you want to use 24-bit color try starting your
      X server in 32-bit per pixel mode for better performance.  That is,
      start your X server with
         startx -- -bpp 32
      instead of
         startx -- -bpp 24
  14. Try disabling dithering with the MESA_NO_DITHER environment variable.
      If this env var is defined Mesa will disable dithering and the
      command glEnable(GL_DITHER) will be ignored.


Debugging:
   Normally Mesa records but does not notify the user of errors.  It is up
   to the application to call glGetError to check for errors.  Mesa supports
   an environment variable, MESA_DEBUG, to help with debugging.  If MESA_DEBUG
   is defined, a message will be printed to stdout whenever an error occurs.

   More extensive error checking is done when Mesa is compiled with the
   DEBUG symbol defined.  You'll have to edit the Make-config file and
   add -DDEBUG to the CFLAGS line for your system configuration.  You may
   also want to replace any optimization flags with the -g flag so you can
   use your debugger.  After you've edited Make-config type 'make clean'
   before recompiling.

   In your debugger you can set a breakpoint in gl_error() to trap Mesa
   errors.

   There is a display list printing/debugging facility.  See the end of
   src/dlist.c for details.


X Display Modes:
   Mesa supports rendering in most X visual types and depths.  When a
   TrueColor or DirectColor visual isn't available dithering is used in RGB
   mode.

   The glXChooseVisual function tries its best to pick an appropriate visual
   for the given attribute list.  However, if this doesn't suit your needs
   you can force Mesa to use any X visual you want (any supported by your
   X server that is) by setting the MESA_RGB_VISUAL and MESA_CI_VISUAL
   environment variables.  When an RGB visual is requested, glXChooseVisual
   will first look if the MESA_RGB_VISUAL variable is defined.  If so, it
   will try to use the specified visual.  Similarly, when a color index
   visual is requested, glXChooseVisual will look for the MESA_CI_VISUAL
   variable.

   The format of accepted values is:  <visual-class> <depth>
   Here are some examples:

   using the C-shell:
    % setenv MESA_RGB_VISUAL "TrueColor 8"        // 8-bit TrueColor
    % setenv MESA_CI_VISUAL "PseudoColor 12"    // 12-bit PseudoColor
    % setenv MESA_RGB_VISUAL "PseudoColor 8"    // 8-bit PseudoColor

   using the KornShell:
    $ export MESA_RGB_VISUAL="TrueColor 8"
    $ export MESA_CI_VISUAL="PseudoColor 12"
    $ export MESA_RGB_VISUAL="PseudoColor 8"


Double buffering (X11 only):
   Mesa can use either an X Pixmap or XImage as the backbuffer when in
   double buffer mode.  Using GLX, the default is to use an XImage.  The
   MESA_BACK_BUFFER environment variable can override this.  The valid
   values for MESA_BACK_BUFFER are:  Pixmap and XImage (only the first
   letter is checked, case doesn't matter).

   A pixmap is faster when drawing simple lines and polygons while an
   XImage is faster when Mesa has to do pixel-by-pixel rendering.  If you
   need depth buffering the XImage will almost surely be faster.  Exper-
   iment with the MESA_BACK_BUFFER variable to see which is faster for
   your application.


Colormaps (X11 only):
   When using Mesa directly or with GLX, it's up to the application writer
   to create a window with an appropriate colormap.  The aux, tk, and GLUT
   toolkits try to minimize colormap "flashing" by sharing colormaps when
   possible.  Specifically, if the visual and depth of the window matches
   that of the root window, the root window's colormap will be shared by
   the Mesa window.  Otherwise, a new, private colormap will be allocated.

   When sharing the root colormap, Mesa may be unable to allocate the colors
   it needs, resulting in poor color quality.  This can happen when a
   large number of colorcells in the root colormap are already allocated.
   To prevent colormap sharing in aux, tk and GLUT, define the environment
   variable MESA_PRIVATE_CMAP.  The value isn't significant.


Fortran bindings:
   Fortan bindings are no longer included with Mesa.  William F. Mitchell
   ([e-mail]) has developed a new set of Mesa/OpenGL and
   GLUT bindings for Fortran.  See http://math.nist.gov/f90gl for more
   information.


Gamma correction (X11 only):
   To compensate for the nonlinear relationship between pixel values
   and displayed intensities, there is a gamma correction feature in
   Mesa.  Some systems, such as Silicon Graphics, support gamma
   correction in hardware (man gamma) so you won't need to use Mesa's
   gamma facility.  Other systems, however, may need gamma adjustment
   to produce images which look correct.  If in the past you thought
   Mesa's images were too dim, read on.

   Gamma correction is controlled with the MESA_GAMMA environment
   variable.  Its value is of the form "Gr Gg Gb" or just "G" where
   Gr is the red gamma value, Gg is the green gamma value, Gb is the
   blue gamma value and G is one gamma value to use for all three
   channels.  Each value is a positive real number typically in the
   range 1.0 to 2.5.  The defaults are all 1.0, effectively disabling
   gamma correction.  Examples using csh:

    % setenv MESA_GAMMA "2.3 2.2 2.4"    // separate R,G,B values
    % setenv MESA_GAMMA "2.0"        // same gamma for R,G,B

   The demos/gamma.c program may help you to determine reasonable gamma
   value for your display.  With correct gamma values, the color intensities
   displayed in the top row (drawn by dithering) should nearly match those
   in the bottom row (drawn as grays).

   Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
   on HP displays using the HP-ColorRecovery technology.

   Mesa implements gamma correction with a lookup table which translates
   a "linear" pixel value to a gamma-corrected pixel value.  There is a
   small performance penalty.  Gamma correction only works in RGB mode.
   Also be aware that pixel values read back from the frame buffer will
   not be "un-corrected" so glReadPixels may not return the same data
   drawn with glDrawPixels.

   For more information about gamma correction see:
   http://www.inforamp.net/~poynton/notes/colour_and_gamma/GammaFAQ.html


Off-screen rendering:
   Mesa 1.2.4 introduced off-screen rendering, a facility for generating
   3-D imagery without having to open a window on your display.  Mesa's
   simple off-screen rendering interface is completely operating system
   and window system independent so programs which use off-screen rendering
   should be very portable.  This new feature effectively enables you to
   use Mesa as an off-line, batch-oriented renderer.

   The "OSMesa" API provides 3 functions for making off-screen renderings:
   OSMesaCreateContext(), OSMesaMakeCurrent(), and OSMesaDestroyContext().
   See the Mesa/include/GL/osmesa.h header for more information.  See the
   demos/osdemo.c file for an example program.   There is no facility for
   writing images to files.

   If you want to generate large images (larger than 1280x1024) you'll
   have to edit the src/config.h file to change MAX_WIDTH and MAX_HEIGHT
   then recompile Mesa.  Image size should only be limited by available
   memory.


Profiling:
   Mesa 1.2.6 introduced a simple profiling facility.  It counts and
   measures the time spent in a number of important rendering operations
   and prints the information in a report before your program exits.

   By default, profiling is disabled.  To enable it, add -DPROFILE to
   the appropriate CFLAGS entry in the Make-config file, then recompile
   Mesa.  In general, you should only enable profiling during program
   development to gain insight into Mesa's performance.  Mesa runs a bit
   slower when profiling is enabled because it requires frequent polling
   of the system clock.

   The profiling report will be printed when glXDestroyContext is called
   _if_ the MESA_PROFILE environment variable is set.  You must be sure
   glXDestroyContext is called before exiting to get the profile report.
   The report will be printed to stdout and includes:

      glBegin/glEnd - number of glBegin/glEnd pairs called, total time,
         and rate in pairs/second.
      vertexes transformed - number of vertices transformed, lit, clip-
         tested, fogged, and mapped to window coordinates, total time,
         and rate in vertexes/second.
      points rasterized - number of points drawn, time, and rate.
      lines rasterized - number of lines drawn, time, and rate.
      polygons rasterized - number of polygons drawn, time and rate.
      overhead - time between glBegin/glEnd not accounted for by vertexes,
         points, lines, and polygons.  This is time spent executing
         glVertex, glNormal, glColor, etc, clipping, primitive assembly,
         and user code between glBegin/glEnd.
      glClear - number of glClears executed, total time and clears/second.
      SwapBuffers - number of swaps executed, total time and swaps/second.

   Note that the real point, line, and polygon rates should be computed by
      adding in the vertex transformation and overhead time factors.


Linux SVGA driver:
   Mesa 1.2.6 has a preliminary Linux SVGA driver for Mesa.  It's based
   on the SVGA library included with Linux.  The driver isn't finished
   yet.  I'm not too familiar with SVGA graphics so I could use some help
   finishing it.  Contact Brian if you want to help.

   To enable the SVGA driver, edit the Make-config file and add -DSVGA to
   the CFLAGS for Linux and add -lvga to the LIBS variable.  There are
   several test programs (vtest.c, vgears.c, vindex.c) in the demos
   directory.  See the include/GL/svgamesa.h and src/svgamesa.c files for
   more information about the driver.


Extensions:
   The following OpenGL extensions are currently implemented:

      GL_EXT_blend_color - allows blending with a constant color
      GL_EXT_blend_minmax - blend min/max operator
      GL_EXT_blend_logic_op - allows glLogicOp to work in RGBA mode
      GL_EXT_blend_subtract - blend subtraction operator
      GL_EXT_vertex_array - vertex array extension
      GL_EXT_paletted_texture - for color indexed textures
      GL_EXT_shared_texture_palette - shared texture palette
      GLX_EXT_visual_info - GLX visual and transparent pixel extension

   For detailed information about the extensions see:
      ftp://sgigate.sgi.com/pub/opengl/extensions/

   There are four Mesa-specific GL/GLX extensions at this time.

   GLX_MESA_pixmap_colormap

      This extension adds the GLX function:

         GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
                                           Pixmap pixmap, Colormap cmap )

      It is an alternative to the standard glXCreateGLXPixmap() function.
      Since Mesa supports RGB rendering into any X visual, not just True-
      Color or DirectColor, Mesa needs colormap information to convert RGB
      values into pixel values.  An X window carries this information but a
      pixmap does not.  This function associates a colormap to a GLX pixmap.
      See the demos/glxpixmap.c file for an example of how to use this
      extension.

   GLX_MESA_release_buffers

      Mesa associates a set of ancillary (depth, accumulation, stencil and
      alpha) buffers with each X window it draws into.  These ancillary
      buffers are allocated for each X window the first time the X window
      is passed to glXMakeCurrent().  Mesa, however, can't detect when an
      X window has been destroyed in order to free the ancillary buffers.

      The best it can do is to check for recently destroyed windows whenever
      the client calls the glXCreateContext() or glXDestroyContext()
      functions.  This may not be sufficient in all situations though.

      The GLX_MESA_release_buffers extension allows a client to explicitly
      deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
      just before an X window is destroyed.  For example:

         #ifdef GLX_MESA_release_buffers
            glXReleaseBuffersMESA( dpy, window );
         #endif
         XDestroyWindow( dpy, window );

      This extension is new in Mesa 2.0.

   GL_MESA_window_pos

      This extension adds the glWindowPos*MESA() functions.  These functions
      are convenient alternatives to glRasterPos*() because they set the
      current raster position to a specific window coordinate, bypassing the
      usual modelview, projection and viewport transformations.  This is
      especially useful for setting the position for glDrawPixels() or
      glBitmap() to a specific window coordinate.

      X and Y parameters (positive and negative) are directly mapped to
      window coordinates.  Z is a depth value clamped to the range [0,1].
      W is directly mapped.  The current raster position valid flag is
      always set to true.  The current raster distance is set to zero.
      The current raster color and texture coordinate are updated in the
      same manner as glRasterPos().  In selection mode a hit record is
      always generated.

      Programs using OpenGL, not Mesa, may also use the glWindowPos*MESA()
      functions by including winpos.h from the src directory and by
      compiling and linking with the winpos.c file from the src directory.

   GL_MESA_resize_buffers

      This extension adds the glResizeBuffersMESA() function.  When this
      function is called, Mesa checks if the color buffer (window) has
      been resized.  If it has, Mesa reallocates the ancillary (depth,
      stencil, accum) buffers.

      Normally, Mesa checks for window size changes whenever glViewport()
      is called.  In some applications it may not be appropriate to call
      glViewport() when the window is resized.  Such applications should
      call glResizeBuffersMESA() instead so the ancillary buffers are
      correctly updated.

      This extension is new in version 2.2.


Version 2.x features:
   Version 2.x of Mesa implements the OpenGL 1.1 API.  The following
   functions are new in Mesa 2.x:

   Texture mapping:
    glAreTexturesResident
    glBindTexture
    glCopyTexImage1D
    glCopyTexImage2D
    glCopyTexSubImage1D
    glCopyTexSubImage2D
    glDeleteTextures
    glGenTextures
    glIsTexture
    glPrioritizeTextures
    glTexSubImage1D
    glTexSubImage2D

   Vertex Arrays:
    glArrayElement
    glColorPointer
    glDrawElements
    glEdgeFlagPointer
    glIndexPointer
    glInterleavedArrays
    glNormalPointer
    glTexCoordPointer
    glVertexPointer

   Client state management:
    glDisableClientState
    glEnableClientState
    glPopClientAttrib
    glPushClientAttrib

   Misc:
    glGetPointer
    glIndexub
    glIndexubv
    glPolygonOffset


Summary of environment variables:
   MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
   MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
   MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
   MESA_DEBUG - if defined, error messages are printed to stderr
   MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
   MESA_GAMMA - gamma correction coefficients (X only)
   MESA_PROFILE - enable reporting of performance measurements
   MESA_XSYNC - enable synchronous X behavior (for debugging only)
   MESA_NO_DITHER - disable dithering, overriding glEnable(GL_DITHER)



Mailing List
============

There is a Mesa mailing list.  Its purpose is to let Mesa users exchange
any ideas, questions, and/or problems they have.  To subscribe, send the
following message to the address [e-mail]

    add [e-mail] mesa

For example:

    add [e-mail] mesa

You will receive a welcome message from the list server when you have been
added to the list.

To unsubscribe from the list send the following message to
[e-mail]

    del [e-mail] mesa

Thanks to Pedro Vazquez ([e-mail]) for setting up and
maintaing the list.



WWW Page
========

There is a Mesa WWW page:  http://www.ssec.wisc.edu/~brianp/Mesa.html



Contributed code
================

There is a contrib/ subdirectory on the Mesa ftp site which contains
contributions from Mesa users.  See the README file in that directory for
more information.

Anyone is welcome to contribute code to the Mesa project, provided you
agree to the GNU license.

If you're contribution code to the Mesa library itself:
   1. Try to write clean code (uniform indentation, comments, meaningful
      identifiers, etc).  It must be readable and maintainable!
   2. Test your code.  On several occations I've incorporated code from
      users which later turned out to have bugs.  Now, I'm pretty hesitant
      to use code which doesn't look good.

If you're contributing changes to Makefile or Make-config be sure your
changes won't cause headaches for other users.  If you're not sure then
maybe a new config target is appropriate.



Reporting Bugs
==============

If you think you've found a bug in Mesa first check if a newer version of
Mesa is available.  Next, check ftp://iris.ssec.wisc.edu/pub/Mesa to see
if a patch for your bug is there.  Otherwise, report the problem.

Since many people have contributed code to Mesa it's important that you
report a bug to the right person:

Area            Contact
----------------------    -------------------------------------------
GLU polygon tessellator    Bogdan Sikorski  [e-mail]
GLU NURBS        Bogdan Sikorski  [e-mail]
Evaluators        Bernd Barsuhn  [e-mail]
Xt/Motif widgets    Thorsten Ohl  [e-mail]
              and Jeroen van der Zijp  [e-mail]
Fortran bindings    William Mitchell  [e-mail]
Amiga driver        Stefan Zivkovic  [e-mail]
Amiwin driver        Victor Ng-Thow-Hing  [e-mail]
Macintosh driver    Miklos Fazekas  [e-mail]
NeXT driver        Pascal Thibaudeau [e-mail]
OS/2 driver        Darren Abbott  [e-mail]
VMS support        Jouk Jansen  [e-mail]
Windows 95/NT driver    Li Wei  [e-mail]
MS-DOS driver        Charlie Wallace  [e-mail]
BeOS driver        Tinic Uro  [e-mail]
GLX encoder/decoder    Steven Parker  [e-mail]
3Dfx driver        David Bucciarelli  [e-mail]
SciTech MGL driver    Kendall Bennett  [e-mail]
Cygnus Win32 support    Stephane Rehel  [e-mail]
S3 Virge driver        [e-mail] or [e-mail]
Mailing list help    Pedro Vazquez  [e-mail]

EVERYTHING ELSE-->    Brian Paul  [e-mail]

Feel free to cc Brian on messages sent to anyone listed above.  None of
the people on this list are under any obligation to respond to bug reports.
However, they have been pretty helpful so far.

When you report a bug please give as much information as possible including
your hardware/software environment, which version of Mesa you're using, how
to reproduce the problem, and if possible, a test program.



Known Bugs
==========

1. Evaluator automatic normal vectors are miscalculated under certain
   conditions.

2. glCopyPixels gives undefined results when source and destination regions
   overlap and pixel zoom!=1.0.

3. Mesa doesn't work too well on Crays.  The problem is that Crays do not
   have the exact C data type sizes which Mesa's X driver relies on.  Better
   Cray support may or may not be seen in the future.

4. gluCylinder, and probably other GLU quadrics, don't generate texture
   coordinates when drawing in point or line mode.

5. NURBS code does not copy user supplied data as it should; it just
   stores pointers to that data. For the moment all data must be valid and
   available utill the gluEndSurface() or the gluEndCurve() call.



Future Plans
============

1. Display list optimization:  scan for duplicate vertices and normals in
   order to reduce number of transformations needed.

2. Implement a "generational" depth buffer which only has to be cleared
   once every 'n' frames.

3. Integrate Mesa into the XFree86 X server.

5. Reorganize src/ directory: put drivers in separate directories.



Why is it the library called Mesa?
==================================

Why not?  More obvious names were considered but had to be rejected:
FreeGL (too similar to the trademarked name OpenGL), Free3D (too similar
to DEC's Open3D).  Also, I'm tired of acronyms.

[I've recently discovered that at least two other software products use the
name Mesa.  A name change may be necessary in the future.  Suggestions are
welcome!]



Contributors
============

Many people have contributed to Mesa.  I really appreciate the help!
Among the contributors are:

Erich Stefan Boleyn - for the glRotate code and testing early Mesa
Joe Kiniry, Kendall Bennett - for opinions and discussion
Marc Buffat - for the gluProject and gluUnproject functions
Bernd Barsuhn, Volker Weiss - for the new implementation of evaluators
Philip Brown - for the initial GLX, GLUT implementation
Thorsten Ohl - for glXUseXFont() and glBitmap bug fixes
Thomas Malik - for new invert_matrix and other xform.c code
Michael Pichler - for X colormap code and numerous bug reports/fixes
Thorsten Ohl, Jeroen van der Zijp - for the Xt/Motif widgets
Bob Mercier - for the new 8-bit RGB dithering code
Pedro Vazquez - for establishing the Mesa mailing list
Bogdan Sikorski - for the GLU polygon tessellation code and NURBS
Linas Vepstas - for his extrusion and swept surface library
Frederic Devernay - for improved X shared memory support
Asif Khan - for bringing _many_ subtle bugs to my attention
Mark Peterson - for the MS Windows driver for Mesa
Gene Lett and Kerris Renkin - for diagnosing several rasterization problems
Alex De Bruyn - for HP Color Recovery display support
Miklos Fazekas - for the Macintosh driver
Frederic Devernay - for many Sun configs and lots of useful feedback
Victor Ng-Thow-Hing - for the Amiga AmiWin port
Bill Triggs - improved texture mapping features
Martin Bernhard - added texture coordinate generation to GLU quadric functions
Pascal Thibaudeau - NeXT support
Jean-Luc Daems, Jacques Leroy - numerous optimization in Mesa 1.2.7
Joerg Hessdoerfer - 16-bit TrueColor optimizations in Mesa 1.2.7
Stefan Zivkovic - for the Amiga driver
Peter McDermott - for the Cirrus Logic Mondello driver
Constantin Filin - for mipmapping/texture mapping code
Darren Abbott - for the OS/2 XFree86 port
Hal Brand - for X line and polygon stippling code
Eric Berdahl - for doing much of the internal overhaul work of Mesa for 2.0
Frank Ortega - for bug fixes and many helpful comments
Mats Lofkvist - for finding a number of bugs in Mesa 2.0
Charlie Wallace - for the MS-DOS driver
Li Wei - for updated Windows 95/NT driver
Pete French - for the OpenStep driver
Tinic Uro - for the BeOS driver
Daniel Barrero - for the 3-D texture mapping extension
Randy Frank - for many bug reports/fixes and code contributions
David Bucciarelli - for the 3Dfx driver
Paul Metzger - for Linux version of 3Dfx driver
Daryll Strauss - for the Linux Glide library
Kendall Bennet - for the SciTech MGL driver
Matthew Stewart-Smith - for updating the Linux SVGA driver
Magnus Lundin - for fixing a mipmap bug
Daniel Barrero - for the GL_EXT_point_parameters extension
Josh Vanderhoof - for Intel X86 assembly language optimizations
S3 - for the S3/Virge Windows 95 driver



This file last revised:  November 13, 1997