


			The WordUp Graphics Toolkit
				Version 4.0

			     Programmer's Guide


		   Copyright 1994 Barry and Chris Egerter

		WordUp Graphics Toolkit: Programmer's Guide	       Page 2

			     TABLE OF CONTENTS

1.0 WHAT IS WGT?.........................................................4

2.0 INITIALIZING AND RESTORING THE VIDEO MODE............................5

3.0 INTRODUCTION TO THE VGA HARDWARE.....................................6

4.0 COLOR................................................................7
  4.1 IMAGE REMAPPING....................................................7

5.0 VIDEO PAGES..........................................................8

6.0 GRAPHICS PRIMITIVES..................................................9

7.0 DISPLAYING TEXT.....................................................10
  7.1 CUSTOM FONTS......................................................10

8.0 IMAGES IN WGT.......................................................12
  8.1 WHAT IS A BLOCK?..................................................12
  8.2 BLOCK COPY MODES..................................................13

9.0 GRAPHIC FILES.......................................................14

10.0 USING EMS MEMORY...................................................15

11.0 INPUT DEVICES......................................................18
  11.1 WGT KEYBOARD HANDLER.............................................18
  11.2 KEYBOARD LOCKOUT.................................................18
  11.3 MOUSE ROUTINES...................................................19
  11.4 JOYSTICK.........................................................19

12.0 SPRITE LIBRARY.....................................................20
  12.1 WHAT IS A SPRITE?................................................20
  12.2 THE SPRITE LIBRARY...............................................20

		WordUp Graphics Toolkit: Programmer's Guide	       Page 3

13.0 MULTIDIRECTIONAL SCROLLING.........................................22
  13.1 TILING...........................................................22
  13.2 TILE TYPES.......................................................22
  13.3 COORDINATE SYSTEMS...............................................23
  13.4 SCROLLING WINDOWS................................................24
  13.5 SCROLLSPRITES....................................................24
  13.6 GLOBAL VARIABLES IN THE SCROLLING LIBRARY........................25
  13.7 SAVING MAP FILES.................................................26
  13.8 USING EMS IN THE SCROLLING LIBRARY...............................26
  13.8 OPTIMIZING SOVERLAP..............................................27

14.0 PROGRAM TIMING.....................................................30

15.0 THE WGT MENU LIBRARY...............................................31

16.0 USING THE WGT FILE SELECTOR........................................33

17.0 WGTLIB: DATA FILE LIBRARIES........................................35

18.0 FLI/FLC ANIMATION LIBRARY..........................................37

19.0 SOUNDBLASTER LIBRARY...............................................38


		WordUp Graphics Toolkit: Programmer's Guide	       Page 4

1.0 What is WGT?
----------------

The WordUp Graphics Toolkit is a library of routines that are callable
from C language under the MS-DOS operating system.  The library was compiled
under Turbo C++ v1.0, therefore a compatible compiler is needed to use this
library.  Any version of Borland's Turbo C++ or Borland C++ (except v4.0) is
compatible with WGT.  Currently, the library is available for the large 
memory model only.

WGT contains over 200 routines for graphics, input devices, sound effects,
and EMS memory management.  While other graphics libraries provide you with
the most basic graphics commands, WGT offers many complex routines, 
including a sprite system, tiled background scrolling, a fully operational
file selector, and animation player.  This means you can spend more time
on programming your application and less time working on the low level
routines required.

The WordUp Graphics Toolkit gives you more than just a library for linking
routines.  The WGT Sprite Editor and WGT Map Maker are two utilities 
which are an integral part of the development process.

The WGT Sprite Editor is a fully featured paint program for managing
sprites, fonts, mouse cursors, and background screens.  It uses a 
graphic user interface and a mouse, allowing you to design images quickly
and effortlessly.  It is the most essential tool in creating graphics 
applications, yet other graphics libraries fail to provide a utility such
as this.

The WGT Map Maker is needed to create background maps for use with the
tiled background scrolling library.  It uses a windowing environment to 
keep your tiles, sprites, and maps organized.  It also includes a 
SVGA viewing mode, tile templates, sprite placement, and even generates 
source code for your particular maps.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 5

2.0 Initializing and Restoring the Video Mode
---------------------------------------------

WGT operates in a single video mode (with the exception of the SVGA library)
called mode 13h.  This mode has screen dimensions of 320x200 pixels, and
has 256 colors on the screen at once.  Only one video page is available in
this mode, however WGT emulates page flipping through the use of virtual
screens.

The vga256 command is used to initialize the WGT library and enter this 
graphics mode.  You will probably want to restore the original video mode
after your program ends, and WGT provides two routines to do this called
wgetmode and wsetmode.

vga256   - Initializes WGT and sets the video mode to 320x200x256
wgetmode - Returns the current video mode
wsetmode - Sets the video mode

Here is a simple program to save the video mode, enter WGT's video mode, and
restore the original mode:

#include <wgt4.h>

int oldmode;

void main (void)
{
 oldmode = wgetmode ();
 vga256 ();
 wsetmode (oldmode);
}

		WordUp Graphics Toolkit: Programmer's Guide	       Page 6

3.0 Introduction to the VGA Hardware
------------------------------------

Before any attempts can be made to write a graphics program or an arcade
game, the programmer should be familiar with the hardware for which he/she 
is developing software.  In the case of the graphics programmer, the video
system is the primary hardware to be concerned with.  The VGA (Video Graphics
Array) is a standard in the world of PC-compatibles (switching rapidly to
Super-VGA).  An attractive feature of this type of video system is the 
ability to display 256 colors at a time (rather than the 16 or fewer which 
were possible on CGA and EGA systems of earlier times).  The arcade-game 
industry quickly adopted one particular graphics mode as the new standard. 
This mode has a horizontal resolution of 320 pixels, a vertical resolution 
of 200 pixels, and a set of 256 colors to use for drawing.  This is mode 
13h (hex) when indexed by a programmer.

With 320*200 pixels representing a full screen, this means that at any
given time, the monitor is updating 64000 pixels.  It does this at about 70hz
(70 cycles a second). Each pixel can be one of 256 colors.  Eight bits of
information are required to achieve 256 unique numbers, so each pixel uses
one byte of memory.  That's a total of 64000 bytes for one screen of data.

A very handy feature of the IBM's video system is that the video RAM is
"mapped" into the addressable memory space.  At segment A000 (the 10th 
segment) the VGA maps in 64k of video RAM.  Using the refresh rate of the 
monitor (70Hz) this section of memory is scanned and drawn several times a 
second.  In order to change what you see on the screen, simply change a few 
bytes in this 64k block of memory, and the VGA hardware will detect the
change and update the screen for you.  Using 16-bit words, the segment starts 
at A000, and the offset begins at 0000.  By manipulating the offset alone you
have access to the full range of pixels on a 320*200*256 screen.  Data is 
stored sequentially, a row at a time.  A suitable formula for addressing 
one individual pixel is:

offset of (x,y) =  (y*320) + x

where the x and y values range from 0-319 and 0-199 respectively.  A position
of (0,0) indicates the top-left screen corner, and (319,199) indicates the
lower-right corner.

Upon calling the vga256 command, a pointer to the visual page at A000:0000 
is created,  called abuf.  This pointer will always point to the location
of the page we are writing to.  You may use the formula above to access
pixels within the video page.  For example:
     abuf[y*320 + x]
would access the pixel at (x,y) on the current video page.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 7

4.0 Color
---------

