Overview
--------
A sprite is an animated graphic, consisting of various single graphics.
With function next_sprite() called once in a game loop for a specific sprite
a pointer of one of these single graphics is given back to be put out.
E.g.: a sprite consists of 3 graphics,
all are defined to be shown 2 loops,
now calling next_sprite() again and again:
(1): you get the 1st graphic
(2): you get the 1st graphic
(3): you get the 2nd graphic
(4): you get the 2nd graphic
(5): you get the 3rd graphic
(6): you get the 3rd graphic
(7): you get the 1st graphic
and so on
The functions
-------------
sprite * create_sprite():
create an empty sprite.
This function is an alternative to load_sprite()/rotate_sprite()/zoom_sprite().
Return value: not NULL=allocated sprite
NULL=error
Example:
sprite * spr1;
// create empty sprite
spr1=create_sprite();
if (spr1==NULL) { [...error...] }
sprite * load_sprite(const char * arg1):
load a sprite from a file, it does the same as create_sprite() and
various calls to add_grafik_to_sprite().
This function is an alternative to create_sprite()/rotate_sprite()/zoom_sprite().
Arguments:
- arg1: filename of the sprite file
Return value: not NULL=loaded sprite
NULL=error
Note: A sprite file is nothing else than a text file with information
which graphic is to be loaded, how long to be shown and so on.
Such a file must be created manually.
The sprite file must have following format:
1. line: "[SPRITE]"
following lines: <graphic file>;<loops>[;ZOOM=<x-zoom>,<y-zoom>][;ROTATE=<degrees>]
Each line represents one graphic of the sprite. Elements are:
<graphic file> is the graphic, it is loaded from the path,
where the sprite file is
<loops> integer value, how many calls
to next_sprite() give back this graphic
ZOOM=<x-zoom>,<y-zoom> optional, how to zoom graphic
in x direction and y direction
ROTATE=<degrees> optional, how to rotate graphic
at given degrees
Comment lines begin with `#'.
Example sprite file:
The sprite file is "/usr/local/game/mygame/sprites/test.sprite"
and contains following lines:
[SPRITE]
pict1.vga;5
../vga/pict2.vga;17;ROTATE=90
/usr/vga/pict3.vga;10;ZOOM=1.5,1.0
pict4.vga;3;ZOOM=0.5,0.5;ROTATE=270
pict5.vga;0
--> 1.line is "[SPRITE]"
2.line shows graphic "/usr/local/game/mygame/sprites/pict1.vga"
for 5 loops
3.line shows graphic "/usr/local/game/mygame/vga/pict2.vga"
rotated at 90 degrees
for 17 loops
4.line shows graphic "/usr/vga/pict3.vga"
zoomed 1.5 in x direction and original size in y direction
for 10 loops
5.line shows graphic "/usr/local/game/mygame/sprites/pict4.vga"
zoomed 0.5 in x direction and 0.5 in y direction
and rotated at 270 degrees
for 3 loops
6.line shows graphic "/usr/local/game/mygame/sprites/pict5.vga"
not at all
Example:
sprite * spr1;
// load sprite
spr1=load_sprite("/usr/local/game/mygame/sprites/test.sprite");
if (spr1==NULL) { [...error...] }
sprite * rotate_sprite(sprite * arg1,int arg2):
create a new sprite from another existing sprite, rotated at certain degrees
This function is an alternative to create_sprite()/load_sprite()/zoom_sprite().
Arguments:
- arg1: existing sprite
- arg2: degrees to rotate arg1 clockwise (-360 to 360)
Return value: not NULL=allocated rotated sprite
NULL=error
Example:
sprite * spr1,* spr2;
// load sprite
spr1=load_sprite("/usr/local/game/mygame/sprites/test.sprite");
if (spr1==NULL) { [...error...] }
// rotate sprite 90 degrees clockwise
spr2=rotate_sprite(spr1,90);
if (spr2==NULL) { [...error...] }
sprite * zoom_sprite(sprite * arg1,float arg2,float arg3):
create a new sprite from another existing sprite, zoomed greater or smaller
This function is an alternative to create_sprite()/load_sprite()/rotate_sprite().
Arguments:
- arg1: existing sprite
- arg2: horizontal zooming factor (x direction), where 1.0 is original size
- arg3: vertical zooming factor (y direction), where 1.0 is original size
Return value: not NULL=allocated zoomed sprite
NULL=error
Example:
sprite * spr1,* spr2;
// load sprite
spr1=load_sprite("/usr/local/game/mygame/sprites/test.sprite");
if (spr1==NULL) { [...error...] }
// zoom sprite x and y half size
spr2=zoom_sprite(spr1,.5,.5);
if (spr2==NULL) { [...error...] }
int add_grafik_to_sprite(sprite * arg1,grafik * arg2,int arg3,int arg4,int arg5,int arg6,int arg7):
Add a graphic to a sprite. This function is called for each graphic after
call to create_sprite().
(Every line of a sprite file (see load_sprite()) represents a call to
add_grafik_to_sprite().)
Arguments:
- arg1: created sprite
- arg2: graphic box
- arg3: start x coordinates of graphic to copy to sprite or 0
- arg4: start y coordinates of graphic to copy to sprite or 0
- arg5: width of graphic to copy to sprite or 0=whole width
- arg6: height of graphic to copy to sprite or 0=whole height
- arg7: how many calls to next_sprite() give back this graphic
Return value: >0 = OK (position of graphic in sprite)
-1 = error
Note: The size of the first graphic which is added to a sprite is saved
as original size (width and height). All following graphics,
which of course can have other width and height,
use this original size to correct their x,y-coordinates
when you call next_sprite() (see next_sprite()).
Note: the graphic is copied into the sprite as a duplicate, therefore
you still have to free your arg2 (graphic box) if no longer needed.
Example:
sprite * spr1;
grafik * gr1;
int x,y,w,h;
spr1=create_sprite(); // create empty sprite
if (spr1==NULL) { [...error...] }
[ ... load graphic into gr1 ... ]
// put whole graphic into sprite, set loops to 22
add_grafik_to_sprite(spr1,gr1,0,0,0,0,22);
free_grafik(gr1);
[ ... load another graphic into gr1 ... ]
// put only the middle of the graphic into sprite, set loops to 14
w=GRAFIK_WIDTH(gr1);
h=GRAFIK_HEIGHT(gr1);
x=w/4; // x start position
y=h/4; // y start position
w/=2; // width of graphic to set to sprite
h/=2; // height of graphic to set to sprite
add_grafik_to_sprite(spr1,gr1,x,y,w,h,14);
free_grafik(gr1);
int SPRITE_WIDTH(sprite * arg1)
int SPRITE_HEIGHT(sprite * arg1):
Macros to get width (SPRITE_WIDTH())
and height (SPRITE_HEIGHT()) of a sprite
(which is in fact width and height of the first graphic of the sprite)
Arguments:
- arg1: sprite
Return value: width of sprite (SPRITE_WIDTH())
or height of sprite (SPRITE_HEIGHT())
Example:
sprite * spr1;
int w,h;
spr1=load_sprite("/usr/local/game/mygame/sprites/test.sprite");
if (spr1==NULL) { [...error...] }
w=SPRITE_WIDTH(gr1);
h=SPRITE_HEIGHT(gr1);
grafik * next_sprite(sprite * arg1,int * arg2,int * arg3):
get actual graphic of a sprite (for drawing out).
When all graphics are through, it begins again.
Arguments:
- arg1: created (and filled) sprite
- arg2: return argument:
address for relative x coordinate to put graphic out:
add arg2 to your origin x coordinate
- arg3: return argument:
address for relative y coordinate to put graphic out:
add arg3 to your origin y coordinate
Return value: pointer to actual graphic
or NULL=no graphic available (sprite empty)
Note: Because the graphics of a sprite can have different sizes, use the
return arguments arg2,arg3 to put the graphic out at the same
position.
Example: there are two graphics in a sprite:
1. with width and height 9,9
2. with width and height 5,5
--> the original size is 9,9.
When getting the first graphic arg2,arg3 is 0,0
When getting the second graphic arg2,arg3 is 2,2
--> put it out at x+arg2,y+arg3
e.g. copy_grafik(NULL,x+arg2,y+arg3,grf,0,0,0,0,RGB_TRANS)
Example:
sprite * spr1;
grafik * gr1;
int x,y;
spr1=load_sprite("/usr/local/game/mygame/sprites/test.sprite");
if (spr1==NULL) { [...error...] }
[ ... ]
// get actual graphic and put it to the backbuffer at 10,10
// with x,y all graphics will be concentric
gr1=next_sprite(spr1,&x,&y);
copy_grafik(NULL,10+x,10+y,gr1,0,0,0,0,RGB_TRANS);
grafik * last_sprite(sprite * arg1,int * arg2,int * arg3):
get graphic of last call to next_sprite() again.
It is the same as next_sprite() but without incrementing the loop counter.
Arguments (the same as in next_sprite()):
- arg1: created (and filled) sprite
- arg2: return argument:
address for relative x coordinate to put graphic out:
add arg2 to your origin x coordinate
- arg3: return argument:
address for relative y coordinate to put graphic out:
add arg3 to your origin y coordinate
Return value: pointer to actual graphic
or NULL=no graphic available (sprite empty or after a call
to reset_sprite())
int reset_sprite(sprite * arg1):
reset a sprite to the beginning (to give back first graphic when next
calling next_sprite()) and return loop sum
Arguments:
- arg1: created (and filled) sprite
Return value: loop sum of the whole sprite
Note: the loop sum can be used as a counter, if a sprite shall be given
out only once (if you don't want to begin again, when all graphics
are given back)
void free_sprite(sprite * arg1):
destroy sprite and free memory
Arguments:
- arg1: sprite
Home | Previous: Graphic box functions | Next: Color functions