tgdlp4.obj function summary:
============================

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


To use tgdlp4xx.obj (tgd = Tale Graphics Driver) the following
hardware items are required:

- IBM compatible PC/XT/AT with 80188 CPU or above
- a VGA card with at least 256KB RAM


tgdlp4xc.obj is assembled for the COMPACT memory model. This
means that all calls to procedures must be declared as NEAR
while pointers to data are all FAR.
tgdlp4xl.obj is assembled 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.

tgdlp4xx.obj expects all parameters to be passed using C
calling conventions. The C calling mechanism looks like this:
When calling a routine, C takes the parameters for the
routine and pushes them onto the stack. For example:
x=routine(parmA,parmB);
Then it calls a routine named "_routine" (adds an underscore
to the head of the routine name).
The code at _routine saves the contents of the registers the
routine will use (except ax) and will execute the requested
function. After execution _routine restores the contents of
the registers (except ax) and passes back control to the
caller. Finally, the caller has to clean up the stack by
pulling the previously pushed parameters (in this case: parmA,
parmB) from it.

The ax register is never saved because sometimes it contains
a result (x in the example). To be more precise:
If the result is 8 bits wide, al will contain it.
If the result is 16 bits wide, ax will contain it.
If the result is 32 bits wide (e.g. a pointer), ax will contain
the lower 16 bits and dx the higher 16 bits.

This is what the C compiler does with our example (assuming
x, parmA, parmB are all 16 bits wide):
	...
	push parmB	;push parameters (Note: since C is a
	push parmA	;right-pusher it pushes parameters
			;from right to left)
	call _routine	;call _routine
	add sp,4	;take parameters from stack
	mov x,ax	;store result in x
	...


PART I: VGA CONFIGURATION
---------------------------------------------------------------

ubyte vgalp4(void);
switch to ModeX

FUNCTION:
This routine enables ModeX and initializes it. vgalp4() must
be called before any other function in tgdlp4xx.obj is used.

A call to this procedure will set the phys. display resolution
according to the screenmode previously selected. If no
screenmode was chosen yet vgalp4() will default to SM_320x200
(320x200x256 phys. screen resolution). Active viewmode will be
VM_320x200, VM_320x400, VM_256x256 or VM_256x512 (depending on
on the active screenmode). Viewpage will be page 0, drawpage
will be page 0. Drawregion will be the entire drawpage. Other
display variables will be set similar to mode 13h (except
screenon which will have the previously selected value or - if
this is the first call to vgalp4() - its default value
[display on]).

The internal variables (syncxscr, drawpens, drawmode, blitpens,
blitmode and font definitions) will have their values as set
by the user or reasonable default settings. vgalp4()
invalidates all previous polygon and pattern definitions (if
there were any). The sprite display list will be cleared.

vgalp4() does not clear the VRAM. This must be done explicitly
by calling clearreg().

INPUTS:
none

RESULT:
ubyte error: !=0 if an error has occured.
Possible errors:
VL4ERR_NOVGA: No VGA card installed.
VL4ERR_LT256: VGA card with less than 256KB detected.

BUGS:
vgalp4() may not work properly when QEMM is active in stealth
mode.

SEE ALSO:
screenmode(), viewmode(), viewpage(), drawpage(), drawreg(),
clearreg()


void co80(void);
switch to text mode

FUNCTION:
This routine switches the VGA card back to mode 03h, the usual
text mode with 80x25 chars text, 16 colors. It is similar to
the DOS command: mode co80.

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
DOS command: mode co80


byte screenmode(ubyte scrnmode);
change the physical resolution of the display

FUNCTION:
To control the physical resolution of the display use this
routine. You can select between these resolutions:
320x200x256, 320x400x256, 256x256x256 and 256x512x256. To set
the desired phys. res. pass SM_320x200, SM_320x400, SM_256x256
or SM_256x512 to the procedure accordingly.

After a call to screenmode() the viewmode is set to VM_320x200,
VM_320x400, VM_256x256 or VM_256x512 - depending on the
selected screenmode. Active viewpage will be page 0, active
drawpage will be page 0. The drawregion will cover the entire
drawpage. A previously defined polygon or pattern will be
invalidated. Calling this function clears the sprite display
list.

screenmode() does not clear the VRAM. This must be done
explicitly by calling clearreg().

INPUTS:
scrnmode: SM_320x200 for 320x200x256 phys. resolution.
	  SM_320x400 for 320x400x256 phys. resolution.
	  SM_256x256 for 256x256x256 phys. resolution.
	  SM_256x512 for 256x512x256 phys. resolution.

RESULT:
byte success: TRUE if function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
viewmode(), viewpage(), drawpage(), drawreg(), clearreg()


byte viewmode(ubyte vjumode);
select a new viewmode

FUNCTION:
In ModeX the VRAM can be organized in different ways. Perhaps 
you already know the 320x200x256 organization of mode 13h.
You know that 320x200x256 requires 64KB of memory. But most
VGA cards have more than just 64KB of memory - a usual size of
a VGA card's VRAM is 256KB. Therefore four 'pages' of
320x200x256 can be installed in VRAM - however this VRAM 
organization is not used in the tgdlp4xx module [in viewmode
VM_320x200/VM_256x256 there are two pages installed in VRAM
- each having the size of 320x400/256x512. The upper part of
these pages can be used as efficient sprite and pattern double
buffers - see also viewpage()]. If a phys. resolution of
320x400/256x512 is selected still 2 'pages' of 320x400x256/
256x512x256 can be held in VRAM - each needing 128KB of memory.
This is achieved in the VM_320x400/VM_256x512 modes. With
256KB of memory the VRAM can be reorganized in a way that
there are 'virtual' resol. of 320x800, 640x400 and 1280x200
available (in the screenmodes SM_320x???). Respectively for
the SM_256x??? screenmodes there are virtual resolutions of
256x1024, 512x512 and 1024x256 existing. The mentioned virtual
resolutions (I call them viewmodes) can be set by passing:
[screenmode SM_320x???]: VM_320x800, VM_640x400, VM_1280x200
[screenmode SM_256x???]: VM_256x1024, VM_512x512, VM_1024x256
as argument to the procedure.
Of course the phys. resolution of the screen is still 320x200,
320x400, 256x256 or 256x512. But you can do graphics output to
the invisible parts of the virtual screen and using viewreg()
you can display previously hidden areas of it.

When changing the viewmode the viewregion is resetted to (0,0).
The drawregion is set to cover the entire new virtual screen.
A previously defined pattern and/or polygon definition will be
invalidated. The sprite display list will be cleared.
If viewmode VM_320x200, VM_320x400, VM_256x256 or VM_256x512
was selected viewpage will be page 0 and drawpage will be page
0. In viewmode VM_320x200 viewpage 0, 1 will cover the
drawpage area (0,200)-(319,399). In viewmode VM_256x256
viewpage 0, 1 will cover the drawpage area (0,256)-(255,511).

The viewmodes are incompatible to each other. A drawing in the
VM_640x400 mode is destroyed when switching to VM_1280x200.
Therefore it is adviseable to do a clearreg() after switching
viewmodes to clear the new virtual screen.