The reason for the popularity of this video mode is the wide range of
colors which may be represented.  From a total of 262,144 colors, 256 may be
displayed at the same time. Each color is made up of 3 primary colors (red,
green, and blue) in varying levels of brightness.  The programmer may select
each of the 256 color indices and set the RGB levels (red/green/blue) to
reflect the color which is to be represented.  The VGA card uses 6 bits to
determine RGB levels.  This gives 64 levels for each primary color, and a
total of 64*64*64 (262,144) possible outcomes.  A level of 0 indicates no 
color, a level of 63 is full brightness.

For example, an RGB value of (0,0,0) results in BLACK (no red, no green,
and no blue).  Increasing each level by one would produce shades of gray
until we reach (63,63,63) which is WHITE.  A value of (63,0,0) is pure red, 
a value of (0,63,0) is pure green, etc.


This range of possibilities may seem to be more than enough for most 
needs, but you must remember that you only have the ability to display 256
colors at any given time.  Careful planning must be made to ensure that all
images may be accurately displayed when onscreen.  If you attempt to show
two pictures with two different palettes (sets of colors), you will have to
show them one at a time to be able to use the right colors.  Some computer
artists will design a palette which has enough unique colors to draw any
image reasonably close to the desired result, but some quality must be
sacrificed.  WGT supplies routines to set palettes, load and save palettes,
cycle through ranges of colors, fade palettes in and out (to black, or
between each other), and redraw images using a palette which is different
than the original.  This last feature is known as remapping an image.

4.1 Image Remapping
-------------------

Let's assume you are displaying a rainbow in one region of the screen,
and would like to show a grayscale image of a person's face on another 
region.  The problem is, the palette you are using to show the rainbow 
doesn't match the one used to draw the face.  WGT can analyze the two 
palettes and find colors in the rainbow which are reasonably close to 
(or exactly the same as) the one used for the face.  It will then change 
the image of the face so that it uses the colors in the rainbow palette 
which suit it best. The end result of this operation is the ability to 
show both the colorful rainbow and the grayscale face at the same time, 
using the same set of 256 colors.  

		WordUp Graphics Toolkit: Programmer's Guide	       Page 8

5.0 Video Pages
---------------

The simplicity of the video system in this mode has provided a lot of
software authors with the ability to write their own video routines.  We have
done this for you, and have specialized in this graphics mode alone to 
provide the absolute fastest, most-powerful and flexible set of routines 
available.  Since only 64k of the VGA card (256k standard) is accessible in 
mode 13h, a technique known as page flipping is not possible (unless the VGA 
is "tweaked", which we will not discuss here).  Page flipping involves the 
creation of an image on a hidden screen, which is shown immediately upon 
completion of the image.  By drawing on the other screen again and then 
flipping back,  smooth animation may be achieved as far as the eye is 
concerned.  Mode 13h always displays the same 64k of video RAM, so we do not 
have the ability to page flip.  WGT solves this problem by allowing us to 
use conventional memory as if it were video RAM.  By allocating 64k blocks 
of memory and telling WGT to write to them instead, we can "draw" on a 
hidden page. The problem occurs when we want to see what has been drawn. 
To do this, we must physically copy the memory into the 64k video buffer.

WGT contains routines which will allow you to specify the region to copy,
and which screens to use as source and destination.  By copying as little
information as necessary to update the visual screen, enough speed may be
obtained to simulate page flipping.  The faster video cards (16-bit) and CPUs
also help avoid flicker due to slow memory copies.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 9

6.0 Graphics Primitives
-----------------------

Every graphics library contains a set of routines to perform the most
basic drawing operations available.  WGT has an extensive collection of
graphics primitives to make life easy for the programmer.  These range from
plotting pixels to drawing texture mapped polygons.  Each primitive is drawn
using a color index which has been previously set.  The following is a list
of the fundamental graphics operations which WGT provides for you:

wbar                 -          Draws a solid rectangle
wbezier              -          Calculates the points on a curve
wbutt                -          Draws a 3D button
wcircle              -          Draws a circle using center and radius
wclip                -          Sets the clipping area
wcls                 -          Clears the entire video page with a color
wdraw_scanpoly       -          Draws a scan-converted concave polygon
wellipse             -          Draws a hollow ellipse with center and radii
wfastputpixel        -          Puts a single pixel on screen - no clipping
wfill_circle         -          Draws a filled circle with center and radius
wfill_ellipse        -          Draws a filled ellipse with center and radii
wfline               -          Draws a fast line with no clipping
wfree_scanpoly       -          Frees memory from a scan-converted polygon
wgetpixel            -          Returns color of a pixel at a point
wgouraudpoly         -          Draws a gouraud-shaded polygon
whline               -          Draws a horizontal line
whollowpoly          -          Draws a hollow polygon
wline                -          Draws a line
wputpixel            -          Sets the color of a pixel at a point
wrectangle           -          Draws a hollow rectangle
wregionfill          -          Fills a region with the current color
wscan_convertpoly    -          Creates a scan-converted polygon in memory
wsetcolor            -          Set color index to use for primitives
wsolidpoly           -          Draws a filled polygon
wstyleline           -          Draws a line using a pattern
wtexturedpoly        -          Draws a texture-mapped polygon
wxorbox              -          Draws a filled box using XOR mode

		WordUp Graphics Toolkit: Programmer's Guide	       Page 10

7.0 Displaying Text
-------------------

WGT provides a set of routines to produce text input/output on the 
graphics screen.  These routines often take fonts (style of characters) as
parameters.  In such a low resolution video mode, text often looks quite
"chunky", and detail may not be achieved.  Nevertheless, a creative font
can produce the desired effect if applied correctly.  The font files used
in WGT are created using the Sprite Editor (a separate utility available
from WSP).  If no fonts are loaded, a default font is used.  The following
are the available font routines for WGT v4.0:

wflashcursor      -    flashes the simulated text cursor once
wfreefont         -    frees memory from a previously loaded font
wgettextheight    -    returns the height of the tallest letter in a string
wgettextwidth     -    returns the width of the entire string
wgtprintf         -    same functionality as printf for text modes
wloadfont         -    allocates memory and loads custom font
wouttextxy        -    displays a string at screen coordinates
wsetcursor        -    sets the height of the text cursor
wstring           -    inputs a string using the default font
wtextbackground   -    sets the background text color
wtextcolor        -    sets the foreground text color
wtextgrid         -    turns the text grid on or off
wtexttransparent  -    turns the text foreground or background on or off


7.1 Custom Fonts
----------------
WGT enables you to create your own fonts with the Sprite Editor.
Only the first 128 characters of the ASCII set are used.  Each character 
can be any size and the characters will be proportionally spaced when 
displayed on the screen.  

The system font has been saved in a sprite file called "system.spr". 
When you want to create a new font, copy "system.spr" to a new name, and
modify the new file.  The file has all characters in normal text, so
you know which sprites represent each character. 

If you don't plan on using certain characters in your program, simply leave 
them as they are.  After you have created your font, you can convert it
into WGT's font file format from within the Sprite Editor.
You can then load the font in your program using the wloadfont command.

To use the new font, declare a font variable such as:
	wgtfont sans_serif;

Then load it in using wloadfont:
        sans_serif = wloadfont ("newfont.fnt");

		WordUp Graphics Toolkit: Programmer's Guide	       Page 11

To display text using the new font, pass the font to the wouttextxy 
or wgtprintf command:
	wgtprintf (10, 10, sans_serif, "This is the new font");

After you are finished using the custom font, release it from memory
with the wfreefont command:
        wfreefont (sans_serif);

The fonts used with the commands described above are single color fonts
only.  Their color is set with the wtextcolor command.  To create a
font with more than one color, store your letters in a sprite file in
a similar manner.  Instead of using the text commands in WGT, you could
use the wputblock command to show each letter individually.

The code below is an example of this technique:

