VgaGames4

VgaGames4 - film man-pages

[.. upper level ..]

# vg4->film->play()

Play film.

SYNTAX
VG_BOOL vg4->film->play(const char *dirname, const struct VG_Rect *rect, VG_BOOL *filmskip, struct VG_Hash *hvar)
FUNCTION PARAMETERS

dirname | Directory-name, where film files are located
rect | Rectangle in window where to play film, or NULL = whole window
filmskip | If not NULL allow skipping film by pressing return-key or escape-key and return whether it was skipped
hvar | Hash with variable-values for text control-commands var and for $(<varname>) - hash-key: variable name - hash-value: variable value (string-value) or NULL

RETURN VALUE
Returns boolean: - VG_TRUE: OK - VG_FALSE: Got exit-request
DESCRIPTION
Play film. The film can be paused by pressing spacebar. The film may be skipped when filmskip is not NULL. The files of the film must be located benath a directory. There are following files: - vars (optional) which contains variables with their default values - film (required) which contains global configuration and checkpoints - <filename>.story (at least one file required) which contains the description of the arrangement of contents - image-files, sound- and music-files, text-files ... the contents of the film Format of the file vars: ------------------------ Comments begin with #. Per line: <variable-name>: <variable-default-value> Example: # colors TEXTCOLOR: 0x000088 BGCOLOR: 0x444444 Format of the file film: ------------------------ Comments begin with #. The first line contains the header: [FILM <parameters> ] where <parameters> are space-separated <key>=<value> from following keys: - RESOLUTION=<x>x<y> # e.g. 320x200, missing: no adjustment to window-size - FLOOP=<number> # time for a film-loop in milli-seconds, missing: 100 - FADEOUT=<1 or 0> # whether fade out window at film-end, missing: 0 - BGCOLOR=<color> # background color (0xRRGGBB or transparent), missing: transparent The values of the parameters may use variables $(<variable>). Example: [FILM RESOLUTION=640x480 FADEOUT=1 FLOOP=100] The following lines define the checkpoints: <checkpoint-name>: [<reference-checkpoint> {+|-}] <film-loops> A checkpoint-name must not begin with a digit and may have letters, digits and underscore. Example: CP_START: 0 # starts at begin of the film CP_FOREST_1: CP_START # starts at CP_START, which is begin of the film CP_FOREST_2: CP_FOREST_1 + 200 # starts 200 film-loops after CP_FOREST_1, # which is 200 film-loops after begin of the film Format of the files <filename>.story: ------------------------------------- Comments begin with #. The first line contains the header: [STORY <parameters> ] where <parameters> are space-separated <key>=<value> from following keys: - DRAWLEVEL=<number> # level-number for drawing order # (begins with 1 = lowest level, which is at first drawn), # missing: 1 The values of the parameters may use variables $(<variable>). Example: [STORY DRAWLEVEL=2] The following lines are grouped into blocks with one of following instructions: - CHECK: name of the checkpoint - SOUND: soundfile to play - MUSIC: musicfile to play (only one at the same time) - DRAW: image/sprite/text to draw The order of the blocks in a story-file between check-points is not important, they are executed simultaneously. The story must at least start and end with a checkpoint, but may have more checkpoints included. Nearly each block consists of one or more indented lines with <subkey>: <value> Following applies to a value of a subkey: - it may use variables $(<variable>) - if it is a boolean test: A boolean test may use the internal number $percent (not $(percent)), which is the percent-number (1 to 100) between the actual two checkpoints. Boolean test operators are: -eq (equal) -ne (not equal) -ge (greater equal) -le (lesser equal) -gt (greater) -lt (lesser) They may be set into brackets and combined with || (or) && (and) Example: ($percent -gt 30 && $percent -le 50) || $percent -eq 80 - if it can be a formula: It may use: - addition: + - subtraction: - - multiplication: * - division: / - modulo: % - brackets: () Example: ($percent + 1) * 10 % 5 The instructions in detail: - CHECK: has no subkeys, just name of checkpoint Example: CHECK: CP_FOREST_1 - SOUND: play a sound, it will be at the latest be stopped at end of the story - FILE: filename of soundfile (path relative to story-file) - VALID: (optional:) boolean test, when to start sound Example: SOUND: VALID: $percent -eq 30 || $percent -eq 70 FILE: data/thunder.wav - MUSIC: play music, it will play independendly of the story - FILE: filename of musicfile (path relative to story-file) - START: (optional:) starting time in percent (1 to 100) between the actual two checkpoints, default: 1 - CRESC: (optional:) whether use crescendo: 1=yes, 0=no, default: no - PLAY: (optional:) - LOOPING: play music looping - END: don't stop film until music ended default: missing (play once) Example: MUSIC: FILE: data/bgmusic.mp3 PLAY: LOOPING - DRAW: draw an image - IMAGE or SPRITE or TEXT: filename of image or sprite or textfile - POSX: x-position (value or formula) - POSY: y-position (value or formula) - VALID: (optional:) boolean test, whether relevant - POSALIGN: (optional:) how to interpret POSX/POSY according to VG_POSITIONS: - upper-left - lower-left - upper-right - lower-right - centered (default) - ZOOM: (optional:) percent-value of zooming (value or formula), default 100 - ROTATE: (optional:) rotating in degrees (value or formula), default 0 - BRIGHT: (optional:) brightness in percent (value or formula), default 100 - OPAQUE: (optional:) opaqueness in percent (value or formula), default 100 - FLIP: (optional:) flipping axe (default: empty): - horizontal - vertical Example: # Begin-checkpoint CHECK: CP_START # draw a text centered on a 320x200 window DRAW: VALID: $percent -ge 33 TEXT: data/text.txt POSX: 160 POSY: 100 # draw an image at the upper right corner DRAW: IMAGE: data/image.bmp POSX: 319 POSY: 0 POSALIGN: upper-right # draw a left-rotating image centered DRAW: IMAGE: data/image.bmp POSX: 160 POSY: 100 ROTATE: 45 - ($percent * 2) # End-checkpoint CHECK: CP_END