3Dfx Glide device driver



Requirements:
-------------

A Voodoo-based videocard/accelerator
DOS (with DJGPP), Windows9x/2k (with MinGW), Linux
Glide3x library for your OS

http://sourceforge.net/projects/glide/



How to compile:
---------------

DJGPP:
   Place the Glide3 SDK in the top Mesa directory:
	$(MESA)/glide3/include/
		3dfx.h, g3ext.h, glide.h, glidesys.h, glideutl.h, sst1vid.h
	$(MESA)/glide3/lib/
		libgld3x.a, libgld3i.a, glide3x.dxe
   Type:
	make -f Makefile.DJ X86=1 FX=1
   Look into the makefile for further information.

MinGW:
   Place the Glide3 SDK in the top Mesa directory:
	$(MESA)/glide3/include/
		3dfx.h, g3ext.h, glide.h, glidesys.h, glideutl.h, sst1vid.h
	$(MESA)/glide3/lib/
		libglide3x.a, glide3x.dll
   Type:
	make -f Makefile.mgw X86=1 FX=1
   Look into the makefile for further information.

Linux:
   Place the Glide3 SDK in /usr/local/glide
	/usr/local/glide/include/
		3dfx.h, g3ext.h, glide.h, glidesys.h, glideutl.h, sst1vid.h
	/usr/local/glide/lib/
		libglide3x.a, libglide3x.so
   Type:
	make linux-glide
	or
	make linux-x86-glide



Compilation defines:
--------------------

FX_DEBUG
	enable driver debug code
FX_TRAP_GLIDE
	enable Glide trace code
FX_PACKEDCOLOR
	use packed color in vertex structure
FX_TC_NAPALM
	map GL_COMPRESSED_RGB[A] to FXT1. Works with VSA100-based cards only.
FX_COMPRESS_S3TC_AS_FXT1_HACK
	map S3TC to FXT1
FX_RESCALE_BIG_TEXURES_HACK
	fake textures larger than HW can support
	(see MESA_FX_MAXLOD environment variable)



Environment variables:
----------------------

The following environment variables affect MesaFX. Those that affect Glide
only, are beyond the scope of this section. Entries that don't have a "Value"
field, can have any value whatsoever
	ex: set MESA_FX_IGNORE_CMBEXT=y

"Note" (*) means that the environment variable affects Glide, too; also, if
the var is not found in the environment, it is searched in windoze registry.
"Note" (!) means that the environment variable is not working as expected;
may have undefined effects, might have effects only at Glide level or might
not have any effect whatsoever. Caveat emptor! Those are to be revised soon.

It is recommended to leave the envvars alone, so that Mesa/Glide will run with
default values. Use them only when you experience crashes or strange behavior.

FX_GLIDE_NUM_TMU
	OS: all
	HW: dual-TMU cards (Voodoo2, Avenger, Napalm)
	Desc: force single-TMU
	Note: (*)
	Value: "1"
FX_GLIDE_SWAPPENDINGCOUNT
	OS: all
	HW: all
	Desc: max # of buffers allowed to build up
	Note: (*) (!)
	Value: "0", "1", "2", "3", "4", "5" or "6"
FX_GLIDE_SWAPINTERVAL
	OS: all
	HW: all
	Desc: number of vertical retraces to wait before swapping
	Note: (*) (!) works only at Glide-level?
SSTH3_SLI_AA_CONFIGURATION
	OS: all
	HW: VSA100-based cards
	Desc: SLI/AA setup
	Note: (*) (!) works only at Glide-level?
	Value:
	    1, 2, 4 chip cards
		"0" - SLI & AA disable
		"1" - SLI disabled, 2 sample AA enabled
	    2, 4 chip cards
		"2" - 2-way SLI enabled, AA disabled
		"3" - 2-way SLI enabled, 2 sample AA enabled
		"4" - SLI disabled, 4 sample AA enabled
	    4 chip cards
		"5" - 4-way SLI enabled, AA disabled
		"6" - 4-way SLI enabled, 2 sample AA enabled
		"7" - 2-way SLI enabled, 4 sample AA enabled
		"8" - SLI disabled, 8 sample AA enabled
SST_DUALHEAD
	OS: win32
	HW: ?
	Desc: ?
	Note: (!) disabled?
MESA_FX_NO_SIGNALS
	OS: linux
	HW: all
	Desc: avoid installing signals
	Note: (!) untested!
MESA_FX_INFO
	OS: all
	HW: all
	Desc: verbose to stderr
	Value: any; special value "r" to redirect stderr to MESA.LOG
MESA_FX_NOSNAP
	OS: all
	HW: Voodoo1, Rush, Banshee
	Desc: do not snap vertices inside Mesa
	Note: to be used with Glide3x that snaps vertices internally
MESA_FX_POINTCAST
	OS: all
	HW: dual-TMU cards (some Voodoo1, Voodoo2, Avenger, Napalm)
	Desc: try to use pointcast palette
	Note: may give adverse effects on UMA cards (Avenger, Napalm)
MESA_FX_IGNORE_PALEXT
	OS: all
	HW: all
	Desc: disable 6666 palette
MESA_FX_IGNORE_PIXEXT
	OS: all
	HW: Napalm
	Desc: force 565 16bpp mode (traditional Voodoo, no 32/15bpp)
MESA_FX_IGNORE_TEXFMT
	OS: all
	HW: Napalm
	Desc: disable 32bit textures
MESA_FX_IGNORE_CMBEXT
	OS: all
	HW: Napalm
	Desc: disable Napalm combiners (color/alpha/texture)
	Note: this option allows dual-TMU cards perform single-pass
	      trilinear, but some advanced (multi)texturing modes
	      won't work (GL_EXT_texture_env_combine)
MESA_FX_IGNORE_MIREXT
	OS: all
	HW: all
	Desc: disable mirror extension
MESA_FX_IGNORE_TEXUMA
	OS: all
	HW: all
	Desc: disable UMA
MESA_FX_IGNORE_TEXUS2
	OS: all
	HW: all
	Desc: disable Texus2
MESA_FX_MAXLOD
	OS: all
	HW: non VSA-100 cards
	Desc: enable large texture support using SW rescaling
	Value:
	    "9"  - 512x512 textures
	    "10" - 1024x1024 textures
	    "11" - 2048x2048 textures
MESA_FX_ALLOW_VP
	OS: all
	HW: all
	Desc: allow vertex program extensions
MESA_GLX_FX
	OS: linux
	HW: Voodoo1, Rush, Voodoo2
	Desc: display mode
	Note: (!) experimental
	Value:
	    "w" - windowed mode
	    "f" - fullscreen mode
	    "d" - disable glide driver
	OS: win32
	HW: Rush, Banshee, Avenger, Napalm
	Desc: display mode
	Note: (!) experimental
	Value:
	    "w" - windowed mode



Contact:
--------

Daniel Borca <dborca 'at' users 'dot' sourceforge 'dot' net>
Hiroshi Morii <koolsmoky 'at' users 'dot' sourceforge 'dot' net>



WARNING! The info below this line is outdated (yet some of it useful). WARNING!
*******************************************************************************



Info for Mesa 4.1
-----------------

The 3dfx Glide driver in Mesa is disabled by default.  Not too many people
use this driver anymore and at some point down the road it will be dropped.

To use/enable the Glide driver either do this:

'./configure --with-glide=DIR'    Where DIR is the location of Glide, like
                                  /usr/ or /usr/local

OR

'make linux-x86-glide'     If using the old-style Makefile system.

The rest of this file hasn't changed since Mesa 3.3.  Some of it's out of
date, but some is still valid.



What do you need ?
------------------

	- A PC with a 3Dfx Voodoo1/2 Graphics or Voodoo Rush based board
	  (Pure3D, Monster 3D, R3D, Obsidian, Stingray 128/3D, etc.).
	  The Quantum3D Obsidian3D-2 X-24 requires some special env. setting
	  under Linux (more information in the "Useful Glide Environment
	  Variables");

	- The 3Dfx Glide library 2.3 or later for your OS (the 2.4 works fine).
	  The Voodoo2 requires the Glide library 2.51. The Glide 3.1 is not
	  compatible with the Glide 2.x so it doesn't work with the current
	  version of the driver;

	- A compiler supported by the Glide library (Micro$oft VC++ (tested),
	  Watcom (tested), GCC for Linux (tested), etc.);

	- It's nice to have two monitors - one for your normal graphics
	  card and one for your 3Dfx card. If something goes wrong with
	  an application using the 3Dfx hardware you can still see your
	  normal screen in order to recover.



Tested on:
----------
	Windows 95 - David Bucciarelli
	Windows NT - Henri Fousse
	MS-DOS
	Linux - Daryll Strauss, Brian Paul, David Bucciarelli
	FreeBSD
	BeOS - Duncan Wilcox
	MacOS - Fazekas Miklos


What is able to do ?
--------------------

	- It is able accelerate points, lines and polygon with flat
	  shading, gouraud shading, Z-buffer, texture mapping, blending, fog and
	  antialiasing (when possible). There is also the support for rendering
	  in a window with a slow trick for the Voodoo Graphics (available only
	  for Linux) and at full speed with the Voodoo Rush chipset.
	  Under Linux is also possible to switch on-the-fly between the fullscreen
	  and in-window rendering hack.
	  There is also the support for using more than one Voodoo Graphics in the
	  some application/PC (you can create one context for each board and use
	  multiple video outputs for driving monitors, videoprojectors or HMDs).
	  The driver is able to fallback to pure software rendering when afeature
	  isn't supported by the Voodoo hardware (however software rendering is
	  very slow compared to hardware supported rendering)



How to compile:
---------------

