Intro: understanding film
=========================

You know what a film is. Yes, exactly this is it.
You cannot create it, only load it from a file.
You start it and can only watch it and hope, one day it is over.
Not exactly, there is a possibility to stop or pause it with a subfunction
you pass as a parameter when starting the film.


Files of a film

A film consists of
 - one film-file
 - some picture-files
The film-file defines when which picture-files are to be loaded.
The picture-file draws pictures to your window and optionally starts a sound.
Additionally in both film-file and picture-file you can declare a loop.
And you can pass parameters from the film-file to a picture-file.
With these possibilities you can reduce the number of your picture-files,
if you are clever.


Format of a film-file

A film-file has:
 - "[FILM " <milliseconds for each loop> "]"
 - one call to a picture-file every line, optionally with a loop
   <number of repeats> <picture-file> [<parameter 1> ... [<parameter 9>]]
   comments begin with "#"

The "milliseconds for each loop" is a number, which is passed as an argument
to vg_wait_time() defining the film speed,
this means how many milliseconds a picture-file is shown.

The "number of repeats" is a number, how often to call this picture-file, and
in the picture-file you get this repeat-number with "$0".
The picture-file is relative not to your game-directory as all other filenames,
but to the location of your film-file.

The optional parameters 1 to 9 are numbers or strings, you get them in the
picture-file with "$1" to "$9".
The references $0 and $1 to $9 can be used in a formula, if they are numbers,
e.g. 320 - $1 * 2.


Format of a picture-file

This is the file, which draws one picture of the film (consisting of one
or bitmaps) to your window.
Its format:
 - once you can (but need not) define:
   + # base coordinates at (x,y) for all bitmap-/sprite-output
     # default: base(0,0)
     base(<x>,<y>)
   + # how many film-loops this picture-file remains
     # default: loop(1)
     loop(<number of loops>)
   + # load a different colormap
     # default: use current colormap
     colormap(<colormap-file>)
   + # set brightness (-62 to 63)
     # default: use current brightness
     brightness(<number>)
   + # at first clear the window with color-index
     # default: don't clear window
     clear(<color-index>)
 - more than once you can (but need not) define:
   + # show bitmap at (x,y), full or transparent output,
     # "bitmap-file" is relative to picture-file, not to your game-directory
     bitmap(<x>,<y>,<"full"|"trans">) <bitmap-file>
   + # show sprite at (x,y), full or transparent output,
     # with vg_sprite_getcurrent() or vg_sprite_getnext()
     # "sprite-file" is relative to picture-file, not to your game-directory
     sprite(<x>,<y>,<"full"|"trans">,<"current"|"next">) <sprite-file>
   + # start sound
     # play it once or in an endless loop (until stop or end of film)
     # "sound-file" is relative to picture-file, not to your game-directory
     soundstart(<"once"|"loop">,<volumepercent 0-200>) <sound-file>
   + # stop sound
     # "sound-file" is relative to picture-file, not to your game-directory
     soundstop() <sound-file>


Example

Your game's name is "mygame".
Your film-filename is "film1.film" and is located under "films/".
All related bitmaps for this film are under "films/bitmaps/".
All related sprites for this film are under "films/sprites/".
All related sounds for this film are under "films/sounds/"
You see a helicopter flying from right to left.
The speed of the film is 40 milliseconds for each loop.
Your path:
  mygame/
  mygame/films/film1.film
  mygame/films/film1.pic1
  mygame/films/film1.pic2
  mygame/films/sprites/propellor.sprite
  mygame/films/bitmaps/propellor.vga
  mygame/films/bitmaps/helicopter.vga
  mygame/films/sounds/motor.wav
Your propellor.sprite:
  (refer to intro-sprite.html)
  [SPRITE]
  ../bitmaps/propellor.vga LOOP=1
  ../bitmaps/propellor.vga LOOP=1 ROTATE=45
  ../bitmaps/propellor.vga LOOP=1 ROTATE=90
  ../bitmaps/propellor.vga LOOP=1 ROTATE=135
Your film1.film:
  [FILM 40]
  1 film1.pic1 loop  # start looping sound
  320 film1.pic2  # draw helicopter, repeating 320 times, using $0 in film.pic2
Your film1.pic1:
  # start motor-sound, using parameter 1 ("once" or "loop")
  soundstart($1,100) sounds/motor.wav
Your film1.pic2:
  # clear window with color-index 0
  clear(0)
  # copy helicopter.vga to x-position 320-$0 (where $0 is 1 to 320)
  bitmap(320-$0,100,trans) bitmaps/helicopter.vga
  # copy rotating propellor onto helicopter
  sprite(320-$0,100,trans,next) sprites/propellor.sprite


Play the film

With vg_film_play() you load and play the film.



FUNCTIONS

vg_film_play()
vg_film_position()

Back to Index