docs/README.DJ

			Mesa 6.3 DOS/DJGPP Port v1.7
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Description:
~~~~~~~~~~~~

Well, guess what... this is the DOS port of Mesa 6.3, for DJGPP fans... Whoa!
The driver has its origins in ddsample.c, written by Brian Paul and found by me
in Mesa 3.4.2.



Legal:
~~~~~~

Mesa copyright applies, provided this package is used within Mesa. For anything
else, see GPL.



Installation:
~~~~~~~~~~~~~

Unzip and type:

	make -f Makefile.DJ [OPTIONS...]

Available options:

     Environment variables:
	CPU		optimize for the given processor.
			default = pentium
	GLU=[mesa|sgi]	specify GLU directory; can be `sgi' (requires GNU/C++)
			or `mesa'.
			default = mesa
	GLIDE		path to Glide3 SDK; used with FX.
			default = $(TOP)/glide3
	FX=1		build for 3dfx Glide3. Note that this disables
			compilation of most DMesa code and requires fxMesa.
			As a consequence, you'll need the DJGPP Glide3
			library to build any application.
			default = no
	X86=1		optimize for x86 (if possible, use MMX, SSE, 3DNow).
			default = no

     Targets:
	all:		build everything
	libgl:		build GL
	libglu:		build GLU
	libglut:	build GLUT
	clean:		remove object files
	realclean:	remove all generated files



Tested on:
	CPU:		AMD Athlon XP 1800+
	Mainboard:	GA-7VTXE w/ 512 MB DDRAM
	Video card:	Voodoo5 6000 AGP w/ 128 MB SDRAM
	DJGPP:		djdev 2.04 + gcc v3.4.3 + make v3.80
	OS:		DOS and Win98SE



FAQ:
~~~~

1. Compilation

   Q) `make' barfs and exits because it cannot find some stupid file.
   A) You need LFN support.
   A) When compiling for Glide (FX=1), pay attention to Glide path.

   Q) Libraries built OK, but linker complains about `vsnprintf' every time I
      compile some demo.
   A) Upgrade to DJGPP 2.04.
   A) Add `vsnprintf.c' to the CORE_SOURCES in `src/Makefile.DJ' (untested!).
   A) Patch `src/mesa/main/imports.c' with the following line:
	#define vsnprintf(buf, max, fmt, arg) vsprintf(buf, fmt, arg)
      This hack should be safe in 90% of the cases, but if anything goes wrong,
      don't come back to me crying.

   Q) `make' complains about DXE3 or something, yet it builds the libraries.
   A) DXE3 refers to the DJGPP dynamic modules. You'll need either the latest
      DJGPP distro, or download the separate package from my web page. Read the
      DXE3 documentation on how to use them.
   A) When compiling for Glide (FX=1), make sure `glide3x.dxe' can be found in
      LD_LIBRARY_PATH (or top `lib' directory).

2. Using Mesa for DJGPP

   Q) Every test I tried crashes badly.
   A) If you have compiled with SSE and you're running under plain DOS, you
      have to disable SSE at run-time. See environment variables below.

   Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
   A) Is that a question? If you have a 3dfx Voodoo (any model), you're
      lucky (check http://sourceforge.net/projects/glide for the DJGPP port).
      If you haven't, sorry; everything is done in software. Suggestions?

   Q) I tried to set refresh rate w/ DMesa, but without success.
   A) Refresh rate control works only for VESA 3.0 and the 3dfx driver (in
      which case FX_GLIDE_REFRESH will be overwritten if it is defined and
      is not 0).

   Q) I made a simple application and it does nothing. It exits right away. Not
      even a blank screen.
   A) Pure software drivers (VESA/VGA/NUL) support only double-buffered modes.
   A) Another weird "feature" is that buffer width must be multiple of 8 (I'm a
      lazy programmer and I found that the easiest way to keep buffer handling
      at peak performance ;-).

   Q) I'm getting a "bad font!" fatal error.
   A) By default, DOS GLUT compiles with GLUT_IMPORT_LIB, to cope with variable
      access inside dynamic modules (same mechanism used for Win32 _DLL). Since
      -DGLUT_IMPORT_LIB affects Mesa's `glut.h', your apps must be compiled the
      same way GLUT was compiled (either with or without defining it). If you
      want to use another `glut.h' when building your own demos, or just don't
      feel happy about this, make sure you remove the line with GLUT_IMPORT_LIB
      from `Mesa/src/glut/dos/Makefile.DJ' before (re)making GLUT. Beware, this
      means you will never EVER be able to safely use `glut.dxe'!

   Q) What is NUL driver good for, if I don't get any output at all?
   A) For debugging. The NUL driver is very much like OSMesa. Everything is
      done just the same as VESA/VGA drivers, only it doesn't touch your video
      hardware. You can query the actual buffer by issuing:
	DMesaGetIntegerv(DMESA_GET_BUFFER_ADDR, &buffer);
      and dump it to a file.

   Q) How do I query for a list of available video modes to choose as a visual?
   A) This is an ugly hack, for which I'm sure I'll burn in hell.
      First, query for a list of modes:
	n = DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, NULL);
      If `n' is strictly positive, you allocate an array of pointers to a given
      struct (which is guaranteed to be extended only - not changed in future):
	struct {
		int xres, yres;
		int bpp;
	} **l = malloc(n * sizeof(void *));
      Now pass the newly allocated buffer to fill in:
	DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, (GLint *)l);
      And collect the info:
	for (i = 0; i < n; i++) {
	    printf("%dx%d:%d\n", l[i]->xres, l[i]->yres, l[i]->bpp);
	}

   Q) The GLUT is incomplete.
   A) See below.



