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