3dfx support for BeOS PowerPC -- version 1.0
=============================================

Hardware 3D for the BeBox (and other BeOS PowerPC machines) with a 3dfx
Voodoo 2 or Voodoo Graphics (Voodoo 1) PCI card:

  - thdfx              kernel driver (BeOS R4 / R4.5)
  - lib3DfxGlide2X.so  Glide 2.x, ported from the source code 3dfx released
                       in 1999 (Voodoo 2 and Voodoo Graphics versions)
  - tests/             3dfx's own Glide test programs (test00 .. test29)
  - opengl/            OpenGL 1.2 (Mesa 3.2.1) accelerated by the Voodoo: BeOS
                       OpenGL programs (BGLView) run on the card unchanged
  - develop/           headers and a small example to write Glide programs

Tested on a BeBox Dual 603e 133 MHz, BeOS 4.5.2, Voodoo 2 12 MB (a Matrox
Millennium II does the 2D): all tests pass, and full games run on it
(Mage Slayer, Virtua Racing). The Voodoo Graphics library is built from
the same port; it has not been tried on a real card yet, but runs all the
tests, the OpenGL demos and those games on the BeBox emulator, which
emulates a Voodoo Graphics (https://github.com/davidraingeard/BeBox,
option -voodoo). Other BeOS PowerPC machines (PowerMac clones) should
work, but have not been tried.

Sources, documentation and the build scripts:
    https://github.com/davidraingeard/BeOS-Glide


1. Install
----------

Copy this folder anywhere (for example /boot/home/3dfx), open a Terminal:

    cd /boot/home/3dfx-beos-ppc-1.0
    sh install.sh              (Voodoo 2)
    sh install.sh voodoo1      (Voodoo Graphics)

This copies the driver to ~/config/add-ons/kernel/drivers/bin (with its
link in drivers/dev), the library to ~/config/lib, and glidereset to
~/config/bin (with OpenGL: see section 5). If install.sh does
not report "card found", reboot: /dev/3dfx_0 must then exist. Otherwise
look for the "thdfx:" lines in /var/log/syslog.

The driver does not touch the card while BeOS boots: it only reads the
PCI list. The Voodoo is a 3D-only card, the 2D card keeps the desktop.


2. Test
-------

Run the tests from a Terminal, in their folder (they read .3df files):

    cd tests/voodoo2
    ./test00 -n 300         clears the screen, 300 frames
    ./test01 -n 300         points
    ./test11 -n 300         direct frame buffer writes
    ./test17 -n 300         textures
    ./test26                frame buffer write + read back test

Without -n, a test waits for a key. Over telnet, Enter sends two
characters and stops the test after one frame: use -n.


3. Safety: the black screen
---------------------------

When a Glide program starts, a relay on the Voodoo switches the monitor
to the 3D picture; grGlideShutdown() switches it back. If a Glide program
crashes, BeOS keeps running but the monitor stays black. Then type,
blind, in the Terminal:

    glidereset

(it opens and closes the Voodoo screen, which gives the monitor back).
For your first tries, keep telnet or ftp enabled (Network preferences),
or plug a second monitor on the Voodoo output.

To remove the driver without a picture: boot from another BeOS volume
and delete home/config/add-ons/kernel/drivers/bin/thdfx and
drivers/dev/thdfx on the volume where it was installed.


4. Writing Glide programs
-------------------------

develop/headers holds glide.h and the headers it needs; develop/example
is a complete program (a spinning shaded triangle) with its makefile:

    cd develop/example
    make
    obj.ppc/triangle

Link with -l3DfxGlide2X (library in ~/config/lib). The headers are the
same for both cards. Programs that used Be's own lib3DfxGlide2X.so also
run with this one (same 122 exported functions, same structures).

Useful environment variables:

    FX_GLIDE_NO_SPLASH=1      no 3dfx logo at start-up
    FX_GLIDE_SWAPINTERVAL=1   wait for the vertical retrace
    SSTV2_INITDEBUG=1         Voodoo 2 initialisation trace
    SST_INITDEBUG=1           Voodoo Graphics initialisation trace

Big-endian notes for porters: the library converts textures and handles
the PCI byte order itself; for direct frame buffer writes through
grLfbLock, 16-bit pixels can be written as is (the card swaps them).


5. OpenGL (Mesa 3.2.1)
---------------------

install.sh also installs Mesa 3.2.1 with its 3Dfx driver, on top of
this Glide:

  ~/config/lib/voodoo/libGL.so   replacement for Be's libGL.so (Mesa +
                                 3Dfx driver + GLU + BGLView), kept apart:
                                 Be's own OpenGL is left untouched
  ~/config/lib/libMesaGL.so      the same OpenGL for programs written for
  ~/config/lib/libMesaGLU.so     Mesa (fxMesa* full-screen interface)
  ~/config/bin/voodoo            runs a program with the Voodoo libGL.so

Any BeOS OpenGL program (a BGLView) then runs on the Voodoo, without
being recompiled:

    voodoo /boot/apps/GLTeapot/GLTeapot     (use your own path)
    voodoo opengl/glspin

The program's window stays on the desktop (it gets the keyboard and the
mouse, and reads "OpenGL : 3dfx Voodoo"); the 3D picture is full screen
on the Voodoo, stretched from the window size. One view at a time uses
the card; the others (or all, with BGL_VOODOO=0) are drawn in software
by Mesa. BGL_VOODOO_SIZE=800x600 picks the resolution (640x480 by
default). Ctrl-C or closing the window gives the screen back. Programs
using Be's BGLScreen (full-screen class) do not load with this libGL.so.

On the BeBox (603e 133 MHz): glspin 76 frames/s, GLTeapot 27 frames/s.

opengl/demos holds Mesa's 3Dfx demos (tunnel, teapot, fire, ray...),
full screen with a GLUT that reads the keyboard from the Terminal they
are started from (h: help, Esc: quit):

    cd opengl/demos
    ./tunnel

develop/opengl holds Mesa's headers (GL/gl.h, glu.h, glut.h, fxmesa.h).
Sources and build: mesa-beos/ in the repository. Mesa's license:
opengl/COPYRIGHT-Mesa.txt.


6. Uninstall
--------------

    sh uninstall.sh

then reboot.


7. License
----------

Glide is distributed under the 3DFX GLIDE Source Code General Public
License (LICENSE-3DFX.txt). The BeOS port, the driver and the scripts
follow the same license; Mesa (opengl/) keeps its own license
(opengl/COPYRIGHT-Mesa.txt). No warranty: you use this at your own risk.

Port by David Raingeard with Claude (Anthropic), 2026 -- tested on a real
BeBox, still running thirty years later.
