The Mesa 3-D graphics library Version 1.2.5 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) glPixelZoom display lists Features which are mostly complete: texture mapping the GLU library NURBS Missing features: anti-aliasing mipmapping, non-point-sampled texture mapping glGetTexGen* functions glGetPolygonStipple The primary goal of this library has been correctness, speed was secondary (but not neglected!). Optimizations will be the focus of most future work. 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. There are also drivers for Microsoft Windows and the Macintosh. See below for more infor- mation. 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. Anyone is welcome to contribute code to the Mesa project, provided you agree to the GNU license. 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 Getting the software ==================== The primary Mesa ftp site is iris.ssec.wisc.edu in the pub/Mesa directory. There is also a contributors directory in pub/Mesa/contrib. Manifest ======== The archive file Mesa-1.2.5.tar.Z can be unpacked with: zcat Mesa-1.2.5.tar.Z | tar xvf - The archive file Mesa-1.2.5.tar.gz can be unpacked with: gzcat Mesa-1.2.5.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 '. 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. Note to 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. 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. Installation for Macintosh ========================== NOTE: At this time, the Mac driver does not work with Mesa 1.2.5 because of changes in the device driver. Use Mesa 1.2.3 until the Mac driver is updated. In addition to the Mesa.tar.Z file you'll also have to get the following files from the ftp contrib directory: GLUT4Mac.sit.hqx Mesa4Mac.sit.1.hqx Mesa4Mac.sit.2.hqx Miklos Fazekas (mti-inf@odin.net) should be contacted if you have questions about the Mac driver. Using the library (with Unix/X11 systems) ========================================= 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/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. 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. 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: 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. 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. 2. 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. 3. Use a Mesa widgets. Look in the widgets/ directory for more info. 4. Go directly to the X/Mesa interface using the functions described in include/GL/xmesa.h. This requires experience with X programming. Using GLX is probably a better choice because it's portable. 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. This can be especially beneficial with Mesa 1.2.3 or later because of its "vectorized" transformation code. 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 whenever 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 (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: 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. Experiment with the MESA_BACK_BUFFER variable 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 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: Mesa 1.2.4 introduces a preliminary Fortran API to Mesa. Only a subset of the gl* functions are supported at this time. None of the glu* functions are available. Also, you'll have to write your window system interface code in C or use the Fortan interface to GLUT since the GLX, XMesa, and widget interfaces don't work with Fortran. To use Mesa from Fortran you must include Mesa/include/GL/fgl.h in your program. All the "GL_FOO_BAR" constants are identical in name and value to their C counterparts. API function names, however, are different in that they are all prefixed with 'fgl' instead of 'gl.' Link your Fortran application with libMesaGL.a just like you would for a C application. See the Mesa/src/fortran.c file to see how wrappers are constructed for each gl* function. If a function you need doesn't have a wrapper yet, please try to implement it yourself then send the new code to the author. The Fortran interface has only been tested on a few systems (IRIX, AIX) at this time. However, the fortran.c file structure should be flexible enough to adapt to most other system's C/Fortran calling conventions. See the comments in that file for more info. demos/fdraw.f and demos/ftest.c is an example of using the Fortran API. Also read include/GL/fgl.h for comments about Fortran API function argument types. Gamma correction: 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). 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. Miscellaneous ============= 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 listproc@iqm.unicamp.br subs mesa For example: subs mesa Brian Paul 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 Mesa ftp site which contains contributions from Mesa users. See the README file in that directory for more information. Known Bugs ========== 1. Perspective-corrected texture map coordinate interpolation can fail under certain conditions due to numerical error. 2. There may be "cracks" between renderings of adjacent NURBS surfaces. 3. NURBS, for now, can't have attribute info other than geometric data. 4. Evaluator automatic normal vectors are miscalculated under certain conditions. 5. glCopyPixels gives undefined results when source and destination regions overlap and pixel zoom!=1.0. 6. Mesa doesn't work too well on Crays. The problem is that Crays do not have the exact C data type sizes which Mesa relies on. Better Cray support may or may not be seen in the future. 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 1.2.3 September 26, 1995 New features: - Mesa header files now equivalent to SGI OpenGL headers - Support for HP's Color Recovery dithering displays - Faster vertex transformation - Faster raster operations into X windows under certain conditions - New configurations: HP w/ shared libs, Ultrix w/ GCC, Data General - 4-bit visuals now supported Bug fixes: - glScissor bug fixed - round-off errors in clipping lines against clip planes fixed - byte swapping between hosts and display servers implemented - glGetError() can be called without a current rendering context - problem with accidentally culled polygons is fixed - fixed some widget compilation problems 1.2.4 November 17, 1995 New features: - More speed improvements (lighting, fogging, polygon drawing) - Window system and OS-independent off-screen rendering - Preliminary Fortran bindings - glPolygonOffsetEXT implemented - glColorMask and glIndexMask now fully implemented - glPixelZoom implemented - display lists fully implemented - gamma correction - dithering in 8-bit TrueColor/DirectColor visuals Changes: - Improved device driver interface - tk.h renamed to gltk.h to avoid conflicts with Tcl's Tk - Dithering support moved from core into device driver Bug fixes: - glEnable/Disable( GL_LIGHTING ) didn't always take effect - glReadPixels byte swapping was broken - glMaterial with pname==GL_AMBIENT_AND_DIFFUSE was broken - duplicate glColor4b() prototype in GL/gl.h removed - stripes in wave -ci demo fixed - GL_LINEAR_MIPMAP_NEAREST had wrong value - bugs in HP Color Recovery support fixed - fixed bug when blending lines, points, bitmaps outside of window 1.2.5 November 30, 1995 New Features: - updated MS Windows driver - new implementation of StaticGray/GrayScale visual support Bug fixes: - pixelzooming with gamma correction or blending didn't work - HP color recovery visual wasn't being picked by glXChooseVisual - glClear didn't always observe glColorMask changes - olympic and offset demos didn't compile on some Suns - texcoord clamping wasn't correct - a polygon optimization introduced an occasional sampling problem Coming up: better texture mapping faster polygon and line drawing 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 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 Your contributions are greatly appreciated! This file last revised: 30 November 1995