updates for Mesa 4.0
[mesa.git] / docs / README.3DFX
1
2 3Dfx Glide device driver for Mesa 3.3
3 (see below for FAQ)
4
5
6 Warning: this document is rather out of date, but most of the information
7 should still apply.
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 NOTE: the in-window rendering feature only works with double-buffering.
213
214
215 On the fly switching between in window rendering and full screen rendering
216 --------------------------------------------------------------------------
217
218 The Mesa 2.6 has introduced the capability of switching
219 on-the-fly between the fullscreen/fullspeed rendering and the in-window
220 hack and vice versa. The on-the-fly switching requires a direct support
221 by the application but it is really easy to add. You have to start
222 your X server in 16 bpp mode and to add the following lines to your
223 application:
224
225 #if defined(FX) && define(XMESA)
226 #include <GL/xmesa.h>
227
228 static int fullscreen=1;
229 #endif
230
231 ...
232
233 /* In the GLUT keyboard event callback */
234
235 #if defined(FX) && !define(WIN32)
236 case ' ':
237 fullscreen=(!fullscreen);
238 XMesaSetFXmode(fullscreen ? XMESA_FX_FULLSCREEN : XMESA_FX_WINDOW);
239 break;
240 #endif
241 ...
242
243 See the 3Dfx/demos/tunnel.c program
244 for an example. You have to set the -DXMESA flag in the Makefile's COPTS
245 to enable it.
246
247 Rendering into an X window with the X11 software driver:
248 --------------------------------------------------------
249
250 Set the MESA_GLX_FX variable to "disable" your GLX-based program will use
251 the X11 software driver (the 3Dfx hardware isn't used at all).
252
253
254
255 Useful Glide Environment Variables:
256 -----------------------------------
257
258 - To disable the 3Dfx logo, set the FX_GLIDE_NO_SPLASH variable.
259
260 - To disable video signal switching:
261 setenv SST_VGA_PASS 1
262 setenv SST_NOSHUTDOWN
263 or for the Voodoo2:
264 setenv SSTV2_VGA_PASS 1
265 setenv SSTV2_NOSHUTDOWN
266
267 - To set the default screen refresh rate:
268 setenv SST_SCREENREFRESH=75
269
270 the supported values are 60, 70, 72, 75, 80, 85, 90, 100, 120.
271
272 - To force the Mesa library to swap buffers as fast as possible,
273 without any vertical blanking synchronization (useful for benchmarks):
274 setenv FX_GLIDE_SWAPINTERVAL 0
275 setenv SST_SWAP_EN_WAIT_ON_VIDSYNC 0
276
277 - You can slight improve the performances of your Voodoo1 board with
278 the following env. var.:
279 setenv SST_FASTMEM 1
280 setenv SST_PCIRD 1
281 setenv SST_GRXCLK 57
282
283 (don't use this setting with the Quantum3D 100SB or with any other
284 SLI configuration: it will hang everything !).
285 The following setting can be used with the Voodoo2:
286 setenv SSTV2_FASTMEM_RAS_READS=1
287 setenv SSTV2_FASTPCIRD=1
288 setenv SSTV2_GRXCLK=95
289
290 - The Quantum3D Obsidian3D-2 X-24 requires some special env. setting
291 in order to work under Linux:
292
293 export SSTV2_FT_CLKDEL=5
294 export SSTV2_TF0_CLKDEL=7
295 export SSTV2_TF1_CLKDEL=7
296 export SSTV2_TF2_CLKDEL=7
297 export SSTV2_SLIM_VIN_CLKDEL=3
298 export SSTV2_SLIM_VOUT_CLKDEL=2
299 export SSTV2_SLIS_VIN_CLKDEL=3
300 export SSTV2_SLIS_VOUT_CLKDEL=2
301
302 (Thanks to Phil Ross for this trick).
303
304
305
306
307 The Mesa/Voodoo Environment Variables:
308 --------------------------------------
309
310 - Only for Windows/Voodoo Rush users, if you define the
311 env. var. MESA_WGL_FX:
312 export MESA_WGL_FX=fullscreen
313 you will get fullscreen rendering;
314
315 - Only for Windows/Voodoo Rush users, if you define the
316 env. var. MESA_WGL_FX:
317 export MESA_WGL_FX=window
318 you will get window rendering (default value);
319
320 - Only for Linux users, you can find more informations about
321 the env. var. MESA_GLX_FX in the "Doing more with Mesa & Linux Glide"
322 section;
323
324 - If you define the env. var. MESA_FX_SWAP_PENDING:
325 export MESA_FX_SWAP_PENDING=4
326 you will able to set the maximum number of swapbuffers
327 commands in the Voodoo FIFO after a swapbuffer (default value: 2);
328
329 - If you define the env. var. MESA_FX_INFO:
330 export MESA_FX_INFO=1
331 you will get some useful statistic.
332
333 - If you define the env. var. MESA_FX_NO_SIGNALS:
334 export MESA_FX_NO_SIGNALS=1
335 Mesa/FX will not install atexit() or signal() handlers.
336
337
338
339 Know BUGS and Problems:
340 -----------------------
341
342 - fog doesn't work in the right way when using the glDepthRange() function;
343
344 - Maximum texture size: 256x256 (this is an hardware limit);
345
346 - Texture border aren't yet supported;
347
348 - A GL_BLEND in a glTexEnv() is not supported (it is an hardware limit);
349
350 - Use the glBindTexture extension (standard in OpenGL 1.1) for texture
351 mapping (the old way: glTexImage inside a display list, download
352 the texture map each time that you call the display list !!!);
353
354 - Stencil buffer and Accumulation buffer are emulated in software (they are not
355 directly supported by the Hardware);
356
357 - Color index mode not implemented (this is an hardware limit);
358
359 - Thre is an know bug in the Linux Glide library so the in-window-rendering hack
360 and any other operations that requires to read the Voodoo frame buffer
361 (like the accumulation buffer support) doesn't work on Voodoo SLI cards.
362
363 - The driver switch to pure software (_slow_) rendering when:
364
365 - Stencil enabled;
366 - Using the Accumulation buffer;
367 - Blend enabled and blend equation != GL_FUNC_ADD_EXT;
368 - Color logic operation enabled and color logic operation != GL_COPY;
369 - Using GL_SEPARATE_SPECULAR_COLOR;
370 - The four values of glColorMask() aren't the some;
371 - Texture 1D or 3D enabled;
372 - Texture function is GL_BLEND;
373 - Using the Multitexture extension with Voodoo cards with only one TMU;
374 - Using the Multitexture extension with Voodoo cards with more than
375 one TMU, and texture function isn't GL_MODULATE;
376 - Point size is != 1.0 or point params vector != (1.0,0.0,0.0);
377 - Line width != 1.0 or using stipple lines.
378 - Using polygon offset or stipple polygons;
379
380 NOTE: this is list is not yet complete.
381
382
383 Hints and Special Features:
384 ---------------------------
385
386 - Under Linux and with a Voodoo Graphics board, you can use
387 XMesaSetFXmode(XMESA_FX_FULLSCREEN or XMESA_FX_WINDOW) in order to
388 switch on the fly between fullscreen rendering and the in-window-rendering
389 hack.
390
391 - The driver is able to use all the texture memory available: 2/4MB on
392 Voodoo1 boards and 8MB (!) on high-end Voodoo1 and Voodoo2 boards.
393
394 - Trilinear filtering is fully supported on Voodoo boards with two TMUs
395 (high-end Voodoo1 boards and Voodoo2 boards). When only one TMU is
396 available the driver fallback to bilinear filter also if you ask
397 for trilinear filtering.
398
399 - The Voodoo driver support multiple Voodoo Graphics boards in the
400 some PC. Using this feature, you can write applications that use
401 multiple monitors, videoprojectors or HMDs for the output. See
402 Mesa-3.1/3Dfx/demos/tunnel2.c for an example of how setup one
403 context for each board.
404
405 - The v0.19 introduces a new powerful texture memory manager: the
406 texture memory is used as a cache of the set of all defined texture
407 maps. You can now define several MBs of texture maps also with a 2MB
408 of texture memory (the texture memory manager will do automatically
409 all the swap out/swap in
410 texture memory work). The new texture memory manager has also
411 solved a lot of other bugs/no specs compliance/problems
412 related to the texture memory usage.
413
414 - Use triangles and quads strip: they are a LOT faster than sparse
415 triangles and quads.
416
417 - The Voodoo driver supports the GL_EXT_paletted_texture. it works
418 only with GL_COLOR_INDEX8_EXT, GL_RGBA palettes and the alpha value
419 is ignored because this is a limitation of the the current Glide
420 version and of the Voodoo hardware. See Mesa-3.1/3Dfx/demos/paltex.c for
421 a demo of this extension.
422
423 - The Voodoo driver directly supports 3Dfx Global Palette extension.
424 It was written for GLQuake and I think that it isn't a good idea
425 to use this extension for any other purpose (it is a trick). See
426 Mesa-3.1/3Dfx/demos/glbpaltex.c for a demo of this extension.
427
428 - The Voodoo driver chooses the screen resolution according to the
429 requested window size. If you open a 640x480 window, you will get
430 a 640x480 screen resolution, if you open a 800x600 window, you
431 will get a 800x600 screen resolution, etc.
432 Most GLUT demos support the '-geometry' option, so you can choose
433 the screen resolution: 'tunnel -geometry 800x600'.
434 Clearly, you Voodoo board must have enough framebuffer RAM (otherwise
435 the window creation will fail).
436
437 - The glGetString(GL_RENDERER) returns more information
438 about the hardware configuration: "Mesa Glide <version>
439 <Voodoo_Graphics|Voodoo_Rush|UNKNOWN> <num> CARD/<num> FB/
440 <num> TM/<num> TMU/<NOSLI|SLI>"
441 where: <num> CARD is the card used for the current context,
442 <num> FB is the number of MB for the framebuffer,
443 <num> TM is the number of MB for the texture memory,
444 <num> TMU is the number of TMU. You can try to run
445 Mesa/demos/glinfo in order to have an example of the output.
446
447 Did you find a lot BUGs and problems ? Good, send me an email.
448
449
450
451 FAQ:
452 ----
453
454 For a complete FAQ check the Bernd Kreimeier's Linux 3Dfx HOWTO
455 available at http://www.gamers.org/dEngine/xf3D (it includes also
456 a lot of informations not strictly related to Linux, so it can be
457 useful also if you don't use Linux)
458
459 1. What is 3Dfx?
460
461 3Dfx Interactive, Inc. is the company which builds the VooDoo 3-D graphics
462 chipset (and others) used in popular PC cards such as the Diamond Monster 3D
463 and the Orchid Righteous 3D (more informations at http://www.3dfx.com).
464
465
466 2. What is Glide?
467
468 Glide is a "thin" programming interface for the 3Dfx hardware. It was
469 originally written for Windows/Intel but has been ported to Linux/Intel
470 by Daryll Strauss.
471
472 3Dfx, Inc. should be applauded for allowing the Linux version of Glide
473 to be written.
474
475 You can directly program with the Glide library if you wish. You can
476 obtain Glide from the "Developer" section of the 3Dfx website: www.3dfx.com
477 There's a Linux/Glide newsgroup at news://news.3dfx.com/3dfx.glide.linux
478
479
480 3. What is fxmesa?
481
482 "fxmesa" is the name of the Mesa device driver for the 3Dfx Glide library.
483 It was written by David Bucciarelli and others. It works on both Linux
484 and Windows. Basically, it allows you to write and run OpenGL-style programs
485 on the 3Dfx hardware.
486
487
488 4. What is GLQuake?
489
490 Quake is a very popular game from id software, Inc. See www.idsoftware.com
491 GLQuake is a version of Quake written for OpenGL. There is now a Linux
492 version of GLQuake with works with the Mesa/3Dfx/Glide combo.
493
494 Here's what you need to run GLQuake on Linux:
495 PC with 100MHz Pentium or better
496 a 3Dfx-based card
497 Mesa 3.1 libraries: libMesaGL.so libMesaGLU.so
498 Glide 2.4 libraries: libglide2x.so libtexus.so
499 GLQuake for Linux.
500
501 Also, the windows version of GLQuake works fine with the Mesa OpenGL32.dll,
502 you have only to copy the Mesa-3.1/lib/OpenGL32.dll in the GLQuake directory
503 in order to test 'MesaQuake'.
504
505
506 5. What is GLUT?
507
508 GLUT is Mark Kilgard's OpenGL Utility Toolkit. It provides an API for
509 writing portable OpenGL programs with support for multiple windows, pop-
510 up menus, event handling, etc.
511
512 Check the Mark's home page for more informations (http://reality.sgi.com/mjk_asd).
513
514 Every OpenGL programmer should check out GLUT.
515
516 GLUT on Linux uses GLX.
517
518
519 6. What is GLX?
520
521 GLX is the OpenGL extension to the X Window System. I defines both a
522 programming API (glX*() functions) and a network protocol. Mesa implements
523 an emulation of GLX on Linux. A real GLX implementation would requires
524 hooks into the X server. The 3Dfx hardware can be used with GLX-based
525 programs via the MESA_GLX_FX environment variable.
526
527
528 7. Is the Voodoo driver able to use the 4Mb texture memory of
529 the Pure3D boards ?
530
531 Yes, the Voodoo driver v0.20 includes the support for Voodoo
532 Graphics boards with more than 2Mb of texture memory.
533
534
535 8. Do the Voodoo driver support the Voodoo Rush under Windows ?
536
537 Yes, Diego Picciani has developed the support for the Voodoo
538 Rush but David Bucciarelli has a Pure3D and a Monster3D and Brian Paul
539 has a Monster3D, so the new versions of the Mesa/Voodoo sometime are
540 not tested with the Voodoo Rush.
541
542
543 9. Do the Voodoo driver support the Voodoo Rush under Linux ?
544
545 No because the Linux Glide doesn't (yet) support the Voodoo Rush.
546
547
548 10. Can I sell my Mesa/Voodoo based software and include
549 a binary copy of the Mesa in order to make the software
550 working out of the box ?
551
552 Yes.
553
554
555 11. Which is the best make target for compiling the Mesa for
556 Linux GLQuake ('make linux-glide', 'make linux-386-glide', etc.) ?
557
558 'make linux-386-opt-glide' for Voodoo1 and 'make linux-386-opt-V2-glide'
559 for Voodoo2 boards because it doesn't include the '-fPIC'
560 option (4-5% faster).
561
562
563 12. Can I use a Mesa compiled with a 'make linux-386-opt-V2-glide'
564 for my applications/programs/demos ?
565
566 Yes, there is only one constrain: you can't run two Mesa applications
567 at the some time. This isn't a big issue with the today Voodoo Graphics.
568
569
570 Thanks to:
571 ----------
572
573 Henri Fousse (he has written several parts of the v0.15 and the old GLUT
574 emulator for Win);
575
576 Diego Picciani (he has developed all the Voodoo Rush support and the wgl
577 emulator);
578
579 Daryll Strauss (for the Linux Glide and the first Linux support);
580
581 Brian Paul (of course);
582
583 Dave 'Zoid' Kirsch (for the Linux GLQuake and Linux Quake2test/Q2 ports)
584
585 Bernd Kreimeier (for the Linux 3Dfx HOWTO and for pushing companies to offer
586 a better Linux support)
587
588 3Dfx and Quantum3D (for actively supporting Linux)
589
590 The most update places where find Mesa VooDoo driver related informations are
591 the Mesa mailing list and my driver WEB page
592 (http://www-hmw.caribel.pisa.it/fxmesa/index.shtml)
593
594
595 David Bucciarelli (davibu@tin.it)
596
597 Humanware s.r.l.
598 Via XXIV Maggio 62
599 Pisa, Italy
600 Tel./Fax +39-50-554108
601 email: info.hmw@plus.it
602 www: www-hmw.caribel.pisa.it