ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/GRAPHICS/MISC/STK100.ZIP/STK.DOC

Text File | 1990-10-20 | 36.6 KB | 910 lines

**********************************************************************
                    This file is part of

         STK -- The sprite toolkit -- version 1.0

              Copyright (C) Jari Karjala 1990

The sprite toolkit (STK) is a FreeWare toolkit for creating high
resolution sprite graphics with PCompatible hardware. This toolkit
is provided as is without any warranty or such thing. See the file
COPYING and the end of this file for further information.

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


STK -- The Sprite ToolKit -- version 1.0, Oct 20, 1990



Intro
=====

The Sprite Toolkit (STK) contains the following sets of functions,
(each function has its set name in front of it):

SPR             lowlevel interface to the sprite functions
SPR_HIT         lowlevel collision detection routines
SPR_FIO         lowlevel sprite file IO
SPR_ANIM        higher level interface to the sprite functions
GR              text IO in the graphics mode and keyboard functions
MOUSE           INT 33 interface to the mouse functions.

Note that there are two different interface levels to the sprite
routines.

The lowlevel functions provide support for simple sprites which
can be put into the screen, hidden from the screen or deleted.
Collisions between them can be detected. The sprite data can
be read from a file, too.

The higher level interface supports animated sprites which are
composed of simple sprites. These animated sprites can move
automatically along some preset direction vector and act on
different special cases, such as hitting the boundary or other
sprite.

The GR functions provide a familiar set of basic text IO
functions, like putch, put and printf, but these functions work
in the graphics mode. There are also GR functions for direct
reading of the keymap. These functions detect multiple
simultaneus keypresses, as required by most arcade style games.

The MOUSE functions provide a very simple interface to the mouse
driver. They are not much more that names to the INT 33 functions.




Using the lowlevel sprite functions
===================================


Initializing
------------

The first thing to do in a program which uses the STK is to
start the graphics mode and initialize the sprites. This is done
by the functions gr_detect, gr_start and spr_initialize (for
further information, see The STK Function Reference). Now we are
ready to use the STK functions.


Creating and destroying sprites
-------------------------------

The sprites are represented by SPRITE handles. The exact definition
of the object pointed by a handle is private to the STK
implementation, therefore the sprites can be manipulated only
with the provided functions.

Each sprite has a shape defined by a sprite map. These can be
created by the SPRED sprite editor. Each sprite map contains the
actual shape of the sprite and the mask which describe the
transparent parts of the sprite.

We must create sprites before we can do anything with them. This
is done with the function spr_create, if we have the sprite
shape bitmaps in static arrays, or with the function
spr_fio_read_smp if the shape is in a sprite map file. Both of
these functions return a SPRITE handle. You can make copies of
sprites by the spr_copy function (you should spr_share the
sprite first to save memory, since copies of shared sprites
share the shape data which can take quite much memory).

The sprite resolution parameter in the spr_create means the
number of shifted images per 8 pixels, ie 4 means that the X
coordinates 0 and 1 will map into the same screen position.  Try
giving a numeric parameter (1,2,4,8) to the StarMines program to
see the effect of resolution parameter (for example "sm 4").

Each sprite should be though of as an object with its own
identity and properties like the current location, the shape
data and the identifier. If you need many sprites with the same
shape, you should use the spr_copy to make copies, NOT to try to
display the same sprite many times at different locations.

When the sprite is no longer needed it should be destroyed with
the spr_delete function, which releases all the resources used
by the sprite.


How much memory do we need
--------------------------

A sprite which is W bytes wide and H scanlines tall and uses
sprite resolution S takes 2*S*((W+1)*H) + 2*(W+1)*H bytes of
memory from far heap and only about 40 bytes from the near heap.
This means that the small memory model is big enough in most
applications.

Example: the sprite is 32 pixels (4 bytes) wide, 24 pixels tall
and we want the best resolution (8). The sprite will need
2*8*((4+1)*24) + 2*(4+1)*24 = 2160 bytes memory.

The memory consumption is one of the reasons why my sprites are
monochrome, they would need 4 times as much memory (in the
example over 8 kbytes for one sprite!) if they had 16 colors.
Also the output would be four times slower making it impossible
to use one pixel resolution in movements with anything slower
than 16 MHz.