void displaystring (char *string, int x, int y, int mode)
{
 int len;
 int i;
 int ch;

 len = strlen (string);

 for (i = 0; i < len; i++)
  {
   ch = string[i];
   wputblock(x,y, sprites[ch], mode);
   x+=wgetblockwidth(sprites[ch]);
  }
}

		WordUp Graphics Toolkit: Programmer's Guide	       Page 12

8.0 Images in WGT
-----------------

The most commonly used features of WGT are the bitmap functions. These
functions manipulate rectangular regions of image data to perform various
effects. Bitmaps in WGT are referred to as BLOCKS.

8.1 What is a BLOCK?
--------------------

A block is a sequential chunk of data loaded from the 64k of video ram.
It is merely a series of numbers ranging from 0-255 indicating the color of
the pixels at each point. If, for example, you have a circle drawn on the
screen, and you wish to preserve a copy of the image in memory, you can call
a routine which grabs the image from the screen and stores a copy in a 
pointer. The pointer is given a name (by you, the programmer) to be used to
reference that image at a later time. The pointer points to the image data
and the block header which is as follows:

    16 bits (1 word)       -     width of image in pixels
    16 bits (1 word)       -     height of image in pixels
    width*height bytes     -     image data, row by row

This format is not required knowledge for most users, but is handy to know
for those who want to create their own bitmap-manipulation routines.

To show the simplicity of the bitmap system, here is a short WGT example
which will draw a circle on the screen and save a copy in a block. The block
will then be used to create a duplicate of the image in the upper-left corner
of the screen.


#include <wgt4.h>

block my_image;

void main (void)
{
  int oldmode;

  oldmode = wgetmode ();         /* preserve initial video mode */
  vga256 ();                     /* initialize WGT system and graphics mode */

  wsetcolor (15);                /* draw with the 16th color entry */
  wbox (100, 100, 115, 130);     /* draw a box from (100,100) to (115,130) */

  my_image = wnewblock (100, 100, 115, 130);/* Grab the image from the screen
                                               and store it in a block */

  wputblock (10, 10, my_image, NORMAL);     /* Paste a copy of the block on
                                               the screen at (10,10) */

  wfreeblock (my_image);                    /* free memory used by block */
  wsetmode (oldmode);                       /* restore old video mode */
}

		WordUp Graphics Toolkit: Programmer's Guide	       Page 13

8.2 Block Copy Modes
--------------------

There are two ways to display a block. The fastest way is to select the
NORMAL technique (see programming example for 3.1). This technique simply
copies out the rectangular region saved in the pointer exactly the way it
is stored. Quite often, however, programmer's do not desire a perfectly
rectangular image, and would prefer to display images with some colors
treated as transparent. WGT allows you to select XRAY mode to indicate that
some parts of the image are not to be displayed. In WGT, any pixel which is
color index 0 will be treated as transparent in this mode. If you were to
display an image of a human figure, and all parts of the rectangular region
which aren't included as the figure are drawn using index 0, they will be
skipped when drawing the image. This technique is slower because WGT must
check each pixel before drawing it, but it provides a very essential mode
for displaying images (primarily used for sprites).

		WordUp Graphics Toolkit: Programmer's Guide	       Page 14

9.0 Graphic Files
-----------------

WGT offers support for several different graphics file formats.  WGT can
load and save PCX, CEL, BMP, BLK, and PAK file formats.  The last two are 
custom formats only used by WGT.  

BLK files are the simplest format, and store the image in an uncompressed 
form.  

PAK files use a run-length encoding compression scheme similar to the PCX 
format.  

CEL files must be in Autodesk Animator 1.0 format.  The image must be no 
greater than 320x200x256.  A palette is also stored in the file.

PCX files are created with many shareware and commercial drawing programs.
The image must be no greater than 320x200x256.  A palette is also stored in 
the file.

BMP files are commonly used in Microsoft Windows, for wallpaper and icons.
Any resolution is supported, and WGT will convert the image into 256 color
mode when loading.  A palette is also stored in the file.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 15

10.0 Using EMS memory
---------------------
Expanded memory, or EMS for short, is extra memory that the processor
cannot directly write to.  This memory is accessed by using a technique 
called "bank switching".   This technique involves splitting the large area
of EMS memory into smaller 16k "pages" which are easier to manage.  A 
"page frame" is a segment of memory that can contain 4 pages at once, and
resides in the conventional memory area.  The page frame is divided into
4 physical page sections, which can contain one of the logical pages
in EMS memory.   When we write to the page frame, we are writing to an
image of the memory in EMS.   If you want to write to a different area in
EMS memory, you simply change which pages are in the page frame.  This is
called "mapping pages".  

Since all of WGT's block routines operate within a single segment 
of memory (64k), it is easier to map 4 pages into the page frame at once.
You then have a full 64k to store a picture, instead of splitting a 
picture into smaller chunks.  Therefore, all of WGT's EMS routines use
the memory in 4 page bundles.

To detect if a computer has an EMS driver in memory, we use the
wems_present command.  This will return 1 if a driver is present, and 0
if no driver resides in memory.   If there is EMS present, you should then
initialize the EMS driver by using the wems_init command.  It will return 
0 on failure, and 1 on success.  Your program must have a minimum amount
of memory in order to run.  You can make sure the computer has enough
EMS memory installed by calling the wems_open command.  You must specify
how many 16k pages your program will require.  Remember that WGT uses 
4 page bundles, so this number must be a multiple of 4.  If the memory
could not be allocated, it will return 0.  The program should be stopped
immediately if there is not enough memory to run.  For example, if your
program requires 512k of EMS memory to run, you would use 32 pages, since
512k / 16k = 32.

Now we will discuss the commands which map pages into the page frame.
The wems_map command will map a logical EMS page into one of the four
physical pages in the page frame.  This command only used if you are writing
your own EMS memory management system.  WGT has a number of commands that
take care of swapping pages around for you.  The wems_getframe command
maps four pages into the page frame at once.  0 will map pages 0,1,2, and 3,
1 will map pages 4,5,6 and 7, etc.  This makes it easy to manage 64k blocks
that you can treat as virtual screens.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 16

WGT uses a special kind of pointer called EMS pointers to tell where
data is being stored.  Since pointers are made of 4 bytes, we can use them
to store information about the position in EMS memory.  The segment word
(first half) is used to store the EMS page.  The offset word (second half)
is used to store the offset of the block within the EMS page.  The page
refers to a 64k block, or 4 EMS pages.  The offset can therefore be from
0-65535.  WGT never uses an offset of 0, since your first EMS pointer would
be 0000:0000 which is a NULL pointer.  All block routines consider NULL
pointers as empty, and this will cause some errors. Here is an example 
EMS pointer:
                   0001:1234
              Page --^   ^---Offset

EMS pointer should NEVER be used as a conventional pointer since they will
be pointing to an invalid conventional memory location.
Before we get into the rest of the EMS functions, we should first mention
the global variables that are available and how they are used.     

wpageframe contains the segment of the page frame.  You can use this to
make a pointer to your data, along with the MK_FP command.  For example,
data=MK_FP(wpageframe,0x0000) will make a far pointer to the page frame.

emsptr is a pointer to the page frame, which is attained by the MK_FP
command mentioned above.

emshandle is a number assigned to the current chunk of EMS memory your 
program is using.  It is not needed for user applications.

emsoffset is an offset that increases when you place data into EMS memory.
If there isn't enough space left in the 64k bundle, the emspage variable is
increased, and the emsoffset variable is reset to 1.

emspage holds the last page number that hasn't been filled with data.  It 
is increased every time the emsoffset variable goes over the 64k limit.
NOTE: emspage refers to a 64k bundle, not a single 16k page.

