
		      The Mesa 3-D graphics library

			    Version 1.1.3 beta

		      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 or aux toolkits will work with Mesa without changing the
source code at all.

Features which are complete include:
	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

Features which aren't yet complete include:
	display lists (~90% complete)
	texture mapping (partially implemented)
	anti-aliasing
	the GLU library (partially implemented)
	see the src/NOTES file for more info


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.  The source has been compiled and tested on a variety of other
Unix/X11 systems.

Only an Xlib device driver is currently available.  Any Unix system
with X should be able to compile the library with little work.  The Amiga
driver is currently out of date and does not work.  Other device drivers
should be straightforward.

The Mesa/X driver uses simple dithering to allow RGB mode rendering on 8-bit
or 1-bit(!) displays when a TrueColor visual isn't available.  A 24-bit
display is recommended for RGB mode rendering.



Manifest
========

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

After you unpacking you should see the following items:

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/include/		- application include files
Mesa/lib/		- application libraries, directory created by make
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 preliminary Mesa widgets



Installation
============

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.



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

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", for example.
Look at the demos/Makefile for an example.

Since the OpenGL API is used, OpenGL documentation can serve as the
documentation for Mesa's core functions.

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. You may want to go directly to the X/Mesa interface using the functions
described in include/GL/xmesa.h.  This requires experience with X pro-
gramming.

2. You may want to use the recently implemented pseudo-GLX functions.
These functions look like, and try to act like, the real GLX functions
used by OpenGL in conjunction with the X window system.  They haven't been
fully tested but seem to work fine with GLUT...

3. GLUT (OpenGL Utility Toolkit) was written by Mark Kilgard at SGI as
a replacement for aux and tk.  It provides a simple and portable interface
to the underlying window system allowing you to write OpenGL applications
quickly and easily.  GLUT isn't included with Mesa but you'll find instruc-
tions on how to get and build GLUT in the file GLUT/README-MESA.

4. If you're using Xt or Motif you'll probably want to use a Mesa widget.
Look in the widgets/ directory for more info.  WARNING:  use the Mesa
widgets at your own risk.  There are known bugs which authors and I will
fix when we have time.


A few tips on getting the best performance from Mesa:

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.


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
now 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.


Display Modes:  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 envi-
ronment 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:  <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:
	$ MESA_RGB_VISUAL="TrueColor 8"
	$ MESA_CI_VISUAL="PseudoColor 12"
	$ MESA_RGB_VISUAL="PseudoColor 8"



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.

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

A number of people are working on Mesa features.  See the WWW page for
more info.

A Mesa mailing list would be nice.  I don't have automated mailing list
software on my system and don't have the time to maintain such a list
manually.  Are there any volunteers to set up a Mesa mailing list?



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

Version    Release Date	   Comments
---------  --------------  -------------------------------------------
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



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.



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



This file last revised:  31 March 1995
