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