vg4->film->play()

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

Returns boolean: - VG_TRUE: OK - VG_FALSE: Got exit-request

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