INPUTS:
vjumode: New viewmode. 
	 Allowed viewmodes, 320x200 phys. res.:
	 VM_320x200:  virtual res.  320x400,  2 pages.
	 VM_320x800:  virtual res.  320x819,  1 page.
	 VM_640x400:  virtual res.  648x404,  1 page.
	 VM_1280x200: virtual res. 1304x200,  1 page.
         Allowed viewmodes, 320x400 phys. res.:
	 VM_320x400:  virtual res.  320x400,  2 pages.
	 VM_320x800:  virtual res.  320x819,  1 page.
	 VM_640x400:  virtual res.  648x404,  1 page.
	 Allowed viewmodes, 256x256 phys. res.:
	 VM_256x256:  virtual res.  256x512,  2 pages.
	 VM_256x1024: virtual res.  256x1024, 1 page.
	 VM_512x512:  virtual res.  512x512,  1 page.
	 VM_1024x256: virtual res. 1024x256,  1 page.
	 Allowed viewmodes, 256x512 phys. res.:
	 VM_256x512:  virtual res.  256x512,  2 pages.
	 VM_256x1024: virtual res.  256x1024, 1 page.
	 VM_512x512:  virtual res.  512x512,  1 page.

RESULT:
byte success: TRUE if function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
uviewmode(), viewpage(), viewreg(), drawpage(), drawreg(),
clearreg()


byte uviewmode(uword xsize,uword ysize);
enable a user defined viewmode

FUNCTION:
If you want to create a virtual screen having your own user
defined resolution you can do so by calling this function.
Pass the desired virtual screen size to the xsize, ysize
variables. xsize may not be smaller than the width of the
physical screen and ysize may not be smaller than the height of
the physical screen. xsize must be dividable by 8. xsize*ysize
may not exceed the value 262144 (256 KB). A user defined
virtual screen has always only 1 page - even if more pages
would fit into VRAM.
Like with viewmode() viewreg() can be called to display hidden
areas of your virtual screen. Remember that all drawings in a
virtual screen are destroyed when using viewmode() or
uviewmode() calls with different virtual screen resolutions.
Therefore it is usefull to clear the virtual screen by calling
clearreg() whenever the screen resolution was changed.
Changing the viewmode by calling uviewmode() has the same
effects as changing the viemode with viewmode(). That means
the viewregion is resetted to (0,0). The drawregion is set to
cover the whole new virtual screen. A previously defined
polygon and/or pattern definition will be invalidated. The
sprite display list will be cleared.

INPUTS:
xsize, ysize: x,y size of the user defined virtual screen. (x,y)
	      size of the virtual screen must be at least as
	      big as the (x,y) size of the physical screen.
	      Additionally xsize must be dividable by 8.
	      xsize*ysize may not be any larger than 262144.

RESULT:
byte success: TRUE if function was successfully executed,
	      FALSE if not.

BUGS:
none known.

SEE ALSO:
viewmode(), viewreg(), drawreg(), clearreg()


void syncxscroll(byte syncxscr);
synchronize horizontal scrolling for older VGA cards
enable vrclk library compability mode

FUNCTION:
This routine has only an effect in conjunction with viewreg().
Older VGA cards require a special synchronization when the
viewregion should be scrolled horizontally. By passing TRUE
to the procedure this synchronization is switched on. It is
executed whenever viewreg() is called. The main disadvantage
of the horizontal scrolling synchronization is that viewreg()
wastes a lot of CPU time synchronizing the scrolling. So if
you don't scroll horizontally at all or you have a 'clever'
VGA card you should switch off horizontal scrolling
synchronization by passing FALSE to syncxscroll().
ATTENTION: It is also required to call syncxscroll(FALSE)
before using functions of the vrclk library - otherwise a
system deadlock will occur.
By default, horizontal scrolling synchronization is ON.

INPUTS:
syncxscr: horizontal scrolling synchronization flag:
	  TRUE if explicit horizontal scrolling sync. is
	  required,
	  FALSE if not.

RESULT:
none

BUGS:
none known

SEE ALSO:
viewreg()


byte viewreg(uword x_pos,uword y_pos);
display an area of the virtual screen

FUNCTION:
In the viewmodes VM_320x800, VM_640x400, VM_1280x200,
VM_256x1024, VM_512x512 and VM_1024x256 it is impossible to
display the whole virtual screen. Only a part of the size of
the physical resolution is visible. To select a region of the
virtual screen to display (the 'viewregion') pass the
coordinates of the upper left corner of it to this function.
The area which will be visible after a call to viewreg() is:
[SM_320x200]: (x_pos,y_pos) - (x_pos+319,y_pos+199)
[SM_320x400]: (x_pos,y_pos) - (x_pos+319,y_pos+399)
[SM_256x256]: (x_pos,y_pos) - (x_pos+255,y_pos+255)
[SM_256x512]: (x_pos,y_pos) - (x_pos+255,y_pos+511)

Possible x_pos's and y_pos's vary on different viewmodes.
Allowed x_pos values range from 0 to:
[SM_320x???]: x-resolution of virtual screen - 320
[SM_256x???]: x-resolution of virtual screen - 256
Allowed y_pos values range from 0 to:
[SM_320x200]: y-resolution of virtual screen - 200
[SM_320x400]: y-resolution of virtual screen - 400
[SM_256x256]: y-resolution of virtual screen - 256
[SM_256x512]: y-resolution of virtual screen - 512

If the syncxscr flag is FALSE you should wait for the end of
the vertical retrace by using the waittof() procedure before
calling viewreg(). If functions of the vrclk library are used
it is not allowed to wait for the vertical retrace via
waittof(). See the description of the vrclk library on
alternate methods to wait for the end of the vertical retrace.

The viewregion can be changed up to 70 times per second. If the
syncxscr flag is TRUE [you can set the syncxscr flag by
syncxscroll()] viewreg() consumes a lot of CPU time to
synchronize horizontal scrolling. This synchronizing is needed
for older VGA cards. If you do not scroll horizontally in your
program or you have a 'clever' VGA card it is VERY recommended
to switch off horizontal scrolling synchronization by calling
syncxscroll(FALSE). It is also REQUIRED to disable horizontal
scrolling synchronization before using functions of the vrclk
library.

This procedure is faster than ordinary scrolling functions
(that's what it's generally used for) since the whole virtual
screen is already stored in VRAM and doesn't have to be copied
from conventional memory.

INPUTS:
x_pos: x coord. of upper left edge of region to display.
       x_pos may range from 0 to (x-resolution of
       virtual screen - x-resolution of physical screen).
y_pos: y coord. of upper left edge of region to display.
       y_pos may range from 0 to (y-resolution of
       virtual screen - y-resolution of physical screen).

RESULT:
byte success: TRUE if function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
screenmode(), viewmode(), uviewmode(), syncxscroll(), waittof()


void splitscrn(uword y_pos);
split screen vertically