emspage and emsoffset may be changed by the application.  If you reset
them to 0 and 1 respectively, you effectively destroy what was placed
in EMS memory previously since further operations will overwrite the 
memory.  You should also remember to make all EMS pointers to NULL if
you do this.

emscurpage tells which 64k bundle is currently mapped in the page frame.
Only the wems_getpage command should change this.


To store something into the EMS page frame manually, use the
wems_storeblock command.  It requires a source pointer, an offset into the
page frame, and the size of the source block.  This is not generally not
used by end applications.

If you want to store a block in EMS, use the wems_storesprite command.
It will automatically calculate the size of the data, and handle the
ems pages and offsets for you.   It will return an EMS pointer to the
block.  To change a block into an EMS pointer, you can assign the returned
value to the same pointer you gave it (because the routine will free the
conventional memory used after moving it to EMS).  For example,
mypic = wems_storesprite(mypic) will change the pointer mypic into a block
stored in EMS.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 17

       wems_storedata is almost the same as wems_storesprite, only it
requires you to know how large the data is.  This is used to store chunks of
data that are not graphical blocks.  This means you must also store the size
of the data somewhere so you can retrieve the correct amount later.

       wems_getsprite maps the given sprite from the sprite array into the
page frame, assuming you've stored you sprites in EMS previously.  It
returns a pointer to the block which was mapped into the page frame.

       wems_getdata operates similar to wems_getsprite only you only give an 
EMS pointer opposed to an index into the sprite array.

       wems_loadsprites is like the wloadsprites command only the sprites are
stored into EMS memory automatically.  This is the most useful EMS routine.

Finally, wems_close shuts down the EMS handler and makes the memory available
to other program.  It must be called before your program quits, or any EMS 
memory previously allocated will not be available until you reboot the 
machine.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 18

11.0 Input Devices
------------------

11.1 WGT Keyboard Handler
-------------------------
The Keyboard Handler installs a custom interrupt handler which intercepts
all keypresses.  This is used to enable multiple keypresses at once and
eliminates the problems with the keyboard buffer filling up, and the 
keyboard repeat rate.   A global array called kbdon contains 128 integers,
each representing the state of a single key on the keyboard.  The integer
contains either 0 or 1.  1 means the key is being pressed.  It will return
to 0 as soon as the key is released.

There are two commands which control the custom interrupt handler.
installkbd replaces the current keyboard interrupt with its own.
uninstallkbd restores the original handler.

When the handler is installed, normal commands that read the keyboard will
not function because keypresses are not placed in the keyboard buffer.
To determine if a key is pressed, you must look at the kbdon array.
Each element in the array corresponds with the scan code returned from
the keyboard when that key is pressed.  To find these scan codes, use
the "scancode.exe" program.  This program will display the scan code
of the key you are pressing.

In addition, a flag is increase every time a key is pressed.  This flag is
called keypressed.  To check if any key was pressed, set the flag to 0 and
wait until it increases.


11.2 Keyboard Lockout
---------------------
Some keyboards have a limit of how many keys can be pressed at once.
Each brand of keyboard is different in the way it behaves.  After a number
of keys are held down, the keyboard will report a value of 255 regardless 
of which keys are actually being pressed.  This is called a keyboard
lockout.  Lockouts occur when you hold down a number of keys in the
same area on the keyboard.  In general, you should find keys which do not 
interfere with each other.  If your program requires multiple keys to
be pressed at once, you should include a utility to alter which keys
should be hit, in order to resolve any keyboard lockouts.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 19

11.3 Mouse Routines
-------------------
The mouse routines support any Microsoft compatible mouse driver.  Before you
use any mouse routines, you must first install WGT's custom mouse interrupt.
This interrupt will be called whenever the mouse is moved or a button is
pressed.  It updates three global variables:

  mx  - X coordinate of mouse cursor
  my  - Y coordinate of mouse cursor
  but - mouse button state

Since these value may change at any time, it is wise to store their values
into some temporary variables.  If you do not store the value, your program
may act incorrectly as the coordinates of the mouse may change halfway
through a procedure which expected them to be constant.

The following is a list of the mouse commands in WGT:

mdeinit        - Removes the custom mouse interrupt
minit          - Installs the custom mouse interrupt and initializes mouse
moff           - Hides the mouse cursor
mon            - Shows the mouse cursor
mouseshape     - Change the shape and hotspot of the mouse
mread          - Reads the position and button state (now obsolete)
msetbounds     - Sets the boundaries of the mouse cursor
msetspeed      - Changes the mouse sensitivity
msetthreshhold - Changes the mouse doubling threshhold
noclick        - Loops until all mouse buttons are released


11.4 Joystick
-------------
The joystick routines allow up to two joysticks to be connected at once.
Before using the routines, the joystick must be calibrated.  This determines
the range of values the joystick will return.

wcalibratejoystick - Determines the joysticks range
wcheckjoystick     - Sees if the joystick is connected
winitjoystick      - Initializes the joystick 
wreadjoystick      - Reads values from the joystick

		WordUp Graphics Toolkit: Programmer's Guide	       Page 20

12.0 Sprite Library
-------------------

12.1 What is a SPRITE?
----------------------
Sprites should not be confused with blocks. A common question which pops
up frequently from many WGT users is, "Can I use a sprite pointer in a block
function?". The answer is yes! A sprite is simply a block, but used with a
special group of functions to produce animation. We shouldn't really change
the name of the image from block to sprite simply due to the context in which
we use it, but the term "sprite" has been an industry standard for many years.

    To produce animation, a series of blocks are displayed and moved on the
visual screen, much like the frames of a cartoon sequence. The artist draws
each block as an individual frame of the animation, and then plays them
back in a specific order to simulate some sort of action. WGT provides 
functions to describe this animation sequence, including the blocks used,
the timing between frames, and the movement of the object. To simplify
the naming of the sprites, an array of blocks is used to reference them. This
array is passed to the sprite functions, and the function uses the index to
access each member.

For example, if the user declares     block my_sprites[1000];   in their
program, they have created an array of pointers to the blocks which will be
used for animation. A single function will load the images from a sprite
file (designed with our Sprite Editor utility) and store them in the array.
Let's assume you want to simulate a human running. Each block in the sprite
file will contain one frame of the animation sequence. If 15 images are used,
they will all be stored in the same file. One call to wloadsprites will
load the image data in the indices 1-15 of the array. 


12.2 The Sprite Library
-----------------------
The sprite library allows you to edit sprites using the WGT Sprite Editor, 
load them in your program, and display them on the screen.  The best part 
about the sprites is you can set up movement and animation sequences and 
the library will handle everything for you. This library is used for 
animations over a static background (unchanging) only. You may NOT combine
this library with the WGT scrolling library.

The sprite library uses the following variables:

int spon=15;		- the highest sprite number used in your program
int spclip=1;		- 0 means sprite clipping is off
			  (might hang computer is it is off)
block spritescreen;	- the virtual screen used as a background

		WordUp Graphics Toolkit: Programmer's Guide	       Page 21

A large structure contains all data about the sprites:

