
		      The Mesa 3-D graphics library

			      Version 1.2.2

		      Copyright (C) 1995  Brian Paul



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

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
Space Science and Engineering Center
University of Wisconsin - Madison
1225 W. Dayton St.
Madison, WI  53706

brianp@ssec.wisc.edu



Status
======

I've been working on this library in my spare time since August, 1993.
It's currently about 90% complete.  You'll find that most programs which
use the OpenGL tk, aux or GLUT toolkits will work with Mesa without changing
the source code at all.

Features which are complete:
	all glBegin() primitives
	all model and view transformations
	clipping (against user clip planes and view volume)
	lighting
	smooth shading
	depth buffering
	accumulation buffer
	alpha testing/blending
	stencil buffer
	dithering
	logic operations
	evaluators  (curves and surfaces)
	feedback/selection
	fog (per-pixel or per-vertex)
	polygon/line stippling
	read/write/copy pixels
	tk and aux libraries for X11
	context switching (multiple windows)
	RGB mode simulated in color mapped windows
	the GLX library (as close as I can get)

Features which are mostly complete:
	display lists
	texture mapping
	the GLU library
	NURBS

Missing features:
	anti-aliasing
	mipmapping, non-point-sampled texture mapping
	glPixelZoom

The primary goal of this library has been correctness, speed was secondary
(but not neglected!).  Many optimizations can still be done.

The core library was originally written on an Amiga using the DCC compiler.
Later on it was moved to an SGI.  Current development is done on an SGI
system.

Mesa works on most Unix workstations with ANSI C and X11.  Now there's also
a Microsoft Windows driver (see windows/README.WIN).  A very outdated and
inoperative Amiga driver is also included.

Please send bug reports to the author.  Include information describing
your system, which version of Mesa you're using, and how to reproduce the
problem.  Bug fixes are especially welcome.  Note that some parts of Mesa
(widgets, GLU tesselator, NURBS, etc) were contributed by others and any
bugs in those components should be sent to the respective author.

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

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



Manifest
========

The archive file Mesa-1.2.2.tar.Z can be unpacked with:
	zcat Mesa-1.2.2.tar.Z | tar xvf -

The archive file Mesa-1.2.2.tar.gz can be unpacked with:
	gzcat Mesa-1.2.2.tar.gz | tar xvf -

After you unpacking you should have the following:

Mesa/README		- this file
Mesa/LICENSE		- the GNU library license
Mesa/Makefile		- top-level Makefile
Mesa/Make-config	- system configurations used by the Makefiles
Mesa/mklib.*		- scripts for making shared libraries for some systems
Mesa/include/		- application include files
Mesa/lib/		- application libraries, created during installation
Mesa/src/		- source code for core library
Mesa/src-glu/		- source code for utility library
Mesa/src-tk/		- source code for tk library
Mesa/src-aux/		- source code for aux library
Mesa/demos/		- demo programs
Mesa/samples/		- sample OpenGL programs from SGI
Mesa/book/		- example programs from the OpenGL Programming Guide
Mesa/GLUT/		- the home for GLUT
Mesa/widgets/		- the Mesa widgets
Mesa/windows/		- Microsoft Windows driver stuff


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 <system>'.  Most popular Unix/X workstations are currently
supported.

The top-level makefile will execute the makefiles in a number of sub-
directories.  When finished, there should be executables in the "demos/",
"samples/", and "book/" directories for you to try out.

If your system 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.

The file src/config.h has many parameters which you can tune before building.

If you want to build the Mesa widgets read the widgets/INSTALL file.

If you want to build the GLUT library read the GLUT/README-MESA file.



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

See the windows/README.WIN file for details.  Note that any problems with
the Windows driver should be addressed to Mark Peterson.



Using the library (with Unix/X11 systems)
=========================================

