Intro: understanding sprites
============================

Sprites are animated bitmaps.
For example, if you want to give out a rotating propellor, it can be very
annoying to draw it in the first three game-loops rotated at 30 degrees, in the
second three game-loops rotated at 60 degrees and so on.
Sprites make this work for you. You only put out the actual bitmap of the
sprite and can forget all the other stuff.

You can load a sprite from a file or create it new.
You can add sprite-elements into a sprite.


Format of a sprite-file

A sprite-file, where to load a sprite from, is a text file with:
 - "[SPRITE]" (to recognize a sprite-file)
 - one sprite-element every line:
   <bitmap-file> [<some arguments>]
   arguments:
     "LOOP"=<number of game-loops>
     "ZOOM"=<x-zoom>,<y-zoom>
     "ROTATE"=<degrees>
     "MIRROR"=<number: 1=vertically or 2=horizontally>
     "SOUND"=<sound-filename>
     "SNDVOL"=<sound-volume from 0 to 200, where 100=default>
   comment lines begin with "#"

 e.g.: bird.vga LOOP=3 MIRROR=1


Creating a sprite-file

You have to create a sprite-file by hand.
For sprite-elements: The bitmap-file and sound-filename are relative not to
                     your game-directory as all other filenames, but to the
                     location of your sprite-file.


Example

Your game's name is "mygame".
Your sprite-filename is "sprite1.sprite" and is located under "sprites/".
The sprite is showing a rotating propellor,
and the propellor-bitmap-file is located under "bitmaps/".
Your path:
  mygame/
  mygame/bitmaps/propellor.vga
  mygame/sprites/sprite1.sprite
Your sprite1.sprite:
  [SPRITE]
  # show propellor not-rotated three game-loops
  ../bitmaps/propellor.vga LOOP=3
  # show propellor rotated at 30 degrees three game-loops
  ../bitmaps/propellor.vga LOOP=3 ROTATE=30
  # and so on
  ../bitmaps/propellor.vga LOOP=3 ROTATE=60
  ../bitmaps/propellor.vga LOOP=3 ROTATE=90
  ../bitmaps/propellor.vga LOOP=3 ROTATE=120
  ../bitmaps/propellor.vga LOOP=3 ROTATE=150
  ../bitmaps/propellor.vga LOOP=3 ROTATE=180
  ../bitmaps/propellor.vga LOOP=3 ROTATE=210
  ../bitmaps/propellor.vga LOOP=3 ROTATE=240
  ../bitmaps/propellor.vga LOOP=3 ROTATE=270
  ../bitmaps/propellor.vga LOOP=3 ROTATE=300
  ../bitmaps/propellor.vga LOOP=3 ROTATE=330

What happens?
Every time you call vg_sprite_getnext(), you get a pointer to the next bitmap.
You call vg_sprite_getnext() 3 times and get the propellor not-rotated.
You call it 3 times again and get the propellor rotated at 30 degrees.
At last you get it rotated 330 degrees.
When you call vg_sprite_getnext() again, you get NULL, which indicates the
end of the sprite. But don't get worried, simply call vg_sprite_getnext()
once more and it continues at the beginning.
If there was defined a sound, it will be played automatically when calling
vg_sprite_getnext().

With vg_sprite_getcurrent() you get the pointer from the last
call to vg_sprite_getnext() without incrementing the loop counter.
This is useful, if you have to get the pointer to the bitmap again,
e.g. because you want to draw this sprite twice or more. If you called
vg_sprite_getnext() instead, the animation would be two or more times as quick.



FUNCTIONS

vg_sprite_createnew()
vg_sprite_createfromfile()
vg_sprite_add()
vg_sprite_duplicate()
vg_sprite_rotate()
vg_sprite_zoom()
vg_sprite_mirror()
vg_sprite_getnext()
vg_sprite_getcurrent()
vg_sprite_reset()
vg_sprite_free()

Back to Index