Garbo/Garbo.cdr/pc/progrmng/stk110.lzh/STK.DOC

Text File | 1991-02-25 | 12.2 KB | 310 lines

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

         STK -- The sprite toolkit -- version 1.1

              Copyright (C) Jari Karjala 1991

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.1, Jan 14, 1991



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 (file
STKREF.DOC)). 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 bitmap 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.

All SPR functions check their SPRITE arguments and if they are
invalid they call the predefined function spr_err, which
terminates the program with an error message. This is very
useful, for example because using a deleted SPRITE can easily
crash the system. You can redefine the function spr_err to do
something else, but I do not recommend that.


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 (functions spr_anim_set_*). After that they must be started
to get them active (spr_anim_start).

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 the following special situations:

- timeout,
- hit X limit of the bounding box,
- hit Y limit of the bounding box,
- hit another sprite (simple or animated).

The fx handler function can be set for each animated sprite
(function spr_anim_set_fx_handler) and this handler is called
whenever such special situation occurs.  This handler can then
adjust the sprite properties (location, direction etc), and then
return a code which defines further actions. The actions are:

- do nothing,
- spr_put again (location changed),
- stop animation (same as spr_anim_stop),
- delete the sprite (same as spr_anim_delete),
- destroy the sprite (same as spr_anim_destroy).

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.



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



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]