typedef struct {
      int           num;	        // sprite number to show on screen
      int           x;		        // x coord
      int           y;		        // y coord
      int           ox;		        // last x coord
      int           oy;		        // last y coord
      unsigned char on;		        // sprite is on?
      int           maxx;	        // area on screen to copy
      int           maxy;	        // Upper left and
      int           minx;               // Bottom right corners of box
      int           miny;               // to copy.
      block         old;                // old block (stores what was
						      behind sprite)

      char          animon;             // animation on?
      int           anm[41];            // number of animation
      unsigned char ans[41];            // delay for animations
      char          curan;              // current animation
      unsigned char delcnt;	        // delay count

      char          movexon;            // x movement on?
      int           mvx[16];            // direction to move
      int           mvn[16];            // number of times to move
      unsigned char mvxs[16];           // delay for movement
      char          curxmove;           // current x move
      int           curmnx;             // number of times moved already
      unsigned char mvxcnt;             // delay count

      char          moveyon;            // y movement on?
      int           mvy[16];            // direction to move
      int           mvny[16];           // number of times to move
      unsigned char mvys[16];           // delay for movement
      char          curymove;           // current y move
      int           curmny;             // number of times moved already
      unsigned char mvycnt;             // delay count

      } sprit;
sprit s[40];

You will probably not need to change any of these.  There are a few
applications however.  

If you need to store the movements or animations as integers, it will be
a pain converting the numbers into a correct string to pass to the animate
command, therefore you can just put them directly into the arrays yourself.

If you draw something other than a sprite on the virtual screen, you will
need to copy more of the screen to the visual page.  Therefore change the
minx,miny,maxx,maxy variables of a sprite that is on to the coordinates
of the area you need to copy.  

		WordUp Graphics Toolkit: Programmer's Guide	       Page 22

13.0 Multidirectional Scrolling
-------------------------------
A large part of the WGT toolkit deals with creating and using a 
scrolling background for games.  When dealing with a large world like this,
it is obvious we cannot use large bitmaps due to the memory limitations
of the PC.  To make a very large background picture while keep the
memory used to a minimum, we need to use a tiling approach.



13.1 Tiling
-----------
Tiling is done by creating a number of small reusable images that can be 
placed together to form a larger background picture.  Some simple
examples are a picture of some grass, dirt, or rocks.  With these tiles,
you can place them together to form a map.  These maps can be created with
the WGT Map Maker.  Each map can be up to 320x200 tiles, and use a maximum
of 256 tiles.  If you're wondering why, 256 is the number of unique 
characters an unsigned character can hold, and 320x200 tiles fits within
a single 64k segment.   Each character holds the number of the tile to
display at that position in the map.  In most graphics libraries, the
job of drawing the tiles from a starting position in the map is left
to the programmer.  However, WGT has a very powerful scrolling library
which controls all the aspects of scrolling the screen, and drawing
sprites in your world.  Therefore we will focus on how to use the scrolling
system rather than how it works.

Tiles are created using the WGT Sprite Editor.  To create a
group of tiles, use the sprite slots 0-255 and save them into a
sprite file.  Sprite files are not for sprites only.  They can hold
any group of images that will be used for any purpose.  The important
point you should remember is that sprite files are just an array of images,
or blocks.  You will see this in the example programs declared as
        block mytiles[256];  or  block mysprites[500];
Tiles are usually square, but they do not have to be.  Rectangular tiles
are allowed in version 4.0 of WGT.   Tiles have a maximum size of 64x64
pixels.  


13.2 Tile Types
---------------
Tile types are a simple way of organizing tiles into similar groups.  The 
most common types of tiles in a game are hollow and solid.  By assigning 
each tile a number, we can categorize each tile.  For example, we can 
define a couple of tile types as such:

                           #define HOLLOW 0
                           #define SOLID  1

		WordUp Graphics Toolkit: Programmer's Guide	       Page 23

An array of 256 integers is used to hold the types for each tile loaded.
All tiles containing a 1 in this array would be considered to be solid
and your program can react accordingly.  In this example, tile contains
a tile image number number from 0 to 255.
  example:   if (tiletypes[tile] == SOLID)
                printf("You hit a wall");

Tile types are not required by the WGT scrolling system, but they do save
you time, and make your source code easier to read if you use defines
like above.

It will also help if you put all the solid tiles together so you can 
access them with an IF statement. 
   example:
        if ((tile >= 128) && (tile <= 200)) 
          {
           if ((tiletypes[tile] == DOOR) && (keys > 0))
              open_the_door ();
           else you_hit_a_wall ();
          }

The tiles 128-200 in this example would contain solid tiles.  A further
comparison would narrow the kind of solid tile down.  If the type of
tile is a DOOR and you have at least 1 key, then it would open the door.
This way you can detect doors, but it won't open them unless you also
have a key.

Planning ahead will save you some programming time. Once you draw the
tiles with the sprite creator and design the map files, it will be hard
to switch the tiles around. Think about this BEFORE you start drawing
your tiles.


13.3 Coordinate Systems
-----------------------

Two different coordinate systems are used with the WGT scrolling system.
They are:

       Map coordinates: Tile increments (tile dimensions)
			To convert a map coordinate to a world coordinate,
			multiply by the tile dimensions.
			These are the same coordinates used in the Map Maker.

     World coordinates: Pixel increments (1 pixel)
			To convert a map coordinate to a world coordinate,
                  divide by the tile dimensions.
			These are used by scrollsprites because they can
                  have any orientation on the map.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 24

13.4 Scrolling Windows
----------------------
A scrolling window is defined with the winitscroll routine.  The window
contains a single scrolling background which can be combined with other
windows to create parallax scrolling effects.   Windows that contain
the background that is farthest away are called NORMAL windows.  All tiles
in these windows are shown normally, with color 0 being drawn.  Windows
that contain the layers overtop the NORMAL window are called PARALLAX
windows.  Every pixel containing the color 0 will be considered to be
see-through.  This allows you to place PARALLAX windows over the NORMAL
window, giving different layers that move at different speeds.  This is
called parallax scrolling.  

The width of a window MUST be a multiple of 4.  This is due to the 386
instructions use within the scrolling system.  To make sure your windows
work properly, either make your tiles multiples of 4, or plan the width
ahead of time.  For example, if your tiles are 31 pixels wide, you could
have a window that is either 4 or 8 tiles across because they will result
in a width that can be divided by four evenly.

When constructing each frame of the animation, you must draw the windows
in order, from back to front.  You may also draw sprites between each
layer if desired.   Once the frame has been completed, it is copied to 
the visual screen with the wcopyscroll routine.  You cannot draw on the
scrolling area using the normal WGT commands (such as line or circle) 
because it is redrawn from scratch every frame.  To place objects onto
the scrolling window, we use a sprite structure called scrollsprites.



13.5 Scrollsprites
------------------
Unlike the commands in wspr.lib, movement and animation is left to the
programmer in the scrolling system.  This is due to the size of the animation
and movement structure required and the number of sprites on the map at once.
Large maps may have over 1000 sprites on at once, so we must keep the memory
used to a minimum.  Sprites used in the scrolling windows are called
scrollsprites.  We will use this term to make a distinction from the
sprites used in the wspr.lib library.

The scrollsprite structure is defined as the following:

typedef struct {		 
	char on;		 /* sprite is turned on=1 */
	int x;			 /* world x coordinate  */
	int y;			 /* world y coordinate  */
	unsigned int num;	 /* image # from sprites array to show  */
	} scrollsprite;

on can be either 0 or 1.   1 means the scrollsprite will be drawn.  
Scrollsprites can be turned off and still retain their coordinates and 
sprite number.

x and y are the world coordinates of the scrollsprite.  World coordinates
are based on the number of pixels in the world, and depend on the size of
the tiles used.  

		WordUp Graphics Toolkit: Programmer's Guide	       Page 25

To make the scrollsprites animate and move, you must change the values in
the scrollsprite array yourself.  For animation, it is wise to place your
sprites in sequence so you can animate them with a simple counter loop.
Once the counter reaches the last sprite image, reset it to the first to
repeat the sequence.  

Moving scrollsprites can be accomplished in many ways.  You may want them to
follow a predetermined path, a random path, or have some kind of artificial 
intelligence to control their movements and actions.

