## BMovie

BMovie — base class for Blinkenlights movies

## Synopsis

    #define     B_MOVIE_MIN_DELAY
    #define     B_MOVIE_DEFAULT_DELAY
    struct      BMovie;
    struct      BMovieFrame;
    #define     B_TYPE_MOVIE_BML
    #define     B_TYPE_MOVIE_BLM
    #define     B_TYPE_MOVIE_GIF
    BMovie*     b_movie_new_from_file           (const gchar *filename,
                                                 gboolean lazy_load,
                                                 GError **error);
    BMovie*     b_movie_new_from_fd             (gint fd,
                                                 GError **error);
    gboolean    b_movie_load                    (BMovie *movie,
                                                 GError **error);
    void        b_movie_unload                  (BMovie *movie);
    gboolean    b_movie_save                    (BMovie *movie,
                                                 FILE *stream,
                                                 GError **error);
    gboolean    b_movie_save_as                 (BMovie *movie,
                                                 GType movie_type,
                                                 FILE *stream,
                                                 GError **error);
    GList*      b_movie_get_frame_at_time       (BMovie *movie,
                                                 GList *seed,
                                                 gint time);
    void        b_movie_prepend_frame           (BMovie *movie,
                                                 gint duration,
                                                 const guchar *data);

## Object Hierarchy

      GObject
       +----BObject
             +----BMovie

## Description

The BMovie class defines a common interface to a Blinkenlights movie. BLib comes with a couple of implementations that correspond to the different file formats. They are referred to by their GType: B_TYPE_MOVIE_BML, B_TYPE_MOVIE_BLM and B_TYPE_MOVIE_GIF.

## Details

### B_MOVIE_MIN_DELAY

    #define B_MOVIE_MIN_DELAY      20

The minimum time for a frame in milliseconds. Shorter frame delays will be set to this value.

### B_MOVIE_DEFAULT_DELAY

    #define B_MOVIE_DEFAULT_DELAY  100

The default time for a frame in milliseconds. Frames with no specified delay will be set to this value.

### struct BMovie

    struct BMovie;

The BMovie struct has various members that may be read directly since not all of them has accessor functions. You must however not change any of the fields.

### struct BMovieFrame

    struct BMovieFrame {

      gint          start;
      gint          duration;
      guchar       *data;
    };

The BMovieFrame struct defines a single movie frame.

gint `start` | the start time of the frame in milliseconds
gint `duration` | the duration of the frame in milliseconds
guchar *`data` | frame data according to the values in the BMovie that owns this frame

### B_TYPE_MOVIE_BML

    #define B_TYPE_MOVIE_BML            (b_movie_bml_get_type ())

Type derived from BMovie that handles movies in the Blinkenlights Markup Language (BML).

### B_TYPE_MOVIE_BLM

    #define B_TYPE_MOVIE_BLM            (b_movie_blm_get_type ())

Type derived from BMovie that handles movies in old-fashioned BLM format.

### B_TYPE_MOVIE_GIF

    #define B_TYPE_MOVIE_GIF            (b_movie_gif_get_type ())

Type derived from BMovie that handles movies in the GIF format.

### b_movie_new_from_file ()

    BMovie*     b_movie_new_from_file           (const gchar *filename,
                                                 gboolean lazy_load,
                                                 GError **error);

Tries to load a BMovie from the file pointed to by `filename`. If `lazy_load` is `TRUE`, only the header is loaded and no frames are stored.

`filename` : | the name of the file to load
`lazy_load` : | whether to do lazy-loading, i.e. only load the header
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | a newly allocated BMovie object or `NULL` if the load failed

### b_movie_new_from_fd ()

    BMovie*     b_movie_new_from_fd             (gint fd,
                                                 GError **error);

Tries to load a BMovie from the UNIX file descriptor `fd`. Lazy loading from file descriptors is not implemented since it doesn't seem to make much sense.

`fd` : | a UNIX file descriptor
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | a newly allocated BMovie object or `NULL` if the load failed

### b_movie_load ()

    gboolean    b_movie_load                    (BMovie *movie,
                                                 GError **error);

Assures that the frames of the `movie` are loaded.

`movie` : | a BMovie object
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` if the movie was loaded successfully.

### b_movie_unload ()

    void        b_movie_unload                  (BMovie *movie);

Unloads the frames of a movie.

The movie object counts how many times you call b_movie_load() and b_movie_unload() and only really unloads the frames if b_movie_unload() was called as often as b_movie_load(). Note that b_movie_new_from_file() and b_movie_new_from_fd() call b_movie_load() unless lazy-loading was requested.

`movie` : | a BMovie object

### b_movie_save ()

    gboolean    b_movie_save                    (BMovie *movie,
                                                 FILE *stream,
                                                 GError **error);

Saves a BMovie object to a `stream`.

`movie` : | a BMovie object
`stream` : | a FILE stream ready for writing
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` on success or `FALSE` otherwise

### b_movie_save_as ()

    gboolean    b_movie_save_as                 (BMovie *movie,
                                                 GType movie_type,
                                                 FILE *stream,
                                                 GError **error);

Saves a BMovie object to a `stream` and allows to specify the file format to use.

The format is specified by passing a type derived from B_TYPE_MOVIE as `movie_type`. At the moment B_TYPE_MOVIE_BML, B_TYPE_MOVIE_BLM and B_TYPE_MOVIE_GIF are supported types.

`movie` : | a BMovie object
`movie_type` : | the movie type to use for saving
`stream` : | a FILE stream ready for writing
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` on success or `FALSE` otherwise

### b_movie_get_frame_at_time ()

    GList*      b_movie_get_frame_at_time       (BMovie *movie,
                                                 GList *seed,
                                                 gint time);

Looks for the frame active after `time` milliseconds.

If you are calling this function subsequentially with increasing time values, you can speed up the search by passing the last return value as the `seed` parameter.

`movie` : | a loaded BMovie object
`seed` : | an optional GList pointer that can speed up the search
`time` : | the time in milliseconds
Returns : | a GList pointer that has the frame as data or `NULL` if the time was out of the `movie`'s range.

### b_movie_prepend_frame ()

    void        b_movie_prepend_frame           (BMovie *movie,
                                                 gint duration,
                                                 const guchar *data);

This is an internal function used by the movie loaders. It should never be called from anywhere else.

`movie` : |
`duration` : |
`data` : |