If sharing is used then the N copies will take 2*S*((W+1)*H) +
2*(W+1)*H*N bytes of memory from the far heap plus those 40
bytes of near heap for each copy.


Manipulating sprites
--------------------

A sprite can be put into the screen with the function spr_put.
A sprite which has been put into the screen can be hidden by the
function spr_hide.  Displaying and hiding sprites do not take
place immediately, but only after the next call to the function
spr_next_pass. This function should be called in the main loop
of the program after all sprites have been spr_put into their
current positions.

What the spr_next_pass really does? It draws all the sprites
which have been spr_put after the previous spr_next_pass into
the hidden display page (and saves the background below them).
Then that display page is activated and the sprites which are in
the now-hidden page are deleted by restoring the previously
saved background data. Therefore you must spr_put the sprites
during every pass of the main loop of the program.

The method described above makes it possible to achieve
reasonably fast flicker-free animation. There is a problem with
this approach: EGA graphics cards are slow changing video pages,
and therefore we must waste about 10 milliseconds waiting after
the screen flip. Hercules cards do not need this wait-state,
therefore Hercules mode is preferred in slower machines. Note
that this wait-state affects the frame speed, and it should be
regulated with the spr_regulate_speed function.

The collision detection should be done after all the sprites
have been spr_put but before the spr_next_pass. It is possible
to either check the collision between a sprite and a coordinate
position, the collision between two sprites (spr_hit) or find
all the sprites a given sprite collides (spr_hit_first and
spr_hit_next). All collisions are first checked by the bounding
box and after that by using the mask map of the sprite.

You can retrieve information about a given sprite by the
functions spr_get_id, spr_get_x, spr_get_y, spr_get_width and
spr_get_height.




Using the higher level sprite functions
=======================================


Creating and destroying animated sprites
----------------------------------------

The animated sprites are represented by ANIM_SPRITE handles. The
exact definition of the object pointed by a handle is private to
the STK implementation, therefore the sprites can be manipulated
only with the provided functions.

The ANIM_SPRITEs are created by the function spr_anim_create.
This function takes simple sprites as parameters. These should
have been generated earlier, for example by the function
spr_create. Note that you must have different instances of
simple sprites for each animated sprite you create.

An animated sprite is deleted by the function spr_anim_delete.
This function will not delete the simple sprites it contains. If
also the simple sprites need to be deleted the function
spr_anim_destroy must be used.


Manipulating animated sprites
-----------------------------

After the animated sprites have been created their locations,
direction vectors, area limits and animation speeds should be
set. After that they must be started to get them active.

A program that uses animated sprites must call the function
spr_anim_next_pass instead of the spr_next_pass function. This
function will spr_put all the animated sprites, handle the
special effects (see below), call the spr_next_pass and then
update the positions and advance the animation of the animated
sprites for the next pass.

The special effects (fx) can be used to change the behavior of
the animated sprites in certain special situations, for example
in collisions with limits or other sprites. The fx_handler
function can be set for each animated sprite and this handler is
called whenever such special situation occurs. This handler can
then adjust the sprite properties etc, and then return a code
which defines further actions, for example re-put (location
changed) or destroy the sprite (somebody shot us!).

The default fx_handler will delete the animated sprite in
collisions and timeouts, and bounce it off the limits. See the
StarMines source for further examples of fx_handlers.

You can retrieve information about a given animated sprite by
the function spr_anim_get_info which returns a pointer into a
static structure describing the animated sprite. These values
may be changed, but it does not affect the animated sprite.




Compiling and linking with the STK
==================================

You need only the files STK.H (include file for function
prototypes and type definitions) and STKS.LIB (small model
library). The include file should be included into every module
which uses the STK functions and the library must be included
into the linking.  The examples below assume that these files
are in the current working directory and the Turbo C is
configured to use small memory model (default).

You should have received the SPRTEST.C example source code with
the STK distribution archieve. (Also the file SPRTEST.SMP is
needed for the sprite data.)  To compile and link the example,
use the following command line:

        tcc sprtest.c stks.lib graphics.lib

Now you should have a working example program SPRTEST.EXE which
will bounce two alien lifeforms around the screen. If they
collide, the first one will be destroyed. After 5000 steps both
the aliens are destroyed. Press Esc to exit the program.