The wshowobjects command is used to display a range of objects on the
map. It has the following prototype:

void wshowobjects (int currentwindow, int start, int end, block *sprites,
                   scrollsprite *wobjects);

The positions of the sprites on the screen are based on the world viewing
coordinates of the current window, and the world coordinates of the objects.
The speed and object will scroll across the screen depends on which window 
it is associated with.


13.6 Global Variables in the Scrolling Library
----------------------------------------------
Several variables contain information about the map and windows being
used.  They are:

windowmaxx : The width of the window (in pixels) minus 1.
windowmaxy : The height of the window (in pixels) minus 1.

worldx     : The world X coordinate at the left corner of the window.
worldy     : The world Y coordinate at the top corner of the window.

worldmaxx  : The highest world X viewing coordinate the window can be.
worldmaxy  : The highest world Y viewing coordinate the window can be.
             The above two are based on the map size and the window size.

mapwidth   : The width (in tiles) of the map.
mapheight  : The height (in tiles) of the map.

tilewidth  : The width (in tiles) of the window.
tileheight : The height (in tiles) of the window.

Each of these variables is an array of 4 integers, one for each of the
4 possible scrolling windows.

Example:

If you are working with window 0, and object 0 is moving to the right,
it is necessary to keep the object within the map boundaries.  Let's say
you want the object to wrap around to the other side of the map.

   wobject[0].x+=8;   /* Move to the right at 8 pixels at a time */
   if (wobject[0].x > mapwidth[0] * tilewidth[0])
       wobject[0].x = -64;  /* Move it a little off the screen so it will
                    slowly come onto the screen instead of suddenly 
                    appearing. */

		WordUp Graphics Toolkit: Programmer's Guide	       Page 26

13.7 Saving Map Files
---------------------
You will need to save a map file when using a "Save Game" feature in your
program.  wsavemap is provided for this purpose.  It will save the map data,
positions of objects, and tiletypes.  It does not save the current viewing
coordinates of the scrolling windows.  You will need to save this and any
other data in a different file.

When using parallax scrolling, it is only necessary to save the layers that
could have been modified with wputblock.  If you do not use this command,
it is better off to just save the scrollsprite arrays in your own file.


13.8 Using EMS in the Scrolling Library
---------------------------------------
There are three elements you can store in EMS memory:  sprites, tiles,
or window buffers.  A window buffer is a block the size of the window's
dimensions which is used to store the scrolling image data.  This is the
data that is copied to the visual screen with wcopyscroll.  This buffer
is not a full screen block, and therefore cannot be written to like a
virtual page.  (In version 3.5, you were able to do this.)  NORMAL windows
require two window buffers, while parallax windows only require one since
they inherit one from the NORMAL window it is linked to.   When using more
than one scrolling window at once, this can require a lot of memory.
It is recommended that you store the window buffers in EMS if you are using
parallax scrolling, or have more than one window.

Storing tiles in EMS has proven to be very slow, because they need to be
accessed frequently.  It also has the disadvantage of not being able to
keep window buffers in EMS at the same time.  This is because we cannot copy
between two places in EMS since they would both have to be in the page frame.
In general, only store tiles in EMS if you are using lots of very large
tiles.  

Storing sprites in EMS has the most advantages.  It does not slow the
frame rate by much, and allows you to put a large amount of graphics into
your game. 

The best configuration for EMS memory is to store sprites and buffers in
EMS, and keep the tiles in conventional.  This has proven to be the fastest
and most efficient of setups.  Of course, the fastest way is to keep
everything in conventional memory, but sometimes that just isn't possible.

When storing one of the three elements in EMS, it must reside completely
within EMS.  You cannot have half of your sprites in EMS, and half in
conventional memory.  WGT uses three flags to tell the scrolling library
where you are storing the elements.  They are:

      int wemstiles;
      int wemsobjects;
      int wemsscroll;   /* (Window buffers) */

		WordUp Graphics Toolkit: Programmer's Guide	       Page 27

By default, these are set to 0, meaning it is using conventional.  If you
plan to use EMS, set the appropriate flag to 1 before you initialize
the scrolling library.  Also, if you are storing tiles or sprites in EMS,
you must use the wems_loadsprites command in place of wloadsprites.  This
command accepts the same parameters, only it loads the images directly into
EMS.  You must have allocated enough EMS memory to hold the images before
you load them.

Once you have initialized the EMS, loaded your images, and initialized
your scrolling windows, your program can run as usual without any other
changes.  The wshowobjects command will swap the sprite images into the
page frame when needed, transparent to the programmer.  If you need to
use a sprite image without using the wshowobjects command, you will have to
map the image into the page frame first with wems_getsprite.

When loading sprite files or other data into EMS, WGT keeps track of 
where the next data can be stored.  If you want to clear what is in EMS,
you can use the wems_reset command.  Two variables are changed in this 
command.  emspage contains the last page not filled with data, and emsoffset
contains the offset in this 64k page where the next data will be stored.
These variables are adjusted every time you store something in EMS.
wems_reset sets emspage to 0, and emsoffset to 1.  Any data stored in 
EMS after this is done will write over the existing data, effectively
erasing it.  Data is never deallocated in EMS, it is simply reused.
You should reset any EMS pointers to NULL after using wems_reset to make sure
you don't use a pointer which may get overwritten.

Some programs may require data to remain in EMS at all times, and have
different sprite files loaded in later.  Since it would be pointless to
reset the EMS completely and lose the static data, you can use your own
EMS "reset".  
    1. Load in or store your static data in EMS
    2. Copy the emspage and emsoffset into two temporary variables.  
    3. Load in your dynamic data.
    4. When you want to change your dynamic data, set emspage and
       emsoffet equal to the temporary variables above, and then load.

Visually:
   -------------------------------------------------
   |             |                                 |
   | STATIC DATA |         DYNAMIC DATA            |
   |             |                                 |
   -------------------------------------------------
                 ^
                 |-This is the location stored in the temporary variables.
This will prevent the new data from overwriting the static data at the
beginning.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 28

13.8 Optimizing SOVERLAP
------------------------
Checking for overlapping scrollsprites can be time consuming, especially when
using sprites in EMS memory.  Below is the source code for the soverlap
routine:

int soverlap (int s1, scrollsprite *wobjects1, block *sprites1,
	      int s2, scrollsprite *wobjects2, block *sprites2)
/* Sees if two objects overlap, by comparing the rectangles each are
   contained in. */
{
    int n1,n2;
    int sw1,sh1,sw2,sh2;  /* width/height of both sprites */
    scrollsprite *obj1;
    scrollsprite *obj2;
    block image;

    obj1=&wobjects1[s1];
    obj2=&wobjects2[s2];

    if ((obj1->on & obj2->on)) /* Are they both on? */
    {
	n1 = obj1->num;  /* for easier reading */
        n2 = obj2->num;
	if (wemsobjects)
	  image = wems_getsprite(n1, sprites1);
	else image = sprites1[n1];
	sw1= *(int *)image;    /* Width is first 2 bytes of data */
	image+=2;
	sh1= *(int *)image;    /* Height is next 2 bytes of data */

	if (wemsobjects)
	  image = wems_getsprite(n2, sprites2);
	else image=sprites2[n2];
	sw2= *(int *)image;    
	image+=2;
	sh2= *(int *)image;

	if (( obj2->x >= obj1->x - sw2 ) &&
	    ( obj2->x <= obj1->x + sw1 ) &&  /* check all four corners */
	    ( obj2->y >= obj1->y - sh2 ) &&
	    ( obj2->y <= obj1->y + sh1 )) return 1;
    }
    return 0; /* not colliding */
}

		WordUp Graphics Toolkit: Programmer's Guide	       Page 29

