>>>IMAGES.DOC

A. Copyright Information

Images.Hpp and Images.Cpp along with this document file are copyright 1991
by the Gamers Programming Workshop, GAMERS forum, Compuserve (GO GAMERS,
section 11). The code and related document are free for use, distribution,
and modification, provided the following conditions are met:

	1. no commercial use of this source code or documents is permitted.
	2. no fee may be charged beyond disk duplication cost for any of this
	   material.
	3. If the code is upgraded or modified a copy of the modification must
	   be uploaded to section 11 of the GAMERS forum on Compuserve. All
	   modifications must be documented and the author's name included in
	   the source code header block, and the subsequent file package must
	   include all the original doc files as well as any additions. If you
	   modify or add functions please update the function list below.


B. Description

Images.hpp and images.cpp provide basic tools for working in graphics mode
13h, the 256 color standard vga mode, which has become the most popular for
producing high quality gaming software. The following files are required to
use the tools in this package:

	IMAGES.HPP   - the image tools header file
	IMAGES.CPP   - image tools function definitions
	KEYBOARD.HPP - low level keyboard interface header file
	KEYBOARD.CPP - functions required by the font class in images.hpp

A demo of the functions in this package is included, as IDEMO.EXE.

NOTE: Compile these modules in the Large model (pointers default to far).

C. Function interface

*****************************************************************************
*****************************************************************************

The following functions are proto'd in IMAGES.HPP and, defined in
IMAGES.CPP:

*****************************************************************************
*****************************************************************************

void unpackpcx(FILE *pcx, const char far *source,
			   char far *dest, unsigned int num_bytes);

Originally used for all PCX unpacking this function was retained when the
pcx class was created so that anyone who needs it will have access to a basic
rle unpacking algorithm for PCX files. It will unpack from a disk file or
a source buffer, depending on which of pcx and source has a valid pointer.
It is illegal for both of these pointers to be NULL, or for both to be valid.
Unpacks num_bytes of data to memory at dest.

*****************************************************************************

void setgraphmode();

setgraphmode() calls interrupt 0x10, function 0x13 to set mode 0x13 graphics
(320 x 200 x 256 colors)

*****************************************************************************

void settextmode();

settextmode() calls interrupt 0x10, function 0x13 to set 80 x 25 x 16 text
mode.

*****************************************************************************

void wait_vbi();

wait_vbi() returns when it senses the start of the next full vertical blank-
ing interval. Use before writing to video ram in order to prevent snow and
flickering. In performance sensitive functions you'll probably want to copy
this short bit of asm code into the function to eliminate the call overhead.

*****************************************************************************

void reporterr(char type, char where[30]);

reporterr() is used to reset text mode and report the particulars of an
error in the images module to the screen. Pass it the result of the offending
function, and a message describing where the error occured. I make no claims
that this is a great error handling system. Feel free to implement your own.

*****************************************************************************

void loadpalette(int start, int number, const p_rec palette);

loadpalette() accesses the DAC directly, and loads number palette registers
beginning with register start. Values loaded are taken from palette. See
the p_rec type defined in IMAGES.HPP.

*****************************************************************************

void readpalette(int start, int number, p_rec palette);

readpalette() accesses the DAC directly, and reads number palette registers
into palette beginning with register start. See p_rec type defined in
IMAGES.HPP

*****************************************************************************

void clrpalette(int start, int number);

clrpalette() clears number palette registers beginning with register start.
Registers are cleared to 0.

*****************************************************************************

void fadepalettein(int start, int count, const p_rec palette);

fadepalettein() does a 64 pass DAC palette fade. It is called by the pcx::
display() member function, and may be called by any other function as well.
Clear the palette first, and then place the image data in the video buffer,
then call this function, which will fade the image in smoothly. Operates on
count registers beginning with register start. See type p_rec defined in
IMAGES.HPP

*****************************************************************************

void fadepaletteout(int start, int count);

fadepaletteout() removes an image from screen by fading the palette registers
to zero. Operates on count registers beginning with register start.

*****************************************************************************

void setgraphseg(unsigned newseg);

setgraphseg() sets the value of the GRAPH_SEG global variable (declared in
IMAGES.CPP to the desired value. All image routines that write or read
video memory (with the exception of the fades, wipes, and dissolves) assume
the video buffer begins at offset 0 of the segment contained in GRAPH_SEG.
This is usefull for redirecting the functions to operate on a virtual screen
in system ram.

*****************************************************************************

void clearscr(int color);

clearscr() clears the entire screen to the passed color. Assumes video buffer
at GRAPH_SEG.

*****************************************************************************

void barfill(int tlx, int tly, int brx, int bry, int color);

barfill() fills the rectangle bounded by top left coord (tlx,tly), and
bottom left coord (blx,bly) with color. Assumes video buffer at GRAPH_SEG

*****************************************************************************

void writepixel(int x, int y, int color);

writepixel() sets the color of the pixel at x,y. Color must be in the range
0..255. Assumes video buffer at GRAPH_SEG.

*****************************************************************************

char readpixel(int x, int y);

readpixel() returns the color value of the pixel at x,y. Color will be in
the range 0..255. Assumes video buffer at GRAPH_SEG.

*****************************************************************************

void far *xy_to_ptr(int x, int y);

xy_to_ptr returns a pointer to video memory at the location of pixel x,y.
Assumes video buffer at GRAPH_SEG.