Mesa
Version 2.0
Copyright (C) 1995-1996 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.
* OpenGL(R) is a registered trademark of Silicon Graphics, Inc.
Author
======
Brian Paul
Avid Technology
6400 EnterPrise Lane, Suite 201
Madison, WI 53719
brianp@elastic.avid.com
Formerly employed at the Space Science and Engineering Center at the
University of Wisconsin in Madison, WI.
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.
As of the 2.0 release Mesa implements the OpenGL 1.1 API specification.
Only a few features are not yet implemented:
trimmed NURBS
line and polygon antialiasing
glGetTexGen* functions
glGetPolygonStipple function
glGetLightiv function
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, and NeXT systems. See
below for more information.
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, non-Unix/X11 device drivers, 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:
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.
The archive file Mesa-2.0.tar.Z can be unpacked with:
zcat Mesa-2.0.tar.Z | tar xf -
The archive file Mesa-2.0.tar.gz can be unpacked with:
gzcat Mesa-2.0.tar.gz | tar xf -
After you unpacking you should have the following files in the Mesa-2.0
directory:
README - this file
README.AMIGA - instructions for using Mesa on Amigas
README.AMIWIN - instructions for using Mesa on Amigas with AmiWin (X11)
README.WIN - instructions for using Mesa with MS Windows
README.GLUT - instructions for using Mesa with GLUT
README.OS2 - instructions for using Mesa with OS/2 and XFree86
LICENSE - the GNU library license
IAFA-PACKAGE - description file
VERSIONS - version history
Makefile - top-level Makefile
Make-config - system configurations used by the Makefiles
Imakefile - for OS/2
mklib.* - shell scripts for making shared libraries for some systems
include/ - application include files
lib/ - application libraries, created during installation
src/ - source code for core library
src-glu/ - source code for utility library
src-tk/ - source code for tk library
src-aux/ - source code for aux library
demos/ - demo programs
samples/ - sample OpenGL programs from SGI
book/ - example programs from the OpenGL Programming Guide
util/ - handly utility functions
widgets-old/ - Mesa widgets for Xt/Motif from Mesa 1.2.x
widgets-sgi/ - SGI OpenGL widgets for Xt/Motif
windows/ - Microsoft Windows driver stuff, from Mesa 1.2.x
windows2/ - Microsoft Windows driver stuff, for Mesa 2.0
NeXT/ - NeXT demo programs
mondello/ - Cirrus Logic Mondello 3-D accelerator code
amiga/ - AmigaDOS driver
nt/ - Windows NT driver
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 <config>'. 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 you only want
to compile the contents of one subdirectory you can 'cd' to that directory
and type 'make <config>' there. For example, to just compile the main
Mesa library: cd src ; make <config>
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.
If you want to build the Mesa/OpenGL widgets you can either use the SGI
OpenGL widget in widgets-sgi/ or the Mesa 1.2.x widget in widgets-old/.
Look in those directories for more information.
If you want to build the GLUT library read the README.GLUT 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.
Note to QNX users: if you have problems running the demos try setting the
stack size to 200K or larger with -N200K, for example.
Note to SunOS 5.4 users: The X shared memory extension may not work
correctly. If Mesa prints an error message to the effect of "Shared memory
error" then you'll have to append the following three lines to the end of
your /etc/system file then reboot:
set shmsys:shminfo_shmmax = 0x2000000
set shmsys:shminfo_shmmni = 0x1000
set shmsys:shminfo_shmseg = 0x100
Installation for Amigas
=======================
To use Mesa on Amigas with AmiWin (an X server for the Amiga), read the
README.AMIWIN file.
To use Mesa on ordinary Amigas read the README.AMIGA file. Problems or
question about the Amiga driver should be sent to Stefan Zivkovic
(d94sz@efd.lth.se).
Installation for Microsoft Windows
==================================
See the windows2/README file for more information. The windows/ directory
is from Mesa 1.2.x and probably will need some hacking to work with
Mesa 2.0.
Installation for Macintosh
==========================
*** Mesa 2.0 does not currently work on the Mac ***
From ftp://iris.ssec.wisc.edu/pub/Mesa/contrib download these files:
mesa0.31b.sit.hqx
GLUT4Mac.sit.hqx
Miklos Fazekas (boga@augusta.elte.hu) should be contacted if you have
questions about the Mac driver.
Installation for NeXT
=====================
*** Mesa 2.0 does not currently work on the Next ***
Simply typing "make next" should compile Mesa and a number of NeXT demo
programs found in the NeXT/ directory. NeXT support was contributed by
Pascal Thibaudeau (pascal@galileo.slip.u-bordeaux.fr). It was implemented
through Mesa's Off-Screen rendering interface.
Installation for OS/2
=====================
*** Mesa 2.0 does not currently work on OS/2 ***
See the README.OS2 file for details. Problems or questions about Mesa
for OS/2 should be sent to Darren Abbott (abbott@hiwaay.net).
Using the library
=================
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.
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-1.2.8/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 (X11 only):
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 README.GLUT.
3. Use an Xt/Motif widget. Look in the widgets-old/ or widgets-sgi
directories 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. 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.
9. Optimized polygon rasterizers are used 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 done 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
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.
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: <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 (X11 only):
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. If you
need depth buffering the XImage will almost surely be faster. Exper-
iment with the MESA_BACK_BUFFER variable to see which is faster for
your application.
Colormaps (X11 only):
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:
The Fortan bindings of Mesa 1.2.x have been removed. 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.
Gamma correction (X11 only):
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).
Alex De Bruyn reports that gamma values of 1.6, 1.6 and 1.9 work well
on HP displays using the HP-ColorRecovery technology.
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.
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_vertex_array - vertex array extension
GLX_EXT_visual_info - GLX visual and transparent pixel extension
For detailed information about the extensions see:
ftp://sgigate.sgi.com/pub/opengl/extensions/
There are three Mesa-specific GL/GLX extensions at this time.
GLX_MESA_pixmap_colormap
This extension adds the GLX function:
GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
Pixmap pixmap, Colormap cmap )
It is an alternative to the standard glXCreateGLXPixmap() function.
Since Mesa supports RGB rendering into any X visual, not just True-
Color or DirectColor, Mesa needs colormap information to convert RGB
values into pixel values. An X window carries this information but a
pixmap does not. This function associates a colormap to a GLX pixmap.
See the demos/glxpixmap.c file for an example of how to use this
extension.
GLX_MESA_release_buffers
Mesa's depth, accumulation, stencil and alpha buffers are associated
with X windows. These buffers are allocated for a window the first
time the window is passed to glXMakeCurrent(). However, Mesa cannot
know exactly when an X window has been destroyed. To deallocate the
ancillary buffers associated with a window, Mesa users should call
glXReleaseBuffers() before destroying a window with XDestroyWindow.
For example:
#ifdef GLX_MESA_release_buffers
glXReleaseBuffersMESA( dpy, window );
#endif
XDestroyWindow( dpy, window );
This extension is new in Mesa 2.0. In the future, the glXDestroyContext
function will examine the display's window tree to find destroyed
windows and release the associated ancillary buffers.
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.
Version 2.0 features:
Version 2.x of Mesa implements the OpenGL 1.1 API. The following
functions are new in Mesa 2.x:
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
Summary of environment variables:
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_BACKBUFFER - specifies how to implement the back color buffer (X only)
MESA_DEBUG - if defined, error messages are printed to stderr
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 debugging only)
Mailing List
============
There is a Mesa mailing list. To subscribe, send the following message to
the address listproc@iqm.unicamp.br
subs mesa <your name>
For example:
subs mesa Brian Paul
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 listproc@iqm.
unicamp.br
unsubscribe mesa
Thanks to Pedro Vazquez (vazquez@iqm.unicamp.br) for setting up 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.
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.
Future Plans
============
1. Display list optimization: scan for duplicate vertices and normals in
order to reduce number of transformations needed.
2. Implement a "generational" depth buffer which only has to be cleared
once every 'n' frames.
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!]
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 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
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
This file last revised: October 10, 1996
Short: 3D library, OpenGL based, Amiga v1.1
Uploader: d94sz@efd.lth.se (Stefan Zivkovic)
Author: brianp@ssec.wisc.edu (BrianP) Amiga Port: d94sz@efd.lth.se (Stefan Zivkovic)
Type: dev/c
Requires: System v39, SAS C Compiler
Version: Mesa v2.0 Amiga version 1.4
The Mesa 3-D graphics library
Version 2.0
Copyright (C) 1995-1996 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.
Miscellaneous
=============
There is a Amiga Mesa WWW page: http://www.efd.lth.se/~d94sz/amesa
and the orginal Mesa WWW page: http://www.ssec.wisc.edu/~brianp/Mesa.html
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
Author
======
Brian Paul
Space Science and Engineering Center
University of Wisconsin - Madison
1225 W. Dayton St.
Madison, WI 53706
brianp@ssec.wisc.edu
AMIGA PORT of MESA: THE OPENGL SOFTWARE EMULATION by Stefan Zivkovic
====================================================================
When I first read about OPENGL in the summer of 1995 I was happy and filled with
joy. A few days later I surfed to the mesa homepage but only to discover that
there was no Amiga version. In the beginning of 1996 someone released a AMIWIN
version so I took the archive home to try it out, but it stayed packed on my HD.
One day when I was home and poking around with my HD I saw the archive and
started to try to make it work. Without luck as it seemed that you needed
the AMIWIN Includes and LIBFILES. But I also discovered that it was possible
to port it with not to much effort (WRONG THERE) so I begun.
For the Amiga there is only three important files + one directory.
src/Amigamesa.c The mesa GL Amiga implementation
(ddsample.c with some Amiga code)
src-tk/Awindow.c The tk (and aux) machine specific code)
include/GL/Amigamesa.h The prototypes for Amigamesa
Amiga/#?
Installing
==========
To spread the amiga files over the archive you will nead lha in your path
and run the installer script in /amiga (or just unpack AMesa.lha yourself)
Compiling
=========
Just execute mklib.amiga (will apeare if you have instelled it correctly)
About the code.
===============
The Code is compiled with cpu=020 math=ieee
If you would like it different then use the /Amiga/scoptions read next statement
The common scoptions file is in /Amiga
Here exists a scoption that is used in the WHOLE package, chance math here
and it will reflect in all dirs
In /Amiga/library there is previews of files to the shared-library version
(This don't work yet but should give you an idea of how to use it)
In /Amiga/Examples there should be some amiga-demo code,
but I've got no code yet so feel free to send me your own examples.
In this state it only renders on a window on a up-to 256 col display but I
have planes to port it to CyberGFX the problem is that I don't own a gfx-card
so this is very low on my priority list, this could change if I had one :)
all tk actions in tkExec are not finished. But most of them is. (low priority)
Most of the examples work. (ALL?)
etc. etc.
Write your own OpenGL code
==========================
1. For a easy start look at the examples in book and modify them
The examples uses a portable layer toolkit Not amiga specific at all
until The shared library is ready you have to define AMIGALIB when
using <GL/gl.h>
2. For a better amigaprogram just open a window (on your favourite screen) and
add a few lines in your source:
-----------------------------------------------------------------------------
/* ADD where you want it */
#include <GL/gl.h>
Init() /* sets up viewport and projections */
{
glMatrixMode (GL_PROJECTION); /* prepare for and then */
glLoadIdentity (); /* define the projection */
glFrustum (-1.0, 1.0, -1.0, 1.0, 1.5, 20.0);/* transformation */
glMatrixMode (GL_MODELVIEW); /* back to modelview matrix*/
glViewport (0, 0, 200, 200); /* define the viewport */
} /* ^ ^ ^^^ ^^^--- The size of the mesa/openGL window */
/* ADD In after you opened your window */
struct amigamesa_context *glcont;
glcont=AmigaMesaCreateContextTags(
AMA_DrawMode,AMESA_AGA,
AMA_Window,(unsigned long) test_window, // My Windowptr
AMA_RastPort,(unsigned long) test_window->RPort,
AMA_Screen,(unsigned long) test_window->WScreen,
AMA_DoubleBuf, GL_FALSE, // or GL_TRUE
AMA_RGBMode, GL_TRUE, // -"-
AMA_Left, test_window->BorderLeft, // offset from left edgr
AMA_Bottom, test_window->BorderBottom+1, // offset from bottom edgr
TAG_DONE,0);
// Neaded tags is AMA_RastPort,AMA_Screen if you suply AMA_Window
// it looks for RastPort and Screen in it so a Window_ptr will due.
if (glcont)
{
AmigaMesaMakeCurrent(glcont);
/* All your gl comands */
/*handle_window_events(test_window); or whatever */
AmigaMesaDestroyContext(glcont);
}
/* Don't forget to call glViewport() when you resize the window */
------------------------------------------------------------------------------
if you set doublebuff to GL_TRUE then you just switch buffer with
AmigaMesaSwapBuffers(glcont);
For more info of the internal of the Amiga port you can check the files
src/Amigamesa.c and include/GL/Amigamesa.h for tk check src-tk/Awindow.c
And info on how do write your own gfx-rutines se include/GL/amigamesa.h for
more instructions
THINGS THAT MAY GO WRONG
========================
WARNIG The api has changes on AmigaMesaCreateContext() it now is called with
a taglist see /include/GL/amigamesa.h
If it won't compile check your env:sc/scoptions maybe there is some conflict
for example this setings are vitale Precision=MIXED, NoStackExtend,
NoStackCheck. If your not sure just rename your env:sc/scoptions while compiling
It compiles but all examples crash everytime:
Set your stack high about 50kb or more.
Linking complains about not finding _glBegin(): or @glBegin():
You have compiled some code using the stack and som using registers as
parameter pasing, You have to chose one of them and us it on both places.
The color are realy bad:
To emulate 24bit I alloc 255 colors in the begining spread over the
palette and then use it. If you like better color buy a GFX-Card.
And wait for gfx-card versions.
Resizing is sometimes very very unhelthy.
LATEST VERSION:
===============
http://www.efd.lth.se/~d94sz/amesa
TODO:
=====
Fix resizing bug.
all tk stuff.
FUTURE:
=======
The API will probably change a little.( Long names -> shorter ex
AmigaMesaDestroyContext renames to MesaDestroyContext...)
A shared library would be nice. (I have started)
Faster and better. (I have a few ideas)
CyberGFX support. (I don't have a Gfx card myself any offer to
give me one would result in CyberGFX support :)
HISTORY:
========
Release:
0.8 This code worked with Mesa 1.2.6 and all makefiles also.
Due to when I released it Mesa 1.2.7 was released and some changes was made
it didn't work.
0.9 Makefiles is remapped to work with Mesa 1.2.7.
Double buffering works.
Implemented fast_poly_draw (big speed improvement).
tkExec a few more tests were done. (right & middle mousebutton is not
implemented)
1.0 I've put a common scoption file in /Amiga (thanks to Kamil Iskra).
Due to the common scoptions you could change CPU and math more easy ,and
compiler options set to default math=ieee, cpu=020 so that it works on
1200's and up
Many bugfixes (thanks to Daniel Jönsson).
Have fixed the smakefile name collision with AMIWIN version.
Mesa 1.2.8 Fixed.
Spellcorrection of the docs were made by Peter Sandén.
All tk's windows are opened on a pubscreen named "MESA" if it exists.
1.1 Faster and more stable (Manny thanks to Jorge Acereda (JAM))
Faster pen usage now it allocates 255 pens and use them (thanks to
Stefan Burström)
A few enchantments here and there.
Fixed a smake bug ignore=A only works in the lates SAS version now I
have changed it to IGN=ALL (Thanx to everyone who reported this one)
1.2 Removed math from smakefiles SAS handles this better self. (Kamil Iskra)
Fixed a serius drawing bug (appered when using GL_SMOTH).
Fixed a very flexible programing API for future gfx-board implementations
Added a BOOL AmigaMesaSetDefs(struct TagItem *tagList); usefull for future encantments
***'API change: AmigaMesaCreateContext uses taglist se include/GL/amigamesa.h
Faster on dubelbuffer rendering. (Now i convert whole dubel buffer c2p)
Easier to integrate future gfx-cards rutines. look in include/GL/amigamesa.h
tk toolkit fixed to work better thanks to Georg 'Wulf' Krämer
1.4 Uppdated to reflect Mesa 2.0
Small Bugfixes.
Please contact me with suggestions and additional info.
You can reach me at:
d94sz@efd.lth.se
Or mail:
Stefan Zivkovic
Kämnärsv. 9L:225
226 46 LUND
Or Phone:
+46 46 150763
AMIGA AMIWIN PORT of MESA: THE OPENGL SOFTWARE EMULATION
========================================================
Port by Victor Ng-Thow-Hing (victorng@dgp.toronto.edu)
Original Author (Brian Paul (brianp@ssec.wisc.edu)
Dec.1 , 1995: Port of release Mesa 1.2.5
- Modifications made to minimize changes to Mesa distribution.
Nov.25, 1995: Port of release Mesa 1.2.4
HISTORY
=======
As a 3D graphics progammer, I was increasingly frustrated to see OpenGL
appearing on so many platforms EXCEPT the Amiga. Up to now, the task
of porting OpenGL directly from native Amiga drawing routines seemed like
a daunting task. However, two important events made this port possible.
First of all, Brian Paul wrote Mesa, the OpenGL software emulator that
can be found on many platforms - except the Amiga and Atari (who cares
about the latter!). This was pretty ironic considering that Mesa was
originally prototyped on an Amiga! The second great event was when
Holger Kruse developed AmiWin, the X11R6 server for the Amiga (definitely
register for this great piece of software) and released a development kit
so one could compile X programs with SAS/C.
Since Mesa had X routines as its primitive drawing operations, this made
a marriage of Mesa and Amiwin feasible. I copied over the sources from
an ftp site, played with the code, wrote some Smakefiles, and voila,
I had OpenGL programs displaying on my Amiga.
Although the speed is nothing to be impressed about, this port can be
potentially useful to those who want to quickly test their code in
wireframe or perhaps learn more about programming with the OpenGL API.
I hope Amiga developers will continue to write excellent software for
their machine, especially more X clients for Amiwin. If you have any
solutions so some of my problems in the porting notes, please send me
some email!
See you around,
Vic.
HOW TO CREATE THE LIBRARIES AND SAMPLE CODE
===========================================
Just run the shell script mklib.amiwin in the mesa directory. This will
make all the libraries and copy them into the mesa/lib directory. If you
don't want to compile everything, just go to the desired directory and
type smake in that directory.
Change any of the variables in the smakefiles as necessary. You will REQUIRE
the Amiwin development kit to compile these libraries since you need X11.LIB
and the shareable X libraries. Some examples require the AmiTCP4.0
net.lib static link library and related header files for unix related
header files and functions like sleep().
HOW TO USE THE MESA LIBRARIES
=============================
Study the Smakefiles in the demos, samples and book directories for the
proper SAS/C options and linkable libraries to use. Basically aux calls
require Mesaaux.LIB, gl calls require MesaGL.LIB, glu calls MesaGLU.LIB,
tk calls Mesatk.LIB. There is a preliminary port of MesaGLUT.LIB toolkit
available in the lib directory with the other Mesa libraries. However,
it seems to cause crashes on some of the sample code. Someone else may want
to attempt a more stable port.
PORTING NOTES TO AMIWIN
=======================
My strategy of porting was to leave as much of the code untouched as
possible. I surrounded any amiga specific changes with
#ifdef AMIWIN ... #endif or #ifndef AMIWIN ... #endif preprocessor
symbols. The code was ported on an Amiga 2000, with Fusion 40 accelerator
and a Picasso II graphics card. The SAS/C 6.56 compiler was used, with
the AmiWin 2.16 X development kit.
All compilations were done for a 68040 CPU with 68882 math coprocessor for
maximum speed. Please edit the smakefile for other compilers.
I wrote smakefiles for the directories I ported. I omitted the Windows
and Widgets directories. The former is for MS Windows and the latter
requires Motif, which is not easily available for the Amiga.
Here are the changes I did per directory:
* mesa
Nov. 25, 1995 v 1.2.4
- added a mklib.amiwin shell script that will make all the libraries and
sample code for Mesa
- created this readme file: readme.AMIGA
* mesa/include
Dec. 1, 1995 v 1.2.5
- added the following to GL/xmesa.h
#ifdef AMIWIN
#include <pragmas/xlib_pragmas.h>
extern struct Library *XLibBase;
#endif
NET CHANGE: xmesa.h
* mesa/src
Nov. 25, 1995 v 1.2.4
- added the necessary pragma calls for X functions to the following:
xmesa1.c, xmesa2.c, xmesa3.c, xfonts.c, glx.c
This prevents undefined symbols errors during the linking phase for
X library calls
- created smakefile
Dec. 1, 1995 v 1.2.5
- removed AMIWIN includes from xmesa1.c, xmesa2.c, xmesa3.c, xfonts.c,
glx.c since they are now defined in include/GL/xmesa.h
NET CHANGE: smakefile
* mesa/src-tk
Nov. 25, 1995 v 1.2.4
- added the necessary pragma calls for X functions to the following:
private.h
- created smakefile
Dec. 1, 1995 v 1.2.5
- removed AMIWIN includes from private.h since it is now defined in
include/GL/xmesa.h
NET CHANGE: smakefile
* mesa/src-glu
Nov. 25, 1995 v 1.2.4
- created smakefile
NET CHANGE: smakefile
* mesa/src-aux
Nov. 25, 1995 v 1.2.4
- added the necessary pragma calls for X functions to the following:
glaux.c
- created smakefile
NET CHANGE: glaux.c, smakefile
* mesa/demos
Nov. 25, 1995 v 1.2.4
- added the necessary pragma calls for X functions to the following:
xdemo.c, glxdemo.c, offset.c
- created smakefile
- put #ifndef AMIWIN ... #endif around sleep() calls in xdemo.c since
they are not part of AmigaDOS.
Dec. 1, 1995 v 1.2.5
- removed AMIWIN defines from xdemo.c, glxdemo.c, offset.c since
already defined in include/GL/xmesa.h
- modified Smakefile to include header and includes from the AmiTCP4.0
net.lib linkable library to provide unix-compatible sys/time.h and
the sleep() function
- removed AMIWIN defines in xdemo.c since sleep() now defined
NET CHANGE: smakefile
* mesa/samples
Nov. 25, 1995 v 1.2.4
- added the necessary pragma calls for X functions to the following:
oglinfo.c
- created smakefile
- put #ifndef AMIWIN ... #endif around sleep() in blendxor.c
- removed olympic from smakefile targets since <sys/time.h> not defined
Dec. 1, 1995 v 1.2.5
- removed AMIWIN defines from oglinfo.c, since already defined in
include/GL/xmesa.h
- modified Smakefile to include header and includes from the AmiTCP4.0
net.lib linkable library to provide unix-compatible sys/time.h and
the sleep() function
- removed AMIWIN defines in blendxor.c for sleep()
- added AMIWIN defines around _MACHTEN_ in olympic.c since xrandom()
functions are not defined in any libraries
- added olympic back into the Smakefile targets
NET CHANGE: smakefile, olympic.c
* mesa/book
Nov. 25, 1995 v 1.2.4
- created smakefile
- removed accpersp and dof from smakefile targets since the SAS/C compile seems to
confuse the near,far variables with near/far memory models.
NET CHANGE: smakefile
* mesa/windows
Dec. 1, 1995 v 1.2.5
- Removed directory to save space since this is only needed for Windows based
machines.
Instructions for Using GLUT with Mesa
Mark Kilgard's GLUT (OpenGL Utility Toolkit) is a toolkit for quickly
and easily writing OpenGL demos and applications.
GLUT has been used successfully with Mesa on many systems. If you have
problems contact Brian Paul if you think the problem is caused by Mesa.
Contact Mark Kilgard, or post to the Mesa mailing list, if you think the
problem is in GLUT.
At the time of Mesa's 2.0 release the latest version of GLUT is 3.1
Here's how to get GLUT and build it using Mesa:
1. Use your WWW browser to open the URL:
http://reality.sgi.com/employees/mjk_asd/glut3/glut3.html
Under "About the GLUT source code distribution" is a link to the
distribution file glut-3.1.tar.Z Click on it to download GLUT.
2. In your shell, move glut-3.1.tar.Z into the Mesa-2.x directory and
unpack it with:
zcat glut.3.1.tar.Z | tar xvf -
3. cd to the GLUT directory:
cd glut-3.1
4. Make a backup copy of Glut.cf:
cp Glut.cf Glut.cf.orig
5. Make sure GLut.cf is writable since we have to edit it:
chmod +w Glut.cf
6. If you're using a Sun with Solaris then define the following two
environment variables from your shell:
OGLHOME to where you've installed Mesa (like /usr/home/brian/Mesa)
OPENWINHOME to something like /usr/openwin
7. Edit Glut.cf as follows. Note that there are two places where these
changes may have to be made depending on whether you're using a Sun
or not.
change: EXTRA_INCLUDES = -I$(TOP)
to look like: EXTRA_INCLUDES = -I$(TOP)/../include -I$(TOP)
change: OPENGL = -lGL
to look like: OPENGL = $(TOP)/../lib/libMesaGL.a
change: GLU = -lGLU
to look like: GLU = $(TOP)/../lib/libMesaGLU.a
NOTE: if you made shared Mesa libraries, the suffixes might be .so instead
of .a
8. Run the mkmkfiles.imake script:
mkmkfiles.imake
9. Run make:
make
10. If all goes well there should be many executables in the progs/
directories for you to try out.
11. You may want to copy the lib/glut/libglut.a file to wherever you have
your Mesa libraries (libMesaGL.a, libMesaGLU.a, etc) if you're going to
use it for your own work.
To build for OS/2 after unpacking original distribution and Mesa for
XFree86/OS2 programming kit:
1. Edit Imakefile in this directory and change TOP variable to top-level
directory (the directory the Imakefile is in).
2. xmkmf -a
3. make
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.