Mesa 3.0 Copyright (C) 1995-1998 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. 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 Avid Technology 1925 Andover St. Tewksbury, MA 01876 brianp@elastic.avid.com My work on Mesa is in no way associated with my work at Avid Technology. 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. 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 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-3.0.tar.gz and optionally MesaDemos-3.0.tar.gz Unpack with: gzcat MesaLib-3.0.tar.gz | tar xf - gzcat MesaDemos-3.0.tar.gz | tar xf - If you don't have gzcat try zcat instead. 2. Unix compressed/tar Download MesaLib-3.0.tar.Z and optionally MesaDemos-3.0.tar.Z Unpack with: zcat MesaLib-3.0.tar.Z | tar xf - zcat MesaDemos-3.0.tar.Z | tar xf - 3. ZIP format Download MesaLib-3.0.zip and optionally MesaDemos-3.0.zip Unpack with: unzip MesaLib-3.0.zip unzip MesaDemos-3.0.zip After unpacking you should have the following files in the new Mesa-3.0 directory: README - this file README.* - detailed information for specific OS/hardware systems LICENSE - the GNU library license IAFA-PACKAGE - description file VERSIONS - version history RELNOTES - version-specific release notes FUTURE - future development plans/ideas CONFORM - results of conformance testing Makefile - top-level Makefile Make-config - system configurations used by the Makefiles 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 NeXT/ - NeXT demo programs BeOS/ - BeOS demo programs mondello/ - Cirrus Logic Mondello 3-D accelerator code *mms* - makefiles for VMS OpenStep/ - OpenStep files ggi/ - Linux GGI demos 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://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 Compiling and Installation ========================== See the appropriate README.* file for system-specific instructions: System README file ----------------- ------------ Unix/X11 README.X11 Windows 95/N% README.WIN32 DOS README.DOS Linux/Windows w/ 3Dfx hardware README.3DFX Linux with GGI README.GGI Linux with threading README.MITS Amigas with Amiwin README.AMIWIN BeOS README.BEOS LynxOS README.LYNXOS SciTech MGL README.MGL IBM OS/2 README.OS2 Windows w/ S3 Virge hardware README.VIRGE VMS README.VMS Header and library files: After you've compiled Mesa and tried the demos I recommend the following procedure for "installing" Mesa on Unix systems. 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 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: 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 (william.mitchell@nist.gov) 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: 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_polygon_offset - polygon Z offset GL_EXT_vertex_array - vertex array extension GL_EXT_texture_object - texture objects GL_EXT_texture3D - 3D texture mapping GL_EXT_paletted_texture - for color indexed textures GL_EXT_shared_texture_palette - shared texture palette GL_EXT_point_parameters - point parameters as a function of Z GL_EXT_rescale_normal - rescale normal vectors GL_EXT_abgr - GL_ABGR pixel format GL_SGIS_texture_edge_clamp - limit texture filtering to texture edge GL_EXT_multitexture - multitexture extension (Be warned: this extension will be replaced in the future by GL_ARB_multitexture) GL_SGIS_multitexture - multitexture extension (Be warned: this extension will be replaced in the future by GL_ARB_multitexture) For detailed information about the extensions see www.opengl.org Other OS-specific extensions are documented in the other README.* files. 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. 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) 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 mesa-request@iqm.unicamp.br add yourname@your.internet.address mesa For example: add brianp@elastic.avid.com 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 mesa-request@iqm.unicamp.br del yourname@your.internet.address mesa Thanks to Pedro Vazquez (vazquez@iqm.unicamp.br) 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 bogdan@cira.it GLU NURBS Bogdan Sikorski bogdan@cira.it Evaluators Bernd Barsuhn bernd@berlin.muc.de Xt/Motif widgets Thorsten Ohl ohl@crunch.ikp.physik.th-darmstadt.de and Jeroen van der Zijp jvz@cyberia.cfdrc.com Fortran bindings William Mitchell william.mitchell@nist.gov Amiga driver Stefan Zivkovic d94sz@efd.lth.se Amiwin driver Victor Ng-Thow-Hing victorng@dgp.toronto.edu Macintosh driver Miklos Fazekas boga@augusta.elte.hu NeXT driver Pascal Thibaudeau pthibaud@frbdx11.cribx1.u-bordeaux.fr OS/2 driver Darren Abbott abbott@hiwaay.net VMS support Jouk Jansen joukj@crys.chem.uva.nl Windows 95/NT driver Theodore A. Jump tjump@spgs.com MS-DOS driver Charlie Wallace cwallace@dreamworks.com BeOS driver Tinic Uro 5uro@informatik.uni-hamburg.de GLX encoder/decoder Steven Parker sparker@taz.cs.utah.edu 3Dfx driver David Bucciarelli tech.hmw@plus.it SciTech MGL driver Kendall Bennett KendallB@scitechsoft.com Cygnus Win32 support Stephane Rehel rehel@kluster.com S3 Virge driver rkoduri@s3.com or pcgamedev@s3.com Multithreading work John Stone johns@umr.edu Mailing list help Pedro Vazquez vazquez@iqm.unicamp.br EVERYTHING ELSE--> Brian Paul brianp@elastic.avid.com 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. Integrate Mesa into the XFree86 X server and support more 3D hardware 2. Further optimizations for AMD 3Dnow!, MMX, etc. 3. Establish a new Mesa WWW site, ftp site and archive maintainer 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 -------------------------------------------------------------------------- $Id: README,v 3.10 1998/09/18 03:10:03 brianp Exp $