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