AmigActive 6/AACD06.ISO/AACD/System/Mesa-3.1/docs/README

Text File | 2000-01-05 | 25KB | 658 lines

                                 Mesa 3.1

                     Copyright (C) 1995-1999  Brian Paul

                              www.mesa3d.org


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.

While Mesa is not a licensed OpenGL implementation, it is currently
being tested with the OpenGL conformance tests.  For the current
conformance status see the CONFORM file included in the Mesa distribution.

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



Author
======

Brian Paul
[e-mail]



Copyright Information
=====================

The Mesa distribution consists of several components.  Different copyrights
apply to different components.  For example, GLUT is copyrighted by Mark
Kilgard, some demo programs are copyrighted by SGI, some of the Mesa
device drivers are copyrighted by the respective authors.

Through version 3.0, the core Mesa library has been distributed under the
GNU Library General Public License.

In Mesa 3.1 the core library will instead be released under an XFree86-
style copyright.  The copyright is being changed so that Mesa can be
integrated into the XFree86 X server in order to support 3D hardware
acceleration.  Mesa will still be a stand-alone library too.

If you have contributed code to Mesa in the past and don't want your
code included in the non-GNU LGPL version please contact Brian to
have your code removed.

See the docs/COPYRIGHT file for more information.


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.  That said, Mesa is still a viable alternative
to OpenGL.  Most OpenGL applications should run with Mesa without code
changes.

Since version 2.0, Mesa implements the OpenGL 1.1 API specification.
Since version 3.0, Mesa implements the OpenGL 1.2 API specification.

Only a few features are not yet implemented:

    trimmed NURBS
    polygon antialiasing


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 ftp://ftp.mesa3d.org/mesa/
See the Mesa home page for mirrors.

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-3.1.tar.gz and optionally MesaDemos-3.1.tar.gz
    Unpack with:
        gzcat MesaLib-3.1.tar.gz | tar xf -
        gzcat MesaDemos-3.1.tar.gz | tar xf -
    or,
        gunzip MesaLib-3.1.tar.gz ; tar xf MesaLib-3.1.tar
        gunzip MesaDemos-3.1.tar.gz ; tar xf MesaLib-3.1.tar
    or,
        tar zxf MesaLib-3.1.tar.gz
        tar zxf MesaDemos-3.1.tar.gz

    If you don't have gzcat try zcat instead.

2. Unix compressed/tar

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

3. ZIP format

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


After unpacking you'll have these files (and more):

docs/README    - this file
docs/README.*    - detailed information for specific OS/hardware systems
docs/COPYRIGHT    - copyright info
docs/VERSIONS    - version history
docs/RELNOTES    - release notes for the new version
docs/CONFORM    - results of conformance testing
Makefile.X11    - "old" top-level Makefile for X11-based systems
Make-config    - "old" system configurations used by the Makefiles
bin/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
util/        - handly utility functions
widgets-mesa/    - Mesa widgets for Xt/Motif
widgets-sgi/    - SGI OpenGL widgets for Xt/Motif

and if you downloaded and unpacked the demos:

src-glut/    - source code for GLUT toolkit
demos/        - GLUT demos
xdemos/        - X11 and SVGA demo programs
samples/    - sample OpenGL programs from SGI
book/        - example programs from the OpenGL Programming Guide,
          converted to GLUT by Mark Kilgard, from GLUT distribution.
3Dfx/        - 3Dfx demos and tests
mtdemos/    - multi-threading demos


Other Mesa-related stuff is at  ftp://ftp.mesa3d.org/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



Compiling and Installation
==========================

See the INSTALL file for instructions.



Compile-time 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.
   After changing config.h you must recompile Mesa.



Using the Library
=================

Performance Tips for software rendering:
   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.


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.


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: [this may no longer work in Mesa 3.1]
   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:
   See the include/GL/gl.h header for a list of supported extensions
   (search for "Compile-time tests".  Documentation for extensions can
   be found at www.opengl.org.

   There are a few Mesa-specific extensions:

   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.


Runtime Configuration File:
   See the CONFIG file for information on how to setup a Mesa config file.


Version 2.x features:
   Version 2.x of Mesa implements the OpenGL 1.1 API with the following
   new features.

   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


Version 3.x features:
   Version 3.x of Mesa implements the OpenGL 1.2 API with the following
   new features:

   BGR, BGRA and packed pixel formats
   New texture border clamp mode
   glDrawRangeElements()
   standard 3-D texturing
   advanced MIPMAP control
   separate specular color interpolation


Summary of environment variables:
   MESA_DEBUG - if defined, error messages are printed to stderr
   MESA_NO_DITHER - disable dithering, overriding glEnable(GL_DITHER)
   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_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 X debugging only)
   MESA_INFO - if defined, print Mesa version, vendor, extension, etc info


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.



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 copyright of the relevant code.

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.




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

If you think you've found a bug in Mesa first check if a newer version of
Mesa is available from the web page at www.mesa3d.org.
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    Theodore A. Jump  [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    No maintainer.  Any volunteers?
S3 Virge driver        [e-mail] or [e-mail]
Multithreading work    John Stone  [e-mail]
Allegro DJGPP driver    Bernhard Tschirren  [e-mail]
Direct3D driver        Leigh McRae  [e-mail]
GGI driver        Jon Taylor  [e-mail]
Mailing list help    Pedro Vazquez  [e-mail]

EVERYTHING ELSE-->    [e-mail]

Feel free to cc [e-mail] 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. 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.

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

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



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.



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
Ted Jump - for Windows compilation support
Keith Whitwell - for version 3.1 vertex transformation optimizations
Holger Waechtler - for 3DNow! optimizations
Gareth Hughes - for the GLU 1.2 polygon tessellator


--------------------------------------------------------------------------
$Id: README,v 3.23.2.2 1999/12/14 20:55:29 brianp Exp $