GRAPHICS

Example Protected Mode Interface to Real Mode Graphics Library.
---------------------------------------------------------------------------

This directory contains example code which demonstrates the
real mode server/protected mode client relationship for an application
which needs to mix real and protected mode code.

In this case the real mode server provides an interface to the
Microsoft C library graphics routines.  The protected mode application
is able to call these routines transparently through protected mode
"glue" or "thunk" routines.

Though this example is specific to the Microsoft C graphics library,
the method it demonstrates can, however, be adapted to provide an
interface to other real mode code without too much problem.

Our sample application is a simple graphics program that draws 1000 random
lines on a CGA-compatible graphics screen.  The sample program has been
compiled with the 80386 MetaWare High C compiler and executes in protected
mode under 386|DOS-Extender (RUN386).

Though the sample program only uses a few of the Microsoft C run-time library
graphics routines, the "glue" code provides interfaces to all the entry points
in the library.  You should be able to link the glue code with other
protected mode applications to provide them with Microsoft C compatible 
graphics routines (see below).

This program demonstrates two different ways of interfacing real mode
and protected mode.  One method uses the -REALBREAK switch to force
386|DOS-Extender to load the protected mode program's real mode communications
buffer in conventional memory.  The other method uses the -CALLBUFS
switch to allocate a buffer in conventional memory which is available
to the application by using far pointers.

The REALBREAK method does not require the protected mode program to use
far pointers to access its real mode communications buffer, and is thus
more efficient.  However, the -REALBREAK switch cannot be supported 
under a DPMI 0.9 host.  The 4.1 release of 386|DOS-Extender can support
-REALBREAK under Windows 3.x, but it requires the PHARLAP.386 Windows VxD
to be installed in the Windows SYSTEM.INI file.

The CALLBUFS method is DPMI compatible but requires accessing the 
communications buffer through far pointers.

---------------------------------------------------------------------------

The following files are located in this directory:

gserver.h	A C header file that defines the communication protocol
		between the real and protected mode code.

gdemo.c		The C source code to the example application which draws
		1000 random lines on the screen.

gglue.c		Example glue routines that run in protected mode and call
		through to the real mode Microsoft C graphics library.  This
		code can be conditionally compiled to use either the -REALBREAK
		or the -CALLBUFS communications method.

prot.asm	Assembler language utility functions used by "gglue.c".  This
		code can be conditionally assembled to use either the 
		-REALBREAK or the -CALLBUFS communications method.

gserver.c	The graphics server that runs in real mode and is
		compiled by the Microsoft C 5.1 compiler and linked with
		the Microsoft C run-time and graphics libraries.

real.asm	Assembly language utility functions used by "gserver.c"
		that switch from real mode back to protected mode.

gdemo_rb.exp	A .EXP file for gdemo.c built to use the -REALBREAK
		communications method.

gdemo_cb.exp	A .EXP file for gdemo.c built to use the -CALLBUFS
		communications method.

gserver.drv	A .EXE file for the real mode graphics server, built
		from gserver.c and real.asm with Microsoft C 5.1.

blddemo.bat	A batch file that builds gdemo_rb.exp, gdemo_cb.exp
		and gserver.drv.

gserver.mak	A make file to build gserver.drv with version 5.1 of the
		Microsoft C compiler.

gdemo.mak	A make file to build gdemo_rb.exp and gdemo_cb.exp with
		the MetaWare High C compiler.

wgdemo.mak	A make file to build wgdemo_rb.exp and wgdemo_cb.exp with
		the Watcom C compiler.

wgdemo.lnk	Indirect link file used by wgdemo.mak.

---------------------------------------------------------------------------

To run the demo, enter:

	C> run386 gdemo_rb		; for the REALBREAK version
	         or
	C> run386 gdemo_cb		; for the CALLBUFS version

---------------------------------------------------------------------------

To rebuild or extend the demos, the following software tools are
needed:

	* Version 2.0 or later of the Phar Lap 386|DOS-Extender SDK

	* Version 1.6 or later of the MetaWare High-C 386 compiler, with
	  the compiler driver turned on.

	* Version 5.1 or later of the Microsoft C 8086 compiler

To rebuild the executable example programs, follow these steps:

	1).  Copy graph.h from the \includes subdirectory of the
	     Microsoft compiler into this directory.

	2).  Edit the gdemo.mak file to set the name of the High C-386
	     compiler driver correctly.

	3).  Edit the gserver.mak file to set the name of the Microsoft
	     C compiler root directory.

	3).  Run the batch file "blddemo"

To build other protected mode applications which can interface to the
Microsoft C graphics library from protected mode:

	1).  If the application includes graph.h, modify it to undefine
	     the cdecl and far keywords before including graph.h. (See
	     the comments in gdemo.c for an explanation.)

	2).  Copy gdemo.mak and modify it for the new application you
	     are building.