FUNCTION:
To split the phys. screen vertically this function is used.
The upper part of the screen will be displayed as previously
selected. From (0,y_pos) of the phys. screen the virtual
screen area from (0,0) - (319,physical screen y-resolution -
y_pos - 1) will be displayed. If viewmode VM_320x200,
VM_320x400, VM_256x256 or VM_256x512 is active the lower part
of the display will be taken from drawpage 0.

y_pos values may not exceed the y-resolution of the physical
screen. If y_pos = y-resolution of the physical screen the
display won't be splitted anymore.

Note: changing the y-coord. of splitscrn() can only be perfomed
while the vertical retrace is active. If this routine is
called before that event the effect of this procedure will be
delayed until the vertical retrace becomes active.

INPUTS:
y_pos: phys. y-coordinate where the screen splitting should
       commence. Valid values for y_pos range from 0 to y-res.
       of the physical screen.

RESULT:
none

BUGS:
none known

SEE ALSO:
waittof()


void scrnon(byte screenon);
enable / disable output to physical screen

FUNCTION:
Output to the physical screen can be suppressed by scrnon() if
FALSE is passed as screenon value and can be enabled again if
the procedure is called with TRUE as argument.

When output to the display is switched off it gets filled with
the border color.

INPUTS:
screenon: FALSE if output to the display should be suppressed.
	  TRUE if output to the display should not be
	  suppressed.

RESULT:
none

BUGS:
none known

SEE ALSO:
ovscol()


void drawmode(ubyte drwmode);
select boolean drawmask mode

FUNCTION:
The boolean drawmask mode selected in drawmode() is used with
all graphics operations except clearreg(). One of the
following mask modes can be chosen:
DM_SOLID: remove mask. Draw graphics 'as is'.
DM_AND: do a binary AND between the VRAM and the graphics
being drawn.
DM_OR: do a binary OR between the VRAM and the graphics
being drawn.
DM_XOR: do a binary XOR between the VRAM and the graphics
being drawn.

Note: If pattern fill is enabled the active drawmode will
always be DM_SOLID for the functions using pattern fill -
independent from the selected drawmode.

INPUTS:
drwmode: boolean drawmask mode. Allowed values:
	 DM_SOLID, DM_AND, DM_OR, DM_XOR

RESULT:
none

BUGS:
none known

SEE ALSO:
all graphics output operations


PART II: GRAPHIC PRIMITIVES
---------------------------------------------------------------

void clearreg(void);
clears the drawregion

FUNCTION:
clearreg() clears the drawregion with the background draw pen
or the current pattern (if pattern fill is active). It always
uses drawmode DM_SOLID to clear the drawregion - even if
another drawmode was selected. However the current drawmode
will not be changed by this routine.

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
drawreg(), pen(), pfill(), drawmode()


void writepixel(word x_pos,word y_pos);
plot a pixel

FUNCTION:
Changes the color of the selected pixel to that currently
specified by the foreground draw pen or by the active
pattern (if pattern fill was previously enabled).

INPUTS:
x_pos: x coordinate at which the selected pixel is located.
y_pos: y coordinate.

RESULT:
none

BUGS:
none known

SEE ALSO:
pen(), pfill(), readpixel()


word readpixel(uword x_pos,uword y_pos);
read the pen value of a pixel

FUNCTION:
To read the color of a pixel this procedure is used. Any pixel
within the virtual screen can be read even if access to
certain areas of the virt. screen was excluded by drawreg().
If it is attempted to read a pixel which is out of the virtual
screen -1 is returned.

INPUTS:
x_pos: x coordinate at which the selected pixel is located.
y_pos: y coordinate.

RESULT:
word color: pen (0..255) number at that position is returned.
	    -1 is returned if cannot read that pixel.

BUGS:
none known

SEE ALSO:
writepixel()


void line(word x1_pos,word y1_pos,word x2_pos,word y2_pos);
draw a line

FUNCTION:
Draws a line from (x1_pos,y1_pos) to (x2_pos,y2_pos). Uses
color of foreground draw pen or pattern (if pattern fill is
active) to fill it.

INPUTS:
x1_pos,y1_pos: (x,y)-coordinates of point to start line
x2_pos,y2_pos: (x,y)-coordinates of point to end line

RESULT:
none

BUGS:
none known

SEE ALSO:
pen(), pfill(), polygrid()


void arc(word x_pos,word y_pos,uword radius_x,uword radius_y,word start_angle,word stop_angle);
draw an arc

FUNCTION:
To draw an arc use this function. (x_pos,y_pos) will be the
center of the arc and radius_x, radius_y the extensions in x,y
direction. Start_angle and stop_angle define the size and
position of the ellipse outline which should be drawn. They
are expected to be in new degrees*10 (x). A value of 0 for
start_angle and of 4000 for stop_angle will draw an entire
ellipse outline. Angle 0 is right of the center of the arc.
Angle 1000 is in top of the center of the arc.

The algorithm used here is different from the one used in
ellipse(). Therefore a ellipse outline created with this
procedure may be different from the ellipse shape created by
ellipse().

(x) a new degree circle runs from 0-400 degrees.

INPUTS:
x_pos,y_pos: coord. of the center of the arc.
radius_x: x-radius of the arc.
radius_y: y-radius of the arc.
start_angle: starting angle for arc. Angle is expected in new
	     degrees*10.
stop_angle: ending angle for arc. Angle is measured in new
	    degrees*10.

RESULT:
none

BUGS:
none known

SEE ALSO:
ellipse()


void polygrid(uword tab_len,word far *poly_table);
draw outline of a polygon

FUNCTION:
With this procedure the outline of any polygon can be drawn.
The algorithm used here is slightly different from the one
used in drawpoly(). That means the outline created here may
not necessarly match the outline of a polygon created with
drawpoly(). The polygon definition table can hold up to
10,000 polygon edge entries.

INPUTS:
tab_len: number of polygon edges contained in the poly_table
	 array.
*polytable: pointer to an array of edge coord. for the polygon.
	    The array looks like this:
	    word polytable[]={ x_pos_edge_1, y_pos_edge_1,
		  	       x_pos_edge_2, y_pos_edge_2,
			       x_pos_edge_3, y_pos_edge_3,
			       ...         , ...           };

RESULT:
none

BUGS:
none known

SEE ALSO:
drawpoly()


void rectangle(word x1_pos,word y1_pos,word x2_pos,word y2_pos);
draw a filled box

FUNCTION:
This procedure is used for drawing a filled rectangle which
has the coordinates:
(x1_pos,y1_pos)-(x2_pos,y1_pos)-(x2_pos,y2_pos)-(x1_pos,y2_pos).
The rectangle will be filled with the color of the foreground
draw pen (if pattern fill is not enabled) or the current
pattern.

INPUTS:
x1_pos,y1_pos: coord. of one edge of the rectangle.
x2_pos,y2_pos: coord. of another edge of the rectangle -
	       positioned diagonally to the first edge.

RESULT:
none

BUGS:
none known

SEE ALSO:
pen(), pfill()


void ellipse(word x_pos,word y_pos,uword radius_x,uword radius_y);
draw a filled ellipse

