Commit 0b27acea authored by Brian Paul's avatar Brian Paul

Documentation/website overhaul. The website content and doc/ directory

are now merged and are one and the same.
parent dc32636c
......@@ -250,15 +250,9 @@ HPCR glClear(GL_COLOR_BUFFER_BIT) dithering
to HP systems with the HPCR (Color Recovery) system.
Extensions:
The following OpenGL GLX extensions are currently implemented:
GLX_EXT_visual_info - GLX visual and transparent pixel extension
GLX_EXT_visual_rating - GLX visual caveats
For detailed information about the extensions see www.opengl.org
There are four Mesa-specific GL/GLX extensions at this time.
Extensions
==========
There are three Mesa-specific GLX extensions at this time.
GLX_MESA_pixmap_colormap
......@@ -317,4 +311,4 @@ Summary of X-related environment variables:
----------------------------------------------------------------------
$Id: README.X11,v 3.9 2002/10/29 23:42:48 brianp Exp $
$Id: README.X11,v 3.10 2003/03/08 17:38:57 brianp Exp $
<HTML>
<title>Banner</title>
<body text="#ffffff" bgcolor="#aa4444">
<center>
<p>
<font size="5">The Mesa 3D Graphics Library</font>
</p>
</center>
</body>
</html>
\ No newline at end of file
<HTML>
<TITLE>Mesa Bug Reporting</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Bug Database</H1>
<p>
Bug reports can be filed in the <a
href="http://sourceforge.net/bugs/?group_id=3" target="_parent">Bug
Database</a> on sourceforge.net. Please follow these guidelines:
</p>
<ul>
<li>Make sure you're using the most recent version of Mesa
<li>Make sure your bug isn't already reported
<li>Include as much information as possible in the report
<li>Provide a simple GLUT-based test program if possible
<li>Check back for follow-ups to the report
</ul>
<p>
Bug reports will automatically be forwarded to the Mesa developer's list.
</p>
<p>
The easier a bug is to reproduce, the sooner it will be fixed.
Please do everything you can to facilitate quickly fixing bugs.
If your bug report is vague or your test program doesn't compile
easily, the problem may not be fixed very quickly.
</p>
</BODY>
</HTML>
This diff is collapsed.
<html>
<title>Contents</title>
<body text="#ffffff" bgcolor="#119955" link="#ffffff" vlink="#dddddd" alink="#ffffff">
<b>Documentation</b>
<ul>
<li><a href="intro.html" target="MainFrame">Introduction</a>
<li><a href="news.html" target="MainFrame">News</a>
<li><a href="systems.html" target="MainFrame">Platforms and Drivers</a>
<li><a href="license.html" target="MainFrame">License & Copyright</a>
<li><a href="faq.html" target="MainFrame">FAQ</a>
<li><a href="VERSIONS" target="MainFrame">Version History</a>
<li><a href="relnotes.html" target="MainFrame">Release Notes</a>
<li><a href="thanks.html" target="MainFrame">Acknowledgements</a>
<li><a href="conform.html" target="MainFrame">Conformance Testing</a>
<li>more docs below...
</ul>
<b>Download / Install</b>
<ul>
<li><a href="http://www.sourceforge.net/projects/mesa3d" target="_parent">Stable Release (5.0.1)</a>
<li><a href="download.html" target="MainFrame">Downloading/Unpacking</a>
<li><a href="install.html" target="MainFrame">Installation</a>
<li><a href="glu.html" target="MainFrame">SGI's GLU</a>
</ul>
<b>Resources</b>
<ul>
<li><a href="lists.html" target="MainFrame">Mailing Lists</a>
<li><a href="bugs.html" target="MainFrame">Bug Database</a>
<li><a href="webmaster.html" target="MainFrame">Webmaster</a>
</ul>
<b>User Topics</b>
<ul>
<LI><A HREF="envvars.html" target="MainFrame">Environment Variables</A>
<LI><A HREF="osmesa.html" target="MainFrame">Off-Screen Rendering</A>
<LI><A HREF="debugging.html" target="MainFrame">Debugging Tips</A>
<LI><A HREF="perf.html" target="MainFrame">Performance Tips</A>
<LI><A HREF="extensions.html" target="MainFrame">Mesa Extensions</A>
<LI><A HREF="mangling.html" target="MainFrame">Function Name Mangling</A>
</ul>
<b>Developer Topics</b>
<ul>
<li><a href="http://sourceforge.net/projects/mesa3d" target="_parent">SourceForge homepage</a>
<li><a href="cvs_branches.html" target="MainFrame">CVS Branch Info</a>
<li><a href="cvs_anonymous.html" target="MainFrame">Anonymous CVS Access</a>
<li><a href="utilities.html" target="MainFrame">Utilities</a>
<li><a href="helpwanted.html" target="MainFrame">Help Wanted</a>
<li><a href="devinfo.html" target="MainFrame">Development Notes</a>
<li><a href="sourcedocs.html" target="MainFrame">Source Documentation</a>
<li><a href="subset.html" target="MainFrame">Subset Information</a>
<LI><A HREF="custom.html" target="MainFrame">Custom Development</A>
</ul>
<b>Links</b>
<ul>
<li><a href="http://www.opengl.org" target="_parent">OpenGL website</a>
<li><a href="http://dri.sourceforge.net" target="_parent">DRI website</a>
<li><a href="games.html" target="MainFrame">Games and Entertainment</a>
<li><a href="libraries.html" target="MainFrame">Libraries and Toolkits</a>
<li><a href="modelers.html" target="MainFrame">Modeling and Rendering</a>
<li><a href="science.html" target="MainFrame">Science and Technical</a>
<li><a href="utility.html" target="MainFrame">Utilities</a>
<li><a href="demos.html" target="MainFrame">Demos / other</a>
</ul>
<A HREF="http://sourceforge.net"
target="_parent"><IMG SRC="http://sourceforge.net/sflogo.php?group_id=3&type=1"
WIDTH="88" HEIGHT="31" ALIGN="BOTTOM" ALT="Sourceforge.net" BORDER="0"></A>
</body>
</html>
\ No newline at end of file
<HTML>
<TITLE>Custom Development</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Custom Development</H1>
<p>
Mesa is primarily developed and maintained on a volunteer basis.
Some Mesa development work has been done in conjuction with contracted
projects, such as the XFree86/DRI drivers.
</p>
<p>
<pre>[Begin shameless plug]</pre>
If you have a need for specific or custom Mesa development work,
<a href="http://www.tungstengraphics.com/" target="_parent">
Tungsten Graphics, Inc.</a> may be able to help you.
<pre>[End shameless plug]</pre>
</p>
</body>
</html>
<HTML>
<TITLE>Anonymous CVS</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Anonymous CVS</H1>
<p>
Anonymous, public, read-only access to the code in CVS is
available. Here are the basic instructions for Unix systems:
</p>
<ol>
<li>Install CVS client software on your computer. Version 1.9.28 is known to work.
</li><li>Login as an anonymous user: <code>cvs -d:pserver:anonymous@cvs.mesa3d.sourceforge.net:/cvsroot/mesa3d
login</code>
</li><li>Just hit return at the <code>CVS password:</code> prompt.
</li><li>Then checkout mesa: <code>cvs -z3 -d:pserver:anonymous@cvs.mesa3d.sourceforge.net:/cvsroot/mesa3d
co Mesa</code>
</li></ol>
<p>To update your Mesa CVS source to the latest CVS source:
</p><ol>
<li><code>cd Mesa</code>
</li><li><code>cvs -z3 -d:pserver:anonymous@cvs.mesa3d.sourceforge.net:/cvsroot/mesa3d
update</code>
</li></ol>
<p>You can browse the Mesa source code in CVS
<a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/">here.
</a>
</p>
</body>
</html>
\ No newline at end of file
<HTML>
<TITLE>CVS Branches</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>CVS Branch Information</H1>
<p>
The Mesa3d sources are split up into two branches. A branch that is to
remain as stable as possible, and an unstable branch where development
work for new versions will be done. The current stable branch is
tagged <code>mesa_3_4_branch</code> while the unstable branch is just
the default. The goal is to adopt and even/odd stable/unstable
versioning scheme similar to the Linux kernel. Hence releases of Mesa
3.2.X should be more stable than Mesa 3.3.X.<p></p> <p>All versions of
Mesa after 3.0 will also be tagged with a branch id. Mesa 3.1 has the
tag <code>mesa_3_1</code>, Mesa 3.2 will be <code>mesa_3_2</code>,
Mesa 3.3 <code>mesa_3_3</code>, etc..</p>
<p>
To checkout a specific branch of mesa just pass <code>-r</code> and
the branch tag after your cvs command. For example <code>cvs checkout
-r mesa_3_4_branch Mesa</code> will checkout the 3.4 branch and
<code>cvs update -r mesa_3_4_branch</code> will convert your current
branch to the 3.4 dev branch.
Consult <a href="http://www.durak.org/cvswebsites/doc/cvs_5.php3#SEC54"
target="_parent">http://www.durak.org/cvswebsites/doc/cvs_5.php3#SEC54</a>
for more on branching in cvs.
</p>
<p>
To see a list of all the CVS branchs run <code>cvs log README</code> (or any
other file) and look for the section labeled <code>symbolic names</code>.
You'll see something like this:
</p>
<pre> symbolic names:
mesa_4_0: 1.3
mesa_4_0_branch: 1.3.0.6
mesa_3_5: 1.3
mesa_3_4_2: 1.3
mesa_3_4_1: 1.3
mesa_3_4: 1.3
mesa_3_4_branch: 1.3.0.4
mesa_3_3: 1.3
mesa_3_2_1: 1.1.1.1
mesa_3_3_texture_env_combine2: 1.3.0.2
mesa_3_2: 1.1.1.1
mesa_3_2_beta_1: 1.1.1.1
mesa_3_1: 1.1.1.1
mesa_3_2_dev: 1.1.1.1.0.2
mesa_3_1_beta_3: 1.1.1.1
start: 1.1.1.1
mesa: 1.1.1
</pre>
</body>
</html>
\ No newline at end of file
<HTML>
<TITLE>Debugging Tips</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Debugging Tips</H1>
<p>
Normally Mesa (and OpenGL) records but does not notify the user of
errors. It is up to the application to call
<code>glGetError</code> 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.
</p>
<p>
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.
</p>
<p>
In your debugger you can set a breakpoint in _mesa_error() to trap Mesa
errors.
</p>
<p>
There is a display list printing/debugging facility. See the end of
src/dlist.c for details.
</p>
</BODY>
</HTML>
<HTML>
<TITLE>Demos</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Demos</H1>
<ul>
<li><a href="http://www.geocities.com/shobhand/homepage.html">Shobhan Dutta's Geartrain and Walkthrough Demos</a>
</li></ul>
</body>
</html>
\ No newline at end of file
<HTML>
<TITLE>Development Notes</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Development Notes</H1>
<H2>Adding Extentions</H2>
<p>
To add a new GL extension to Mesa you have to do the following.
<pre>
If glext.h doesn't define the extension, edit include/GL/gl.h and add:
- new enum tokens
- new API function entry points
- #define GL_EXT_the_extension_name 1
If adding a new API function (call it glNewFunctionEXT):
- insert glNewFunctionEXT()into src/apiext.h
- edit src/types.h and add NewFunction to the gl_api_table struct
- implement gl_NewFunction() in the appropriate src file
- hook gl_NewFunction() into pointers.c
- add display list support in dlist.c for save_NewFunction()
- add glNewFunctionEXT to gl_GetProcAddress() in extensions.c or
in the device driver's GetProcAddress() function if appropriate
</pre>
<p>
If adding new GL state be sure to update get.c and enable.c
</p>
<p>
In general, look for an extension similar to the new one that's already
implemented in Mesa and follow it by example.
</p>
<H2>Coding Style</H2>
<p>
Mesa's code style has changed over the years. Here's the latest.
</p>
<p>
Comment your code! It's extremely important that open-source code be
well documented. Also, strive to write clean, easily understandable code.
</p>
<p>
3-space indentation
</p>
<p>
If you use tabs, set them to 8 columns
</p>
<p>
Brace example:
</p>
<pre>
if (condition) {
foo;
}
else {
bar;
}
</pre>
<p>
Here's the GNU indent command which will best approximate my preferred style:
</p>
<pre>
indent -br -i3 -npcs infile.c -o outfile.c
</pre>
<p>
Local variable name example: localVarName (no underscores)
</p>
<p>
Constants and macros are ALL_UPPERCASE, with _ between words
</p>
<p>
Global vars not allowed.
</p>
<p>
Function name examples:
</p>
<pre>
glFooBar() - a public GL entry point (in dispatch.c)
_mesa_FooBar() - the internal immediate mode function
save_FooBar() - retained mode (display list) function in dlist.c
foo_bar() - a static (private) function
_mesa_foo_bar() - an internal non-static Mesa function
</pre>
<H2>Writing a Device Driver</H2>
<p>
XXX to do
</p>
<H2>Making a New Mesa Release</H2>
<p>
These are the instructions for making a new Mesa release.
</p>
<p>
Prerequisites (later versions may work):
</p>
<ul>
<li> autoconf 2.50
<li> automake 1.4-p2
<li> libtool 1.4
</ul>
<p>
Be sure to do a "cvs update -d ." in the Mesa directory to
get all the latest files.
</p>
<p>
Update the version strings in src/get.c and src/X/fakeglx.c to return
the new Mesa version number.
</p>
<p>
Create/edit the docs/RELNOTES-X-Y file to document what's new in the release.
Edit the docs/VERSIONS file too.
Update the docs/IAFA-PACKAGE file.
</p>
<p>
Edit Make-config and change the MESA_MAJOR and/or MESA_MINOR versions.
</p>
<p>
Edit the GNU configure stuff to change versions numbers as needed:
Update the version string (second argument) in the line
"AM_INIT_AUTOMAKE(Mesa, 3.3)" in the configure.in file.
</p>
<p>
Remove the leading `dnl' from the line "dnl AM_MAINTAINER_MODE".
</p>
<p>
Verify the version numbers near the top of configure.in
</p>
<p>
Run "fixam -f" to disable automatic dependency tracking.
</p>
<p>
Run the bootstrap script to generate the configure script.
</p>
<p>
Edit Makefile.X11 and verify DIRECTORY is set correctly. The Mesa
sources must be in that directory (or there must be a symbolic link).
</p>
<p>
Edit Makefile.X11 and verify that LIB_NAME and DEMO_NAME are correct.
If it's a beta release, be sure the bump up the beta release number.
</p>
<p>
cp Makefile.X11 to Makefile so that the old-style Mesa makefiles
still work. ./configure will overwrite it if that's what the user runs.
</p>
<p>
Make a symbolic link from $(DIRECTORY) to Mesa. For example,
ln -s Mesa Mesa-3.3 This is needed in order to make a correct
tar file in the next step.
</p>
<p>
Make the distribution files. From inside the Mesa directory:
<pre>
make -f Makefile.X11 lib_tar
make -f Makefile.X11 demo_tar
make -f Makefile.X11 lib_zip
make -f Makefile.X11 demo_zip
</pre>
<p>
Copy the distribution files to a temporary directory, unpack them,
compile everything, and run some demos to be sure everything works.
</p>
<p>
Upload the *.tar.gz and *.zip files to ftp.mesa3d.org
</p>
<p>
Update the web site. CJ Beyer (cj@styx.phy.vanderbilt.edu) can
help with this and uploading to the ftp site.
</p>
<p>
Make the announcement to the SourceForge.net sites: mesa3d-dev@lists.sf.net,
mesa3d-users@lists.sf.net and mesa3d-announce@lists.sf.net
</p>
<H2>Autoconf info</H2>
<p>
In order to run the bootstrap script you'll need:
<p>
<pre>
autoconf 2.50
automake 1.4-p5
libtool 1.4
</pre>
</body>
</html>
<HTML>
<TITLE>Getting Mesa</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Downloading / Unpacking</H1>
<p>
Mesa can be downloaded from the
<a href="http://www.sourceforge.net/projects/mesa3d" target="_parent">
SourceForge download area</A>.
</p>
<p>
Since 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.
</p>
<p>
Mesa is available in at least three archive formats:
</p>
<pre>
1. GNU zip/tar
Download MesaLib-X.Y.tar.gz and optionally MesaDemos-X.Y.tar.gz
Unpack with:
gzcat MesaLib-X.Y.tar.gz | tar xf -
gzcat MesaDemos-X.Y.tar.gz | tar xf -
or
gunzip MesaLib-X.Y.tar.gz ; tar xf MesaLib-X.Y.tar
gunzip MesaDemos-X.Y.tar.gz ; tar xf MesaLib-X.Y.tar
or
tar zxf MesaLib-X.Y.tar.gz
tar zxf MesaDemos-X.Y.tar.gz
If you don't have gzcat try zcat instead.
2. Unix compressed/tar
Download MesaLib-X.Y.tar.Z and optionally MesaDemos-X.Y.tar.Z
Unpack with:
zcat MesaLib-X.Y.tar.Z | tar xf -
zcat MesaDemos-X.Y.tar.Z | tar xf -
3. ZIP format
Download MesaLib-X.Y.zip and optionally MesaDemos-X.Y.zip
Unpack with:
unzip MesaLib-X.Y.zip
unzip MesaDemos-X.Y.zip
</pre>
<p>
After unpacking you'll have these directories (and more):
</p>
<pre>
Makefile.X11 - "old" top-level Makefile for X11-based systems
Make-config - system configurations used by the Makefile.X11
configure - the GNU autoconf script
bin/ - shell scripts for making shared libraries, etc
include/ - GL header (include) files
lib/ - client libraries, created during installation
src/ - source code for the main libGL library
si-glu/ - SGI Sample Implementation of libGLU
src-glu/ - old source code for libGLU (obsolete)
docs/ - documentation
util/ - handly utility functions
widgets-mesa/ - Mesa widgets for Xt/Motif (obsolete)
widgets-sgi/ - SGI OpenGL widgets for Xt/Motif
and if you downloaded and unpacked the demos:
src-glut/ - source code for GLUT toolkit
demos/ - GLUT demos
xdemos/ - X11 and SVGA demo programs
samples/ - sample OpenGL programs from SGI
book/ - example programs from the OpenGL Programming Guide,
converted to GLUT by Mark Kilgard, from GLUT distribution.
images/ - image files
</pre>
<p>
Proceed to <a href="install.html">compilation and installation
instructions</a>.
</p>
<H1>GLUT</H1>
<p>
Mesa 2.5 and later includes Mark Kilgard's GLUT library (GL Utility Toolkit).
GLUT is built automatically on systems which support it.
</p>
<p>
The GLUT tests, demos, examples, etc are not included, just the main library.
To obtain the latest complete release of GLUT please visit the
<a href="http://www.opengl.org/developers/documentation/glut/index.html"
target ="_parent">GLUT homepage</a>
</p>
</BODY>
</HTML>
<HTML>
<TITLE>Environment Variables</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Environment Variables</H1>
<p>
Mesa supports the following environment variables:
</p>
<ul>
<li>MESA_DEBUG - if defined, error messages are printed to stderr
<li>MESA_NO_DITHER - disable dithering, overriding glEnable(GL_DITHER)
<li>MESA_RGB_VISUAL - specifies the X visual and depth for RGB mode (X only)
<li>MESA_CI_VISUAL - specifies the X visual and depth for CI mode (X only)
<li>MESA_BACK_BUFFER - specifies how to implement the back color buffer (X only)
<li>MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
<li>MESA_GAMMA - gamma correction coefficients (X only)
<li>MESA_XSYNC - enable synchronous X behavior (for X debugging only)
</ul>
</BODY>
</HTML>
<HTML>
<TITLE>Mesa Extensions</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Mesa Extensions</H1>
<p>
A number of extensions have been developed especially for Mesa.
The specifications follow.
</p>
<UL>
<LI><A HREF="MESA_agp_offset.spec">MESA_agp_offset.spec</A>
<LI><A HREF="MESA_copy_sub_buffer.spec">MESA_copy_sub_buffer.spec</A>
<LI><A HREF="MESA_packed_depth_stencil.spec">MESA_packed_depth_stencil.spec</A>
<LI><A HREF="MESA_pack_invert.spec">MESA_pack_invert.spec</A>
<LI><A HREF="MESA_pixmap_colormap.spec">MESA_pixmap_colormap.spec</A>
<LI><A HREF="MESA_release_buffers.spec">MESA_release_buffers.spec</A>
<LI><A HREF="MESA_resize_buffers.spec">MESA_resize_buffers.spec</A>
<LI><A HREF="MESA_set_3dfx_mode.spec">MESA_set_3dfx_mode.spec</A>
<LI><A HREF="MESA_sprite_point.spec">MESA_sprite_point.spec</A> (obsolete)
<LI><A HREF="MESA_trace.spec">MESA_trace.spec</A> (obsolete)
<LI><A HREF="MESA_window_pos.spec">MESA_window_pos.spec</A>
<LI><A HREF="MESA_ycbcr_texture.spec">MESA_ycbcr_texture.spec</A>
</UL>
</BODY>
</HTML>
This diff is collapsed.
<HTML>
<TITLE>Games</TITLE>
<BODY text="#000000" bgcolor="#55bbff" link="#111188">
<H1>Games</H1>
<ul>
<li><a href="http://www.psc.edu/%7Esmp/a3d/">Asteroids3D</a> - 3D asteroids game
</li><li><a href="http://evlweb.eecs.uic.edu/aej/AndyBattalion.html" target="_parent">Battalion</a>
- battle game
</li><li><a href="http://bzflag.sourceforge.net/" target="_parent">BZFLAG</a> - 3-D tank
battle game
</li><li><a href="http://www.speakeasy.org/%7Emorse/copter-commander">Copter Commander</a> - 2d multiplayer side scroller
</li><li><a href="http://www.crystalspace.org/" target="_parent">CrystalSpace</a> - Free
3d game engine
</li><li><a href="http://www.afn.org/%7Ecthugha/" target="_parent">Cthugha</a> - music-sync'ed
graphical effects
</li><li><a href="http://www.sics.se/dive/" target="_parent">DIVE</a> - Distributed Interactive
Virtual Environment
</li><li><a href="http://www.newdoom.com/doomlegacy/" target="_parent">Doom Legacy</a>
- an OpenGL port of id software's popular game, Doom
</li><li><a href="http://www.asimov.de/intern_dropit.html" target="_parent">DropIt</a> - 3-D tetris game
</li><li><a href="http://www.flightgear.org/" target="_parent">Flight Gear</a> - Flight
simulator
</li><li><a href="http://freetrek.linuxgames.com/" target="_parent">Free Trek</a> - Star
Trek battle simulator