lp4supp.obj function summary:
=============================

This list contains UNIX-like summaries for the routines that
are currently contained in lp4suppx.obj.

lp4suppx.obj is for use with the tgdlp4xx.obj ModeX graphics
driver. It is not a stand alone module. The system requirements
for lp4suppx.obj are the same as for tgdlp4xx.obj (see
tgdlp4.txt).

lp4suppc.obj is compiled for the COMPACT memory model.
This means that all calls to procedures must be declared as
NEAR while pointers to data are all FAR.
lp4suppl.obj is compiled for the LARGE memory model. In this
model all calls to procedures as well as all pointers to data
are to be declared as FAR.

lp4suppx.obj expects all parameters to be passed using C
calling conventions. The C calling mechanism is described in
tgdlp4.txt.


void freebc(bcdescr huge *bcinfo);
free all memory that was allocated with readbc()

FUNCTION:
This procedure frees all the memory allocated by readbc() for
LP4 bitmap structures and data. freebc() should be called when
a LP4 bitmap is no longer needed. Do not use the freebitmap()
routine contained in tgdsuppx.obj to free any data allocated by
readbc().

INPUTS:
*bcinfo: pointer to the lp4 bitmap descriptor created by
	 readbc().

RESULT:
none

BUGS:
none known

SEE ALSO:
readbc()


bcdescr huge *readbc(const char far *filename,ubyte bcnumber,ubyte far *loaderr);
read a LP4 bitmap from a LP4 file

FUNCTION:
A LP4 bitmap created by PPMTOLP4 can be read by this routine.
readbc() interprets and converts data contained in a bitmap
part of a LP4 file so that it is easily accessible from
tgdlp4xx.obj routines. The main information contained in a LP4
bitmap is:
* number of colors of the bitmap
* RGB values of the colors of the bitmap
* the bitmap itsself

readbc() returns a pointer to a LP4 bitmap descriptor. The LP4
bitmap descriptor looks like this:
struct { cmhdr  huge *cmdescr;
	 ubyte  far  *cmap;	  /* this is a huge ptr really */
	 bmhdr  huge *bmdescr;
	 ubyte  huge *bmap;
	 bitmap far  *tgdbmdescr; /* this is a huge ptr really */
       } bcdescr;

You can access the main information of a LP4 bitmap by:
bcdescr->cmdescr->colors to get the number of colors-1 of the
			 LP4 bitmap.
bcdescr->cmap to get the actual color map of the bitmap.
Together both informations can be used without modification
to set the colors for a bitmap using tgdlp4xx.obj's rgb6()
function:
rgb6(0,bcdescr->cmdescr->colors,bcdescr->cmap);

the bitmap structure itself can be accessed by:
bcdescr->tgdbmdescr
The bitmap structure is fully initialized. You can use it
instantly for blitting the bitmap (or parts of it) to the
screen by using tgdlp4xx.obj's bltbitmap().

INPUTS:
*filename: pointer to the \0 terminated name of the LP4 file
	   from which the bitmap should be extracted from.
bcnumber: number of bitmap to load out of an LP4 file. The
	  first bitmap in a LP4 file has the number 1, the
	  second bitmap has the number 2...
	  valid numbers for bitmaps range from 1-255.
*loaderr: pointer to an error variable. If an error has occured
	  while executing readbc() this variable will contain
	  information about where the error has occured.

RESULT:
bcdescr *bcinfo: pointer to a LP4 bitmap descriptor containing
		 information about the LP4 bitmap. If bcinfo
		 is 0 the LP4 bitmap descriptor was not
		 created. The reason for this is stored in the
		 error variable. error can have the following
		 values: 0 - no error occured.
			 LP4ERR_NOFILE: LP4 file could not be
			 opened.
			 LP4ERR_BADFILE: file is not a valid
			 LP4 file or the LP4 file version is
			 not supported by readbc().
			 LP4ERR_NOMEM: not enough memory free
			 to create the LP4 structures.
			 LP4ERR_EOF: requested bitmap is not
			 present in this LP4 file i.e. you
			 have tried to load bitmap #3 from
			 a LP4 file in which are only 2
			 bitmaps.

BUGS:
none known

SEE ALSO:
freebc()
tgdlp4.txt: rgb6(), bltbitmap()


void freefc(fcdescr huge *fcinfo);
free all memory that was allocated with readfc()

FUNCTION:
This procedure frees all the memory that was allocated by
readfc() for LP4 font structures and data. freefc() should be
called when a LP4 font is no longer needed.

INPUTS:
*fcinfo: pointer to the lp4 font descriptor created by
	 readfc().

RESULT:
none

BUGS:
none known

SEE ALSO:
readfc()


fcdescr huge *readfc(const char far *filename,ubyte fcnumber,ubyte far *loaderr);
read a LP4 font from a LP4 file

FUNCTION:
A LP4 font created by FNTTOLP4 can be read by this routine.
readfc() interprets and converts data contained in a font
part of a LP4 file so that it is easily accessible from
tgdlp4xx.obj routines. The main information contained in a LP4
font is:
* number of colors of the font
* RGB values of the colors of the font
* the font itsself