FUNCTION:
ellipse() draws a filled ellipse with (x_pos,y_pos) as center
of the ellipse, radius_x as extension in the x-direction and
radius_y as extension in the y-direction. If radius_x=radius_y
(ideally) a circle will be drawn.

INPUTS:
x_pos,y_pos: coord. of the center of the ellipse.
radius_x: x-radius of the ellipse.
radius_y: y-radius of the ellipse.

RESULT:
none

BUGS:
none known

SEE ALSO:
redrawpoly(), arc()


void metagon(word x_pos,word y_pos,uword scanlines,word far *meta_table);
draw a by horizontal lines defined polygon

FUNCTION:
A special polygon (I call it metagon) can be drawn by this
procedure. A metagon is a polygon which is defined by an array
of horizontal lines. Every single horizontal line of a metagon
has to be defined by yourself. This may sound inconvenient but
after all metagons can be drawn extremly fast and are easily
moveable. Unlike a conventional polygon where all polygon edge
coordinates have to be changed to move it a metagon can be
moved by simply changing its position coordinates (x_pos,y_pos).

No more than 10,000 horizontal lines may be defined in the
metagon definition table.

INPUTS:
x_pos,y_pos: position of the metagon. The x_pos coordinate is
	     added to the x coordinates of each horizontal
	     line definition in the metagon table to form the
	     final x-position of the metagon.
	     The horizontal lines of which a metagon consists
	     of are drawn beginning from y_pos.
scanlines: number of horizontal lines-1 of which the metagon
	   is made of.
*meta_table: pointer to an array of x-coordinates for each
	     horizontal line. The array looks like this:
	     word meta_table[]={ x_pos_1_hline1,
				 x_pos_2_hline1,
				 x_pos_1_hline2,
				 x_pos_2_hline2,
				 ... };
	     hline1 will be drawn at y_pos, hline2 at y_pos+1,
	     ...

RESULT:
none

BUGS:
none known

SEE ALSO:
drawpoly(), redrawpoly()


void drawpoly(uword tab_len,const word far *poly_table);
draw a convex polygon

FUNCTION:
drawpoly() can draw simple, convex polygons very fast. The
polygon definition table can hold up to 10,000 polygon edge
entries. The polygon will be filled with the current pattern
(if pattern fill is enabled) or the color of the foreground
draw pen.

INPUTS:
tab_len: number of polygon edges contained in the poly_table
	 array.
*polytable: pointer to an array of edge coord. for the polygon.
	    The array looks like this:
	    word polytable[]={ x_pos_edge_1, y_pos_edge_1,
			       x_pos_edge_2, y_pos_edge_2,
			       x_pos_edge_3, y_pos_edge_3,
			       ...         , ...           };

RESULT:
none

BUGS:
This procedure is limited to convex polygons. It will not
draw more complex polygons correctly. However the system will
not crash if it is attempted to generate more complex polygons.

SEE ALSO:
pen(), pfill(), redrawpoly(), polygrid()


void redrawpoly(void);
redraw the last polygon/metagon or the last ellipse

FUNCTION:
Redraws the last polygon defined by drawpoly()/metagon() or
the last ellipse defined by ellipse(). This depends on what
object was drawn last.

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
drawpoly(), metagon(), ellipse()


PART III: PATTERN FILL
---------------------------------------------------------------

byte pattern(uword x_pos,uword y_pos,uword x_size,uword y_size);
choose a pattern for pattern fill

FUNCTION:
To select a pattern for the pattern fill algorithm pass the
coordinates of the upper left edge of the pattern (which must
be present somewhere inside the virtual screen) in the
x_pos, y_pos variables. x_pos must be dividable by 4. Pass
the size of the pattern in the x_size, y_size variables. The
x-size of a pattern must also be dividable by 4. The minimum
(x,y) size of a pattern is (4,1).

pattern() does not automatically enable pattern fill. Use
pfill(TRUE) to enable pattern fill. Pattern fill can only be
switched on if a valid pattern(rectangle) was defined.

The pattern(rectangle) will be invalidated whenever vgalp4(),
screenmode(), viewmode() or uviewmode() is called. In viewmode
VM_320x200, VM_320x400, VM_256x256 and VM_256x512 changing the
active drawpage will also change the active pattern definition.

INPUTS:
x_pos,y_pos: coord. of the upper left edge of the pattern.
	     x_pos must be dividable by 4.
x_size,y_size: x,y size of the pattern. x_size must be
	       dividable by 4.
	       x_pos+x_size may range from 4 to (x-size of
	       virtual screen).
	       y_pos+y_size may range from 1 to (y-size of
	       virtual screen).

RESULT:
byte success: TRUE if pattern(rectangle) is valid,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
pfill(), vgalp4(), screenmode(), viewmode(), uviewmode(),
drawpage()


byte pfill(byte pattenable);
enable/disable pattern fill

FUNCTION:
With this function it is possible to enable pattern fill.

Pattern fill is supported with these tgdlp4xx functions:
clearreg(), writepixel(), line(), arc(), polygrid(),
rectangle(), ellipse(), metagon(), drawpoly(), redrawpoly(),

To enable pattern fill pattenable must have the value TRUE.
To disable pattern fill pattenable must have the value FALSE.
Pattern fill can only be enabled if a valid pattern(rectangle)
was selected with pattern(). Once pattern fill is active it
will override any drawmode() setting. The default drawmode for
pattern fill is DM_SOLID and cannot be changed. If pattern
fill is switched off the previously selected drawmode becomes
active again.

pattern fill will automatically be disabled when one of these
functions is called: vgalp4(), screenmode(), viewmode(),
uviewmode().

INPUTS:
pattenable: TRUE if pattern fill should be enabled,
	    FALSE if pattern fill should be disabled.

RESULT:
byte pfillstatus: TRUE if pattern fill is enabled,
		  FALSE if not.

SEE ALSO:
pattern(), clearreg(), writepixel(), line(), arc(), polygrid(),
rectangle(), ellipse(), metagon(), drawpoly(), redrawpoly(),
drawmode(), vgalp4(), screenmode(), viewmode(), uviewmode()


PART IV: BITMAPS
---------------------------------------------------------------

void bltbitmap(word dest_x,word dest_y,uword src_x,uword src_y,uword xsize,uword ysize,bitmap far *yourbitmap);
blit a part of a bitmap into the virtual screen

FUNCTION:
A part of a bitmap can be copied from conventional memory to
VRAM with this procedure. dest_x and dest_y define the upper
left edge of the destination rectangle which is in VRAM where
the bitmap should be blitted to. src_x and src_y define the
upper left edge of the part of the source bitmap which is in
conventional memory where should be blitted from. xsize and
ysize define the x-size and y-size of the blit rectangle. The
smallest blit rectangle has the size (0,0) which means that
only one pixel should be blitted.

INPUTS:
dest_x,dest_y: upper left edge of the destination rectangle 
	       where should be blitted to.
src_x,src_y: upper left edge of a rectangle within the source
	     where is blitted from.
xsize,ysize: size of the blit rectangle.
	     src_x+xsize may range from 0 to bitmap.xsize
	     src_y+ysize may range from 0 to bitmap.ysize