If you prefer the integrated environment, you should include the
file STKS.LIB in the project file. You might like to use the
supplied file SPRTEST.PRJ to compile and link the test program
in the integrated environment. If you get "multiply defined
symbol" errors from the linker, you have probably the graphics
library option enabled in the options/linker menu. Either
disable that option or edit the project file.




The STK Function Reference
==========================


The basic sprite functions and variables (SPR)
----------------------------------------------

/**********************************************************************
* The delay after setvisualpage() before removing old objects in
* the funtion spr_next_pass().
* Many EGA/VGA cards need some milliseconds to switch pages,
* and therefore the sprites flash if this delay is too short.
*
* If someone has better solutions in dealing with this problem,
* I sure would like to know about them.
*
* Time is given in milliseconds and the default is 10 ms for EGA
* and 0 ms for Hercules (use spr_regulate_speed to balance the frame
* rate with different display adapters).
**********************************************************************/
extern int spr_pass_delay;

/**********************************************************************
* The maximum coordinate values for current graphics adapter.
* (Variables defined in module grmisc.c, and initialized in gr_start)
* (It is faster to use variables instead of getmaxx() and getmaxy());
**********************************************************************/
#define spr_max_x gr_max_x
#define spr_max_y gr_max_y

/**********************************************************************
* The sprite type is private.
**********************************************************************/
typedef void *SPRITE;

/**********************************************************************
* Initialize the sprite system to the given display hardware.
* Supported graphicsdrivers: EGAMONO and HERCMONO
* NOTE: This function must be called before any other sprite funtions
*       and the graphics mode must have been set before this call.
*
* graphicsdriver  The BGI identifier for the graphics driver used.
**********************************************************************/
void spr_initialize(int graphicsdriver);

/**********************************************************************
* Create a sprite from the given bitmaps.
*
* w,h   Width (must be < 512) and height (<256) of sprite in pixels
* pic   The picture bitmap for the sprite
* mask  The mask bitmap for the sprite
* res   The number of steps wanted per 8 bit interval in horizontal
*       direction (1,2,4,8). For example, the value 8 gives one
*       pixel resolution in X-direction.
* ID    The user supplied ID for the sprite (not obligatory)
*
* Return: the newly created sprite or NULL if parameter error,
*           sprite too big or out-of-memory
**********************************************************************/
SPRITE spr_create(WORD w, WORD h,
                  BITMAP pic, BITMAP mask,
                  BYTE res, WORD ID);

/**********************************************************************
* Create a shared version of the given sprite. This allows
* n spr_copies which all share the shape data thus saving
* quite much memory.
*
* spr   The sprite to share
* n     The maximum number of shared copies
*
* Return: New SPRITE or NULL if error (out of memory, spr==NULL, etc)
**********************************************************************/
SPRITE spr_share(SPRITE spr, BYTE n);

/**********************************************************************
* Create a copy of the given sprite. If the sprite was shared
* then a shared copy is created (if possible).
*
* spr   The sprite to share
* id    The ID for the new sprite
*
* Return: New SPRITE of NULL if error (out of memory, spr was NULL,
* no more shared copies)
**********************************************************************/
SPRITE spr_copy(SPRITE spr, WORD id);

/**********************************************************************
* Put the sprite into the given position into the display.
* NOTE: the call has no effect on screen until a call to
*       spr_next_pass() is made.
* NOTE: Cannot be called twice for the same sprite before spr_hide or
*       spr_next_pass().
*
* spr   The sprite to put
* x     The X coordinate
* y     The Y coordinate
**********************************************************************/
void spr_put(SPRITE spr, WORD x, WORD y);

/**********************************************************************
* Remove the sprite from the display.
* NOTE: the call has no effect on screen until a call to
*       spr_next_pass() is made.
*
* spr   The sprite to hide
**********************************************************************/
void spr_hide(SPRITE spr);

/**********************************************************************
* Delete the given sprite and release associated memory buffers.
*
* spr   The sprite to delete
**********************************************************************/
void spr_delete(SPRITE spr);

/**********************************************************************
* Draw all sprites into hidden screen page,
* activate hidden screen page,
* delete old sprites from the new hidden page.
*
* Return: The current visual page
**********************************************************************/
WORD spr_next_pass(void);