libGLUT (the toolkit):
~~~~~~~~~~~~~~~~~~~~~~

Well, this "skeletal" GLUT implementation was taken from AllegGL project and
heavily changed. Thanks should go to Bernhard Tschirren, Mark Kilgard, Brian
Paul and probably others (or probably not ;-). GLUT functionality will be
extended only on an "as needed" basis.

GLUT talks to hardware via PC_HW package which was put together from various
pieces I wrote long time ago. It consists from the keyboard, mouse and timer
drivers.

My keyboard driver used only scancodes; as GLUT requires ASCII values for keys,
I borrowed the translation tables (and maybe more) from Allegro -- many thanks
to Shawn Hargreaves et co. Ctrl-Alt-Del (plus Ctrl-Alt-End, for Windows users)
will shut down the GLUT engine unconditionally: it will raise SIGINT, which in
turn will (hopefully) call the destructors, thus cleaning up your/my mess ;-)
NB: since the DJGPP guys ensured signal handlers won't go beyond program's
space (and since dynamic modules shall) the SIGINT can't be hooked (well, it
can, but it is useless), therefore you must live with the 'Exiting due to
signal SIGINT' message...

The mouse driver is far from complete (lack of drawing, etc), but is enough to
make almost all the demos work. Supports the CuteMouse WheelAPI.

The timer is pretty versatile for it supports multiple timers with different
frequencies. While not being the most accurate timer in the known universe, I
think it's OK. Take this example: you have timer A with a very high rate, and
then you have timer B with very low rate compared to A; now, A ticks OK, but
timer B will probably loose precision!

As an addition, stdout and stderr are redirected and dumped upon exit. This
means that `printf' can be safely called during graphics. A bit of a hack, I
know, because all messages come in bulk, but I think it's better than nothing.
"Borrowed" from LIBRHUTI (Robert Hoehne).

Window creating defaults: (0, 0, 300, 300), 16bpp. However, the video mode is
chosen in such a way that first window will fit. If you need high resolution
with small windows, set initial position far to the right (or way down); then
you can move them back to any position right before the main loop.



Environment variables:
~~~~~~~~~~~~~~~~~~~~~~
	DMESA_NULDRV		- (any value) force NUL driver
	GLUT_FPS		- print frames/second statistics to stderr
	MESA_NO_SSE		- (any value) safe option under pure DOS
	DMESA_GLUT_REFRESH	- set vertical screen refresh rate (VESA3)
	DMESA_GLUT_BPP		- set default bits per pixel (VGA needs 8)
	DMESA_GLUT_ALPHA	- set default alpha bits (8)
	DMESA_GLUT_DEPTH	- set default depth bits (16)
	DMESA_GLUT_STENCIL	- set default stencil bits (8)
	DMESA_GLUT_ACCUM	- set default accum bits (16)



History:
~~~~~~~~

v1.0 (mar-2002)
	initial release

v1.1 (sep-2002)
	+ added 3dfx Glide3 support
	+ added refresh rate control
	+ added fonts in GLUT
	* lots of minor changes

v1.2 (nov-2002)
	* synced w/ Mesa-4.1
	- removed dmesadxe.h

v1.3 (mar-2003)
	+ enabled OpenGL 1.4 support
	+ added MMX clear/blit routines
	+ enabled SGI's GLU compilation
	+ added samples makefile
	+ added new GLUT functions
	+ added color-index modes
	+ added Matrox Millennium MGA2064W driver
	+ added 8bit FakeColor (thanks to Neil Funk)
	+ added VGA support (to keep Ben Decker happy)
	! fixed some compilation errors (reported by Chan Kar Heng)
	* optimized driver for faster callback access... yeah, right :)
	* overhauled virtual buffer and internal video drivers
	* better fxMesa integration
	* revamped GLUT
	* switched to DXE3

v1.4 (dec-2003)
	+ enabled GLUT fonts with DXE
	+ truly added multi-window support in GLUT (for Adrian Woodward)
	* accomodated makefiles with the new sourcetree
	* fixed some ALPHA issues
	* minor changes to PC_HW/timer interface
	x hacked and slashed the 3dfx driver (w/ help from Hiroshi Morii)

v1.5 (jan-2004)
	+ added interface to query available "visuals" (GLFW - Marcus Geelnard)
	+ added GLUT timer callback
	- removed Matrox Millennium MGA2064W driver
	x more changes to the 3dfx driver

v1.6 (aug-2004)
	+ implemented NUL driver
	+ added DMesaGetProcAddress and glutGetProcAddress
	* reorganized fxMesa wrapper to handle multiple contexts
	! fixed a horrible bug in VGA initialization routine
	! fixed partial clears

v1.7 (???-2005)
	+ enabled OpenGL 2.0 support
	+ added support for sw texture compression
	* minor rework



Contact:
~~~~~~~~

Name:   Daniel Borca
E-mail: dborca@users.sourceforge.net
WWW:    http://www.geocities.com/dborca/