home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
World of Shareware - Software Farm 2
/
wosw_2.zip
/
wosw_2
/
CPROG
/
WGT_TC21.ZIP
/
WSPR.DOC
< prev
next >
Wrap
Text File
|
1992-07-17
|
10KB
|
334 lines
WSPR.LIB Documentation
~~~~~~~~~~~~~~~~~~~~~~
The WordUp Graphics Toolkit Version 2.0 includes a special
library for sprites. The library allows you to edit sprites using
the WGT Sprite Creator, 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.
Using WSPR.LIB
~~~~~~~~~~~~~~
To use the library, you must also link wgt.lib, and include
wgt.h and wspr.h. The library needs a lot of memory so make sure
you have lots, and set the program heap size in the Options\Debugger
menu.
Sprite Procedures
~~~~~~~~~~~~~~~~~
int wloadsprites(color *palette,char *filename,block sprites[201]);
Loads a sprite file created with the WGT Sprite Creator.
Returns -1 if unsuccessful or 0 if successful
Sprite files now contain 200 sprites instead of 100.
Remember to change this in your previous programs.
This command will load all sprites, as well as the colour
palette.
Example usage:
ok=wloadsprites(&palette,"game.spr",sprites);
--------------------------------------------------------------------------
void wfreesprites(block sprites[201]);
Frees memory previously allocated from loadsprites.
Example usage:
wfreesprites(sprites);
--------------------------------------------------------------------------
void initspr(void);
Initializes sprite library.
Sets up internal variables, and makes a virtual screen
called 'spritescreen'.
Assumes you have loaded sprites into an array called 'sprites'.
You must call it sprites for these routines to work.
You must call this after you load in sprites using wloadsprites.
If you need to call this more than once in a program, you
must free the virtual screen by wfreeblock(spritescreen).
Example usage:
initspr(sprites);
--------------------------------------------------------------------------
void spriteon(int number,int x coord,int y coord,int spritenum);
Turns a sprite on at the coordinates, using the spritenum block
from the sprites array. Spritenum is the same as the sprite numbers in
the WGT Sprite Creator. Number can range from 1 to 40. This means you
can have 40 sprites on the screen at once.
Each call to spriteon must be followed later in the program by
a spriteoff. Do not call spriteon using the same number twice in a row
or the computer may hang. You must turn the sprite off and back on again.
Example usage:
spriteon(1,160,100,3);
--------------------------------------------------------------------------
void spriteoff(int number);
Turns off a sprite. See above.
Example usage:
spriteoff(3);
--------------------------------------------------------------------------
void animate(int number,char *animation sequence);
Sets up animation for a sprite. Number is the sprite number
to animate. The string you must pass takes the following form:
"(spritenum,delay)(spritenum2,delay2)R"
Between each set of brackets is the information required to animate the
sprite. The first number is the sprite number, and the second is how long
that sprite number is displayed. You then make another set and use
different sprite numbers and delays. If you place a CAPITAL R at the end
of the string, the animation will (R)epeat itself when it gets to the end.
If you leave the R out, the animation will occur once, and stop.
You can have 40 sets for animation.
For example: To animate sprite number one between two sprites, and repeat:
Animate(1,"(1,0)(2,0)R");
^ ^ ^ ^
| | | | R repeats the sequence
| | |
| | |Second sprite shown is number 2, with no delay
| |
Sprite to animate |First sprite shown is number 1, with no delay
After calling this procedure, you must turn the animation on with animon.
Example usage:
Animate(4,"(5,12)(69,0)(200,100)");
--------------------------------------------------------------------------
void animon(int spritenum);
Turns animation on for the sprite. See above for setting animation.
Example usage:
animon(3);
--------------------------------------------------------------------------
void animoff(int spritenum);
Freezes animation for the sprite.
Example usage:
animoff(3);
--------------------------------------------------------------------------
void movex(int spritenum,char *movement sequence);
Sets up horizontal movement for a sprite.
Works the similar to animate only there are 3 numbers in each set.
You can have 15 sets for movement.
movex(3,"(1,50,1)(-1,50,0)R");
The first number in the set is added to the current x coordinate
of the sprite. Therefore if the sprite is at 100,50 on the screen, and
you make the number a 5, the sprite will move to 105,50. This number can
be anything, so you can have the sprite move right (positive numbers),
left (negative numbers) or nowhere (zero).
The second number in the set is the number of times to move the
sprite before going on to the next set. Always >0!
The third number in the set is the delay for each time the sprite
moves. Try using 0 at first and increase it to slow the sprites down.
If the set was (1,50,1), then the sprite would move to the right
one pixel, 50 times, with a delay of 1 for each move. Then the next set
would be activated. If you have a CAPITAL R at the end of the string,
the movement will repeat.
For example, to make sprite 2 move back and forth on the screen
continuously:
movex(2,"(1,200,0)(-1,200,0)R");
To make a sprite move from the left side to the right, and jump
back to the left again:
movex(2,"(1,319,0)(-319,1,0)R");
^
| This moves the sprite 319 pixels to the left!
--------------------------------------------------------------------------
void movey(int spritenum,char *movement sequence);
Sets up vertical movement for a sprite.
Exactly the same a movex. See above.
--------------------------------------------------------------------------
void movexon(int spritenum);
Turns horizontal movement for a sprite on.
Example usage:
movexon(3);
--------------------------------------------------------------------------
void movexoff(int spritenum);
Turns horizontal movement for a sprite off.
Example usage:
movexoff(3);
--------------------------------------------------------------------------
void moveyon(int spritenum);
Turns vertical movement for a sprite on.
Example usage:
moveyon(3);
--------------------------------------------------------------------------
void moveyoff(int spritenum);
Turns vertical movement for a sprite off.
Example usage:
moveyoff(3);
--------------------------------------------------------------------------
int overlap(int spritenum 1,int spritenum 2);
Tests if two sprites overlap each other on the screen.
They both must be turned on.
Returns 1 if they are overlapping.
(Used for detecting collisions)
--------------------------------------------------------------------------
**************************************************************************
The sprite library uses the following variables:
int spon=15; - the highest sprite number used in your program
(may be up to 40)
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
A large structure contains all data about the sprites:
typedef struct {
unsigned char 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 spritescreen, 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. See breakout.c for an example of this.
The sprite library is designed for use with non-changing backgrounds.
If you need to change the background, you must use the above technique
to copy the area modified. Future versions will provide more control
over this problem.