*yourbitmap: pointer to the bitmap structure which looks like
	     this:
	     struct { uword xsize,ysize;
		      uword bytespline;
		      ubyte huge *plane[4]; /* but you can use far, too */
		    } bitmap;

RESULT:
none

BUGS:
none known

SEE ALSO:
bltmode(), getbitmap()
tgdsupp.txt: newbitmap(), freebitmap()
lp4supp.txt: readbc(), freebc()


void getbitmap(word dest_x,word dest_y,uword src_x,uword src_y,uword xsize,uword ysize,bitmap far *yourbitmap);
blit a part of the virtual screen into a bitmap

FUNCTION:
A part of the virtual screen can be copied to a bitmap placed
in conventional memory with this procedure. dest_x and dest_y
define the upper left edge of the destination rectangle inside
the bitmap where the VRAM area should be blitted to. src_x and
src_y define the upper left edge of the part of the virtual
screen where should be blitted from. xsize and ysize define
the x-size and y-size of the blit rectangle. The smallest blit
rectangle has the size (0,0) which means that only one pixel
should be blitted.

If the pre-reserved bitmap is smaller than the blit rectangle
the rectangle is sized to the max. size of the bitmap by
cutting off at the right and at the bottom of the rectangle.
Please note that the bitmap structure must be initialized and
memory for the bitmap must be allocated by your program.
(Note: To create a bitmap structure and reserve memory for a
bitmap the newbitmap() function declared in tgdsupp.h can be
used.) getbitmap() does not create a bitmap structure nor
initialize it nor allocate memory for the bitmap.

getbitmap() can get areas of the virtual screen excluded by
drawreg().

INPUTS:
dest_x,dest_y: upper left edge of the destination rectangle
	       where should be blitted to.
src_x,src_y: upper left edge of a rectangle within the source
	     where is blitted from.
xsize,ysize: size of the blit rectangle.
	     src_x+xsize may range from 0 to (x-size of virtual
	     screen - 1).
	     src_y+ysize may range from 0 to (y-size of virtual
	     screen - 1).
*yourbitmap: pointer to the bitmap structure which looks like
	     this:
	     struct { uword xsize,ysize;
		      uword bytespline;
		      ubyte huge *plane[4]; /* but you can use far, too */
		    } bitmap;

RESULT:
none

BUGS:
none known

SEE ALSO:
tgdsupp.txt: newbitmap(), freebitmap()
bltbitmap(), drawreg()


void bltmode(ubyte blitmode);
select a blitmode

FUNCTION:
bltmode() is used to select a blitmode. This has no effect on
getbitmap().
You can set the following blitmodes:
BM_SOLID: blit a bitmap to VRAM 'as is'.
BM_TRANSPARENT: don't blit pixels into VRAM which have the
		blit background color as selected in bltpen().
		This makes the background of a bitmap look
		transparent if used correctly.
BM_COLREPLACE: replace pixels having the blit pen background
	       color with pixels having the draw pen
	       background color and replace pixels having the
	       blit pen foreground color with pixels having
	       the draw pen foreground color.
BM_COLREPLACE|BM_TRANSPARENT: do first a BM_COLREPLACE. After
			      this do a BM_TRANSPARENT.

INPUTS:
blitmode: blitmode. Allowed values: BM_TRANSPARENT,
	  BM_COLREPLACE, BM_COLREPLACE|BM_TRANSPARENT

RESULT:
none

BUGS:
none known

SEE ALSO:
bltbitmap(), bltpen()


void bltpen(ubyte blitpen,ubyte color);
select blit pens

FUNCTION:
Selects a color for foreground or background blit pen.
Set pen to PEN_B if a color (0..255) for the background
blit pen should be selected.
Set pen to PEN_F if a color (0..255) for the foreground
blit pen should be selected.

INPUTS:
blitpen: blit pen to change. Allowed values are: PEN_B, PEN_F.
color: new color for blit pen. color may range from 0-255.

RESULT:
none

BUGS:
none known

SEE ALSO:
bltmode()


byte vramcopy(uword dest_x,uword dest_y,uword src_x,uword src_y,uword size_x,uword size_y);
copy an area inside the VRAM to the VRAM

FUNCTION:
This routine copies a rectangular area which must be present in
VRAM to the VRAM. src_x, src_y are the coordinates of the top
left edge of the source rectangle; dest_x and dest_y are the
coordinates of the top left edge of the destination rectangle.
src_x and dest_x must be dividable by 4. Pass the size of the
area to copy in size_x, size_y. size_x must also be dividable
by 4. The minimum size for an area to copy is (4,1). Source
and destination areas may overlap.

WARNING: vramcopy() ignores the drawregion settings which
means you can copy from anywhere inside VRAM to anywhere.
However you cannot copy from/to areas out of the virtual
screen. If this is attempted vramcopy() doesn't do anything and
returns FALSE.

vramcopy() can be used to build a tile system for tgdlp4xx.
You can store tiles in invisible parts of the virtual screen
and blit them to the visible part when required.

INPUTS:
dest_x,dest_y: top left edge of destination area. dest_x must
	       be dividable by 4.
src_x,src_y: top left edge of source area. src_x must be
	     dividable by 4.
size_x,size_y: size of the copy rectangle. size_x must be
	       dividable by 4.
	       (src_x+size_x) and (dest_x+size_x) may range
	       from 4 to (x-size of virtual screen).
	       (src_y+size_y) and (dest_y+size_y) may range
	       from 1 to (y-size of virtual screen).

RESULT:
byte success: TRUE if the function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
drawreg()


PART V: SPRITES
---------------------------------------------------------------

void resetspr(void);
reset sprite system

FUNCTION:
A call to resetspr() clears all entries in the sprite display
list and resets the sprite engine. This means tgdlp4xx forgets
about the existence of all used sprites. You will not be able
to access a used sprite using tgdlp4xx.obj functions anymore
(even if it is still visible on the screen).

resetspr() does not free any memory that was allocated for
sprites. It also doesn't destroy any of the user accessible
sprite structures. You can re-init the sprite system by adding
sprites to the sprite display list again using addspr().

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
addspr()


byte addspr(ubyte sprno,uword sprsavex,uword sprsavey,spriteinc far *usersprite);
add a sprite to the sprite display list

FUNCTION:
Before a sprite can be displayed, moved or animated it has to
be introduced to the sprite system. This introduction is made
by addspr() which adds a sprite to the tgdlp4xx internal
sprite display list. Once a sprite is in the display list you
can call all following sprite functions:
removespr(), onspr(), offspr(), movespr(), animspr(),
refreshspr(), ucollspr(), areaoffspr(), areaonspr().

The tgdlp4xx sprite system is prioritized. Every sprite has
it's own priority which defines which sprite will be above of
which sprite when two or more sprites overlap. The sprite with
priority 0 will always lie on top of all other sprites, while
the sprite with priority 31 will always be beyond any other
sprite. All sprites are having a higher priority than the
background and will hide it at non transparent positions.
Sprites are always drawn in BM_TRANSPARENT, DM_SOLID mode with
transparent color 0. However the current blit-/drawmode is
not changed by the sprite system and will still be active with
any other draw command.
Pass in sprno the sprite priority (0-31) of the sprite to add.
Every sprite priority is allowed to exist only once. If a
sprite in the sprite display list has already the priority
requested for the sprite to add the routine will fail.