/**********************************************************************
* This function tries to regulate the frame speed by delaying if
* we are doing more frames per second than we should. The target
* speed is 1 frame per one clock tick (about 18 frames per second).
* This is reasonable target speed at least for 286 machines.
* This function should be called after each spr_next_pass() call.
**********************************************************************/
void spr_regulate_speed(void);



Information retrieving functions:


/**********************************************************************
* Return the user supplied identifier of the sprite
**********************************************************************/
WORD spr_get_id(SPRITE spr);

/**********************************************************************
* Return the X coordinate of the sprite in pixels from top-left
**********************************************************************/
WORD spr_get_x(SPRITE spr);

/**********************************************************************
* Return the Y coordinate of the sprite in pixels from top-left
**********************************************************************/
WORD spr_get_y(SPRITE spr);

/**********************************************************************
* Return the width of the sprite in pixels
**********************************************************************/
WORD spr_get_width(SPRITE spr);

/**********************************************************************
* Return the height of the sprite in pixels
**********************************************************************/
WORD spr_get_height(SPRITE spr);



The sprite file IO functions (SPR_FIO)
--------------------------------------

There is not many sprite file IO functions currently, but there
are many possibilities for future expansion. For example, some
kind of binary library of ready made SPRITE objects. Let me
know, if you do something...


/**********************************************************************
* Create a sprite from the given SMP file.
*
* smpfile   The sprite bitmap file name.
* res       The number of steps wanted per 8 bit interval in horizontal
*           direction (1,2,4,8). For example, the value 8 gives one
*           pixel resolution in X-direction.
* ID        The user supplied ID for the sprite (not obligatory)
*
* Return: the newly created sprite or NULL if file not found, read
*         error or out-of-memory
**********************************************************************/
SPRITE spr_fio_read_smp(char *smpfile, BYTE res, WORD ID);



The collision detection functions (SPR_HIT)
-------------------------------------------

Collisions may be checked only for the sprites which have been
spr_put() since the last call to spr_next_pass().
First bouding boxes are checked, and after that the possible
collisions are checked by comparing the mask bitmaps.


/**********************************************************************
* Check whether the given point is inside the given sprite.
*
* Return: 0 if no collision, negative otherwise.
**********************************************************************/
int spr_hit_with_point(SPRITE spr, WORD x, WORD y);

/**********************************************************************
* Check whether the given sprites collide against each other.
*
* Return: 0 if no collision, negative otherwise.
**********************************************************************/
int spr_hit(SPRITE spr1, SPRITE spr2);

/**********************************************************************
* Find the first sprite colliding the given sprite. Use spr_hit_next
* to get the next sprites.
* Return: The colliding sprite or NULL if no collision
**********************************************************************/
SPRITE spr_hit_first(SPRITE spr);

/**********************************************************************
* Find the next sprite colliding with the given sprite.
* Return: The colliding sprite or NULL if no collision
**********************************************************************/
SPRITE spr_hit_next(SPRITE spr);



The animated sprite handling defines, variables and functions (SPR_ANIM)
-------------------------------------------------------------------------


/**********************************************************************
* The animated sprite is a private datatype
**********************************************************************/
typedef void *ANIM_SPRITE;

/**********************************************************************
* The information structure returned by the spr_anim_get_info()
**********************************************************************/
typedef struct _anim_spr_info {
    int     x,y;                            /** location        **/
    int     dx,dy;                          /** movement vector **/
    int     lef, top, rig, bot;             /** limits          **/
    WORD    frame, frame_delay, timeout;    /** time info       **/
    WORD    id;     /** the user spesified id of current sprite **/
    int     w,h;                            /** width&height    **/
} ANIM_SPR_INFO;


/**********************************************************************
* The values for fx_mode and fx_type. (See spr_anim_set_fx_handler)
**********************************************************************/
#define SPR_ANIM_FX_ALL       (0xFFFF) /** all fx       **/
#define SPR_ANIM_FX_TIMEOUT     (1<<0) /** timeout      **/
#define SPR_ANIM_FX_HIT_X_LIMIT (1<<1) /** hit x limit  **/
#define SPR_ANIM_FX_HIT_Y_LIMIT (1<<2) /** hit y limit  **/
#define SPR_ANIM_FX_HIT_SPRITE  (1<<3) /** hit other spr**/

