Initial import.

1 files changed, 88 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..039d4fa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# verite-gl - OpenGL implementation for the Rendition Verite V2x00
+
+This project provides an implementation of OpenGL 1.2 (with a few 
+extensions) for the Rendition Verite V2100/V2200 graphics cards on 
+NetBSD. It is based on Mesa 6.2.2, with a hardware-accelerated 
+`verite` driver added.
+
+This is the userland half of the project, providing `libGL` library.
+It has no external dependencies, however it requires a NetBSD kernel 
+built with `veritefb(4)` driver and the 3D microcode (`v2000gl.uc`) 
+from the Windows driver package (latest beta recommended). The Mesa 
+driver talks to the kernel driver via `/dev/verite3d` and the
+`verite3dio.h` ioctl ABI.
+
+The driver does not require (or even support) the X Window System - an
+application using this OpenGL implementation always takes over the whole 
+screen.
+
+## Build
+
+Requires:
+- NetBSD toolchain (native, or cross-compiler built with the NetBSD `build.sh`).
+- GNU make (`gmake`).
+
+Building on the target NetBSD system:
+```
+gmake netbsd-verite
+```
+
+Cross-building from a different system:
+```
+gmake netbsd-verite \
+    VERITE_CROSS=/path/to/tooldir/bin/ \
+    VERITE_SYSROOT=/path/to/netbsd/sysroot
+```
+
+Successful build will create `lib/libGL.a`. 
+
+## Build a program
+
+See `include/GL/gl.h` for the OpenGL API and `include/GL/vrmesa.h` for 
+the Verite-specific functions. Note that the second include is necessary
+since we are not using the usual GLX or WGL APIs to create a rendering 
+context. See examples for usage.
+
+`libGL.a` is self-contained:
+
+```
+cc -Iinclude your_app.c lib/libGL.a -lm -o your_app
+```
+
+The `examples/` (`cube`, `rave`) contain runnable programs. Buidl and run
+as the user with permissions to `/dev/verite3d`, point `VERITE_UCODE` 
+evironment variable at the `v2000gl.uc` 3D microcode.
+
+If the `/dev/verite3d` does not exist on your system, despite running a
+kernel with `veritefb(4)` driver loaded, create it using `MAKEDEV`.
+
+Reported strings: `GL_VENDOR` = `Rendition`, `GL_RENDERER` =
+`Mesa Rendition Verite V2200`, `GL_VERSION` = `1.2 Mesa 6.2.2`.
+
+## What's where
+
+- `src/mesa/drivers/verite/` - the driver, plus the `rlgl` and `libv3d`
+  low level libraries, `verite3dio.h` ioctl ABI.
+- `src/mesa/ppc/` - PowerPC 603e/e300 semi-optimized vertex ops (optional).
+- `configs/netbsd-verite` - the build config.
+- everything else - Mesa 6.2.2 with minor patches here and there.
+
+## Caveats
+
+The driver only supports one visual, 16-bit RGB565, double buffered, 
+with Z-buffer. Resolution depends on the kernel driver and Mesa will
+automatically switch color depth to 16-bit when context is created.
+
+Performance is not stellar, but it is usable for simple 3D applications.
+The example programs run at v-sync rates (60 FPS) on a V2200 card with 
+640x480 resolution, on a PowerPC 603e CPU at 400 MHz. 
+
+GLQuake runs at around 18 FPS on the same machine. Hand-optimized Quake
+MiniGL driver (not included here) delivers 27 FPS on the same machine, 
+so there is room for improvement.
+
+The driver should work on any Rendition Verite V2100/V2200 card, and any
+architecture supported by NetBSD as long as it has functional PCI
+subsystem and working DMA (absolutely necessary), however it was tested 
+only on PowerPC.
+