Header and library files:
   To use the library with your own applications you may want to move the
   files in "include/" to "/usr/local/include/" and the libraries in "lib/"
   to "/usr/local/lib/".  Then compile your graphics application with
   "-I/usr/local/include" and link with "-L/usr/local/lib -lMesaGL -lMesaGLU",
   for example.  Look at the demos/Makefile for an example.

   While Mesa includes its own header files you can optionally compile Mesa
   using the real OpenGL header files if you have them.  Just remove or move
   the GL/gl.h, GL/glx.h, and GL/glu.h Mesa files and replace them with copies
   or links to the real OpenGL header files.  Then recompile Mesa.


Toolkits:
   Initially, you may write your own Mesa programs using the aux or tk tool-
   kits which are used in the OpenGL Programming Guide and in SGI's demos,
   respectively.  However, these toolkits weren't meant for use in real app-
   lications.  You have several alternatives:

      1. Go directly to the X/Mesa interface using the functions described in
      include/GL/xmesa.h.  This requires experience with X programming.

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

      3. GLUT (OpenGL Utility Toolkit) was written by Mark Kilgard at SGI as
      a replacement for aux and tk.  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 GLUT/README-MESA.

      4. Use a Mesa widgets.  Look in the widgets/ directory for more info.


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. Use double buffering as it's often faster than single buffering
   4. 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.
   5. Recompile Mesa with more optimization if possible.
   6. Try to maximize the amount of drawing done between glBegin/glEnd pairs.
   7. Use the MESA_BACK_BUFFER variable to find best performance in double
      buffered mode.


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 when an error occurs.


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 (though not all are
   supported) 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 re-
   quested, 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:
   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.  Using the
   MESA_BACK_BUFFER variable you can experiment to see which is faster for
   your application.  


Colormaps:
   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 happend 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.



Miscellaneous
=============

See the src/NOTES file for more detailed info about the implementation
of Mesa.  See the book/NOTES and samples/NOTES files for information
about which demos work or don't work, and why.

The latest version of Mesa can be found at iris.ssec.wisc.edu in pub/Mesa/

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

There is a Mesa mailing list.  To subscribe, send the following message to
the address listserv@iqm.unicamp.br

subs mesa <your name>
set mesa mail ack

For example:

subs mesa Brian Paul
set mesa mail ack

The second line tells the list processor to send you a copy of your own
messages.

You will receive a welcome message from the list server when you have been
added to the list.  It tells you how to post messages to the list, how
to unsubscribe, etc.  Thanks to Pedro Vazquez for setting up the list.

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



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

1. Polygons with two nearly-co-located vertices may be mis-rendered or
   accidentally culled.

2. Perspective-corrected texture map coordinate interpolation can fail under
   certain conditions due to numerical error.

3. There may be "cracks" between renderings of adjacent NURBS surfaces.

4. NURBS, for now, can't have other attributes info than geometric data.

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



Version History
===============

1.0 beta   February 1995
    Initial release

1.1 beta   March 4, 1995
    Many improvements:
	- faster point and line drawing (2x faster)
	- more systems supported, better Makefiles
	- many small bug fixes
	- pseudo-GLX functions added
	- GLUT support
	- new implementation of evaluators (eval2.c)
	- Renamed lib*.a files to avoid collisions

1.1.1 beta   March 7, 1995
    Reverted from eval2.c to eval.c due to FPE on Linux
    more speed improvements
    more Makefile changes

1.1.2 beta   March 14,1995
    Using eval2.c again
    more FPE-prevention checks (0-length normals are OK)
    a few small bug fixes
    much faster pixel logic ops!
    faster transformation arithmetic
    implementation of SGI's blending extensions
    glXUseXFont implemented
    added MESA_DEBUG environment variable support

1.1.3 beta   March 31,1995
    gluScaleImage() and gluBuild2DMipMaps() implemented
    Mesa widgets for Xt/Motif
    more bug fixes
    blendEXT demos
    added environment variables for selecting visuals
    almost all GLUT demos work correctly now
    faster X device driver functions