/**********************************************************************
* The FX_RET values for the fx_handler return
**********************************************************************/
#define SPR_ANIM_FX_RET_NOTHING (0)     /** continue normally       **/
#define SPR_ANIM_FX_RET_RE_PUT  (1)     /** put the sprite again    **/
#define SPR_ANIM_FX_RET_STOP    (2)     /** stop the animation      **/
#define SPR_ANIM_FX_RET_DELETE  (3)     /** delete the anim.sprite  **/
#define SPR_ANIM_FX_RET_DESTROY (4)     /** destroy the anim.sprite **/



/**********************************************************************
* Create an animated sprite from the given simple sprites.
* The sprites must have the same width and height attributes.
* Set the following defaults:
*   x,y = 0,0
*   dx,dy = 0,0
*   lef,top,rig,bot = 0,0,spr_max_x,spr_max_y
*   frame_delay, timeout = 0,0
*   fx_mode = FX_ALL
*   fx_handler = default_fx (TIMEOUT & HIT_SPRITE delete, LIMITs bounce.)
*
* count The number of simple sprites
* ...   The simple sprites
*
* Return: ANIM_SPRITE if no errors or
*          NULL if memory allocation error, count>ANIM_SPRITE_MAX
*           or ... contains a NULL sprite.
**********************************************************************/
ANIM_SPRITE spr_anim_create(WORD count, ...);

/**********************************************************************
* Start the sprite animation.
*
* aspr  The animated sprite to use
**********************************************************************/
void spr_anim_start(ANIM_SPRITE aspr);

/**********************************************************************
* Stop the animation of the given sprite. This means that after the
* next pass this sprite will not be shown nor updated.
*
* aspr  The animated sprite to stop
**********************************************************************/
void spr_anim_stop(ANIM_SPRITE aspr);

/**********************************************************************
* Delete the given animated sprite. The simple sprites it contains are
* NOT deleted.
*
* aspr  The animated sprite to use
**********************************************************************/
void spr_anim_delete(ANIM_SPRITE aspr);

/**********************************************************************
* Delete the given animated sprite. The simple sprites it contains are
* ALSO deleted.
*
* aspr  The animated sprite to destroy
**********************************************************************/
void spr_anim_destroy(ANIM_SPRITE aspr);

/**********************************************************************
* spr_put all animated sprites then check for special effects (call
* fx_handler(s) if necessary, and act according to the return values).
* Call spr_next_pass and after that update frame indices and locations
* of all animated sprites.
*
* Return: The current visual page
**********************************************************************/
WORD spr_anim_next_pass(void);



/**********************************************************************
* Return a pointer into a static info structure of the sprite.
* Note: the structure is only a copy which is overwritten by the
*       next call to this function.
**********************************************************************/
ANIM_SPR_INFO *spr_anim_get_info(ANIM_SPRITE aspr);

/**********************************************************************
* Set the location of the animated sprite.
**********************************************************************/
void spr_anim_set_location(ANIM_SPRITE aspr, WORD x, WORD y);

/**********************************************************************
* Set the movement vector of the animated sprite.
**********************************************************************/
void spr_anim_set_vector(ANIM_SPRITE aspr, int dx, int dy);

/**********************************************************************
* Set the limits for the animated sprite. The function takes care
* of the bottom/right adjustments due to the size of the sprite.
*
* Note again, that all simple sprites belonging to the animated sprite
* must have the same width & heigth.
**********************************************************************/
void spr_anim_set_limits(ANIM_SPRITE aspr,
                         WORD lef, WORD top, WORD rig, WORD bot);


/**********************************************************************
* Set the frame delay and timeout values. (-1 means no change for
* that value).
*
* NOTE: The 'frame' MUST NOT be changed from an fx_handler!!
*
* frame         The current animation frame number (0..nr of frames-1)
* frame_delay   The number of passes for each frame change (0=no change)
* timeout       The number of passes before timeout action (0=infinite)
**********************************************************************/
void spr_anim_set_time(ANIM_SPRITE aspr,
                       int frame, int frame_delay, int timeout);