Sprites do save their background and restore it automagically
when they are moved or switched off. In order to do this the
sprite system requires information about the location of the
sprite background buffer. All sprite background buffers must
be located inside the virtual screen entirely. They may lie in
a region of the virtual screen excluded by drawreg(). Pass the
coordinates of the upper left edge of the sprite background
buffer rectangle in the (sprsavex,sprsavey) variables.
sprsavex must be dividable by 4.
The sprite background buffers of all sprites in the sprite
display list may not overlap. You must check this condition by
yourself. The size of a sprite background buffer rectangle is
calculated as follows:
x_size of sprite background buffer = x_size of sprite + 4,
if x_size of sprite is dividable by 4.
x_size of sprite background buffer = (x_size of sprite AND
252) + 8 if x_size of sprite is not dividable by 4.
y_size of sprite background buffer = y_size of sprite.
Example:
A sprite has the size 35x47. (sprsavex,sprsavey) have the
values (0,0). The sprite background buffer has the size of:
(35 AND 252)+8,47 = 40,47. That means you may place the next
sprite background buffer at coordinates (40,0) for example.

If a sprite was successfully added to the sprite display list
it is in OFF state. Its position is (0,0) in the virtual
screen and the active sprite animation sequence number is 0.

Note: In the following descriptions the term 'sprite number'
is equal to the term 'sprite priority'.

INPUTS:
sprno: priority of sprite that should be added to the sprite
       display list. sprno may range from 0-31.
sprsavex,sprsavey: coordinates of the upper left edge of the
		   sprite background buffer. sprsavex must
		   be dividable by 4.
*usersprite: pointer to a sprite incarnation structure which
	     is supplied by the newsprite() function contained
	     in tgdsupp.h.

RESULT:
byte success: TRUE if sprite was successfully added to the
	      sprite display list,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
removespr(), onspr(), offspr(), movespr(), animspr(),
refreshspr(), ucollspr(), areaoffspr(), areaonspr()
tgdsupp.txt: newsprite(), freesprite()
lp4supp.txt: readsc(), freesc()


byte removespr(ubyte sprno);
remove a sprite from the sprite display list

FUNCTION:
This procedure has the reverse effect of addspr(). It removes
a sprite from the display list and therefore frees the
previously occupied sprite slot in the list. The sprite slot
in the sprite display list can be re-used immediately if
removespr() was executed successfully.

A sprite can only be removed from the sprite display list if
it is switched off. To switch off a sprite use the command
sequence: offspr(sprite number); refreshspr();

removespr() doesn't free any memory allocated for sprites or
touch any of the user accessible sprite structures.

INPUTS:
sprno: number of sprite that should be removed from the sprite
       display list. Valid sprite numbers range from 0-31.

RESULT:
byte success: TRUE if the function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
addspr(), offspr(), refreshspr()


void onspr(ubyte sprno);
display a sprite

FUNCTION:
onspr() prepares a sprite to be switched on. The sprite will
appear in the drawregion at the with movespr() selected
position in the animation sequence number selected by
animspr(). onspr() doesn't switch on a sprite. It only stores
the SPRITE_ON command in the sprite command queue. You must
call refreshspr() after onspr() to switch the sprite on
effectively.

INPUTS:
sprno: number of sprite to prepare to display. The
       corresponding sprite slot must be occupied in the
       sprite display list.

RESULT:
none

BUGS:
none known

SEE ALSO:
movespr(), animspr(), refreshspr()


void offspr(ubyte sprno);
hide a sprite

FUNCTION:
offspr() prepares a sprite to be switched off. offspr() does
not really switch off the sprite. To effectively hide the
sprite you must first call this routine and then refreshspr().

INPUTS:
sprno: number of sprite to prepare to be switched off. The
       corresponding sprite slot in the sprite display list
       must be occupied.

RESULT:
none

BUGS:
none known

SEE ALSO:
refreshspr()


void movespr(ubyte sprno,word sprxpos,word sprypos);
move a sprite

FUNCTION:
Pass in (sprxpos,sprypos) the position (to be more exact the
coordinates for the top left edge of the sprite) where the
sprite should be moved to and the desired sprite movement will
be prepared. Actually movespr() doesn't really move the
sprite. To move the sprite call refreshspr() after calling
movespr().
Note: movespr() can move sprites which are in OFF state.

INPUTS:
sprno: number of sprite to be prepared to move. The
       corresponding sprite slot must be occupied in the
       sprite display list.
sprxpos,sprypos: coordinates where the sprite (the top left
		 edge of the sprite) should be moved to. Note
		 that sprites are clipped by the drawregion
		 settings as well as all other draw commands.

RESULT:
none

BUGS:
none known

SEE ALSO:
refreshspr()


void animspr(ubyte sprno,ubyte spranimno);
animate a sprite

FUNCTION:
To prepare a sprite animation pass the sprite number of the
sprite that should be animated in sprno. Pass the sprite
animation sequence number to display in spranimno. Calling
animspr() does only store the sprite animation command in the
sprite command queue and has therefore no visible effect until
refreshspr() is called.
Note: animspr() can animate sprites which are in OFF state.

INPUTS:
sprno: number of sprite to be prepared to animate. The
       corresponding sprite slot must be occupied in the
       sprite display list.
spranimno: sprite animation sequence number to display. The
	   sprite animation sequence number may range from 0-
	   (number of max. defined sprite animation sequence).

RESULT:
none

BUGS:
none known

SEE ALSO:
refreshspr()


void refreshspr(void);
execute sprite commands stored in the sprite command queue

FUNCTION:
This procedure is the heart of the sprite system. It executes
the sprite functions prepared by onspr(), offspr(), movespr()
and animspr(). The tgdlp4xx sprite machine doesn't require you
to use pre-defined sprite animation or movement sequences. And
yet this sprite system can be very effective if it is used
correctly: 
refreshspr() can globally optimize your sprite commands. So
you shouldn't call refreshspr() after every sprite operation,
but first prepare all sprite actions and then call refreshspr()
only once.
Example:
You want to move sprite 0 to (150,200). After the movement
sprite animation sequence 2 of sprite 0 should be displayed.
Additionally you want to move sprite 1 to (3,7) and switch
on sprite 2.
Here's how you SHOULDN'T do it:
movespr(0,150,200); refreshspr();
animspr(0,2); refreshspr();
movespr(1,3,7); refreshspr();
onspr(2); refreshspr();

And here's how the procedures are called correctly:
movespr(0,150,200);
animspr(0,2);
movespr(1,3,7);
onspr(2);
refreshspr();

Remember: FIRST do all sprite operations, THEN call
refreshspr().

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
onspr(), offspr(), movespr(), animspr()


udword ucollspr(ubyte sprno);
sprite collision detection

