NAME
====
  vg_film_play() - load and play a film


SYNOPSIS
========
  int vg_film_play(const char * filename, int (*func)(int))


DESCRIPTION
===========
  Loads the film filename and plays the film.

  filename should use a relative path to the game-directory,
  e.g. your game resides under "mygame/":
    mygame/
    mygame/films/
    ...
  then loading "film1.film" under "films" should use this path:
    films/film1.film

  For the format of the film-file filename refer to Understanding film.
 
  If the parameter (*func) is NULL, no subfunction will be called,
  which means that the film is played until it ends.

  You may include a function in your game "int function(int msec)" and pass
  it as the parameter (*func) to vg_film_play().
  This function is called once every loop of the film.
  There you have the possibility to process keystrokes, e.g. for pausing
  the film or stopping it.
  Additionally in your function you must call the functions
   - vg_window_flush()
   and
   - vg_wait_time() with the parameter msec
  Your function must return
    0=OK
    or
    1=stop the film

  Example for a minimalistic function:
    int subfunction(int msec) {
      vg_window_flush();
      vg_wait_time(msec);
      return(0);
    }


RETURN VALUE
============
  If it succeeds, it returns 0.
  If an error occurs, it returns -1, giving out an error message to stderr.


SEE ALSO
========
  Index
  Understanding film
  vg_film_position()