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