## BModule Internal API

BModule Internal API — the internal API for users of BModules

## Synopsis

    BModule*    b_module_new                    (GType module_type,
                                                 gint width,
                                                 gint height,
                                                 guchar *buffer,
                                                 BModulePaintCallback paint_callback,
                                                 gpointer paint_data,
                                                 GError **error);
    void        b_module_set_aspect             (BModule *module,
                                                 gdouble aspect_ratio);
    gboolean    b_module_prepare                (BModule *module,
                                                 GError **error);
    void        b_module_relax                  (BModule *module);
    void        b_module_start                  (BModule *module);
    void        b_module_stop                   (BModule *module);
    void        b_module_event                  (BModule *module,
                                                 BModuleEvent *event);
    gint        b_module_tick                   (BModule *module);
    void        b_module_describe               (BModule *module,
                                                 gchar **title,
                                                 gchar **description,
                                                 gchar **author);

## Description

## Details

### b_module_new ()

    BModule*    b_module_new                    (GType module_type,
                                                 gint width,
                                                 gint height,
                                                 guchar *buffer,
                                                 BModulePaintCallback paint_callback,
                                                 gpointer paint_data,
                                                 GError **error);

This function tries to create the class for the `module_type` and queries it with the given width and height. Only if the class can handle the requested size, a BModule instance is created and initialized with the given values.

`module_type` : | the type of module to create
`width` : | width of the frame buffer
`height` : | height of the frame buffer
`buffer` : | pointer to a preallocated buffer or `NULL`
`paint_callback` : | the function to call in b_module_paint()
`paint_data` : | data to pass to the `paint_callback`
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | the newly allocate BModule object

### b_module_set_aspect ()

    void        b_module_set_aspect             (BModule *module,
                                                 gdouble aspect_ratio);

Sets the pixel (or window) aspect ratio for the `module`. Most modules ignore this value but some may adapt their output to take the shape of pixels into account.

`module` : | a BModule object
`aspect_ratio` : | the new pixel aspect ratio (x / y)

### b_module_prepare ()

    gboolean    b_module_prepare                (BModule *module,
                                                 GError **error);

This function first queries the module once more to check that it can handle the current settings. If the query succeeds, the prepare() method of the module is called. The module should then prepare itself and will be able to start as soon as b_module_start() is called.

`module` : | a BModule object
`error` : | location to store the error occuring, or `NULL` to ignore errors
Returns : | `TRUE` is the module has successfully prepared itself, `FALSE` otherwise

### b_module_relax ()

    void        b_module_relax                  (BModule *module);

Calls the relax() method of the `module` causing it to release resources allocated in b_module_prepare().

`module` : | a BModule object

### b_module_start ()

    void        b_module_start                  (BModule *module);

Emits the start signal for `module`. If `module` has a lifetime set, a timer is installed that stops the module when the lifetime expires.

You need to prepare `module` by calling b_module_prepare() before it can be started.

`module` : | a BModule object

### b_module_stop ()

    void        b_module_stop                   (BModule *module);

Emits the stop signal for `module`. You may only call this function for a BModule that is currently running.

`module` : | a BModule object

### b_module_event ()

    void        b_module_event                  (BModule *module,
                                                 BModuleEvent *event);

Dispatches an event to `module` by calling its event() method with `event`. This function has no effect if the module is not currently running.

`module` : | a BModule object
`event` : | pointer to a BModuleEvent

### b_module_tick ()

    gint        b_module_tick                   (BModule *module);

Calls the tick() method of `module`. You may only call this function for a BModule that is currently running.

`module` : | a BModule object
Returns : | the number of milliseconds until tick() should be called again or -1 to indicate that no further ticks are requested

### b_module_describe ()

    void        b_module_describe               (BModule *module,
                                                 gchar **title,
                                                 gchar **description,
                                                 gchar **author);

This function queries `module` for a title, description and the name of the author. It does so by calling the modules describe() method. You may pass `NULL` as return location if you are not interested in a particular information. The `title` is guaranteed to be available, `description` and `author` may be `NULL` if the module doesn't provide this information.

You must free all returned strings using g_free() if you don't need them any longer.

`module` : | a BModule object
`title` : | return location for the module title or `NULL`
`description` : | return location for the module description or `NULL`
`author` : | return location for the name of the module author or `NULL`