readfc() returns a pointer to a LP4 font descriptor. The LP4
font descriptor looks like this:
struct { cmhdr   huge *cmdescr;
	 ubyte   far  *cmap;	  /* this is a huge ptr really */
	 fmhdr   huge *fmdescr;
	 ubyte   huge *bmap;
	 fontmap far  *tgdfmdescr;/* this is a huge ptr really */
       } fcdescr;

You can access the main information of a LP4 font by:
fcdescr->cmdescr->colors to get the number of colors-1 of the
			 LP4 font.
fcdescr->cmap to get the actual color map of the font.
Together both informations can be used without modification
to set the colors for a font using tgdlp4xx.obj's rgb6()
function:
rgb6(0,fcdescr->cmdescr->colors,fcdescr->cmap);

the font(map) structure itself can be accessed by:
fcdescr->tgdfmdescr
The font(map) structure is fully initialized. You can set the
font this way: font(fcdescr->tgdfmdescr); [font() is a
tgdlp4xx.obj function.]

INPUTS:
*filename: pointer to the \0 terminated name of the LP4 file
	   from which the font should be extracted from.
fcnumber: number of font to load out of an LP4 file. The
	  first font in a LP4 file has the number 1, the
	  second font has the number 2...
	  valid numbers for fonts range from 1-255.
*loaderr: pointer to an error variable. If an error has occured
	  while executing readfc() this variable will contain
	  information about where the error has occured.

RESULT:
fcdescr *fcinfo: pointer to a LP4 font descriptor containing
		 information about the LP4 font. If fcinfo
		 is 0 the LP4 font descriptor was not
		 created. The reason for this is stored in the
		 error variable. Refer to the readbc() 
		 description for the meaning of the values of
		 the error variable.

BUGS:
none known

SEE ALSO:
freefc()
tgdlp4.txt: rgb6(), font(), prttext()


void freesc(scdescr huge *scinfo);
free all memory that was allocated with readsc()

FUNCTION:
This procedure frees all the memory allocated by readsc() for
LP4 sprite animation structures and data. freesc() should be
called when a LP4 sprite animation is no longer needed.
Note: freesc() doesn't free any memory that was allocated with
the newsprite() routine declared in tgdsuppx.obj. Use the
freesprite() procedure contained in the same file to free that
memory.

INPUTS:
*scinfo: pointer to the lp4 sprite descriptor created by
	 readsc().

RESULT:
none

BUGS:
none known

SEE ALSO:
readsc()
tgdsupp.txt: newsprite(), freesprite()


scdescr huge *readsc(const char far *filename,ubyte scnumber,ubyte far *loaderr);
read a LP4 sprite animation from a LP4/SP4 file

FUNCTION:
A LP4 sprite animation created by LP4TOSP4 can be read by this
routine. readsc() interprets and converts data contained in a
sprite animation part of a LP4/SP4 file so that it is easily
accessible from tgdsuppx.obj / tgdlp4xx.obj routines. The main
information contained in a LP4 sprite animation is:
* number of colors of the sprite animation
* RGB values of the colors of the sprite animation
* the sprite animation itsself

readsc() returns a pointer to a LP4 sprite descriptor. The LP4
sprite descriptor looks like this:
struct { cmhdr  huge   *cmdescr;
	 ubyte  far    *cmap;	  /* this is a huge ptr really */
	 smhdr  huge   *smdescr;
	 ubyte  huge   *bmap;
	 spritemap far *tgdsmdescr; /* this is a huge ptr really */
       } scdescr;

You can access the main information of a LP4 sprite animation
by:
scdescr->cmdescr->colors to get the number of colors-1 of the
			 LP4 sprite animation.
scdescr->cmap to get the actual color map of the sprite
	      animation.
Together both informations can be used without modification
to set the colors for a sprite animation using tgdlp4xx.obj's
rgb6() function:
rgb6(0,scdescr->cmdescr->colors,scdescr->cmap);

the spritemap structure (= the sprite animation structure)
itself can be accessed by:
scdescr->tgdsmdescr
The spritemap structure is fully initialized. You can use it
to generate a sprite incarnation structure using the
tgdsuppx.obj procedure: newsprite(). The sprite incarnation
structure is needed to display sprites on the screen using
tgdlp4xx.obj's addspr() and onspr() functions.

INPUTS:
*filename: pointer to the \0 terminated name of the LP4/SP4
 	   file from which the sprite animation should be
	   extracted from.
scnumber: number of sprite animation to load out of an LP4/SP4
	  file. The first sprite animation in a LP4/SP4 file
	  has the number 1, the second sprite animation has
	  the number 2...
	  valid numbers for sprite animations range from 1-255.
*loaderr: pointer to an error variable. If an error has occured
	  while executing readsc() this variable will contain
	  information about where the error has occured.

RESULT:
scdescr *scinfo: pointer to a LP4 sprite descriptor containing
		 information about the LP4 sprite animation.
		 If scinfo is 0 the LP4 sprite descriptor was
		 not created. The reason for this is stored in
		 the error variable. Refer to the readbc() 
		 description for the meaning of the values of
		 the error variable.

BUGS:
none known

SEE ALSO:
freesc()
tgdsupp.txt: newsprite(), freesprite()
tgdlp4.txt: rgb6(), addspr(), onspr(), refreshspr()

