docs/README.DJ - platform/external/mesa3d - Gitiles

 			Mesa 5.0 DOS/DJGPP Port v1.3
 			~~~~~~~~~~~~~~~~~~~~~~~~~~~~


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

 Well, guess what... this is the DOS port of Mesa 5.0, 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 = k6
 	BIG_OPT=1	crazy optimizations; not very useful, though...
 			default = no
 	SGI_GLU=1	build SGI's GLU instead of Mesa's.
 			default = no
 	GLIDE		absolute path to Glide library; used with FX.
 			default = $(TOP)/include/glide3
 	FX=1		build for 3dfx Glide3; use it if you have the Glide
 			SDK (designed for your platform), and, of course, a
 			3dfx card... Note that this disables compilation of
 			actual DMesa code, as Glide does all the stuff!
 			default = no
 	HAVE_X86=1	optimize for i386.
 			default = no
 	HAVE_MMX=1	MMX instructions; use only if you assembler/compiler
 			supports MMX instruction set; backwards compatibility
 			with older processors is still preserved.
 			default = no
 	HAVE_SSE=1	(see HAVE_MMX)
 			default = no
 	HAVE_3DNOW=1	(see HAVE_MMX)
 			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:		K6-2 (CXT) @500(412.5) MHz
 	Mainboard:	ViA Apollo VP2/97 w/ 128 MB SDRAM
 	Video card:	PowerColor EvilKing3 (Voodoo3 3000 PCI) w/ 16 MB SDRAM
 	DJGPP:		djdev 2.04 + gcc v3.2 + make v3.79.1
 	OS:		DOS and Win9x


 FAQ:
 ~~~~

 1. Compilation

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

 2. Dynamic modules

    Q) What are you mumbling about dynamic modules?
    A) You must have the DXE3 package (available on my site) installed in order
       to build the dynamic modules.

    Q) DXE3 modules give me headaches...
    A) The DXE3 modules are not compulsory. The static libraries are still built
       and you can use them in the old-fashioned, classic way... and learn to
       live with your huge executable size. For example:
 	gcc -o OUT.exe IN.c -lglut -lglu -lgl

    Q) Okay, DXE3 modules are built. How can I use them?
    A) Build your export object file; then link it with your application.
       For example:
 	dxe3res -o dmesadxe.c gl.dxe glu.dxe glut.dxe
 	gcc -o dmesadxe.o -c -fno-builtin dmesadxe.c
 	gcc -o OUT.exe dmesadxe.o IN.c -liglut -liglu -ligl -ldl

 3. Using Mesa for DJGPP

    Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
    A) Is that a question? If you have a Voodoo3/Banshee card, you're lucky. The
       Glide port is on my web page. If you haven't, sorry; everything is done
       in software. Suggestions?

    Q) I made a simple application and it does nothing. It exits right away. Not
       even a blank screen.
    A) Single-buffered is not allowed at all. Until I can find a way to use
       *REAL* hardware acceleration, it won't get implemented.
    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) My demo doesn't display text. I know I used the glut font routines!
    A) Then you probably use GLUT as a DXE. Well, there is no direct access to
       variables due to the way DXE works. Read the documentation. The author of
       GLUT took this into account for _WIN32 DLL's only; I don't want to modify
       his headers. The only workaround is to link GLUT the old way :-(

    Q) I tried to set refresh rate w/ DMesa, but without success.
    A) Refresh rate control works only for VESA 3.0. If you were compiling for
       Glide, see Glide info. If not, sorry!

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


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

 Well, this "skeletal" GLUT implementation is not mine. 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.

 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 positioning, drawing, etc), but
 is enough to make almost all the demos work.

 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: 640x480x16 at (0,0), 8-bit stencil, 16-bit accum.
 However, the video mode is chosen in such a way that first window will fit. If
 you need high resolution with small windows, try to place them far to the right
 (or way down).

 The following environment variables can customize GLUT behaviour:
 	DMESA_GLUT_REFRESH	-	set vertical screen refresh rate
 	DMESA_GLUT_BPP		-	set default bits per pixel


 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 (dec-2002)
 	+ enabled OpenGL 1.4 support
 	+ added MMX clear/blit routines
 	+ enabled SGI's GLU compilation
 	+ added color-index modes
 	+ added 8bit FakeColor (thanks to Neil Funk)
 	+ added VGA support (to keep Ben Decker happy)
 	* fixed GLUT compilation error (reported by Chan Kar Heng)
 	* overhauled virtual buffer and internal video drivers
 	* better fxMesa integration
 	* extended GLUT functionality
 	* switched to DXE3


 Contact:
 ~~~~~~~~

 Name:   Borca Daniel
 E-mail: dborca@yahoo.com
 WWW:    http://www.geocities.com/dborca/
	Mesa 5.0 DOS/DJGPP Port v1.3
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~



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

	Well, guess what... this is the DOS port of Mesa 5.0, 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 = k6
	BIG_OPT=1 crazy optimizations; not very useful, though...
	default = no
	SGI_GLU=1 build SGI's GLU instead of Mesa's.
	default = no
	GLIDE absolute path to Glide library; used with FX.
	default = $(TOP)/include/glide3
	FX=1 build for 3dfx Glide3; use it if you have the Glide
	SDK (designed for your platform), and, of course, a
	3dfx card... Note that this disables compilation of
	actual DMesa code, as Glide does all the stuff!
	default = no
	HAVE_X86=1 optimize for i386.
	default = no
	HAVE_MMX=1 MMX instructions; use only if you assembler/compiler
	supports MMX instruction set; backwards compatibility
	with older processors is still preserved.
	default = no
	HAVE_SSE=1 (see HAVE_MMX)
	default = no
	HAVE_3DNOW=1 (see HAVE_MMX)
	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: K6-2 (CXT) @500(412.5) MHz
	Mainboard: ViA Apollo VP2/97 w/ 128 MB SDRAM
	Video card: PowerColor EvilKing3 (Voodoo3 3000 PCI) w/ 16 MB SDRAM
	DJGPP: djdev 2.04 + gcc v3.2 + make v3.79.1
	OS: DOS and Win9x



	FAQ:
	~~~~

	1. Compilation

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

	2. Dynamic modules

	Q) What are you mumbling about dynamic modules?
	A) You must have the DXE3 package (available on my site) installed in order
	to build the dynamic modules.

	Q) DXE3 modules give me headaches...
	A) The DXE3 modules are not compulsory. The static libraries are still built
	and you can use them in the old-fashioned, classic way... and learn to
	live with your huge executable size. For example:
	gcc -o OUT.exe IN.c -lglut -lglu -lgl

	Q) Okay, DXE3 modules are built. How can I use them?
	A) Build your export object file; then link it with your application.
	For example:
	dxe3res -o dmesadxe.c gl.dxe glu.dxe glut.dxe
	gcc -o dmesadxe.o -c -fno-builtin dmesadxe.c
	gcc -o OUT.exe dmesadxe.o IN.c -liglut -liglu -ligl -ldl

	3. Using Mesa for DJGPP

	Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
	A) Is that a question? If you have a Voodoo3/Banshee card, you're lucky. The
	Glide port is on my web page. If you haven't, sorry; everything is done
	in software. Suggestions?

	Q) I made a simple application and it does nothing. It exits right away. Not
	even a blank screen.
	A) Single-buffered is not allowed at all. Until I can find a way to use
	REAL hardware acceleration, it won't get implemented.
	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) My demo doesn't display text. I know I used the glut font routines!
	A) Then you probably use GLUT as a DXE. Well, there is no direct access to
	variables due to the way DXE works. Read the documentation. The author of
	GLUT took this into account for _WIN32 DLL's only; I don't want to modify
	his headers. The only workaround is to link GLUT the old way :-(

	Q) I tried to set refresh rate w/ DMesa, but without success.
	A) Refresh rate control works only for VESA 3.0. If you were compiling for
	Glide, see Glide info. If not, sorry!

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



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

	Well, this "skeletal" GLUT implementation is not mine. 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.

	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 positioning, drawing, etc), but
	is enough to make almost all the demos work.

	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: 640x480x16 at (0,0), 8-bit stencil, 16-bit accum.
	However, the video mode is chosen in such a way that first window will fit. If
	you need high resolution with small windows, try to place them far to the right
	(or way down).

	The following environment variables can customize GLUT behaviour:
	DMESA_GLUT_REFRESH - set vertical screen refresh rate
	DMESA_GLUT_BPP - set default bits per pixel



	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 (dec-2002)
	+ enabled OpenGL 1.4 support
	+ added MMX clear/blit routines
	+ enabled SGI's GLU compilation
	+ added color-index modes
	+ added 8bit FakeColor (thanks to Neil Funk)
	+ added VGA support (to keep Ben Decker happy)
	* fixed GLUT compilation error (reported by Chan Kar Heng)
	* overhauled virtual buffer and internal video drivers
	* better fxMesa integration
	* extended GLUT functionality
	* switched to DXE3



	Contact:
	~~~~~~~~

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