Linux:
------
	Here are the basic steps for using the 3Dfx hardware with Mesa
	on Linux:

	- You'll need the Glide library and headers.  Mesa expects:
		/usr/local/glide/include/*.h        // all the Glide headers
		/usr/local/glide/lib/libglide2x.so

	  If your Glide libraries and headers are in a different directory
	  you'll have to modify the Mesa-config and mklib.glide files.

	- Unpack the MesaLib-3.1.tar.gz and MesaDemos-3.1.tar.gz archives;

	- If you're going to use a newer Mesa/Glide driver than v0.27 then
          unpack the new driver archive over the Mesa directory.

	- In the Mesa-3.1 directory type "make linux-glide"

	- Compilation _should_ finish without errors;

	- Set your LD_LIBRARY_PATH environment variable so that the
	  libglide2x.so and Mesa library files can be found.  For example:
	    setenv LD_LIBRARY_PATH "/usr/local/glide/lib:/SOMEDIR/Mesa-3.1/lib"

	- You'll have to run Glide-based programs as root or set the suid
	  bit on executables;

	- Try a demo:
	    cd gdemos
	    su
	    setenv MESA_GLX_FX f
	    ./gears     (hit ESC to exit)

	- You can find the demos especially designed for the Voodoo driver in
	  in the Mesa-3.1/3Dfx/demos directory (type "make" in order to compile
	  everything).

MacOS:
------
	Check the WEB page at http://valerie.inf.elte.hu/~boga/Mesa.html

MS Windows:
-----------

	For the MSVC++:
	- The glide2x.lib have to be in the default MSVC++ lib directory;

	- The Glide headers have to be in the default MSVC++ include directory;

	- You must have the vcvars32.bat script in your PATH;

	- Go to the directory Mesa-3.1 and run the mesafx.bat;

	- The script will compile everything (Mesa-3.1/lib/OpenGL32.{lib,dll},
	  Mesa-3.1/lib/GLU32.{lib,dll}, Mesa-3.1/lib/GLUT32.{lib,dll} and
          Voodoo demos);

	- At the end, you will be in the Mesa-3.1/3Dfx/demos directory;

	- Try some demo (fire.exe, teapot.exe, etc.) in order to check if
	  everything is OK (you can use Alt-Tab or Ctrl-F9 to switch between
	  the Voodoo screen and the windows desktop);

	- Remember to copy the Mesa OpenGL32.dll, GLU32.dll and GLUT32.dll in the
          some directory were you run your Mesa based applications.

	- I think that you can easy change the Makefile.fx files in order
	  to work with other kind of compilers;

	- To discover how open the 3Dfx screen, read the sources under
	  the Mesa-3.1/3Dfx/demos directory. You can use the GLUT library or
          the Diego Picciani's wgl emulator.

	NOTE: the MSVC++ 5.0 optimizer is really buggy. Also if you install the
	SP3, you could have some problem (you can disable optimization in order
	solve these kind of problems).


Doing more with Mesa & Linux Glide:
-----------------------------------

	The MESA_GLX_FX environment variable can be used to coax most
	GLX-based programs into using Glide (and the __GLUT library
	is GLX-based__).

        Full-screen 3Dfx rendering:
        ---------------------------

	1. Set the MESA_GLX_FX variable to "fullscreen":

		ksh:
			export MESA_GLX_FX = "fullscreen"
		csh:
			setenv MESA_GLX_FX fullscreen

	2. As root, run a GLX-based program (any GLUT demo on Linux).

	3. Be careful:  once the 3Dfx screen appears you won't be able
	to see the GLUT windows on your X display.  This can make using
	the mouse tricky!  One solution is to hook up your 3Dfx card to
	a second monitor.  If you can do this then set these env vars
	first:

		setenv SST_VGA_PASS 1
		setenv SST_NOSHUTDOWN

	or for the Voodoo2:

		setenv SSTV2_VGA_PASS 1
		setenv SSTV2_NOSHUTDOWN

        Rendering into an X window with the help of the Voodoo hardware:
        ----------------------------------------------------------------

	1. Start your X server in 16 bpp mode (XFree86:  startx -- -bpp 16)
	   in order to have the best performance and the best visual
	   quality. However you can use any visual depth supported by X.

	2. Set the following environment variables:
		export MESA_GLX_FX="window"	# to enable window rendering
		export SST_VGA_PASS=1	# to stop video signal switching
		export SST_NOSHUTDOWN=1	# to stop video signal switching
	    OR
		setenv MESA_GLX_FX window
		setenv SST_VGA_PASS 1
		setenv SST_NOSHUTDOWN 1

	(the Voodoo2 requires to use "SSTV2_" instead "SST_").

	3. As root, try running a GLX-based program

	How does it work?  We use the 3Dfx hardware to do rendering then
	copy the image from the 3Dfx frame buffer into an X window when
	the SwapBuffers() function is called.  The problem with this
	idea is it's slow.  The image must be copied from the 3Dfx frame
	buffer to main memory then copied into the X window (and when the X
	visual depth doesn't match the Voodoo framebufffer bit per pixel, it
	is required also a pixel format translation).

	NOTE: the in-window rendering feature only works with double-buffering.


        On the fly switching between in window rendering and full screen rendering
	--------------------------------------------------------------------------

	The Mesa 2.6 has introduced the capability of switching
	on-the-fly between the fullscreen/fullspeed rendering and the in-window
	hack and vice versa. The on-the-fly switching requires a direct support
	by the application but it is really easy to add. You have to start
	your X server in 16 bpp mode and to add the following lines to your
	application:

		#if defined(FX) && define(XMESA)
		#include <GL/xmesa.h>

		static int fullscreen=1;
		#endif

		...

		/* In the GLUT keyboard event callback */

		#if defined(FX) && !define(WIN32)
		  case ' ':
		    fullscreen=(!fullscreen);
		    XMesaSetFXmode(fullscreen ? XMESA_FX_FULLSCREEN : XMESA_FX_WINDOW);
		    break;
		#endif
		...

       	See the 3Dfx/demos/tunnel.c program
       	for an example.  You have to set the -DXMESA flag in the Makefile's COPTS
       	to enable it.

  	Rendering into an X window with the X11 software driver:
        --------------------------------------------------------

	Set the MESA_GLX_FX variable to "disable" your GLX-based program will use
	the X11 software driver (the 3Dfx hardware isn't used at all).



Useful Glide Environment Variables:
-----------------------------------

	- To disable the 3Dfx logo, set the FX_GLIDE_NO_SPLASH variable.

	- To disable video signal switching:
		setenv SST_VGA_PASS 1
		setenv SST_NOSHUTDOWN
	  or for the Voodoo2:
		setenv SSTV2_VGA_PASS 1
		setenv SSTV2_NOSHUTDOWN

        - To set the default screen refresh rate:
                setenv SST_SCREENREFRESH=75

          the supported values are 60, 70, 72, 75, 80, 85, 90, 100, 120.

	- To force the Mesa library to swap buffers as fast as possible,
	  without any vertical blanking synchronization (useful for benchmarks):
		setenv FX_GLIDE_SWAPINTERVAL 0
                setenv SST_SWAP_EN_WAIT_ON_VIDSYNC 0

	- You can slight improve the performances of your Voodoo1 board with
	  the following env. var.:
		setenv SST_FASTMEM 1
		setenv SST_PCIRD 1
		setenv SST_GRXCLK 57

	  (don't use this setting with the Quantum3D 100SB or with any other
	  SLI configuration: it will hang everything !).
	  The following setting can be used with the Voodoo2:
		setenv SSTV2_FASTMEM_RAS_READS=1
		setenv SSTV2_FASTPCIRD=1
		setenv SSTV2_GRXCLK=95

	- The Quantum3D Obsidian3D-2 X-24 requires some special env. setting
	  in order to work under Linux:

		export SSTV2_FT_CLKDEL=5
		export SSTV2_TF0_CLKDEL=7
		export SSTV2_TF1_CLKDEL=7
		export SSTV2_TF2_CLKDEL=7
		export SSTV2_SLIM_VIN_CLKDEL=3
		export SSTV2_SLIM_VOUT_CLKDEL=2
		export SSTV2_SLIS_VIN_CLKDEL=3
		export SSTV2_SLIS_VOUT_CLKDEL=2

	  (Thanks to Phil Ross for this trick).




The Mesa/Voodoo Environment Variables:
--------------------------------------

	- Only for Windows/Voodoo Rush users, if you define the
	  env. var. MESA_WGL_FX:
		export MESA_WGL_FX=fullscreen
	  you will get fullscreen rendering;

	- Only for Windows/Voodoo Rush users, if you define the
	  env. var. MESA_WGL_FX:
		export MESA_WGL_FX=window
	  you will get window rendering (default value);

	- Only for Linux users, you can find more informations about
	  the env. var. MESA_GLX_FX in the "Doing more with Mesa & Linux Glide"
	  section;

	- If you define the env. var. MESA_FX_SWAP_PENDING:
		export MESA_FX_SWAP_PENDING=4
	  you will able to set the maximum number of swapbuffers
	  commands in the Voodoo FIFO after a swapbuffer (default value: 2);

        - If you define the env. var. MESA_FX_INFO:
		export MESA_FX_INFO=1
          you will get some useful statistic.

        - If you define the env. var. MESA_FX_NO_SIGNALS:
		export MESA_FX_NO_SIGNALS=1
          Mesa/FX will not install atexit() or signal() handlers.



Know BUGS and Problems:
-----------------------

	- fog doesn't work in the right way when using the glDepthRange() function;

	- Maximum texture size: 256x256 (this is an hardware limit);

	- Texture border aren't yet supported;

	- A GL_BLEND in a glTexEnv() is not supported (it is an hardware limit);

        - Use the glBindTexture extension (standard in OpenGL 1.1) for texture
	  mapping (the old way: glTexImage inside a display list, download
	  the texture map each time that you call the display list !!!);

	- Stencil buffer and Accumulation buffer are emulated in software (they are not
	  directly supported by the Hardware);

	- Color index mode not implemented (this is an hardware limit);

	- Thre is an know bug in the Linux Glide library so the in-window-rendering hack
	  and any other operations that requires to read the Voodoo frame buffer
	  (like the accumulation buffer support) doesn't work on Voodoo SLI cards.

	- The driver switch to pure software (_slow_) rendering when:

		- Stencil enabled;
		- Using the Accumulation buffer;
		- Blend enabled and blend equation != GL_FUNC_ADD_EXT;
		- Color logic operation enabled and color logic operation != GL_COPY;
		- Using GL_SEPARATE_SPECULAR_COLOR;
		- The four values of glColorMask() aren't the some;
		- Texture 1D or 3D enabled;
		- Texture function is GL_BLEND;
		- Using the Multitexture extension with Voodoo cards with only one TMU;
		- Using the Multitexture extension with Voodoo cards with more than
		   one TMU, and texture function isn't GL_MODULATE;
		- Point size is != 1.0 or point params vector != (1.0,0.0,0.0);
		- Line width != 1.0 or using stipple lines.
		- Using polygon offset or stipple polygons;

	NOTE: this is list is not yet complete.


Hints and Special Features:
---------------------------

	- Under Linux and with a Voodoo Graphics board, you can use
	  XMesaSetFXmode(XMESA_FX_FULLSCREEN or XMESA_FX_WINDOW) in order to
	  switch on the fly between fullscreen rendering and the in-window-rendering
	  hack.

	- The driver is able to use all the texture memory available: 2/4MB on
	  Voodoo1 boards and 8MB (!) on high-end Voodoo1 and Voodoo2 boards.

	- Trilinear filtering is fully supported on Voodoo boards with two TMUs
	  (high-end Voodoo1 boards and Voodoo2 boards). When only one TMU is
	  available the driver fallback to bilinear filter also if you ask
	  for trilinear filtering.

        - The Voodoo driver support multiple Voodoo Graphics boards in the
          some PC. Using this feature, you can write applications that use
          multiple monitors, videoprojectors or HMDs for the output. See
	  Mesa-3.1/3Dfx/demos/tunnel2.c for an example of how setup one
          context for each board.

	- The v0.19 introduces a new powerful texture memory manager: the
	  texture memory is used as a cache of the set of all defined texture
	  maps. You can now define several MBs of texture maps also with a 2MB
	  of texture memory (the texture memory manager will do automatically
	  all the swap out/swap in
	  texture memory work). The new texture memory manager has also
	  solved a lot of other bugs/no specs compliance/problems
	  related to the texture memory usage.

	- Use triangles and quads strip: they are a LOT faster than sparse
	  triangles and quads.

	- The Voodoo driver supports the GL_EXT_paletted_texture. it works
	  only with GL_COLOR_INDEX8_EXT, GL_RGBA palettes and the alpha value
	  is ignored because this is a limitation of the current Glide
	  version and of the Voodoo hardware. See Mesa-3.1/3Dfx/demos/paltex.c for
	  a demo of this extension.

	- The Voodoo driver directly supports 3Dfx Global Palette extension.
	  It was written for GLQuake and I think that it isn't a good idea
	  to use this extension for any other purpose (it is a trick). See
	  Mesa-3.1/3Dfx/demos/glbpaltex.c for a demo of this extension.

	- The Voodoo driver chooses the screen resolution according to the
	  requested window size. If you open a 640x480 window, you will get
	  a 640x480 screen resolution, if you open a 800x600 window, you
	  will get a 800x600 screen resolution, etc.
	  Most GLUT demos support the '-geometry' option, so you can choose
	  the screen resolution: 'tunnel -geometry 800x600'.
	  Clearly, you Voodoo board must have enough framebuffer RAM (otherwise
	  the window creation will fail).

	- The glGetString(GL_RENDERER) returns more information
          about the hardware configuration: "Mesa Glide <version>
          <Voodoo_Graphics|Voodoo_Rush|UNKNOWN> <num> CARD/<num> FB/
          <num> TM/<num> TMU/<NOSLI|SLI>"
          where: <num> CARD is the card used for the current context,
          <num> FB is the number of MB for the framebuffer,
          <num> TM is the number of MB for the texture memory,
          <num> TMU is the number of TMU. You can try to run
          Mesa/demos/glinfo in order to have an example of the output.

Did you find a lot BUGs and problems ? Good, send me an email.



FAQ:
----

For a complete FAQ check the Bernd Kreimeier's Linux 3Dfx HOWTO
available at http://www.gamers.org/dEngine/xf3D (it includes also
a lot of informations not strictly related to Linux, so it can be
useful also if you don't use Linux)

1. What is 3Dfx?

3Dfx Interactive, Inc. is the company which builds the VooDoo 3-D graphics
chipset (and others) used in popular PC cards such as the Diamond Monster 3D
and the Orchid Righteous 3D (more informations at http://www.3dfx.com).


2. What is Glide?

Glide is a "thin" programming interface for the 3Dfx hardware.  It was
originally written for Windows/Intel but has been ported to Linux/Intel
by Daryll Strauss.

3Dfx, Inc. should be applauded for allowing the Linux version of Glide
to be written.

You can directly program with the Glide library if you wish.  You can
obtain Glide from the "Developer" section of the 3Dfx website: www.3dfx.com
There's a Linux/Glide newsgroup at news://news.3dfx.com/3dfx.glide.linux


3. What is fxmesa?

"fxmesa" is the name of the Mesa device driver for the 3Dfx Glide library.
It was written by David Bucciarelli and others.  It works on both Linux
and Windows.  Basically, it allows you to write and run OpenGL-style programs
on the 3Dfx hardware.


4. What is GLQuake?

Quake is a very popular game from id software, Inc.  See www.idsoftware.com
GLQuake is a version of Quake written for OpenGL.  There is now a Linux
version of GLQuake with works with the Mesa/3Dfx/Glide combo.

Here's what you need to run GLQuake on Linux:
   PC with 100MHz Pentium or better
   a 3Dfx-based card
   Mesa 3.1 libraries:  libMesaGL.so  libMesaGLU.so
   Glide 2.4 libraries:  libglide2x.so  libtexus.so
   GLQuake for Linux.

Also, the windows version of GLQuake works fine with the Mesa OpenGL32.dll,
you have only to copy the Mesa-3.1/lib/OpenGL32.dll in the GLQuake directory
in order to test 'MesaQuake'.


5. What is GLUT?

GLUT is Mark Kilgard's OpenGL Utility Toolkit.  It provides an API for
writing portable OpenGL programs with support for multiple windows, pop-
up menus, event handling, etc.

Check the Mark's home page for more informations (http://reality.sgi.com/mjk_asd).

Every OpenGL programmer should check out GLUT.

GLUT on Linux uses GLX.


6. What is GLX?

GLX is the OpenGL extension to the X Window System.  I defines both a
programming API (glX*() functions) and a network protocol.  Mesa implements
an emulation of GLX on Linux.  A real GLX implementation would requires
hooks into the X server.  The 3Dfx hardware can be used with GLX-based
programs via the MESA_GLX_FX environment variable.


7. Is the Voodoo driver able to use the 4Mb texture memory of
the Pure3D boards ?

Yes, the Voodoo driver v0.20 includes the support for Voodoo
Graphics boards with more than 2Mb of texture memory.


8. Do the Voodoo driver support the Voodoo Rush under Windows ?

Yes, Diego Picciani has developed the support for the Voodoo
Rush but David Bucciarelli has a Pure3D and a Monster3D and Brian Paul
has a Monster3D, so the new versions of the Mesa/Voodoo sometime are
not tested with the Voodoo Rush.


9. Do the Voodoo driver support the Voodoo Rush under Linux ?

No because the Linux Glide doesn't (yet) support the Voodoo Rush.


10. Can I sell my Mesa/Voodoo based software and include
a binary copy of the Mesa in order to make the software
working out of the box ?

Yes.


11. Which is the best make target for compiling the Mesa for
Linux GLQuake ('make linux-glide', 'make linux-386-glide', etc.) ?

'make linux-386-opt-glide' for Voodoo1 and 'make linux-386-opt-V2-glide'
for Voodoo2 boards because it doesn't include the '-fPIC'
option (4-5% faster).


12. Can I use a Mesa compiled with a 'make linux-386-opt-V2-glide'
for my applications/programs/demos ?

Yes, there is only one constrain: you can't run two Mesa applications
at the some time. This isn't a big issue with the today Voodoo Graphics.


Thanks to:
----------

Henri Fousse       (he has written several parts of the v0.15 and the old GLUT
	            emulator for Win);

Diego Picciani     (he has developed all the Voodoo Rush support and the wgl
	            emulator);

Daryll Strauss     (for the Linux Glide and the first Linux support);

Brian Paul         (of course);

Dave 'Zoid' Kirsch (for the Linux GLQuake and Linux Quake2test/Q2 ports)

Bernd Kreimeier    (for the Linux 3Dfx HOWTO and for pushing companies to offer
                    a better Linux support)

3Dfx and Quantum3D (for actively supporting Linux)

The most update places where find Mesa VooDoo driver related informations are
the Mesa mailing list and my driver WEB page
(http://www-hmw.caribel.pisa.it/fxmesa/index.shtml)


David Bucciarelli (davibu@tin.it)

Humanware s.r.l.
Via XXIV Maggio 62
Pisa, Italy
Tel./Fax +39-50-554108
email: info.hmw@plus.it
www: www-hmw.caribel.pisa.it

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.

                         Mesa / BeOS Information



* Introduction

Brian Paul added in Mesa 3.1 a driver for BeOS R4.5 operating system.
This driver implements a clone of the BGLView class.  This class,
derived from BView, allows OpenGL rendering into any BeOS window.  His
driver was updated in Mesa 4.1 and again in version 6.1 by Philippe
Houdoin, who's maintaining this driver since.

Any application which uses the BGLView should be able to use Mesa
instead of Be's OpenGL without changing any code.

Since Be's OpenGL implementation (as of R5) is basically just the
SGI sample implementation, it's pretty slow.  You'll see that Mesa
is considerably faster.


* Source Code

The source code for the driver is in src/mesa/drivers/beos/ directory.
It's not 100% finished at this time but many GLUT-based demos are
working.  No optimizations have been made at this time.


* Compiling

Since Mesa 6.x, it can be build under BeOS with both the R5 builtin gcc version
or more recent gcc versions available for BeOS, like this gcc version 2.95.3 for BeOS
you can find at http://www.bebits.com/app/2157.
Anyway, keep in mind that to take full advantage of Mesa x86 optimizations, you better
want to use gcc 2.95.3 or sooner versions...

To build Mesa-powered BeOS libGL.so version, open an Terminal window,
move to Mesa root folder and type this command:

$ make beos

Note that the "beos" argument is only needed the first time to setup build config.
Next times, typing "make" will be enough.

When it finishes the Mesa based libGL.so library for
BeOS will be in the lib/ directory, along libglut.so library.
Several demo/test programs should have been build too under progs/* folders.
If it stop when building one of the progs/* programs, you may want to ignore it
and force make to move on next target by adding the -k make option:

$ cd progs
$ make -k

To install it as Be's default libGL.so replacement, put it in your
/boot/home/config/lib/ directory. All your GL/GLUT apps will use
the Mesa based then.

By default, it build a non-debug version library.
The x86 (MMX, SSE and 3DNOW) optimizations are also supported for x86 target.
For PowerPC BeOS flavor, sorry, Mesa don't have ppc (Altivec) optimizations
yet.

To build a DEBUG version, type instead this :

$ DEBUG=1 make


* Example Programs

Look under progs/beos/ for some BGLView-based programs.
You should find under progs/samples and progs/redbook directories GLUT-based programs too.
They all should have been compiled along with the Mesa library.


* GLUT

A beta version of GLUT 3.7 port for BeOS, made by Jake Hamby, can be found at
http://anobject.com/jehamby/Code/Glut-3.7-x86.zip.
This is the version currently included in Mesa source code, and
build in lib/libglut.so.

A previous 3.5 version of this GLUT BeOS port used to be available at
http://home.beoscentral.com/jehamby/Glut-3.5-x86.zip.

They're special versions of GLUT for the BeOS platform.  I don't
believe Mark Kilgard's normal GLUT distribution includes BeOS
support.


* Special Features

Mesa's implementation of the BGLView class has an extra member
function:  CopySubBufferMESA().  It basically works like SwapBuffers()
but it only copies a sub region from the back buffer to the front
buffer.  This is a useful optimization for some applications.
If you use this method in your code be sure that you check at runtime
that you're actually using Mesa (with glGetString) so you don't
cause a fatal error when running with Be's OpenGL.


* Work Left To Do

- BDirectWindow single buffering support is not implemented yet.
- Color index mode is not implemented yet.
- Reading pixels from the front buffer not implemented yet.
- There is also a BGLScreen class in BeOS for full-screen OpenGL rendering.
  This should also be implemented for Mesa.
- Multiple renderers add-ons support, first step toward hardware acceleration
  support.

* Other contributors to this BeOS port

Jake Hamby                      jhamby <at> anobject <dot> com
Marcin Konicki                  ahwayakchih <at> neoni <dot> net
Francois Revol                  revol <at> free <dot> fr
Nathan Whitehorn                nathanw <at> uchicago <dot> edu


* Older BeOS Driver

Mesa 2.6 had an earlier BeOS driver.  It was based on Mesa's Off-screen
rendering interface, not BGLView.  If you're interested in the older
driver you should get Mesa 2.6.


* BeOS and Glide

Mesa 3.0 supported the 3Dfx/Glide library on Beos.  Download Mesa 3.0
if interested.  Ideally, the 3Dfx/Glide support should be updated to
work with the new Mesa 3.1 BGLView implementation.

The Glide library hasn't been updated for BeOS R4 and newer, to my knowledge,
as of February, 1999.


----------------------------------------------------------------------

                          Mesa Cygwin/X11 Information


WARNING
=======

If you installed X11 (packages xorg-x11-devel and xorg-x11-bin-dlls ) with the
latest setup.exe from Cygwin the GL (Mesa) libraries and include are already
installed in /usr/X11R6.

The following will explain how to "replace" them.

Installation
============

How to compile Mesa on Cygwin/X11 systems:

1. Shared libs:
    type 'make cygwin-sl'.

    When finished, the Mesa DLL will be in the Mesa-x.y/lib/ and
    Mesa-x.y/bin directories.


2. Static libs:
    type 'make cygwin-static'.
    When finished, the Mesa libraries will be in the Mesa-x.y/lib/ directory.

Header and library files:
   After you've compiled Mesa and tried the demos I recommend the following
   procedure for "installing" Mesa.

   Copy the Mesa include/GL directory to /usr/X11R6/include:
	cp -a include/GL /usr/X11R6/include

   Copy the Mesa library files to /usr/X11R6/lib:
	cp -a lib/* /usr/X11R6ocal/lib

   Copy the Mesa bin files (used by the DLL stuff) to /usr/X11R6/bin:
	cp -a lib/cyg* /usr/X11R6/bin

Xt/Motif widgets:
   If you want to use Mesa or OpenGL in your Xt/Motif program you can build
   the widgets found in either the widgets-mesa or widgets-sgi directories.
   The former were written for Mesa and the later are the original SGI
   widgets.  Look in those directories for more information.
   For the Motif widgets you must have downloaded the lesstif package.


Using the library
=================

Configuration options:
   The file src/mesa/main/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 (Win32 DLLS) you may have to set an
   environment variable to specify where the Mesa libraries are located.
   Set the PATH variable to include /your-dir/Mesa-2.6/bin.
   Otherwise, when you try to run a demo it may fail with a message saying
   that one or more DLL couldn't be found.


Xt/Motif Widgets:
   Two versions of the Xt/Motif OpenGL drawing area widgets are included:

      widgets-sgi/	SGI's stock widgets
      widgets-mesa/	Mesa-tuned widgets

   Look in those directories for details


Togl:
   Togl is an OpenGL/Mesa widget for Tcl/Tk.
   See http://togl.sourceforge.net for more information.



X Display Modes:
   Mesa supports RGB(A) rendering into almost any X visual type and depth.

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


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

   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


Overlay Planes

   Overlay planes in the frame buffer are supported by Mesa but require
   hardware and X server support.  To determine if your X server has
   overlay support you can test for the SERVER_OVERLAY_VISUALS property:

	xprop -root | grep SERVER_OVERLAY_VISUALS


HPCR glClear(GL_COLOR_BUFFER_BIT) dithering

   If you set the MESA_HPCR_CLEAR environment variable then dithering
   will be used when clearing the color buffer.  This is only applicable
   to HP systems with the HPCR (Color Recovery) system.


Extensions
==========
   There are three Mesa-specific 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 xdemos/glxpixmap.c file for an example of how to use this
      extension.

   GLX_MESA_release_buffers

      Mesa associates a set of ancillary (depth, accumulation, stencil and
      alpha) buffers with each X window it draws into.  These ancillary
      buffers are allocated for each X window the first time the X window
      is passed to glXMakeCurrent().  Mesa, however, can't detect when an
      X window has been destroyed in order to free the ancillary buffers.

      The best it can do is to check for recently destroyed windows whenever
      the client calls the glXCreateContext() or glXDestroyContext()
      functions.  This may not be sufficient in all situations though.

      The GLX_MESA_release_buffers extension allows a client to explicitly
      deallocate the ancillary buffers by calling glxReleaseBuffersMESA()
      just before an X window is destroyed.  For example:

         #ifdef GLX_MESA_release_buffers
            glXReleaseBuffersMESA( dpy, window );
         #endif
         XDestroyWindow( dpy, window );

      This extension is new in Mesa 2.0.

   GLX_MESA_copy_sub_buffer

      This extension adds the glXCopySubBufferMESA() function.  It works
      like glXSwapBuffers() but only copies a sub-region of the window
      instead of the whole window.

      This extension is new in Mesa version 2.6



Summary of X-related 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_BACK_BUFFER - specifies how to implement the back color buffer (X only)
   MESA_PRIVATE_CMAP - force aux/tk libraries to use private colormaps (X only)
   MESA_GAMMA - gamma correction coefficients (X only)


----------------------------------------------------------------------
README.CYGWIN - lassauge April 2004 - based on README.X11

			Mesa 6.5 DOS/DJGPP Port v1.8
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Description:
~~~~~~~~~~~~

Well, guess what... this is the DOS port of Mesa 6.5, for DJGPP fans... Whoa!
The driver uses OSMesa to draw off screen, and then blits the buffer.  This is
not terribly efficient, and has some drawbacks, but saves maintenance costs.



Legal:
~~~~~~

Mesa copyright applies.



Installation:
~~~~~~~~~~~~~

Unzip and type:

	make -f Makefile.DJ [OPTIONS...]

Available options:

     Environment variables:
	CPU		optimize for the given processor.
			default = pentium
	GLIDE		path to Glide3 SDK; used with FX.
			default = $(TOP)/glide3
	FX=1		build for 3dfx Glide3. Note that this disables
			compilation of most DMesa code and requires fxMesa.
			As a consequence, you'll need the DJGPP Glide3
			library to build any application.
			default = no
	X86=1		optimize for x86 (if possible, use MMX, SSE, 3DNow).
			default = no

     Targets:
	all:		build everything
	libgl:		build GL
	libglu:		build GLU
	libglut:	build GLUT
	clean:		remove object files
	realclean:	remove all generated files



Tested on:
	Video card:	Radeon 9500
	DJGPP:		djdev 2.04 + gcc v4.1.0 + make v3.80
	OS:		DOS, Win98SE, WinXP (using Videoport driver)



FAQ:
~~~~

1. Compilation

   Q) `make' barfs and exits because it cannot find some stupid file.
   A) You need LFN support.
   A) When compiling for Glide (FX=1), pay attention to Glide path.

   Q) Libraries built OK, but linker complains about `vsnprintf' every time I
      compile some demo.
   A) Upgrade to DJGPP 2.04.
   A) Add `vsnprintf.c' to the CORE_SOURCES in `src/Makefile.DJ' (untested!).
   A) Patch `src/mesa/main/imports.c' with the following line:
	#define vsnprintf(buf, max, fmt, arg) vsprintf(buf, fmt, arg)
      This hack should be safe in 90% of the cases, but if anything goes wrong,
      don't come back to me crying.

   Q) `make' complains about DXE3 or something, yet it builds the libraries.
   A) DXE3 refers to the DJGPP dynamic modules. You'll need either the latest
      DJGPP distro, or download the separate package from my web page. Read the
      DXE3 documentation on how to use them.
   A) When compiling for Glide (FX=1), make sure `glide3x.dxe' can be found in
      LD_LIBRARY_PATH (or top `lib' directory).

2. Using Mesa for DJGPP

   Q) Every test I tried crashes badly.
   A) If you have compiled with SSE and you're running under plain DOS, you
      have to disable SSE at run-time. See environment variables below.

   Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
   A) Is that a question? If you have a 3dfx Voodoo (any model), you're
      lucky (check http://sourceforge.net/projects/glide for the DJGPP port).
      If you haven't, sorry; everything is done in software.

   Q) I tried to set refresh rate w/ DMesa, but without success.
   A) Refresh rate control works only for VESA 3.0 and the 3dfx driver (in
      which case FX_GLIDE_REFRESH will be overwritten if it is defined and
      is not 0).

   Q) I made a simple application and it does nothing. It exits right away. Not
      even a blank screen.
   A) Software drivers (VESA/VGA/NUL) must to be constructed as single-buffered
      visuals.  However, DMesaSwapBuffers must be called to get any output.
   A) Another weird "feature" is that buffer width must be multiple of 8 (I'm a
      lazy programmer and I found that the easiest way to keep buffer handling
      at peak performance ;-).

   Q) I'm getting a "bad font!" fatal error.
   A) Always use GLUT_STROKE_* and GLUT_BITMAP_* constants when dealing with
      GLUT fonts. If you're using `glut.dxe', then make sure GLUT_STROKE_* and
      GLUT_BITMAP_* are mapped to integer constants, not to the actual font
      address (same mechanism used for Win32 _DLL).

   Q) What is NUL driver good for, if I don't get any output at all?
   A) For debugging. The NUL driver is very much like OSMesa. Everything is
      done just the same as VESA/VGA drivers, only it doesn't touch your video
      hardware. You can query the actual buffer by issuing:
	DMesaGetIntegerv(DMESA_GET_BUFFER_ADDR, &buffer);
      and dump it to a file.

   Q) How do I query for a list of available video modes to choose as a visual?
   A) This is an ugly hack, for which I'm sure I'll burn in hell.
      First, query for a list of modes:
	n = DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, NULL);
      If `n' is strictly positive, you allocate an array of pointers to a given
      struct (which is guaranteed to be extended only - not changed in future):
	struct {
		int xres, yres;
		int bpp;
	} **l = malloc(n * sizeof(void *));
      Now pass the newly allocated buffer to fill in:
	DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, (GLint *)l);
      And collect the info:
	for (i = 0; i < n; i++) {
	    printf("%dx%d:%d\n", l[i]->xres, l[i]->yres, l[i]->bpp);
	}

   Q) The GLUT is incomplete.
   A) See below.



libGLUT (the toolkit):
~~~~~~~~~~~~~~~~~~~~~~

Well, this "skeletal" GLUT implementation was taken from AllegGL project and
heavily changed. Thanks should go to Bernhard Tschirren, Mark Kilgard, Brian
Paul and probably others (or probably not ;-). GLUT functionality will be
extended only on an "as needed" basis.

GLUT talks to hardware via PC_HW package which was put together from various
pieces I wrote long time ago. It consists from the keyboard, mouse and timer
drivers.

My keyboard driver used only scancodes; as GLUT requires ASCII values for keys,
I borrowed the translation tables (and maybe more) from Allegro -- many thanks
to Shawn Hargreaves et co. Ctrl-Alt-Del (plus Ctrl-Alt-End, for Windows users)
will shut down the GLUT engine unconditionally: it will raise SIGINT, which in
turn will (hopefully) call the destructors, thus cleaning up your/my mess ;-)
NB: since the DJGPP guys ensured signal handlers won't go beyond program's
space (and since dynamic modules shall) the SIGINT can't be hooked (well, it
can, but it is useless), therefore you must live with the 'Exiting due to
signal SIGINT' message...

The mouse driver is far from complete (lack of drawing, etc), but is enough to
make almost all the demos work. Supports the CuteMouse WheelAPI.

The timer is pretty versatile for it supports multiple timers with different
frequencies. While not being the most accurate timer in the known universe, I
think it's OK. Take this example: you have timer A with a very high rate, and
then you have timer B with very low rate compared to A; now, A ticks OK, but
timer B will probably loose precision!

As an addition, stdout and stderr are redirected and dumped upon exit. This
means that `printf' can be safely called during graphics. A bit of a hack, I
know, because all messages come in bulk, but I think it's better than nothing.
"Borrowed" from LIBRHUTI (Robert Hoehne).

Window creating defaults: (0, 0, 300, 300), 16bpp. However, the video mode is
chosen in such a way that first window will fit. If you need high resolution
with small windows, set initial position far to the right (or way down); then
you can move them back to any position right before the main loop.



Environment variables:
~~~~~~~~~~~~~~~~~~~~~~
	DMESA_NULDRV		- (any value) force NUL driver
	GLUT_FPS		- print frames/second statistics to stderr
	MESA_NO_SSE		- (any value) safe option under pure DOS
	DMESA_GLUT_REFRESH	- set vertical screen refresh rate (VESA3)
	DMESA_GLUT_BPP		- set default bits per pixel (VGA needs 8)
	DMESA_GLUT_ALPHA	- set default alpha bits (8)
	DMESA_GLUT_DEPTH	- set default depth bits (16)
	DMESA_GLUT_STENCIL	- set default stencil bits (8)
	DMESA_GLUT_ACCUM	- set default accum bits (16)



History:
~~~~~~~~

v1.0 (mar-2002)
	initial release

v1.1 (sep-2002)
	+ added 3dfx Glide3 support
	+ added refresh rate control
	+ added fonts in GLUT
	* lots of minor changes

v1.2 (nov-2002)
	* synced w/ Mesa-4.1
	- removed dmesadxe.h

v1.3 (mar-2003)
	+ enabled OpenGL 1.4 support
	+ added MMX clear/blit routines
	+ enabled SGI's GLU compilation
	+ added samples makefile
	+ added new GLUT functions
	+ added color-index modes
	+ added Matrox Millennium MGA2064W driver
	+ added 8bit FakeColor (thanks to Neil Funk)
	+ added VGA support (to keep Ben Decker happy)
	! fixed some compilation errors (reported by Chan Kar Heng)
	* optimized driver for faster callback access... yeah, right :)
	* overhauled virtual buffer and internal video drivers
	* better fxMesa integration
	* revamped GLUT
	* switched to DXE3

v1.4 (dec-2003)
	+ enabled GLUT fonts with DXE
	+ truly added multi-window support in GLUT (for Adrian Woodward)
	* accomodated makefiles with the new sourcetree
	* fixed some ALPHA issues
	* minor changes to PC_HW/timer interface
	x hacked and slashed the 3dfx driver (w/ help from Hiroshi Morii)

v1.5 (jan-2004)
	+ added interface to query available "visuals" (GLFW - Marcus Geelnard)
	+ added GLUT timer callback
	- removed Matrox Millennium MGA2064W driver
	x more changes to the 3dfx driver

v1.6 (aug-2004)
	+ implemented NUL driver
	+ added DMesaGetProcAddress and glutGetProcAddress
	* reorganized fxMesa wrapper to handle multiple contexts
	! fixed a horrible bug in VGA initialization routine
	! fixed partial clears

v1.7 (???-2005)
	+ enabled OpenGL 2.0 support
	+ added support for sw texture compression
	+ added FreeGLUT specific functions
	* no more GLX sources in DOS GLUT
	* made GLUT timer callbacks less accurate but safer

v1.8 (apr-2006)
	* killed lots of code, the driver is now a front-end to OSMesa
	* fixed problem with WinNT (http://www.volny.cz/martin.sulak/)
	- removed 3dfx Glide3 support (temporarily?)



Contact:
~~~~~~~~

Name:   Daniel Borca
E-mail: dborca@users.sourceforge.net
WWW:    http://www.geocities.com/dborca/

GGIMesa for LibGGI 2.x

Requirements:
-------------
LibGGI 2.0 or greater

Installation:
-------------
To install GGIMesa, follow the instructions in INSTALL.GNU.  If you
wish to install GGIGLUT as well, first install GGIMesa and then run

make
make install (must be root)

in ggi/ggiglut.

Notes:
------

* Set the environment variables GGIMESA_DEBUG and/or GGIGLUT_DEBUG
to 255 to see lots of debugging output.

* GGIGLUT contains support for all of the GLUT 3.6 API except for the
high-level primitive drawing functions, but many of the functions (in
particular the menu drawing functions) are just stubs.

Mesa 3.0 for LynxOS builds in the following way:

make lynxos

This will build all the libraries and demo applications. You should have
around 400 megabytes free for everything since everything is done with
static
libraries.

Before using this make file however, you should perform the following
actions:
0) cd to the Mesa-3.0 directory
1) Copy the GL directory under the include directory to /usr/include.
2) Copy the files in the lib directory to /lib.
3) Make links so that the Mesa libraries look like ordinary OpenGL
libraries
in /lib. This is important for compatibility with other OpenGL apps. This
is done as follows:

cd /lib
ln -s libMesaGL.a libGL.a
ln -s libMesaGLU.a libGLU.a

Mesa 3.0 includes the GLUT (GL Utility Toolkit) by default.
The demo applications are done using this toolkit.

Mesa makefiles for building their apps could be used as well, but the
following one is much more concise. Note that the order of the X libraries
is important to the linker so that all symbols get resolved correctly.
Changing the order may result in having to list a library twice to make
sure all linkages are made correctly.

----cut here for Makefile -----

FILES = your_app.x

SPECIAL_INCLUDES = -I/usr/include/GL

SPECIAL_CFLAGS = -g  -ansi -pedantic -funroll-loops -ffast-math -DSHM

SPECIAL_LIBS = -lglut -lGLU -lGL -lm -L/usr/X11/lib -lXext -lXmu -lXi \
-lX11 -lbsd -g

STANDARD_OFILES = $(FILES:.x=.o)

%.o: %.c
	gcc -c $(SPECIAL_CFLAGS) $(SPECIAL_INCLUDES) $< -o $@

all: $(STANDARD_OFILES)
	gcc -o your_app $(STANDARD_OFILES) $(SPECIAL_LIBS)


----cut here for Makefile-----

I have tested Mesa under LynxOS 3.0 and 3.01. It should build fine under
other
versions as well. Note, however, that LynxOS versions prior to 3.0 are not
binary compatible, so you will have to rebuild from source.


Vik Sohal
vik@lynx.com
January 13, 1999

			     Mesa 6.1 for MinGW32
			     ~~~~~~~~~~~~~~~~~~~~



Quick & dirty start:
--------------------

	mingw32-make -f Makefile.mgw [OPTIONS...]

   Look into the corresponding makefiles for further information.
   Check README.3DFX to find out how to compile Mesa Glide3 driver
   with MinGW32!



*******************************************************************************
The Mingw port for Mesa 3-D Graphics Library was created August 30, 1998 by Paul Garceau.

Updated January 13, 2000; June 3, 2005 -- Paul Garceau <pgarceau@users.sourceforge.net>

DISCLAIMER:  I make this port of the Mesa 3-D Graphics Library as a service
to the general public.  I can, in no way support or make any guarantee that the
build will work for your system.

Acknowledgements:

	Daniel Borca, whose work and commitment to maintaining the Mingw port of the Mesa 3-D Graphics Library has been, and will continue to be greatly appreciated by an overworked and underpaid developer such as myself.
	Without the creative inspiration and personal commitment provided by Mumit Khan, Jan-Jaap Vanderhagen and Colin Peters, Mingw would never have existed.  	Acknowledgements also need to be given to all of the developers who have worked on Mingw, Mesa and Msys over the years.
	Last, but certainly far from the least, Brian Paul, who has dedicated at least the last seven or eight years of his life to making Mesa 3-D Graphics Library what it is today and managing the development for all of those years.
*********************************************************************************

Greetings,

	Feel free to modify or change things related to the Mingw build as you see fit, just remember that, the author of the current build may not be able to support any modifications you might want to make to the files which have been included for the build.

Mesa core components are licensed under XFree-86 (for more on licensing of Mesa 3-D Graphics Library, check out the Mesa homepage (http://www.mesa3d.org).

The Mingw generated libraries themselves are licensed under the GNU-LGPL license.  Source code for Mingw can be found at http://www.mingw.org.  For licensing terms on Mingw, please visit http://www.mingw.org.

	It is recommended that you use the latest "stable" release of Mingw.  "Candidates" are beta testing distributions for Mingw.  Mingw is available at http://www.mingw.org.

	This build has been tested under WinNT4/SP6.  Win9x and WinNT5 remain untested by me.  I have not tested any of the demos included with Mesa3d.

Installation:

	This readme assumes that you already have extracted the necessary files to a working directory/folder that Mingw can use to build the Mesa3D libraries and that you know where that directory/folder is located on your Windows system.  If you have any questions about how to set things up properly which is specific to Mesa3D, the folks on the Mesa3D mailing lists (http://www.mesa3d.org) would probably be happy to assist you.  Also you can probably ask anyone on the Mingw mailing lists for any questions specific to Mingw (http://www.mingw.org)

Targets and Environment variables used for Mingw build:

	Before going into the actual build of the libraries, here is a list of available targets for the make process:

	"all" or "libgl"  -- this target will build libopengl.a, a static library.  It will not build the demos, etc.

	clean -- this target will clean up most of the Mesa 3-D Graphics Library/object code from your hard drive.

	realclean -- this target will clean up all of the Mesa 3D Graphics Library and the Mesa object code that it can find.

	Environment Variables:

	The environment variables are used to determine what sort of graphics driver support needs to be included in the finished Mesa 3-D Graphics Library.

	GLIDE		path to Glide3 SDK; used with FX.
			default = $(TOP)/glide3
	FX=1		build for 3dfx Glide3. Note that this disables
			compilation of most WMesa code and requires fxMesa.
			As a consequence, you'll need the Win32 Glide3
			library to build any application.
			default = no
	ICD=1		build the installable client driver interface
			(windows opengl driver interface)
			default = no
	X86=1		optimize for x86 (if possible, use MMX, SSE, 3DNow).
			default = no


Running the Build:

	Launch Mingw.
	From the Windows Command Prompt:
	Set Environment Variables (as needed).
	"cd" to your Mesa3D 'root' directory.
	Enter "mingw32-make -f makefile.mgw <target>

	That's all there is to it.

	Enjoy!

		Paul G. <pgarceau@users.sourceforge.net>
		Daniel Borca <dborca@users.sourceforge.net>



******This section is added by Heromyth <zxpmyth@yahoo.com.cn>*************

====================
Updated on 2007-7-21
====================

Notice:
	1) The generated DLLs are *not* compatible with the ones built
with the other compilers like VC8, especially for GLUT.

	2) Although more tests are needed, it can be used individually!

	3) You can set the options about whether using STDCALL to build MESA. The
config file is <Mesa3D-root>\configs\config.mgw. The default setting is that:
		ALL_USING_STDCALL = 1
, which means using STDCALL to build MESA.

	4) Of course, you can MESA without using STDCALL,I like this:)
The setting is :
		ALL_USING_STDCALL = 0
To do this, however, you must modify wingdi.h which is in MingW's include dir.
For example, run:
	notepad	C:\MingW\include\wingdi.h
, and delete all the lines where all the wgl*() functions are. Because they would
be conflicted with the ones in <Mesa3D-root>\include\GL\mesa_wgl.h.

>>>>>>>>>> Conflicted Functions List >>>>>>>>>>
WINGDIAPI BOOL WINAPI wglCopyContext(HGLRC,HGLRC,UINT);
WINGDIAPI HGLRC WINAPI wglCreateContext(HDC);
WINGDIAPI HGLRC WINAPI wglCreateLayerContext(HDC,int);
WINGDIAPI BOOL WINAPI wglDeleteContext(HGLRC);
WINGDIAPI BOOL WINAPI wglDescribeLayerPlane(HDC,int,int,UINT,LPLAYERPLANEDESCRIPTOR);
WINGDIAPI HGLRC WINAPI wglGetCurrentContext(void);
WINGDIAPI HDC WINAPI wglGetCurrentDC(void);
WINGDIAPI int WINAPI wglGetLayerPaletteEntries(HDC,int,int,int,COLORREF*);
WINGDIAPI PROC WINAPI wglGetProcAddress(LPCSTR);
WINGDIAPI BOOL WINAPI wglMakeCurrent(HDC,HGLRC);
WINGDIAPI BOOL WINAPI wglRealizeLayerPalette(HDC,int,BOOL);
WINGDIAPI int WINAPI wglSetLayerPaletteEntries(HDC,int,int,int,const COLORREF*);
WINGDIAPI BOOL WINAPI wglShareLists(HGLRC,HGLRC);
WINGDIAPI BOOL WINAPI wglSwapLayerBuffers(HDC,UINT);
WINGDIAPI BOOL WINAPI wglUseFontBitmapsA(HDC,DWORD,DWORD,DWORD);
WINGDIAPI BOOL WINAPI wglUseFontBitmapsW(HDC,DWORD,DWORD,DWORD);
WINGDIAPI BOOL WINAPI wglUseFontOutlinesA(HDC,DWORD,DWORD,DWORD,FLOAT,FLOAT,int,LPGLYPHMETRICSFLOAT);
WINGDIAPI BOOL WINAPI wglUseFontOutlinesW(HDC,DWORD,DWORD,DWORD,FLOAT,FLOAT,int,LPGLYPHMETRICSFLOAT);
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

====================
Updated on 2007-7-22
====================
	I havn't thought that I would find a better way to solve my problems so soon.
I changed the method in which the import-libs and DLLs are made. After this update,
the DLLs of MESA are more optimized and more compatible.
	It seems that there is no need to keep the building way of 'NO-STDCALL'.The
way of USING_STDCALL is so nice! The file <Mesa3D-root>\configs\config.mgw is
also not needed, and can be deleted safely!



*********************************************************************************

			Mesa 3.0 MITS Information


This software is distributed under the terms of the GNU Library
General Public License, see the LICENSE file for details.


This document is a preliminary introduction to help you get
started. For more detaile information consult the web page.

http://10-dencies.zkm.de/~mesa/



Version 0.1 (Yes it's very alpha code so be warned!)
Contributors:
  Emil Briggs    	(briggs@bucky.physics.ncsu.edu)
  David Bucciarelli 	(tech.hmw@plus.it)
  Andreas Schiffler 	(schiffler@zkm.de)



1. Requirements:
     Mesa 3.0.
     An SMP capable machine running Linux 2.x
     libpthread installed on your machine.


2. What does MITS stand for?
     MITS stands for Mesa Internal Threading System. By adding
     internal threading to Mesa it should be possible to improve
     performance of OpenGL applications on SMP machines.


3. Do applications have to be recoded to take advantage of MITS?
     No. The threading is internal to Mesa and transparent to
     applications.


4. Will all applications benefit from the current implementation of MITS?
     No. This implementation splits the processing of the vertex buffer
     over two threads. There is a certain amount of overhead involved
     with the thread synchronization and if there is not enough work
     to be done the extra overhead outweighs any speedup from using
     dual processors. You will not for example see any speedup when
     running Quake because it uses GL_POLYGON and there is only one
     polygon for each vertex buffer processed. Test results on a
     dual 200 Mhz. Pentium Pro system show that one needs around
     100-200 vertices in the vertex buffer before any there is any
     appreciable benefit from the threading.


5. Are there any parameters that I can tune to try to improve performance.
     Yes. You can try to vary the size of the vertex buffer which is
     define in VB_MAX located in the file src/vb.h from your top level
     Mesa distribution. The number needs to be a multiple of 12 and
     the optimum value will probably depend on the capabilities of
     your machine and the particular application you are running.


6. Are there any ways I can modify the application to improve its
   performance with the MITS?
     Yes. Try to use as many vertices between each Begin/End pair
     as possbile. This will reduce the thread synchronization
     overhead.


7. What sort of speedups can I expect?
     On some benchmarks performance gains of up to 30% have been
     observerd. Others may see no gain at all and in a few rare
     cases even some degradation.


8. What still needs to be done?
     Lots of testing and benchmarking.
     A portable implementation that works within the Mesa thread API.
     Threading of additional areas of Mesa to improve performance
     even more.



Installation:

   1. This assumes that you already have a working Mesa 3.0 installation
      from source.
   2. Place the tarball MITS.tar.gz in your top level Mesa directory.
   3. Unzip it and untar it. It will replace the following files in
      your Mesa source tree so back them up if you want to save them.


	 README.MITS
         Make-config
	 Makefile
	 mklib.glide
         src/vbxform.c
	 src/vb.h

   4. Rebuild Mesa using the command

          make linux-386-glide-mits

The NeXT support has now been incorporated into the OpenStep support.
You can build NeXT libraries simply by typing "make next", though before
linking they will need to be ranlib'd by hand. For more information see
the README.OpenStep file, together with the README files in OpenStep/Old_Demos.

-Pete French. (pete@ohm.york.ac.uk) 28/5/1998

            README for port of Mesa 3.x to XFree86 on OS/2 (X/2)
                          (as of 19990514)


                           Contents:

                           1) Binary release
                           2) Building from sources
                           3) History
                           4) Todo
                           5) Mesa Home Page


1) Binary release

   Though the Mesa sources should build in a quite reasonable time even on
   a 585 class machine a binary relase is available (check topic 4) for an URL)
   This package includes:

     - lib/MesaGL.dll,  MesaGL.a
     - lib/MesaGLU.dll, MesaGLU.a
     - lib/glut.dll,    glut.a
     - include/GL/*.h

    Installing this in your XFree86 tree will enable you to build and
    run all applications compatible with Mesa (and the current DLL
    interface, of course ;-)
    As usual the OMF-style libraries can be created using emxomf.
    (e.g. "emxomf foo.a"  creates the foo.lib omf-style library).
    The static libraries are rarely used and you have to rebuild
    Mesa to get them. They're a supported target, so you get
    them in a straightforward way (see below).

    The testing of these libraries was limited to the supplied
    demos/examples and a quite small number of third-party apps.
    No warranty ... as usual ...  ;-)


2)  Instructions to build Mesa 3.x for XFree86/OS2 from sources:

    Except the official Mesa source distribution you need:
      - a recent version of XFree86 (3.3.x or above) including
        the programming libraries
      - EMX 0.9c (0.9d might work, never checked)
      - GNU make
      - REXX (!)

    The creation of the DLLs as well as of the static libraries
    (if you want to have them) is handled in "mklib-emx.cmd",
    a small REXX script. Perhaps not the best idea, but this
    way it fits best in the scheme used to build libraries
    on all platforms in Mesa 3.x.

    To actually build the libraries and demos, check mklib-emx.cmd
    and modify it as desired. Then type
      make os2-x11
    and wait for completion ;-)


3)  History

    Initially Darren Abbott (abbott@hiwaay.net) ported Mesa versions 2.x
    to XFree86 OS/2. This port might still be available from
       http://fly.HiWAAY.net/~abbott/xfree86-os2/xfree86.html

    The current port picked up things during the beta test for 3.0.
    No major changes in the source were done. The build mechanism under OS/2
    has been made very similar to other platforms (if you treat mklib-emx.cmd
    as a "black box").
    Advantage is that X/2 is now a valid target and all files are
    integrated in the official source distribution.
    Disadvantage is that this port (i.e. the DLLs' interface itself) is
    definitly NOT COMPATIBLE to those of version 2.x.
    It's uncertain whether this would be at all possible but since there
    a _very_ few those apps it's not worth to find out anyway.
    Also some libs (MesaTK, MesaAUX) are withdrawn from the Mesa distribution,
    and accordingly from the OS/2 port.

4) Todo

    By now binary compatiblity is ensured by using the function names
    as entry points instead of ordinals. This might cost performance and
    is subject to change in future. In addition the supplied X86 assembler
    source is not used yet.

5)  Mesa Home Page

    You can get the source code and more information about Mesa from
       http://www.mesa3d.org/

    The OS/2 ports should be available from
       http://r350.ee.ntu.edu.tw/~hcchu/os2/ports

--
Alexander Mai
st002279@hrzpub.tu-darmstadt.de

This is a port of the GL and GLU libraries to NeXT/Apple object
orientated systems. As these systems have their own window handling
systems we simply use the offscreen rendering capability of Mesa
to generate bitmaps which may then be displayed by the application
with a View as required. Example pieces of code may be found in the
OpenStep directory.

Sadly there are now a proliferation of different system that we need to
support compilation for: The original NextStep system, The OpenStep
system, the Rhapsody/Mac OS X system and also the windows implementations
of the latter two systems. This version of the code has been compiled and
tested under the following architectures:

	NextStep 3.3
	OpenStep 4.2
	Rhapsody DR2
	WebObjects for NT 3.5
	WebObjects for NT 4.0

All tests were done with Intel processors. Feedback on other systems would,
however, be appreciated !

On UNIX systems simply type "make openstep". Under Windows systems
with WebObjects run the "win32-openstep.sh" script from within the Bourne
shell provided with the development environment. In both cases this will
build the libraries and place them into the "lib" directory. Some examples
may be found in the OpenStep directory showing how to use the code in an
actual application (MesaView) as well as some command line demos.

The CC variable may be specified on the command line for doing such things
as building FFAT libraries or using alternative compilers to the standard 'cc'
e.g.  make CC='cc -arch m68k -arch i386' openstep" will build the libraries
with both intel and motorola architectures.

-Pete French. (pete@ohm.york.ac.uk) 7/6/1999

             Info on using Mesa 3.0 with Linux Quake I and Quake II



Disclaimer
----------

I am _not_ a Quake expert by any means.  I pretty much only run it to
test Mesa.  There have been a lot of questions about Linux Quake and
Mesa so I'm trying to provide some useful info here.  If this file
doesn't help you then you should look elsewhere for help.  The Mesa
mailing list or the news://news.3dfx.com/3dfx.linux.glide newsgroup
might be good.

Again, all the information I have is in this file.  Please don't email
me with questions.

If you have information to contribute to this file please send it to
me at brianp@elastic.avid.com



Linux Quake
-----------

You can get Linux Quake from http://www.idsoftware.com/

Quake I and II for Linux were tested with, and include, Mesa 2.6.  You
shouldn't have too many problems if you simply follow the instructions
in the Quake distribution.



RedHat 5.0 Linux problems
-------------------------

RedHat Linux 5.x uses the GNU C library ("glibc" or "libc6") whereas
previous RedHat and other Linux distributions use "libc5" for its
runtime C library.

Linux Quake I and II were compiled for libc5.  If you compile Mesa
on a RedHat 5.x system the resulting libMesaGL.so file will not work
with Linux Quake because of the different C runtime libraries.
The symptom of this is a segmentation fault soon after starting Quake.

If you want to use a newer version of Mesa (like 3.x) with Quake on
RedHat 5.x then read on.

The solution to the C library problem is to force Mesa to use libc5.
libc5 is in /usr/i486-linux-libc5/lib on RedHat 5.x systems.

Emil Briggs (briggs@tick.physics.ncsu.edu) nicely gave me the following
info:

>   I only know what works on a RedHat 5.0 distribution. RH5 includes
> a full set of libraries for both libc5 and glibc. The loader ld.so
> uses the libc5 libraries in /usr/i486-linux-libc5/lib for programs
> linked against libc5 while it uses the glibc libraries in /lib and
> /usr/lib for programs linked against glibc.
>
> Anyway I changed line 41 of mklib.glide to
>     GLIDELIBS="-L/usr/local/glide/lib -lglide2x -L/usr/i486-linux-libc5/lib"
>
> And I started quake2 up with a script like this
> #!/bin/csh
> setenv LD_LIBRARY_PATH /usr/i486-linux-libc5/lib
> setenv MESA_GLX_FX f
> ./quake2 +set vid_ref gl
> kbd_mode -a
> reset


I've already patched the mklib.glide file.  You'll have to start Quake
with the script shown above though.



**********************

Daryll Strauss writes:

Here's my thoughts on the problem. On a RH 5.x system, you can NOT build
a libc5 executable or library. Red Hat just doesn't include the right
stuff to do it.

Since Quake is a libc5 based application, you are in trouble. You need
libc5 libraries.

What can you do about it? Well there's a package called gcc5 that does
MOST of the right stuff to compile with libc5. (It brings back older
header files, makes appropriate symbolic links for libraries, and sets
up the compiler to use the correct directories) You can find gcc5 here:
ftp://ecg.mit.edu/pub/linux/gcc5-1.0-1.i386.rpm

No, this isn't quite enough. There are still a few tricks to getting
Mesa to compile as a libc5 application. First you have to make sure that
every compile uses gcc5 instead of gcc. Second, in some cases the link
line actually lists -L/usr/lib which breaks gcc5 (because it forces you
to use the glibc version of things)

If you get all the stuff correctly compiled with gcc5 it should work.
I've run Mesa 3.0B6  and its demos in a window with my Rush on a Red Hat
5.1 system. It is a big hassle, but it can be done. I've only made Quake
segfault, but I think that's from my libRush using the wrong libc.

Yes, mixing libc5 and glibc is a major pain. I've been working to get
all my libraries compiling correctly with this setup. Someone should
make an RPM out of it and feed changes back to Brian once they get it
all working. If no one else has done so by the time I get the rest of my
stuff straightened out, I'll try to do it myself.

							- |Daryll



*********************

David Bucciarelli (tech.hmw@plus.it) writes:

I'm using the Mesa-3.0beta7 and the RedHat 5.1 and QuakeII is
working fine for me.  I had only to make a small change to the
Mesa-3.0/mklib.glide file, from:


    GLIDELIBS="-L/usr/local/glide/lib -lglide2x
-L/usr/i486-linux-libc5/lib -lm"

to:

    GLIDELIBS="-L/usr/i486-linux-libc5/lib -lglide2x"

and to make two symbolic links:

[david@localhost Mesa]$ ln -s libMesaGL.so libMesaGL.so.2
[david@localhost Mesa]$ ln -s libMesaGLU.so libMesaGLU.so.2

I'm using the Daryll's Linux glide rpm for the Voodoo2 and glibc (it
includes also the Glide for the libc5). I'm not using the /dev/3Dfx and
running QuakeII as root with the following env. var:

export
LD_LIBRARY_PATH=/dsk1/home/david/src/gl/Mesa/lib:/usr/i486-linux-libc5/lib

I think that all problems are related to the glibc, Quake will never
work if you get the following output:

[david@localhost Mesa]$ ldd lib/libMesaGL.so
        libglide2x.so => /usr/lib/libglide2x.so (0x400f8000)
        libm.so.6 => /lib/libm.so.6 (0x40244000)
        libc.so.6 => /lib/libc.so.6 (0x4025d000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00000000)

You must get the following outputs:

[david@localhost Mesa]# ldd lib/libMesaGL.so
        libglide2x.so => /usr/i486-linux-libc5/lib/libglide2x.so
(0x400f3000)

[root@localhost quake2]# ldd quake2
        libdl.so.1 => /lib/libdl.so.1 (0x40005000)
        libm.so.5 => /usr/i486-linux-libc5/lib/libm.so.5 (0x40008000)
        libc.so.5 => /usr/i486-linux-libc5/lib/libc.so.5 (0x40010000)

[root@localhost quake2]# ldd ref_gl.so
        libMesaGL.so.2 =>
/dsk1/home/david/src/gl/Mesa/lib/libMesaGL.so.2 (0x400eb000)
        libglide2x.so => /usr/i486-linux-libc5/lib/libglide2x.so
(0x401d9000)
        libX11.so.6 => /usr/i486-linux-libc5/lib/libX11.so.6
(0x40324000)
        libXext.so.6 => /usr/i486-linux-libc5/lib/libXext.so.6
(0x403b7000)
        libvga.so.1 => /usr/i486-linux-libc5/lib/libvga.so.1
(0x403c1000)
        libm.so.5 => /usr/i486-linux-libc5/lib/libm.so.5 (0x403f5000)
        libc.so.5 => /usr/i486-linux-libc5/lib/libc.so.5 (0x403fd000)


***********************

Steve Davies (steve@one47.demon.co.uk) writes:


Try using:

    export LD_LIBRARY_PATH=/usr/i486-linux-libc5/lib
    ./quake2 +set vid_ref gl

to start the game... Works for me, but assumes that you have the
compatability libc5 RPMs installed.


***************************

WWW resources - you may find additional Linux Quake help at these URLs:


http://quake.medina.net/howto

http://webpages.mr.net/bobz

http://www.linuxgames.com/quake2/



----------------------------------------------------------------------

Mesa Threads README
-------------------

Thread safety was introduced in Mesa 2.6 by John Stone and
Christoph Poliwoda.

It was redesigned in Mesa 3.3 so that thread safety is
supported by default (on systems which support threads,
that is).  There is no measurable penalty on single
threaded applications.

NOTE that the only _driver_ which is thread safe at this time
is the OS/Mesa driver!


At present the mthreads code supports three thread APIS:
  1) POSIX threads (aka pthreads).
  2) Solaris / Unix International threads.
  3) Win32 threads (Win 95/NT).

Support for other thread libraries can be added src/glthread.[ch]


In order to guarantee proper operation, it is
necessary for both Mesa and application code to use the same threads API.
So, if your application uses Sun's thread API, then you should build Mesa
using one of the targets for Sun threads.

The mtdemos directory contains some example programs which use
multiple threads to render to osmesa rendering context(s).

Linux users should be aware that there exist many different POSIX
threads packages. The best solution is the linuxthreads package
(http://pauillac.inria.fr/~xleroy/linuxthreads/) as this package is the
only one that really supports multiprocessor machines (AFAIK). See
http://pauillac.inria.fr/~xleroy/linuxthreads/README for further
information about the usage of linuxthreads.

If you are interested in helping with thread safety work in Mesa
join the Mesa developers mailing list and post your proposal.


Regards,
  John Stone           -- j.stone@acm.org  johns@cs.umr.edu
  Christoph Poliwoda   -- poliwoda@volumegraphics.com


Version info:
   Mesa 2.6 - initial thread support.
   Mesa 3.3 - thread support mostly rewritten (Brian Paul)

VMS support contributed by Jouk Jansen (joukj@hrem.stm.tudelft.nl)


The latest version was tested on a VMSAlpha7.2 system using DECC6.0, but
probably also works for other versions.

At the moment only the libraries LIBMESGL.EXE/LIBMESGL.OLB,
LIBMESAGLU.EXE/LIBMESAGLU.OLB and LIBGLUT.EXE/LIBGLUT.OLB and the demos of the
directory [.DEMOS] can be build.
However, feel free to create the missing "decrip.mms-files" in the other
directories.

 The make files were tested
using the DIGITAL make utility called MMS.  There is also a public domain
clone available (MMK) and I  think, but it is not tested, that this
utility will give (hardly) any problem.

To make everything just type MMS (or MMK) in the main directory of
mesagl.  For MMS the deafult makefile is called descrip.mms, and
that is what I have called it.  I included alse some config files,
all having mms somewhere in the name which all the makefiles need
(just as your unix makefiles).

On Alpha platforms at default a sharable images for the libraries are created.
To get a static library make it by typing MMS/MACRO=(NOSHARE=1).
On VAX platforms only static libraries can be build.

23-sep-2005
changed default compilation to use /float=ieee/ieee=denorm. The reason for
this is that it makes Mesa on OpenVMS better compatible with other platforms
and other packages for VMS that I maintain.
For more information see
      http://nchrem.tnw.tudelft.nl/openvms
      https://bugs.freedesktop.org/show_bug.cgi?id=4270
You may want to compile Mesa to use VAX-floating point arithmetic, instead
of IEEE floating point by removing the /float=IEEE/denorm flag from the
compiler options in the descrip.mms files.

File: docs/README.WIN32

Last updated: Apr 25, 2007 - Karl Schultz - kschultz@users.sourceforge.net

Quick Start
----- -----

Unzip the MesaLib, MesaGLUT, and MesaDemos ZIP files into the same
directory.  The libs and demos build separately, so if you do not care
about the demos or GLUT, you only need to unzip MesaLib.  If you unzip
more than one ZIP file, they all need to be unzipped into the same
directory.  Don't worry, you will not overwrite anything.

The Windows build system uses Microsoft Visual Studio.  Project files
for a specific version of Visual Studio are in their own directory in
the top-level "windows" directory.  For example, Visual Studio 8 files
are in windows/VC8.

Support has been dropped for versions of Visual Studio prior to 8. The
main reason is because Microsoft now provides a free compiler and
developer environment.  Visual Studio Express can be found at

http://msdn.microsoft.com/vstudio/express/visualc/default.aspx

You'll also need the Platform SDK.  Instructions for obtaining and
using the SDK with Visual Studio Express can be found at

http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/

The project files to build the core Mesa library, Windows Mesa
drivers, OSMesa, and GLU are in the mesa directory.  The project files
to build GLUT and some demo programs are in the progs directory.

Makefiles are no longer shipped or supported, but can be generated
from the projects using Visual Studio.


Windows Drivers
------- -------

At this time, only the GDI driver is known to work.  Most of the demos
in progs/demos should work with this driver.

Source code also exists in the tree for other drivers in
src/mesa/drivers/windows, but the status of this code is unknown.

The GDI driver operates basically by writing pixel spans into a DIB
section and then blitting the DIB to the window.  The driver was
recently cleaned up and rewitten and so may have bugs or may be
missing some functionality.  The older versions of the CVS source may
be useful in figuring out any problems, or report them to me.

To build Mesa with the GDI driver, build the mesa, gdi, and glu
projects in the Visual Studio workspace found at

	windows/VC8/mesa/mesa.sln

The osmesa DLL can also be built with the osmesa project.

The build system creates a lib top-level directory and copies
resulting LIB and DLL files to this lib directory.  The files are:

	OPENGL32.LIB, GLU32.LIB, OSMESA32.LIB
	OPENGL32.DLL, GLU32.DLL, OSMESA32.DLL

If the MesaDemos ZIP file was extracted, the DLL files are also copied
to the demos directory.  This facilitates running the demos as described
below.


GLUT and Demos
---- --- -----

A Visual Studio workspace can be found at

	windows/VC8/progs/progs.sln

It can be used to build GLUT and a few demos.  The GLUT lib and DLL
are copied to the top-level lib directory, along with the Mesa libs.

The demo build system expects to find the LIB files in the top level
lib directory, so you must build the Mesa libs first.  The demo
executables are placed in the demos directory, because some of them
rely on data files found there.  Also, the Mesa lib DLL's were copied
there by the Mesa lib build process.  Therefore, you should be able to
simply run the demo executables from the demo directory.

If you want to run the demos from the Visual Studio, you may have to
change the startup directory and explicitly state where the executables are.

You may also build all the demo programs by using a makefile.  Go to
the progs/demos directory and make sure you have executed VCVARS32.BAT
or whatever setup script is appropriate for your compiler.  Then,

	nmake -f Makefile.win

should build all the demos.


Build System Notes
----- ------ -----

VC8
---

No notes.


General
-------

After building, you can copy the above DLL files to a place in your
PATH such as $SystemRoot/SYSTEM32.  If you don't like putting things
in a system directory, place them in the same directory as the
executable(s).  Be careful about accidentially overwriting files of
the same name in the SYSTEM32 directory.

The DLL files are built so that the external entry points use the
stdcall calling convention.

Static LIB files are not built.  The LIB files that are built with are
the linker import files associated with the DLL files.

The si-glu sources are used to build the GLU libs.  This was done
mainly to get the better tessellator code.

To build "mangled" Mesa, add the preprocessor define USE_MGL_NAMESPACE
to the project settings.  You will also need to edit src/mesa.def to
change all the gl* symbols to mgl*.  Because this is easy to do with a
global replace operation in a text editor, no additional mangled
version of mesa.def is maintained or shipped.

If you have a Windows-related build problem or question, it is
probably better to direct it to me (kschultz@users.sourceforge.net),
rather than directly to the other Mesa developers.  I will help you as
much as I can.  I also monitor the Mesa mailing lists and will answer
questions in this area there as well.


Karl Schultz

                        WindML Driver for Mesa 4.0


Requirements
------------

Tornado 2 + WindML, Cumulative Patchs are recommended.

I suppose you have a valid WindML installation. Double buffer hardware
gives better performance than double buffer software so if you can
compile your WindML driver with this option, just do it. I/O
redirection is adviced in target server.


Tested on
---------

During the development, my main target was a CoolMonster:
- Video card: CT69000
- CPU: PENTIUM 266MHz

and my host a Windows NT + Tornado 2.


Installation
------------

1. Mesa sources must be in root directory (C:\)

2. Add the following line to your torVars.bat:
set MESA_BASE=C:\Mesa

OR copy the new torVars.bat in your bin path:
c:/Mesa/src/ugl/tornado/torVars.sample ->
/mnt/nt/Tornado/host/x86-win32/bin/torVars (for example)

3. In a command prompt:
$ torVars
$ cd c:\Mesa
$ make -f Makefile.ugl CPU=PENTIUM

Take a long while...

5. Include all the files from ugldemos folder to build some downloadable
   application modules

4. Download UGL/Mesa object files on target

For example via the WindShell:
ld < c:\Tornado\target\lib\objMesaGL.o
ld < c:\Tornado\target\lib\objMesaUGL.o
ld < c:\Tornado\target\lib\objMesaGLU.o
ld < c:\Tornado\target\lib\objGLUTshapes.o
ld < c:\Tornado\target\lib\objMesaOS.o

You can put the previous lines in a file and use:
< filename

6. Download the application modules.

7. In WindShell, run:
-> uglalldemos

During the show some messages will appear, it provides some useful
information on key management.


Coding
------

Sample Usage:

In addition to the usual ugl calls to initialize UGL, (may be find an
input driver), you must do the following to use the UGL/Mesa interface:

1. Call uglMesaCreateContext() to create a UGL/Mesa rendering context,
   given the display format.

2. Call uglMesaMakeCurrent() to bind the UGL/Mesa buffers to an
   UGL/Mesa Context and to make the context the current one.

3. Make gl* calls to render your graphics.

4. Use uglMesaSwapBuffers() when double buffering to swap front/back buffers.

5. Before the UGL is destroyed, call MesaDestroyContext().

6. Before exiting, call if required uglEventQDestroy and then
   uglDeinitialize();

Limitations
-----------

I found the following limitations in my driver :
 - Color Indexed management is only in 8 bits
 - It's possible to mix UGL/OpenGL application with a software
   double buffer

Modifications
------------

New files in Mesa:
- Makefile.ugl
- rules.windmlmesa
- docs/README.UGL
- include/GL/uglmesa.h
- si-glu/Makefile.ugl
- src/Makefile.ugl
- src/ugl/torGLUTShapesInit.c
- src/ugl/torMesaUGLInit.c
- src/ugl/ugl_api.c
- src/ugl/ugl_dd.c
- src/ugl/ugl_glutshapes.c
- src/ugl/ugl_line.c
- src/ugl/ugl_span.c
- src/ugl/ugl_tri.c
- src/ugl/uglmesaP.h
- ugldemos/*

Modified files in Tornado 2.0:
- c:\Tornado\host\x86-win32\bin\torVars.bat
rem Command line build environments
set WIND_HOST_TYPE=x86-win32
set WIND_BASE=C:\Tornado
set MESA_BASE=C:\Mesa
set PATH=%WIND_BASE%\host\%WIND_HOST_TYPE%\bin;%PATH%
- c:\Tornado\target\config\comps\VxWorks\01uglmesa.cdf
- c:\Tornado\target\h\GL\*

Todo
----
- GCC 2.96, ASM compilation

Thanks to:
----------

Precision Insight team for their great job around Mesa, XFree, and DRI.
Wind River Systems to take me as an intern.


Stephane Raimbault
<stephane.raimbault@windriver.com>
<stephane.raimbault@deesse.univ-lemans.fr>

July 24, 2001