FUNCTION:
Use this routine to detect sprite collisions between two or
more sprites. ucollspr() checks the user defined sprite
collision rectangle of the passed sprite for overlapping
against all other (active) sprite user collision rectangles.
Refer to tgdsupp.txt: newsprite() for a description of the
creation of user defined sprite collision rectangles.

The procedure returns a bitfield, where the bitnumbers of
the passed sprite's overlapping sprite(s) are set. If no
sprite overlaps the passed sprite only the bit for the passed
sprite is set (the passed sprite overlaps itself, of course).
If no bit is set it was not possible to compute overlapping
sprites. This is the case when the asked sprite is switched
off or if it is out of the drawregion.

INPUTS:
sprno: Number of sprite of which the user defined collision
       rectangle should be tested for overlapping against all
       other user defined collision rectangles of all other
       active (ON) sprites. The corresponding sprite slot must
       be occupied in the sprite display list.

RESULT:
udword collfield: bitfield where the bits of the asked sprite
		  colliding sprites are set.
		  0 if an error has occured.

BUGS:
none known

SEE ALSO:
tgdsupp.txt: newsprite()


byte areaoffspr(uword xpos,uword ypos,uword xsize,uword ysize);
switch off sprites in a certain area

FUNCTION:
Sometimes it is usefull to be able to switch off all sprites
in a certain screen area to have the possibility to modify the
sprite background. Think of a pacman eating its pills. To
erase the pill pacman has just eaten you call areaoffspr()
with the coordinates and the size of the pill. All sprites in
this area will be switched off. You modify the background
(= you erase the pill) and switch on the sprites again using
areaonspr(). Areaonspr() notifies the sprites hidden by this
routine of the fact that their background has changed and they
will automatically update their sprite background buffers so
if you move or switch off the sprite(s) next time the correct
(=new) background will be restored.

areaoffspr() can be called sequentially multiple times to
switch off sprites in multiple areas.

After calling areaoffspr() the sprite system is in background
refresh mode and refreshspr() has no effect.

INPUTS:
xpos,ypos: coordinates of the upper left edge of the area
	   within the drawregion where sprites should be
	   switched off.
xsize,ysize: (x-1,y-1) size of the area. A (xsize,ysize)
	     value of (0,0) means the area has a size of 1
	     pixel.

RESULT:
byte success: TRUE if the function was successfully completed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
areaonspr()


void areaonspr(void);
clear sprite machine background refresh mode

FUNCTION:
areaonspr() is used together with areaoffspr(). If all
background updates in all by areaoffspr() marked areas are
done call this procedure once to put the tgdlp4xx sprite
system back in normal operation mode and send a message to
the sprites that were switched off by areaoffspr() that their
background has changed in order to make them save the new
background to their background buffers. This procedure will
then redisplay the sprites as they were displayed before
calling areaoffspr().

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
areaoffspr()


PART VI: TEXT FUNCTIONS
---------------------------------------------------------------

void txtcrsr(word x_pos,word y_pos);
set text cursor and text cursor home position

FUNCTION:
Sets the text cursor to (x_pos,y_pos). The next character
printed to the virtual screen with prttext() will appear at
this position. Also, the cursor home position is set. If
prttext() detects 0x0c in a string the text cursor position
will be resetted to the coordinate pair that was passed last
to this routine.

INPUTS:
x_pos,y_pos: new current position of the text cursor as well
	     as new home position of the text cursor.

RESULT:
none

BUGS:
none known

SEE ALSO:
prttext()


void prttext(const char far *text);
print a string

FUNCTION:
prttext() prints a string at the current text cursor position
to the virtual screen using the font selected with font(). If
no font was previously selected it uses the tgdlp4xx system
font.
prttext() doesn't print the special characters 0x00-0x0f.
However it recognizes some of the special characters as
control codes:
0x00: end of string
0x0a: line feed
0x0c: cursor home
0x0d: carriage return
all other special characters will be ignored.
If this procedure encounters characters that are not defined
in the font a whitespace (= blank, transparent character of
the size of a space) will be printed instead. This routine
changes the position of the text cursor, of course.

prttext() uses bltbitmap() to blit characters into VRAM.
Therefore the previously selected blitmode, blitpens and
drawmode will be active with prttext().

INPUTS:
*text: pointer to a string that should be printed to the
       virtual screen.

RESULT:
none

BUGS:
No character in the selected font may exceed the size of
255x255 pixels. The (x,y)-spacing doesn't count to the char
size.

SEE ALSO:
font(), txtcrsr(), bltmode(), bltpen(), drawmode()


udword txtwidth(const char far *text);
calculate width of a string in pixels

FUNCTION:
This procedure calculates the x-size of a string in pixels
using the font metrics of the current font. This means a
string can be - for example - centered by this formula
(assuming 320x200 resolution):
txtcrsr((320-(uword)txtwidth(string))>>1,y_pos);
Since txtwidth() uses the current font metrics to calculate
the string width the described text centering function will
work fine for all fonts - independent of their size.

Note: if a special character (0x00-0x0f) appears inside the
string to evaluate the string length calculation will be
stopped. For txtwidth() the special characters 0x00-0x0f have
always the x-size 0.

INPUTS:
*text: pointer to a string of which the width should be
       computed.

RESULT:
udword textwidth: width of string in pixels (assuming the
		  currently selected font is being used to
		  print the string).

BUGS:
none known

SEE ALSO:
font(), prttext()


fontmap far *font(fontmap far *newfont);
set font to use with prttext()

FUNCTION:
The font being used to print text with the prttext() routine
can be changed by this procedure. Simply pass a pointer to the
fontmap structure of the font that shall be used as the
parameter to activate the new font.

If the tgdlp4xx system font shall be used pass 0 as the
argument. The ASCII character set defined in the tgdlp4xx
system font ranges from 32 (' ') - 126 ('~'). The tgdlp4xx
system font is fixed width, character size: 8x8.

Currently the size of a single character inside a font is
limited to 255x255 pixels even if the x- and y-sizes of a
character are defined as uwords in the fontmap structure.

INPUTS:
*newfont: pointer to a fontmap structure. The fontmap structure
	  looks like this:
	  struct { ubyte fonttype;
		   ubyte startchr,stopchr;
		   ubyte pad;		/* for word alignment */
		   uword chrxsize,chrysize;
		   word spacingx,spacingy;
		   bitmap fontbitmap;
		 } fontmap;
	  *newfont must be 0 if the tgdlp4xx system font shall
	  be set.

RESULT:
fontmap *oldfont: pointer to the fontmap previously used for
		  prttext().

BUGS:
The size (to be more precise: chrxsize, chrysize) of a single
character in a font may not exceed 255x255 pixels.

SEE ALSO:
prttext()


PART VII: COLORS
---------------------------------------------------------------

void pen(ubyte pen,ubyte color);
select the draw pens

FUNCTION:
Selects a color for foreground or background draw pen.

Set pen to PEN_B if the color for the background draw pen
should be changed. The color of the background draw pen is
used to clear the drawregion with clearreg(). It may range
from 0-255.

Set pen to PEN_F if the color for the foreground draw pen
should be changed. The color of the foreground draw pen is
used for all drawing operations such as writepixel(),
line(), rectangle()... It may range from 0-255.

