VgaGames 3 - Animation man-pages

[.. upper level ..]

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
VG3_sprite_new() VG3_sprite_clone() VG3_sprite_free()