/**********************************************************************
* Sets the special effects handler function.
* The function should have the following prototype:
*
*   WORD func(ANIM_SPRITE aspr, WORD fx_type, SPRITE spr);
*
* The aspr is the animated sprite, fx_type is the type of the
* effect which caused this call and spr is the colliding sprite
* (if fx_type was HIT_SPRITE).
*
* The function should return one of the FX_RET values defined above.
*
* A NULL handler means that all special effects cause spr_anim_delete.
*
* fx_mask     The types of effects relayed to the handler.
* fx_handler  The handler function.
**********************************************************************/
void spr_anim_set_fx_handler(ANIM_SPRITE aspr,
                             WORD fx_mask,
                             WORD (fx_handler)(ANIM_SPRITE,WORD,SPRITE));



The text IO and keyboard variables and functions (GR)
-----------------------------------------------------

Modes for the gr_detect:

#define GR_TYPE_ANY 0   /* Any mode will do */
#define GR_TYPE_SPR 1   /* The best possible mode for the sprite toolkit */

/**********************************************************************
* Detect the graphics card and mode of the system.
* The type parameter can be used to specify special requests (see above).
* graphdriver and graphmode parameters are returned. They contain -1
* if some error occured (cannot find requested mode, etc)
**********************************************************************/
void gr_detect(int type, int *graphdriver, int *graphmode);

/***************************************************************************
* Initializes the graphics system. Search BGI drivers from the path defined
* in the enviroment variable BGIDIR or current directory. Set videomode
* into the BIOS are to fool mouse drivers with Hercules graphics.
* Set gr_end at exit and ctrl-C signals.
* Terminate with error message if initialization fails.
*
* graphdriver   pointer to the driver ID (or DETECT)
* graphmode     pointer to the mode ID
***************************************************************************/
void gr_start(int *graphdriver, int *graphmode);

/***************************************************************************
* Returns to the text mode
***************************************************************************/
void gr_end(void);


/**********************************************************************
* gr_putch, gr_puts, gr_printf work as the as in text modes.
* '\n', '\r' are handled as in standard text modes.
* Scrolling or backspacing not implemented.
**********************************************************************/
void gr_putch(char ch);
void gr_puts(char *s);
void gr_printf(char *s,...);
#define gr_gotoxy(x, y) moveto(x*8, y*8)

/**********************************************************************
* Print text at the given position. (x and y in pixels)
**********************************************************************/
void gr_xy_printf(int x, int y, char *s,...);

/**********************************************************************
* Print text into both graphics pages at the given position.
* (x and y in pixels) Page 0 is left active.
**********************************************************************/
void gr_dual_xy_printf(int x, int y, char *s,...);

/**********************************************************************
* Return a keypress if one pending, otherwise 0.
* Extended codes contain 0 in the low byte.
*
* Automatic key repeat disabled by setting kbd buffer head and tail
* equal.
**********************************************************************/
int gr_inkey(void);

/**********************************************************************
* Read a string from screen in graphics mode. (Max len 80)
* Backspace deletes characters, Esc returns a null pointer.
**********************************************************************/
char *gr_gets(char *cpdest, int max_len);

/**********************************************************************
* This variable defines the text writing mode (default GR_MODE_CLEAR)
**********************************************************************/
extern int gr_text_mode;

/**********************************************************************
* The maximum coordinate values for current graphics adapter.
* (It is faster to use variables instead of getmaxx() and getmaxy());
**********************************************************************/
extern int gr_max_x;
extern int gr_max_y;

#define GR_MODE_OR      (1<<0)      /* OR the text over previous graphics */
#define GR_MODE_CLEAR   (1<<1)      /* Clear the backgroud bvefore print  */


/**********************************************************************
* Array of booleans for each key of the keyboard (indexed by the scan
* code value). Non-zero if key pressed, zero otherwise.
* The array is updated during the kbd_grab, see the function
* gr_start_kbd_grab below.
**********************************************************************/
extern char gr_keys[128];

/**********************************************************************
* Set a new handler for the keyboard. This handler sets and resets
* the gr_keys array values for each scancode received, then calls
* the old handler and after all that flushes the keyboard buffer.
**********************************************************************/
void gr_start_kbd_grab(void);

/**********************************************************************
* End the kbd grab, ie restore the original keyboard handler
**********************************************************************/
void gr_end_kbd_grab(void);

/**********************************************************************
* Defines for the scan codes of some keys. See others from
* some book, for example Peter Norton's Programmers guide or
* write a small program to try them...
**********************************************************************/

