VG3_sprite_load()
Load an animated sprite from file.SYNTAX
struct vg3_sprite *
VG3_sprite_load(struct vg3_window *wstruct,
const char *filename)
FUNCTION PARAMETERS
wstruct | Window-struct |
filename | Sprite file |
RETURN VALUE
Returns a pointer to the loaded sprite or NULL on failure.
ERRORS
On error VG3_errmsg() returns:
EINVAL - error in argument
EIO - file corrupt
ERANGE - function value error
DESCRIPTION
Load an animated sprite from file and return pointer to it.
A sprite file is a text file:
Comments begin with "#".
The first line with "[SPRITE]" defines common parameters:
- parameters
- LOOP: default number of game-loops for each sprite element
- LIFETIME: how often to repeat the sprite before end, or 0 = do not end
- SNDWAIT: whether all sounds of the sprite must be played before it ends or repeats
- examples
- [SPRITE]
- [SPRITE LOOP=5]
- [SPRITE LOOP=5 LIFETIME=0]
- [SPRITE LOOP=5 LIFETIME=3 SNDWAIT=1]
There must be no spaces around "="
The following blocks of lines describe in each case a sprite element.
Each sprite element is described by a set of keys and values.
Each key is at one line,
- the first key is at the beginning of the line
- the following keys are indented
All keys are optional.
Following keys are defined:
- REPEAT: a number
How often to repeat this element before going to the next one.
This sets the variable ${repeat} from 1 to REPEAT
- LOOP: a number or a formula
number of game-loops for this element or 0 = use default LOOP number
- BMP: a filename (with path), relative to the path of the sprite file
image file to show
(this key may be repeated,
useful within a REPEAT to show repeatedly a list of images)
- ZOOM: a number or a formula
zoom factor of the image (refer to struct vg3_image_attributes)
- ROTATE: a number or a formula
rotating degrees of the image (refer to struct vg3_image_attributes)
- FLIP: a number or a formula
flipping of the image (refer to struct vg3_image_attributes)
- BRIGHT: a number or a formula
brightness of the image (refer to struct vg3_image_attributes)
- ALPHA: a number or a formula
transparency of the image (refer to struct vg3_image_attributes)
- SOUND: a filename (with path), relative to the path of the sprite file
audio file to play
only wave- and flac-files are allowed
- SNDVOL: a number or a formula
volume of the sound (0 to 255), default = 100
A formula uses the variable ${repeat} and can use
- addition: +
- subtraction: -
- multiplication: *
- division: /
- modulo: %
- brackets: ()
Example:
[SPRITE LOOP=2]
# show images/img1.bmp for 8 game-loops instead of 2
BMP = images/img1.bmp
LOOP = 8
# play a sound at default volume, and show no image
SOUND = sounds/snd1.wav
# rotate images/img1.bmp from 359 to 0 degrees counterclockwise
REPEAT = 360
BMP = images/img1.bmp
ROTATE = 360 - ${repeat}
# show alternately images/img1.bmp and images/img2.bmp for 3 times, each for 8 loops
REPEAT = 3
BMP = images/img1.bmp
BMP = images/img2.bmp
LOOP = 8
SEE ALSO