1.1.4 beta   April 20,1995
    Bug fixes:
	- missing #define SEEK_SET in src-tk/image.c
	- compile glShadeModel into display lists
	- fixed pow() domain error in src/light.c
	- fixed "flickering bitmaps" in double buffer mode
	- fixed tk.h and aux.h for C++
	- state of LIGHT_MODEL_LOCAL_VIEWER was inverted
    New features:
	- MUCH, MUCH nicer dithering in 8-bit RGB mode
	- updated widgets and widget demos
	- Implemented GLXPixmap functions
	- Added GLU 1.1 and GLX 1.1 functions
	- Changed the X/Mesa interface API, more versatile
	- Implemented gluPartialDisk()

1.2   May 22,1995
    Bug fixes:
	- IRIX 4.x makefile problem
	- modified tk to share root colormap as needed
	- gluLookAt normalization problem
	- suppress Expose, NoExpose events in swapbuffers
	- glBitmap() and glDrawPixels() clipping
    New features:
	- GL_BLEND, GL_MODULATE, GL_DECAL, and GL_REPLACE_EXT texture
	      modes implemented
	- texture maps stored more efficiently
	- texture maps can be compiled into display lists
	- Bogdan Sikorski's GLU polygon tesselation code
	- Linas Vepstas's sweep and extrusion library
	- glXCreateContext()'s shareList parameter works as it's supposed to.
	      XMesaCreateContext() updated to accept a shareList parameter too.
	- Mesa can be compiled with real OpenGL .h files
	- MESA_BACK_BUFFER environment variable
	- better GLX error checking

1.2.1   June 22, 1995
    Bug fixes:
	- X/Mesa double buffer window resize crash
	- widgets now pass PointerMotion events
	- X/Mesa incorrect default clear color and drawing color
	- more robust X MIT-SHM support in X/Mesa
	- glTexImage( format=GL_LUMINANCE ) didn't work
	- GL_LINE mode polygons with line width > 1.0 could cause a crash
	- numerous feedback bugs
	- glReadPixels() from depth buffer was wrong
	- error prone depth and stencil buffer allocation
    New features:
	- Preliminary Microsoft Windows driver
	- Implemented a number of missing functions: glEvalCoord[12][df]v(),
	    glGet...(), etc.
	- Added a few missing symbols to gl.h and glu.h
	- Faster rendering of smooth-shaded, RGBA, depth-buffered polygons.
	- Faster rendering of lines when width=2.0
	- Stencil-related functions now work in display lists
    Changes:
	- renamed aux.h as glaux.h (MS-DOS names can't start with aux)
	- most filenames are in 8.3 format to accomodate MS-DOS
	- use GLubytes to store arrays of colors instead of GLints

1.2.2   August 2, 1995
    New features:
	- texture mapped points and lines
	- NURBS! (but not 100% complete)
	- viewports may safely extend beyond window boundaries
	- MESA_PRIVATE_CMAP environment variable
	- Grayscale X display support
	- two new demos:  demos/gears.c and demos/shadow.c
	- MachTen for MacIntosh configuration
    Bug fixes:
	- glGet*(GL_DEPTH_BITS) returned bytes, not bits
	- point, line, and bitmap rasterization suffered from roundoff errors
	- fixed a division by zero error in line clippping
	- occasional wrong default background color really fixed!
	- glDepthFunc(GL_ALWAYS) with glDepthMask(GL_FALSE) didn't work
	- gluBuild2DMipmaps malloc problem fixed
	- view volume clipping of smooth shaded lines resulted in bad colors
    Changes:
	- new visual selection method in glXChooseVisual()
	- improved GLU quadric functions
	- call XSync for glFinish and XFlush for glFlush
	- glVertex() calls now use a function pointer to avoid conditionals
	- removed contrib directory from Mesa tar file (available on ftp site)
	- AIX shared library support
	- Removed GLUenum type as it's not in OpenGL


Coming up...
	All new triangle rasterization
	MacIntosh driver



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!]



Thanks to
=========

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
Thorsten Ohl, Jeroen van der Zijp - for the widget set
Bob Mercier - for the new 8-bit RGB dithering code
Pedro Vazquez - for establishing the Mesa mailing list
Bogdan Sikorski - for the GLU polygon tesselation 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


Your contributionss are greatly appreciated!



This file last revised:  1 August 1995