#define GR_KEY_ESC  1
#define GR_KEY_1    2
#define GR_KEY_2    3
#define GR_KEY_3    4
#define GR_KEY_4    5
#define GR_KEY_5    6
#define GR_KEY_6    7
#define GR_KEY_7    8
#define GR_KEY_8    9
#define GR_KEY_9    10
#define GR_KEY_0    11

#define GR_KEY_TAB  15
#define GR_KEY_Q    16
#define GR_KEY_W    17
#define GR_KEY_E    18
#define GR_KEY_R    19
#define GR_KEY_T    20
#define GR_KEY_Y    21
#define GR_KEY_U    22
#define GR_KEY_I    23
#define GR_KEY_O    24
#define GR_KEY_P    25

#define GR_KEY_A    30
#define GR_KEY_S    31
#define GR_KEY_D    32
#define GR_KEY_F    33
#define GR_KEY_G    34
#define GR_KEY_H    35
#define GR_KEY_J    36
#define GR_KEY_K    37
#define GR_KEY_L    38

#define GR_KEY_Z    44
#define GR_KEY_X    45
#define GR_KEY_C    46
#define GR_KEY_V    47
#define GR_KEY_B    48
#define GR_KEY_N    49
#define GR_KEY_M    50
#define GR_KEY_COMMA    51
#define GR_KEY_DOT      52

#define GR_KEY_SPACE    57

#define GR_KEY_ARROW_UP     72
#define GR_KEY_ARROW_DOWN   80
#define GR_KEY_ARROW_LEFT   75
#define GR_KEY_ARROW_RIGHT  77



The mouse interface variables and functions (MOUSE)
---------------------------------------------------

/** Codes for button presses **/
#define BUTTON_LEFT         1
#define BUTTON_RIGHT        2
#define BUTTON_MS_MIDDLE    (BUTTON_RIGHT | BUTTON_LEFT)
#define BUTTON_MIDDLE       4

/* First mask and then shape bitmap (must be WORDs) */
typedef unsigned int MOUSE_POINTER[2][16];

extern MOUSE_POINTER mouse_pointer_arrow;    /* HotSpot 1,1   */
extern MOUSE_POINTER mouse_pointer_hourglass;/* HotSpot 7,7  */
extern MOUSE_POINTER mouse_pointer_cross;    /* HotSpot 7,7   */

/** For further information, see the mouse documention **/
int     mouse_driver_init(void);                                /**  0 **/
void    mouse_show_pointer(void);                               /**  1 **/
void    mouse_hide_pointer(void);                               /**  2 **/
void    mouse_get_pointer_xy(int *x, int *y);                   /**  3 **/
void    mouse_get_rel_pointer_xy(int *x, int *y);               /** 11 **/
int     mouse_get_buttons(void);                                /**  3 **/
int     mouse_get_presses(int buttons);                         /**  5 **/
int     mouse_get_releases(int buttons);                        /**  6 **/
void    mouse_set_pointer_xy(int x, int y);                     /**  4 **/
void    mouse_set_sensitivity(int x, int y);                    /** 15 **/
void    mouse_set_pointer_shape(int HotX, int HotY, MOUSE_POINTER shape);
void    mouse_set_pointer_window(int a, int b, int c, int d);    /**  7 **/
void    mouse_disable_pointer_window(int a, int b, int c, int d);/** 16 **/
void    mouse_set_light_pen(int a);                         /** 13 & 14 **/

/**********************************************************************
* Initialize the mouse driver, set the pointer shape and pointer window.
* Return: the number of buttons or 0 if no mouse driver detected
**********************************************************************/
int     mouse_initialize(void);



GRTYPES - typedefs for the Sprite Toolkit
-----------------------------------------

#ifndef NULL
#define NULL ((void*)0)
#endif

typedef unsigned char BYTE;
typedef unsigned int  WORD;
typedef BYTE *BITMAP;



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



If you have any comments, suggestions, extensions, bug reports
(and fixes), let me know. I would also like to hear about the
programs you create with the aid of the Sprite Toolkit. In fact,
the main reason for writing the Sprite Toolkit was to increase
the number of good Public Domain and ShareWare games for PC
compatibles. I hope this toolkit will give you the initial
thrust you needed to implement that game you have been dreaming
about!


Jari Karjala
Veropellontie 11
00780 Helsinki
Finland

FUNET: [e-mail]