docs/README.3DFX

   1
   2                      3Dfx Glide device driver for Mesa 3.1
   3                                 (see below for FAQ)
   4
   5
   6 This software is distributed under the terms of the GNU Library
   7 General Public License, see the LICENSE file for details.
   8
   9
  10
  11 What do you need ?
  12 ------------------
  13
  14         - A PC with a 3Dfx Voodoo1/2 Graphics or Voodoo Rush based board
  15           (Pure3D, Monster 3D, R3D, Obsidian, Stingray 128/3D, etc.).
  16           The Quantum3D Obsidian3D-2 X-24 requires some special env. setting
  17           under Linux (more information in the "Useful Glide Environment
  18           Variables");
  19
  20         - Mesa 3.1;
  21
  22         - The 3Dfx Glide library 2.3 or later for your OS (the 2.4 works fine).
  23           The Voodoo2 requires the Glide library 2.51. The Glide 3.1 is not
  24           compatible with the Glide 2.x so it doesn't work with the current
  25           version of the driver;
  26
  27         - A compiler supported by the Glide library (Micro$oft VC++ (tested),
  28           Watcom (tested), GCC for Linux (tested), etc.);
  29
  30         - A lot of patience, this is an alpha release.
  31
  32         - It's nice to have two monitors - one for your normal graphics
  33           card and one for your 3Dfx card. If something goes wrong with
  34           an application using the 3Dfx hardware you can still see your
  35           normal screen in order to recover.
  36
  37
  38
  39 Tested on:
  40 ----------
  41         Windows 95 - David Bucciarelli
  42         Windows NT - Henri Fousse
  43         MS-DOS
  44         Linux - Daryll Strauss, Brian Paul, David Bucciarelli
  45         FreeBSD
  46         BeOS - Duncan Wilcox
  47         MacOS - Fazekas Miklos
  48
  49
  50 What is able to do ?
  51 --------------------
  52
  53         - It is able accelerate points, lines and polygon with flat
  54           shading, gouraud shading, Z-buffer, texture mapping, blending, fog and
  55           antialiasing (when possible). There is also the support for rendering
  56           in a window with a slow trick for the Voodoo Graphics (available only
  57           for Linux) and at full speed with the Voodoo Rush chipset.
  58           Under Linux is also possible to switch on-the-fly between the fullscreen
  59           and in-window rendering hack.
  60           There is also the support for using more than one Voodoo Graphics in the
  61           some application/PC (you can create one context for each board and use
  62           multiple video outputs for driving monitors, videoprojectors or HMDs).
  63           The driver is able to fallback to pure software rendering when afeature
  64           isn't supported by the Voodoo hardware (however software rendering is
  65           very slow compared to hardware supported rendering)
  66
  67
  68
  69 How to compile:
  70 ---------------
  71
  72 Linux:
  73 ------
  74         Here are the basic steps for using the 3Dfx hardware with Mesa
  75         on Linux:
  76
  77         - You'll need the Glide library and headers.  Mesa expects:
  78                 /usr/local/glide/include/*.h        // all the Glide headers
  79                 /usr/local/glide/lib/libglide2x.so
  80
  81           If your Glide libraries and headers are in a different directory
  82           you'll have to modify the Mesa-config and mklib.glide files.
  83
  84         - Unpack the MesaLib-3.1.tar.gz and MesaDemos-3.1.tar.gz archives;
  85
  86         - If you're going to use a newer Mesa/Glide driver than v0.27 then
  87           unpack the new driver archive over the Mesa directory.
  88
  89         - In the Mesa-3.1 directory type "make linux-glide"
  90
  91         - Compilation _should_ finish without errors;
  92
  93         - Set your LD_LIBRARY_PATH environment variable so that the
  94           libglide2x.so and Mesa library files can be found.  For example:
  95             setenv LD_LIBRARY_PATH "/usr/local/glide/lib:/SOMEDIR/Mesa-3.1/lib"
  96
  97         - You'll have to run Glide-based programs as root or set the suid
  98           bit on executables;
  99
 100         - Try a demo:
 101             cd gdemos
 102             su
 103             setenv MESA_GLX_FX f
 104             ./gears     (hit ESC to exit)
 105
 106         - You can find the demos especially designed for the Voodoo driver in
 107           in the Mesa-3.1/3Dfx/demos directory (type "make" in order to compile
 108           everything).
 109
 110 MacOS:
 111 ------
 112         Check the WEB page at http://valerie.inf.elte.hu/~boga/Mesa.html
 113
 114 MS Windows:
 115 -----------
 116
 117         For the MSVC++:
 118         - The glide2x.lib have to be in the default MSVC++ lib directory;
 119
 120         - The Glide headers have to be in the default MSVC++ include directory;
 121
 122         - You must have the vcvars32.bat script in your PATH;
 123
 124         - Go to the directory Mesa-3.1 and run the mesafx.bat;
 125
 126         - The script will compile everything (Mesa-3.1/lib/OpenGL32.{lib,dll},
 127           Mesa-3.1/lib/GLU32.{lib,dll}, Mesa-3.1/lib/GLUT32.{lib,dll} and
 128           Voodoo demos);
 129
 130         - At the end, you will be in the Mesa-3.1/3Dfx/demos directory;
 131
 132         - Try some demo (fire.exe, teapot.exe, etc.) in order to check if
 133           everything is OK (you can use Alt-Tab or Ctrl-F9 to switch between
 134           the Voodoo screen and the windows desktop);
 135
 136         - Remember to copy the Mesa OpenGL32.dll, GLU32.dll and GLUT32.dll in the
 137           some directory were you run your Mesa based applications.
 138
 139         - I think that you can easy change the Makefile.fx files in order
 140           to work with other kind of compilers;
 141
 142         - To discover how open the 3Dfx screen, read the sources under
 143           the Mesa-3.1/3Dfx/demos directory. You can use the GLUT library or
 144           the Diego Picciani's wgl emulator.
 145
 146         NOTE: the MSVC++ 5.0 optimizer is really buggy. Also if you install the
 147         SP3, you could have some problem (you can disable optimization in order
 148         solve these kind of problems).
 149
 150
 151 Doing more with Mesa & Linux Glide:
 152 -----------------------------------
 153
 154         The MESA_GLX_FX environment variable can be used to coax most
 155         GLX-based programs into using Glide (and the __GLUT library
 156         is GLX-based__).
 157
 158         Full-screen 3Dfx rendering:
 159         ---------------------------
 160
 161         1. Set the MESA_GLX_FX variable to "fullscreen":
 162
 163                 ksh:
 164                         export MESA_GLX_FX = "fullscreen"
 165                 csh:
 166                         setenv MESA_GLX_FX fullscreen
 167
 168         2. As root, run a GLX-based program (any GLUT demo on Linux).
 169
 170         3. Be careful:  once the 3Dfx screen appears you won't be able
 171         to see the GLUT windows on your X display.  This can make using
 172         the mouse tricky!  One solution is to hook up your 3Dfx card to
 173         a second monitor.  If you can do this then set these env vars
 174         first:
 175
 176                 setenv SST_VGA_PASS 1
 177                 setenv SST_NOSHUTDOWN
 178
 179         or for the Voodoo2:
 180
 181                 setenv SSTV2_VGA_PASS 1
 182                 setenv SSTV2_NOSHUTDOWN
 183
 184         Rendering into an X window with the help of the Voodoo hardware:
 185         ----------------------------------------------------------------
 186
 187         1. Start your X server in 16 bpp mode (XFree86:  startx -- -bpp 16)
 188            in order to have the best performance and the best visual
 189            quality. However you can use any visual depth supported by X.
 190
 191         2. Set the following environment variables:
 192                 export MESA_GLX_FX="window"     // to enable window rendering
 193                 export SST_VGA_PASS=1   // to stop video signal switching
 194                 export SST_NOSHUTDOWN=1 // to stop video signal switching
 195             OR
 196                 setenv MESA_GLX_FX window
 197                 setenv SST_VGA_PASS 1
 198                 setenv SST_NOSHUTDOWN 1
 199
 200         (the Voodoo2 requires to use "SSTV2_" instead "SST_").
 201
 202         3. As root, try running a GLX-based program
 203
 204         How does it work?  We use the 3Dfx hardware to do rendering then
 205         copy the image from the 3Dfx frame buffer into an X window when
 206         the SwapBuffers() function is called.  The problem with this
 207         idea is it's slow.  The image must be copied from the 3Dfx frame
 208         buffer to main memory then copied into the X window (and when the X
 209         visual depth doesn't match the Voodoo framebufffer bit per pixel, it
 210         is required also a pixel format translation).
 211
 212         On the fly switching between in window rendering and full screen rendering
 213         --------------------------------------------------------------------------
 214
 215         The Mesa 2.6 has introduced the capability of switching
 216         on-the-fly between the fullscreen/fullspeed rendering and the in-window
 217         hack and vice versa. The on-the-fly switching requires a direct support
 218         by the application but it is really easy to add. You have to start
 219         your X server in 16 bpp mode and to add the following lines to your
 220         application:
 221
 222                 #if defined(FX) && define(XMESA)
 223                 #include <GL/xmesa.h>
 224
 225                 static int fullscreen=1;
 226                 #endif
 227
 228                 ...
 229
 230                 /* In the GLUT keyboard event callback */
 231
 232                 #if defined(FX) && !define(WIN32)
 233                   case ' ':
 234                     fullscreen=(!fullscreen);
 235                     XMesaSetFXmode(fullscreen ? XMESA_FX_FULLSCREEN : XMESA_FX_WINDOW);
 236                     break;
 237                 #endif
 238                 ...
 239
 240         See the 3Dfx/demos/tunnel.c program
 241         for an example.  You have to set the -DXMESA flag in the Makefile's COPTS
 242         to enable it.
 243
 244         Rendering into an X window with the X11 software driver:
 245         --------------------------------------------------------
 246
 247         Set the MESA_GLX_FX variable to "disable" your GLX-based program will use
 248         the X11 software driver (the 3Dfx hardware isn't used at all).
 249
 250
 251
 252 Useful Glide Environment Variables:
 253 -----------------------------------
 254
 255         - To disable the 3Dfx logo, set the FX_GLIDE_NO_SPLASH variable.
 256
 257         - To disable video signal switching:
 258                 setenv SST_VGA_PASS 1
 259                 setenv SST_NOSHUTDOWN
 260           or for the Voodoo2:
 261                 setenv SSTV2_VGA_PASS 1
 262                 setenv SSTV2_NOSHUTDOWN
 263
 264         - To set the default screen refresh rate:
 265                 setenv SST_SCREENREFRESH=75
 266
 267           the supported values are 60, 70, 72, 75, 80, 85, 90, 100, 120.
 268
 269         - To force the Mesa library to swap buffers as fast as possible,
 270           without any vertical blanking synchronization (useful for benchmarks):
 271                 setenv FX_GLIDE_SWAPINTERVAL 0
 272                 setenv SST_SWAP_EN_WAIT_ON_VIDSYNC 0
 273
 274         - You can slight improve the performances of your Voodoo1 board with
 275           the following env. var.:
 276                 setenv SST_FASTMEM 1
 277                 setenv SST_PCIRD 1
 278                 setenv SST_GRXCLK 57
 279
 280           (don't use this setting with the Quantum3D 100SB or with any other
 281           SLI configuration: it will hang everything !).
 282           The following setting can be used with the Voodoo2:
 283                 setenv SSTV2_FASTMEM_RAS_READS=1
 284                 setenv SSTV2_FASTPCIRD=1
 285                 setenv SSTV2_GRXCLK=95
 286
 287         - The Quantum3D Obsidian3D-2 X-24 requires some special env. setting
 288           in order to work under Linux:
 289
 290                 export SSTV2_FT_CLKDEL=5
 291                 export SSTV2_TF0_CLKDEL=7
 292                 export SSTV2_TF1_CLKDEL=7
 293                 export SSTV2_TF2_CLKDEL=7
 294                 export SSTV2_SLIM_VIN_CLKDEL=3
 295                 export SSTV2_SLIM_VOUT_CLKDEL=2
 296                 export SSTV2_SLIS_VIN_CLKDEL=3
 297                 export SSTV2_SLIS_VOUT_CLKDEL=2
 298
 299           (Thanks to Phil Ross for this trick).
 300
 301
 302
 303
 304 The Mesa/Voodoo Environment Variables:
 305 --------------------------------------
 306
 307         - Only for Windows/Voodoo Rush users, if you define the
 308           env. var. MESA_WGL_FX:
 309                 export MESA_WGL_FX=fullscreen
 310           you will get fullscreen rendering;
 311
 312         - Only for Windows/Voodoo Rush users, if you define the
 313           env. var. MESA_WGL_FX:
 314                 export MESA_WGL_FX=window
 315           you will get window rendering (default value);
 316
 317         - Only for Linux users, you can find more informations about
 318           the env. var. MESA_GLX_FX in the "Doing more with Mesa & Linux Glide"
 319           section;
 320
 321         - If you define the env. var. MESA_FX_SWAP_PENDING:
 322                 export MESA_FX_SWAP_PENDING=4
 323           you will able to set the maximum number of swapbuffers
 324           commands in the Voodoo FIFO after a swapbuffer (default value: 2);
 325
 326         - If you define the env. var. MESA_FX_INFO:
 327                 export MESA_FX_INFO=1
 328           you will get some useful statistic.
 329
 330
 331 Know BUGS and Problems:
 332 -----------------------
 333
 334         - fog doesn't work in the right way when using the glDepthRange() function;
 335
 336         - Maximum texture size: 256x256 (this is an hardware limit);
 337
 338         - Texture border aren't yet supported;
 339
 340         - A GL_BLEND in a glTexEnv() is not supported (it is an hardware limit);
 341
 342         - Use the glBindTexture extension (standard in OpenGL 1.1) for texture
 343           mapping (the old way: glTexImage inside a display list, download
 344           the texture map each time that you call the display list !!!);
 345
 346         - Stencil buffer and Accumulation buffer are emulated in software (they are not
 347           directly supported by the Hardware);
 348
 349         - Color index mode not implemented (this is an hardware limit);
 350
 351         - Thre is an know bug in the Linux Glide library so the in-window-rendering hack
 352           and any other operations that requires to read the Voodoo frame buffer
 353           (like the accumulation buffer support) doesn't work on Voodoo SLI cards.
 354
 355         - The driver switch to pure software (_slow_) rendering when:
 356
 357                 - Stencil enabled;
 358                 - Using the Accumulation buffer;
 359                 - Blend enabled and blend equation != GL_FUNC_ADD_EXT;
 360                 - Color logic operation enabled and color logic operation != GL_COPY;
 361                 - Using GL_SEPARATE_SPECULAR_COLOR;
 362                 - The four values of glColorMask() aren't the some;
 363                 - Texture 1D or 3D enabled;
 364                 - Texture function is GL_BLEND;
 365                 - Using the Multitexture extension with Voodoo cards with only one TMU;
 366                 - Using the Multitexture extension with Voodoo cards with more than
 367                    one TMU, and texture function isn't GL_MODULATE;
 368                 - Point size is != 1.0 or point params vector != (1.0,0.0,0.0);
 369                 - Line width != 1.0 or using stipple lines.
 370                 - Using polygon offset or stipple polygons;
 371
 372         NOTE: this is list is not yet complete.
 373
 374
 375 Hints and Special Features:
 376 ---------------------------
 377
 378         - Under Linux and with a Voodoo Graphics board, you can use
 379           XMesaSetFXmode(XMESA_FX_FULLSCREEN or XMESA_FX_WINDOW) in order to
 380           switch on the fly between fullscreen rendering and the in-window-rendering
 381           hack.
 382
 383         - The driver is able to use all the texture memory available: 2/4MB on
 384           Voodoo1 boards and 8MB (!) on high-end Voodoo1 and Voodoo2 boards.
 385
 386         - Trilinear filtering is fully supported on Voodoo boards with two TMUs
 387           (high-end Voodoo1 boards and Voodoo2 boards). When only one TMU is
 388           available the driver fallback to bilinear filter also if you ask
 389           for trilinear filtering.
 390
 391         - The Voodoo driver support multiple Voodoo Graphics boards in the
 392           some PC. Using this feature, you can write applications that use
 393           multiple monitors, videoprojectors or HMDs for the output. See
 394           Mesa-3.1/3Dfx/demos/tunnel2.c for an example of how setup one
 395           context for each board.
 396
 397         - The v0.19 introduces a new powerful texture memory manager: the
 398           texture memory is used as a cache of the set of all defined texture
 399           maps. You can now define several MBs of texture maps also with a 2MB
 400           of texture memory (the texture memory manager will do automatically
 401           all the swap out/swap in
 402           texture memory work). The new texture memory manager has also
 403           solved a lot of other bugs/no specs compliance/problems
 404           related to the texture memory usage.
 405
 406         - Use triangles and quads strip: they are a LOT faster than sparse
 407           triangles and quads.
 408
 409         - The Voodoo driver supports the GL_EXT_paletted_texture. it works
 410           only with GL_COLOR_INDEX8_EXT, GL_RGBA palettes and the alpha value
 411           is ignored because this is a limitation of the the current Glide
 412           version and of the Voodoo hardware. See Mesa-3.1/3Dfx/demos/paltex.c for
 413           a demo of this extension.
 414
 415         - The Voodoo driver directly supports 3Dfx Global Palette extension.
 416           It was written for GLQuake and I think that it isn't a good idea
 417           to use this extension for any other purpose (it is a trick). See
 418           Mesa-3.1/3Dfx/demos/glbpaltex.c for a demo of this extension.
 419
 420         - The Voodoo driver chooses the screen resolution according to the
 421           requested window size. If you open a 640x480 window, you will get
 422           a 640x480 screen resolution, if you open a 800x600 window, you
 423           will get a 800x600 screen resolution, etc.
 424           Most GLUT demos support the '-geometry' option, so you can choose
 425           the screen resolution: 'tunnel -geometry 800x600'.
 426           Clearly, you Voodoo board must have enough framebuffer RAM (otherwise
 427           the window creation will fail).
 428
 429         - The glGetString(GL_RENDERER) returns more information
 430           about the hardware configuration: "Mesa Glide <version>
 431           <Voodoo_Graphics|Voodoo_Rush|UNKNOWN> <num> CARD/<num> FB/
 432           <num> TM/<num> TMU/<NOSLI|SLI>"
 433           where: <num> CARD is the card used for the current context,
 434           <num> FB is the number of MB for the framebuffer,
 435           <num> TM is the number of MB for the texture memory,
 436           <num> TMU is the number of TMU. You can try to run
 437           Mesa/demos/glinfo in order to have an example of the output.
 438
 439 Did you find a lot BUGs and problems ? Good, send me an email.
 440
 441
 442
 443 FAQ:
 444 ----
 445
 446 For a complete FAQ check the Bernd Kreimeier's Linux 3Dfx HOWTO
 447 available at http://www.gamers.org/dEngine/xf3D (it includes also
 448 a lot of informations not strictly related to Linux, so it can be
 449 useful also if you don't use Linux)
 450
 451 1. What is 3Dfx?
 452
 453 3Dfx Interactive, Inc. is the company which builds the VooDoo 3-D graphics
 454 chipset (and others) used in popular PC cards such as the Diamond Monster 3D
 455 and the Orchid Righteous 3D (more informations at http://www.3dfx.com).
 456
 457
 458 2. What is Glide?
 459
 460 Glide is a "thin" programming interface for the 3Dfx hardware.  It was
 461 originally written for Windows/Intel but has been ported to Linux/Intel
 462 by Daryll Strauss.
 463
 464 3Dfx, Inc. should be applauded for allowing the Linux version of Glide
 465 to be written.
 466
 467 You can directly program with the Glide library if you wish.  You can
 468 obtain Glide from the "Developer" section of the 3Dfx website: www.3dfx.com
 469 There's a Linux/Glide newsgroup at news://news.3dfx.com/3dfx.glide.linux
 470
 471
 472 3. What is fxmesa?
 473
 474 "fxmesa" is the name of the Mesa device driver for the 3Dfx Glide library.
 475 It was written by David Bucciarelli and others.  It works on both Linux
 476 and Windows.  Basically, it allows you to write and run OpenGL-style programs
 477 on the 3Dfx hardware.
 478
 479
 480 4. What is GLQuake?
 481
 482 Quake is a very popular game from id software, Inc.  See www.idsoftware.com
 483 GLQuake is a version of Quake written for OpenGL.  There is now a Linux
 484 version of GLQuake with works with the Mesa/3Dfx/Glide combo.
 485
 486 Here's what you need to run GLQuake on Linux:
 487    PC with 100MHz Pentium or better
 488    a 3Dfx-based card
 489    Mesa 3.1 libraries:  libMesaGL.so  libMesaGLU.so
 490    Glide 2.4 libraries:  libglide2x.so  libtexus.so
 491    GLQuake for Linux.
 492
 493 Also, the windows version of GLQuake works fine with the Mesa OpenGL32.dll,
 494 you have only to copy the Mesa-3.1/lib/OpenGL32.dll in the GLQuake directory
 495 in order to test 'MesaQuake'.
 496
 497
 498 5. What is GLUT?
 499
 500 GLUT is Mark Kilgard's OpenGL Utility Toolkit.  It provides an API for
 501 writing portable OpenGL programs with support for multiple windows, pop-
 502 up menus, event handling, etc.
 503
 504 Check the Mark's home page for more informations (http://reality.sgi.com/mjk_asd).
 505
 506 Every OpenGL programmer should check out GLUT.
 507
 508 GLUT on Linux uses GLX.
 509
 510
 511 6. What is GLX?
 512
 513 GLX is the OpenGL extension to the X Window System.  I defines both a
 514 programming API (glX*() functions) and a network protocol.  Mesa implements
 515 an emulation of GLX on Linux.  A real GLX implementation would requires
 516 hooks into the X server.  The 3Dfx hardware can be used with GLX-based
 517 programs via the MESA_GLX_FX environment variable.
 518
 519
 520 7. Is the Voodoo driver able to use the 4Mb texture memory of
 521 the Pure3D boards ?
 522
 523 Yes, the Voodoo driver v0.20 includes the support for Voodoo
 524 Graphics boards with more than 2Mb of texture memory.
 525
 526
 527 8. Do the Voodoo driver support the Voodoo Rush under Windows ?
 528
 529 Yes, Diego Picciani has developed the support for the Voodoo
 530 Rush but David Bucciarelli has a Pure3D and a Monster3D and Brian Paul
 531 has a Monster3D, so the new versions of the Mesa/Voodoo sometime are
 532 not tested with the Voodoo Rush.
 533
 534
 535 9. Do the Voodoo driver support the Voodoo Rush under Linux ?
 536
 537 No because the Linux Glide doesn't (yet) support the Voodoo Rush.
 538
 539
 540 10. Can I sell my Mesa/Voodoo based software and include
 541 a binary copy of the Mesa in order to make the software
 542 working out of the box ?
 543
 544 Yes, you have simply to include some informations about authors
 545 and where the library sources are available (check the LICENSE
 546 file for more informations about the GNU GPL).
 547
 548
 549 11. Which is the best make target for compiling the Mesa for
 550 Linux GLQuake ('make linux-glide', 'make linux-386-glide', etc.) ?
 551
 552 'make linux-386-opt-glide' for Voodoo1 and 'make linux-386-opt-V2-glide'
 553 for Voodoo2 boards because it doesn't include the '-fPIC'
 554 option (4-5% faster).
 555
 556
 557 12. Can I use a Mesa compiled with a 'make linux-386-opt-V2-glide'
 558 for my applications/programs/demos ?
 559
 560 Yes, there is only one constrain: you can't run two Mesa applications
 561 at the some time. This isn't a big issue with the today Voodoo Graphics.
 562
 563
 564 Thanks to:
 565 ----------
 566
 567 Henri Fousse       (he has written several parts of the v0.15 and the old GLUT
 568                     emulator for Win);
 569
 570 Diego Picciani     (he has developed all the Voodoo Rush support and the wgl
 571                     emulator);
 572
 573 Daryll Strauss     (for the Linux Glide and the first Linux support);
 574
 575 Brian Paul         (of course);
 576
 577 Dave 'Zoid' Kirsch (for the Linux GLQuake and Linux Quake2test/Q2 ports)
 578
 579 Bernd Kreimeier    (for the Linux 3Dfx HOWTO and for pushing companies to offer
 580                     a better Linux support)
 581
 582 3Dfx and Quantum3D (for actively supporting Linux)
 583
 584 The most update places where find Mesa VooDoo driver related informations are
 585 the Mesa mailing list and my driver WEB page
 586 (http://www-hmw.caribel.pisa.it/fxmesa/index.shtml)
 587
 588
 589 David Bucciarelli (davibu@tin.it)
 590
 591 Humanware s.r.l.
 592 Via XXIV Maggio 62
 593 Pisa, Italy
 594 Tel./Fax +39-50-554108
 595 email: info.hmw@plus.it
 596 www: www-hmw.caribel.pisa.it