As you can see above, two sprites must be mapped into the page frame for
each call to soverlap.  This makes using sprites in EMS very slow, however
we can get around this mapping completely by storing the dimensions of all
the sprites in a table.  From then on, we can simply look them up from the
table and we don't need to worry about mapping EMS pages in.  For example:

int spritewidth[1001];
int spriteheight[1001];

void get_sprite_sizes(void)
/* Stores the width and height of each sprite into a table */
{
int i;
block emsbl;

for (i = 0; i < 1000; i++)  /* Assuming we have 1000 sprites loaded */
 {
  if (wemsobjects)
    emsbl = wems_getdata(sprites[i]);
  else
    emsbl = sprites[i];
  spritewidth[i] = wgetblockwidth(emsbl);
  spriteheight[i] = wgetblockheight(emsbl);
 }
}

int collide (int s1, int s2)
/* Sees if two objects overlap, by comparing the rectangles each are
   contained in.  Assumes we are using the same image and scrollsprite
   arrays for both sprites, and they are called sprites and wobject. */

{
    int n1,n2;
    int sw1,sh1,sw2,sh2;  /* width/height of both sprites */
    scrollsprite *obj1;
    scrollsprite *obj2;
    block image;

    obj1=&wobject[s1];
    obj2=&wobject[s2];

    if ((obj1->on & obj2->on)) /* Are they both on? */
    {
	n1 = obj1->num;  /* for easier reading */
        n2 = obj2->num;
	sw1 = spritewidth[n1];
	sh1 = spriteheight[n1];
	sw2 = spritewidth[n2];
	sh2 = spriteheight[n2];
	if (( obj2->x >= obj1->x - sw2 ) &&
	    ( obj2->x <= obj1->x + sw1 ) &&  /* check all four corners */
	    ( obj2->y >= obj1->y - sh2 ) &&
	    ( obj2->y <= obj1->y + sh1 )) return 1;
    }
    return 0; /* not colliding */
}



		WordUp Graphics Toolkit: Programmer's Guide	       Page 30

14.0 Program Timing
-------------------
WGT offers one routine for controlling the speed of your program.  Since
a computer game may have different frame rates (number of frames of animation
per second) depending on which computer you run it on, it is necessary to
make the game run at the proper speed.  Of course you cannot speed up a 
slow computer, but you can always make sure that someone with a Pentium and
a local bus video card doesn't suffer from a game that runs too fast.

To store the time, use the C function gettime.  You will want to store two
times, one at the beginning of each frame, and one at the end.  This way
you can find out how much time was needed to draw a single frame of
animation.

The wtimer command will take two times and return the difference between them
in microseconds.  To use this resulting value, you need a while loop.
For example:

  do
   {  /* Animation loop
    gettime(&time1)
    ...
    /* Do animation and draw screen */ 
    ...
    do
     {
      gettime(&time2)                     /* Loop until at least 5  */
     } while (wtimer (time1, time2) < 5); /* microseconds has passed */
   } /* End of animation loop */

This will make sure each frame remain on the screen for 5 microseconds.
The frame rate can be determined by dividing 100 by the value you use in
the while loop.  In this case the program would have a maximum speed of 20 
frames per second (FPS).  

You should also note that since the PC's system timer has a resolution of
18.2 ticks per second, the maximum frame rate you can control is about 
18 FPS.  You can get around this by either using your own high resolution
timer, or perhaps increasing the speed of the system timer.  Both of these
techniques are out of the scope of this manual, and are left as an exercise
to the reader.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 31

15.0 The WGT Menu Library
-------------------------
The WGT Menu Library provides a quick and easy method of selecting 
options available to the end user.  If you have a mouse, you can simply
move to the item you want, and click the mouse button. If do not have a 
mouse, use the arrow keys to move around in the drop down menus.

Creating a drop down menu:

First you need to define what the names of the drop down menus will be.
This is done be entering them into an array at the beginning of your
program:

char *menubar[10] = {" QUIT  "," FILES "," Menu 1 "," Menu 2 ", NULL, 
                     NULL, NULL, NULL, NULL, NULL};

These names will appear on the menu bar at the top of the screen.
Notice how some are 'NULL'. These will not show anything on the menu bar.
You should put spaces on either side of the names, to keep the choices
apart. When a user moves the mouse over these names (or presses F10 when
there is no mouse installed), a sub-menu will appear.

To define the sub-menus, you must enter each choice as follows:

dropdown[0].choice[0]=" Help ";
dropdown[0].choice[1]=" Quit ";
dropdown[1].choice[0]=" Load ";
dropdown[1].choice[1]=" Save ";
	 ^         ^
Menu # --|         |--Choice #


This would make sub-menus under the first and second drop-down choices.
It would look like this:

   Quit    Files    Menu 1    Menu 2
 | Help || Load |
 | Quit || Save |
 |------||------|

The format for sub-menus is:
dropdown[m].choice[n]="Your choice"

with m and n ranging from 0 to 9.

This means you can have up to 10 drop down menus, with up to 10
choices in each, for a total of 100 choices available to the user
at a click of the mouse button!

To determine which menu choice was clicked on, use the checkmenu command.
This command will remain in a loop until the mouse button is clicked, or
the user selects a menu choice with the keyboard by hitting enter on the
drop down menu.   If the mouse is clicked below the menu bar, checkmenu
will return -1.  This allows you to have other buttons on the screen that
can be selected, by looking at where the mouse was clicked.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 32

Menus can support different fonts as well. To change the font, load it in
using the wloadfont command and change the variable menufont:

	menufont = sans_serif;

The menu will be shown using your font when it is displayed.  Make sure 
the font is not too large however, or the all menus will not fit on the 
screen.

Related variables:

Each drop down menu can have different colors.  To change them, 
set the following variables:

dropdown[0].color=?
dropdown[0].bordercolor=?
dropdown[0].textcolor=?


The menu bar can have different colors as well by setting:

menubarcolor=254;
menubartextcolor=1;
bordercolor=255;
highlightcolor=144;

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To see if the mouse is installed, check the variable:

int mouseinstalled;    =1 if installed, 0 if not installed

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At default, the hotkey which brings the drop down menus from the keyboard
is F10. You can change this key by changing the value in

char menuhotkey;

		WordUp Graphics Toolkit: Programmer's Guide	       Page 33

16.0 Using the WGT File Selector
--------------------------------
WGT includes a routines which displays a fully functional window for
selecting filename.   It can list files with common extensions, and
change to different drives and directories.  To activate the file selector,
use the wfilesel command.

The file selector looks like this:

                 ͻ
                          Load a sprite file          
                 ĺ
                   
                 ĺ
                  Ŀ    Ŀ    Ŀ 
                   *.spr       *.*       *.spr  
                           
                  Ŀ Ŀ 
                  A:                   <DRIVE>  - 
                  B:                   <DRIVE>  Ĵ 
                  C:                   <DRIVE>  ۳ 
                  D:                   <DRIVE>  ۳ 
                  GAMES                  <DIR>    
                  WORK                   <DIR>    
                  ADVENT.SPR             12056  Ĵ 
                  SUPER.SPR             150345  + 
                    
                 ĺ
                                Cancel                
                 ͼ

At the top of the window, a title will be shown which tells you what file 
operation will be performed on the chosen file.  The most common file 
operations are loading and saving.  Below the title is a black box.  This is
the text entry box.  If you prefer typing in a filename instead of using the 
mouse, you can simply begin typing the filename.  After the first letter is 
pressed, a cursor will be shown in the text entry box.  You may also click 
on the box to begin entering your text.  The backspace, delete, and arrow 
keys are all functional when in the text entry box. 

