initial rev

1 files changed, 594 insertions, 0 deletions

diff --git a/docs/README.3DFX b/docs/README.3DFX
new file mode 100644
index 0000000000..4431516e78
--- /dev/null
+++ b/docs/README.3DFX
@@ -0,0 +1,594 @@
+
+                     3Dfx Glide device driver for Mesa 3.0
+				(see below for FAQ)
+
+
+This software is distributed under the terms of the GNU Library
+General Public License, see the LICENSE file for details.
+
+
+
+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");
+
+	- Mesa 3.0;
+
+	- 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.0 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.);
+
+	- A lot of patience, this is an alpha release.
+
+	- 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.0.tar.gz and MesaDemos-3.0.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.0 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.0/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.0/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.0 and run the mesafx.bat;
+
+	- The script will compile everything (Mesa-3.0/lib/OpenGL32.{lib,dll},
+	  Mesa-3.0/lib/GLU32.{lib,dll}, Mesa-3.0/lib/GLUT32.{lib,dll} and
+          Voodoo demos);
+
+	- At the end, you will be in the Mesa-3.0/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.0/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).
+
+        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:
+        --------------------------------------------------------
+
+	Undefine the MESA_GLX_FX env var and 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.
+
+
+Know BUGS and Problems:
+-----------------------
+
+	- 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.0/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 the current Glide
+	  version and of the Voodoo hardware. See Mesa-3.0/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.0/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.0 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.0/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, you have simply to include some informations about authors
+and where the library sources are available (check the LICENSE
+file for more informations about the GNU GPL).
+
+
+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 (tech.hmw@plus.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