docs/README.3DFX

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