Vgagames: Sprite functions:
===========================

 

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