VG3_film_play()

int VG3_film_play(struct vg3_window *wstruct, struct vg3_multilang *mlang, const char *filename, int skip)

Returns integer: - 0: OK - 1: Got request for closing the window and exiting the game - 2: OK, but cancelled by user

Load a film from file and play it. A film is described by one film file and more or less film picture files. Both are text files. Comments begin with "#". Film file: The first line with "[FILM]" defines common parameters: - parameters - FREQ: duration of a film loop in milliseconds - MUSIC: music file to play, optionally after a colon with an integer whether to play it only once optionally after another colon with an integer whether to wait for its end - BG: file for background image - examples - [FILM] - [FILM FREQ=50 BG=images/bg.bmp] - [FILM FREQ=50 MUSIC=sound/music.wav] - [FILM FREQ=50 MUSIC=sound/music.wav:1] # play music.wav only once - [FILM FREQ=50 MUSIC=sound/music.wav:1:1] # play once and wait for ending There must be no spaces around "=" The following lines load in each case a film picture: - parameters separated by space - FILMPIC: filename of the film picture (with path), relative to the path of the film file - REPEAT: how often to repeat this film picture before going to the next one. This sets the variable ${repeat} from 1 to REPEAT and the variable ${repeatmax} to REPEAT There must be no spaces around "=" The film file is processed sequentially. As soon as one film picture file has been ended, the next one is loaded. Example: [FILM FREQ=50 MUSIC=sound/music.wav:0] # first film picture FILMPIC=filmpic.1 # next 100 film pictures FILMPIC=filmpic.2 REPEAT=100 Film picture file: The first line with "[FILMPIC]" defines common parameters: - parameters - LOOP: number of film loops for this film picture - examples - [FILMPIC LOOP=3] There must be no spaces around "=" The following blocks of lines describe in each case a film picture element. A film picture element is commonly an image or a sprite or a text with its centered coordinates and attributes, maybe accompanied by playing a sound. Each film picture 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: - VALID: a boolean test whether this film picture element is relevant for now - POSX: a number or a formula x-position of the image or sprite-image - POSY: a number or a formula y-position of the image or sprite-image - BMP: a filename (with path), relative to the path of the film picture file image file to show, instead of key "SPRITE" or "MTEXT" - SPRITE: a filename (with path), relative to the path of the film picture file image of a sprite file to show, instead of key "BMP" or "MTEXT" - MTEXT: a filename (with path), relative to the path of the film picture file (multilanguage)-text to create a text-image to show, instead of key "BMP" or "SPRITE" The format of the file must be: 1.line: <font-file> ":" <foreground-color> ":" <background-color> e.g. font-file: 8x8.font color: 0x<RR><GG><BB>, e.g. 0xffff00 next line(s): text or multilanguage-key for text - 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 film picture file audio file to play once only wave- and flac-files are allowed - SNDVOL: a number or a formula volume of the sound (0 to 255), default = 100 - MUSEND: a number or a formula resulting in 0 or 1 whether fade out background-music - WINBR: a number or a formula brightness of the window (0 to 255), default = 255 There are five variables: - ${repeat}: the actual value of the parameter REPEAT of the film file - ${repeatmax}: the highest value of the parameter REPEAT of the film file - ${winw}: the width of the window in pixels - ${winh}: the height of the window in pixels - ${imgw}: the width of the actual image in pixels (not defined for key VALID) - ${imgh}: the height of the actual image in pixels (not defined for key VALID) A formula uses the variables with - addition: + - subtraction: - - multiplication: * - division: / - modulo: % - brackets: () e.g.: (${repeat} + 1) * 2 A boolean test uses two formulas and consists of - equal: -eq - not equal: -ne - greater equal: -ge - less equal: -le - greater than: -gt - less than: -lt - brackets: () - connecting with AND: && - connecting with OR: || e.g.: (${repeat} + 1) * 2 -gt 50 && ${repeat} -lt 100 Example: [FILMPIC LOOP=1] # this film picture should be repeated at least 75 times # show a sunnyboy sprite walking from left to right # according to the repeated call SPRITE = sprites/sprite.sunnyboy POSX = ${repeat} POSY = 160 # if ${repeat} is between 50 and 75 show another big sunnyboy at the right VALID = ${repeat} -ge 50 && ${repeat} -le 75 SPRITE = sprites/sprite.sunnyboy POSX = 280 POSY = 160 ZOOM = 200 # if ${repeat} is 75 play a sound VALID = ${repeat} -eq 75 SOUND = sounds/snd1.wav