INPUTS:
pen: draw pen to change. Allowed values are: PEN_B, PEN_F.
color: new color for draw pen. color may range from 0-255.

RESULT:
none

BUGS:
none known

SEE ALSO:
clearreg(), writepixel(), line(), arc(), polygrid(),
rectangle(), ellipse(), metagon(), drawpoly(), redrawpoly()


void ovscol(ubyte color);
select a border color

FUNCTION:
A color from 0 - 255 to fill the border of the physical
screen can be selected using this procedure. If output to
the physical screen is switched off the entire display will
be filled with the color chosen here.

INPUTS:
color: color for display border. Color may range from 0..255.

RESULT:
none

BUGS:
none known

SEE ALSO:
scrnon()


void rgb6(ubyte col_register,ubyte tab_len,ubyte far *col_table);
set RedGreenBlue intensities of specified color(s)

FUNCTION:
With this procedure it is possible to change RGB values of
colors. col_register represents the number of the starting
color which shall be changed (0..255).
tab_len represents the (number of colors-1) that should be
changed (0..255).
col_table is a pointer to an array of ubytes containing the
RGB color component values. The RGB component values inside
the array may range from 0 - 63. Do a waittof() before calling
this procedure to prevent 'snow' on the physical screen while
the RGB values are being updated.

INPUTS:
col_register: number of color to start with changing RGB
	      values (0..255).
tab_len: (number of colors-1) that should be changed (0..255)
*col_table: pointer to an array of RGB values for the colors
	    The array looks like this:
            ubyte rgbarray[]={
			/* RGB for 1st color to change */
			red,
			green,
			blue,
			/* RGB for 2nd color to change */
			red,
			green,
			blue,
			...
			     };
	    each color component value inside the array may
	    range from 0-63.

RESULT:
none

BUGS:
none known

SEE ALSO:
pen(), ovscol(), waittof()


PART IIX: CLIPPING
---------------------------------------------------------------

byte drawreg(uword x_pos,uword y_pos,uword x_size,uword y_size);
set rectangle in which graphics output is allowed

FUNCTION:
A rectangle (the 'drawregion') inside the virtual screen can
be defined by this procedure. All subsequent graphics
operations can only be performed within this rectangle except
read operations which can be executed at any position within
the virtual screen. By default the drawregion covers the
entire virtual screen and cannot be made any larger. This
means that the system memory cannot be corrupted by passing
incorrect coordinates to graphics output operations.

INPUTS:
x_pos,y_pos: upper left edge of the rectangle within the
	     virtual screen.
x_size,y_size: x,y size of the rectangle. (0,0) means a size
	       of 1x1 pixels.
x_pos+x_size may range from 0 to (x-res. of virt. screen - 1).
y_pos+y_size may range from 0 to (y-res. of virt. screen - 1).

RESULT:
byte success: TRUE if function was successfully executed,
	      FALSE if not.

BUGS:
none known

SEE ALSO:
vramcopy()


PART IX: DOUBLE BUFFERING
---------------------------------------------------------------

void drawpage(ubyte page);
select a drawpage

FUNCTION:
In viewmode VM_320x200, VM_320x400, VM_256x256 and VM_256x512
the VRAM is organized in a special way: in independent but
identical 'pages' which are called drawpages. There are two
independent drawpages in each of the mentioned viewmodes
available with the page numbers: 0, 1.
The pages are identical in that way that they all have the
same coordinate system: virtual (x,y) coordinates range from
(0,0) to (319,399) [VM_320x???] or (0,0) to (255,511)
[VM_256x???].

You can direct graphics output to a drawpage by passing the
page number (0, 1) to drawpage(). All following graphics
manipulation will be applied to the selected drawpage.

drawpage() is used in conjunction with viewpage() to put an
efficient double buffer method to your disposal.

INPUTS:
page: number of page to be selected for graphics output.
      The following page numbers are possible:
      in VM_320x200, VM_320x400, VM_256x256 and VM_256x512
      viewmode: 0, 1.

RESULT:
none

BUGS:
none known

SEE ALSO:
viewmode(), viewpage()


void viewpage(ubyte page);
select a viewpage

FUNCTION:
In viewmode VM_320x200, VM_320x400, VM_256x256 and VM_256x512
a drawpage can be displayed by passing its page number to this
procedure.
In viewmode VM_320x200 always the lower part of the drawpage
(coordinates: [0,200]-[319,399]) will be displayed by
viewpage(). The not displayable upper part is usually used as
a sprite and/or pattern double buffer.
The same facts apply to the VM_256x256 viewmode. The lower
part of the drawpage in this mode has the coordinates:
(0,256)-(255,511).

Unlike conventional double buffering methods changing the
visible drawpage (the 'viewpage') virtually takes no time
since all drawpages are already stored in VRAM and don't have
to be copied from conventional memory.

Note: the viewpage can only be changed while the vertical
retrace is active. If this routine is called before that
event the effect of this procedure will be delayed until the
vertical retrace becomes active.

INPUTS:
page: number of page to be selected for display.
      The following page numbers are possible:
      in VM_320x200, VM_320x400, VM_256x256 and VM_256x512
      viewmode: 0, 1.

RESULT:
none

BUGS:
none known

SEE ALSO:
viewmode(), drawpage(), waittof()


PART X: MISC
---------------------------------------------------------------

void waittof(void);
wait for the end of a vertical retrace

FUNCTION:
Used to synchronize graphics operations with the physical
output device. When waittof() returns, the state of the VGA
card as well as the VRAM can be manipulated without the user
taking notice of this.
However only small manipulations which do not need a long time
to execute can be performed if the operations should be hidden
from being noticed by the user.
ATTENTION: When using functions of the vrclk library this
routine may not be used - otherwise a system deadlock will
occur.

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
viewpage(), viewreg(), splitscrn(), rgb6()


sincostab far *tgdsincos(word angle);
calculate the sine and cosine for a specified angle

FUNCTION:
This procedure returns a pointer to a structure in which the
sine and cosine of the requested angle are stored. The angle
parameter is expected to be in new degrees*10 (x); the sine
and cosine values inside the structure range from -32767 to
32767. To obtain the 'real' sin/cos results of the specified
angle divide the sin/cos values in the structure by 32767.

This routine can be used to calculate rotation matrices very
efficiently. No math coprocessor is required to execute this
function.

(x) a new degree circle runs from 0-400 degrees.

INPUTS:
angle: angle (in new degrees*10) of which the sin and cos
       values are requested.

RESULT:
sincostab *sincosptr: pointer to a table containing the sin/
		      cos values of the specified angle
		      multiplied by 32767. The table looks
		      like this:
		      struct { word sin; word cos; } sincostab;

BUGS:
none known

SEE ALSO:



SHAREWARE LIMITATIONS:
----------------------

The maximum number of sprites that can be used in this
shareware version (tgdlp4sc.obj) of the Tale Graphics Driver
is limited to 8. They carry the sprite numbers 0-7.

Besides of this the shareware version is identical to the
complete versions of the graphics driver.

