diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.3DFX | 594 |
1 files changed, 594 insertions, 0 deletions
diff --git a/docs/README.3DFX b/docs/README.3DFX new file mode 100644 index 00000000000..4431516e782 --- /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 ([email protected]) + +Humanware s.r.l. +Via XXIV Maggio 62 +Pisa, Italy +Tel./Fax +39-50-554108 +email: [email protected] +www: www-hmw.caribel.pisa.it |