Below the text entry box are three file mask buttons.  The first contains
the current file mask.  All files with this extension will be listed in 
the directory listing below.  If you want to change the file mask, click
on the first button and type in the new mask.  Hit enter when you are 
finished and the file listing will change accordingly.  The second file
mask button is always "*.*", which will list every file in the current
directory.  The third button sets the file mask to the default mask which
was first used in the file selector.  

In the middle of the file selector, the file listing is shown.  There are
three kinds of elements in the listing, each distinguished by the text to the
right of them.  Disk drives are shown with "<DRIVE>" beside the drive name.
Clicking on a drive will attempt to change the current directory to that
drive.  Directories are shown with "<DIR>" beside the directory name.  
Use the ".." directory name to move back a level in the directory tree.
Files are shown with their file size to the right of them.  Clicking on one
of these will close the file selector, and perform the action on the file.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 34

To the right of the directory listing is a slider and two buttons.  The 
buttons move up and down through the directory listing.  The slider shows
a box in relation to which portion of the listing is being shown.  If you
hold the mouse button while dragging the box, you can quickly move to a
different location in the listing.  As well, moving up or down a page at
a time can be achieved by clicking above or below the box.

At the bottom of the file selector is a cancel button.  This is used to
abort the file operation.

If a filename is chosen, the routine will return a pointer to the
filename.  If the cancel button was chosen, it returns NULL.

The file selector can be moved around on the screen if you pass it the
name of a block containing the current screen contents.  It will then be
able to restore the background when it is moved to a different location.
This block is also used to erase the file selector when the routine ends.
If the block is null, it is up to the programmer to restore the screen,
and the selector will be fixed in one location.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 35

17.0 WGTLIB: Data File Libraries
--------------------------------
In order to protect your graphic files from other users, WGT provides a
way to collect all of your files into one large data file and even 
protect it with a password.  This will prevent other programmers using
WGT to look at your graphics.  Data files are created using the 
"wgtlib.exe" utility.  It operates similar to the tlib utility included
with the C compiler.

It can drastically reduce the number of files sitting around in a 
directory, and reduces the chances that one of the necessary files 
is stored in an improper directory.

WGTLIB is a DOS parameter based program which combines the given files 
into a LIBRARY. You begin by specifying a library filename, password 
(if desired), and then specify individual filenames.  

	Options:
		+          Add file to library
		-          Remove file from library
		*          Extract file without removing it
		-* or *-   Extract file and remove it from library
		+$	   Add password to library
		-$	   Remove password from library
		*$	   Modify existing password
		@	   Execute commands in listfile

	Examples:
	---------
	
	To update a library file called TEST.LIB and add LIBFILE.DOC,
TYPE	WGTLIB TEST.LIB +LIBFILE.DOC (enter)

	To update TEST.LIB and add two files and a password,
TYPE	WGTLIB TEST.LIB +WGTLIB.EXE +$MYPASSWORD +LIBFILE.TPU

	To view the contents of TEST.LIB (with password),
TYPE    WGTLIB TEST.LIB #MYPASSWORD

	To remove WGTLIB.EXE from TEST.LIB,
TYPE	WGTLIB TEST.LIB #MYPASSWORD -WGTLIB.EXE

	To remove the password from TEST.LIB,
TYPE	WGTLIB TEST.LIB #MYPASSWORD -$

	To execute all commands within a listfile,
TYPE	WGTLIB TEST.LIB @MAKEFILE.DAT
	Where MAKEFILE.DAT contains +,-,*,-* or *-,+$,-$,*$ commands
	(one per line)

		WordUp Graphics Toolkit: Programmer's Guide	       Page 36

	NOTES:
		-any time you specify a library filename which does not
		 exist, WGTLIB creates a new file
		-once a password is added, you must specify what it is
		 using # and the password as the second parameter for
		 all subsequent commands
		-removing a password only requires a -$, no other parameters
		-full pathnames are accepted anywhere a filename is used
		-passwords are a maximum of 15 characters

Using a library file is very simple:

Initialize the library file by calling
	setlib("libfile.wlb");
If you set a password on the file, call
	setpassword("secret");
otherwise you should indicate no password with
        setpassword(" ");
All other commands in WGT which load something off the disk will look
in the library file. To test it, make a new directory and copy your
program and the library file. Do not copy the separate files you put
inside the library file. Try running the program. It should work with
no problems unless you forgot to put a file in the library, or you
have pathnames in your load commands.

	Suggestions for files to store in a library:
	--------------------------------------------

	1) Anything which you would like to remain hidden from the user.
	2) Graphics images to be used in a program.
	3) Sound files (VOC,CMF,MOD)
	4) EXE'S and COM's that you rarely use (ZIP the library and store
	   on a floppy). This prevents separation of related files when
	   backing up information.
	5) Drivers, etc. which a program requires to run. A neat trick is
	   to store multiple drivers within the library. If you use
           different video, sound, or printer drivers according to the 
           user's setup, you can store all the possibilities in one file.
           Then when the program runs, it loads the appropriate driver 
           into a buffer and outputs it to disk. Now the user has only
           the necessary files in the directory. 
           It can be done in memory instead of disk as well.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 37

18.0 FLI/FLC Animation Library
------------------------------
This small library is used to display animations stored in FLI or FLC
format.  These formats are used by the commercial programs Animator(Pro)
and 3D Studio, both by Autodesk.  The files store information in a
compressed format which reduces the amount of data that needs to be stored,
especially in large graphic-intensive animation sequences.  Even with
the compression scheme, some files will exceed the memory capacity of
the computer or at least the 640k barrier in DOS. To handle these
situations, the library supports playing animations straight from disk
or from EMS memory.

If you choose to play from disk, any size file may be loaded and played,
but continued disk access will slow down the animation. If you have a
slow computer or a slow disk drive, this may cause significant delay.

From EMS memory, files may be played as long as the entire file fits into
memory at once. Since every machine can have a different memory limitation,
you must be careful to provide enough error-detection as possible when
loading and playing from EMS.


To load and play an animation, a certain logical sequence must be 
performed. First, we must select a mode to use. Simply set the global
variable "flic_mode" to one of the constants:

         FLIC_DISK (1)         or            FLIC_EMS (2)

Animation files may change the palette during execution, and some programs
do not want their palette altered. To prevent the palette from being
changed (if you do this, colors probably won't look right) you can set
the "flic_color" variable to 0. This variable defaults to 1.

At this point, animation is extremely simple. First, call the openflic
command and pass it a filename to load. Once this is completed you may
perform the nextframe command in a while loop. This loop should check the
return value of the nextframe command and watch for a result of FLIC_DONE.
You may choose to break out of the loop at this point, or you may continue
(the animation will cycle through indefinitely). Once the animation loop is 
done, you should call closeflic to close the file and tidy up any loose ends.

		WordUp Graphics Toolkit: Programmer's Guide	       Page 38

19.0 SoundBlaster Library
-------------------------
The SoundBlaster libraries included with WGT require the software drivers
provided with the sound card to be loaded beforehand.  These drivers are
"CT-VOICE.DRV" and "SBFMDRV.COM".   The ct-voice driver is loaded into 
memory by WGT's commands, but sbfmdrv must be run from DOS first since it
is an executable file.

Global Variables:

typedef char far * wgtsong;    /* A simple way remember a CMF song. */

unsigned char fmstat;   /* Status of the FM playing routines.
			   0- not playing (Your song has finished)
			   255 Song is playing
			   1-254 Song marker found
                         */

int fmint;             /* Current FM interrupt being used by SBFMDRV.COM
			  The SBFMDRV driver reports this value when
                          installed. */

