## BModule

BModule — definition of the Blinkenlights Game API

## Synopsis

    struct      BModule;
    struct      BModuleEvent;
    enum        BModuleEventType;
    enum        BModuleKey;
    gboolean    (*BModulePaintCallback)         (BModule *bmodule,
                                                 guchar *buffer,
                                                 gpointer data);
    void        b_module_ticker_start           (BModule *module,
                                                 gint timeout);
    void        b_module_ticker_stop            (BModule *module);
    void        b_module_request_stop           (BModule *module);
    void        b_module_paint                  (BModule *module);

## Object Hierarchy

      GObject
       +----BModule

## Properties

      "lifetime"             gint                 : Write / Construct
      "speed"                gdouble              : Write / Construct

## Signal Prototypes

    "start"     void        user_function      (BModule *bmodule,
                                                gpointer user_data);
    "stop"      void        user_function      (BModule *bmodule,
                                                gpointer user_data);

## Description

## Details

### struct BModule

    struct BModule;

The BModule struct has a couple of fields that may be read directly from a BModule implementation. You must however not change any members directly. Usually a BModule uses the `width`, `height`, `channels`, `maxval`, `aspect` and `num_players` fields.

The `buffer` variable is the only one a BModule may write to. It does so when it needs to update the frame buffer. It is however recommened to use utility functions like b_module_fill() instead of writing into the `buffer`. All other fields of BModule are considered private.

### struct BModuleEvent

    struct BModuleEvent {

      gint             device_id;
      BModuleEventType type;
      BModuleKey       key;
    };

The BModuleEvent struct defines an event delivered to a BModule. The `key` field is only valid if the type is `B_EVENT_TYPE_KEY`. More field may be added when new event types are added.

gint `device_id` | the event source
BModuleEventType `type` | the type of event
BModuleKey `key` | the key

### enum BModuleEventType

    typedef enum
    {
      B_EVENT_TYPE_UNKNOWN = 0,
      B_EVENT_TYPE_KEY,
      B_EVENT_TYPE_PLAYER_ENTERED,
      B_EVENT_TYPE_PLAYER_LEFT
    } BModuleEventType;

This enumeration classifies an event into a number of types.

### enum BModuleKey

    typedef enum
    {
      B_KEY_0,
      B_KEY_1,
      B_KEY_2,
      B_KEY_3,
      B_KEY_4,
      B_KEY_5,
      B_KEY_6,
      B_KEY_7,
      B_KEY_8,
      B_KEY_9,
      B_KEY_HASH,
      B_KEY_ASTERISK
    } BModuleKey;

Enumeration of the possible key values in an event of type `B_EVENT_TYPE_KEY`.

### BModulePaintCallback ()

    gboolean    (*BModulePaintCallback)         (BModule *bmodule,
                                                 guchar *buffer,
                                                 gpointer data);

A callback that is registered when a BModule is created using b_module_new(). It is called from b_module_paint() and typically causes a Blinkenlights frame packet to be emitted. You don't need to care about this if you are implementing a BModule.

`bmodule` : |
`buffer` : |
`data` : |
Returns : |

### b_module_ticker_start ()

    void        b_module_ticker_start           (BModule *module,
                                                 gint timeout);

Starts a timeout for `module` that will call cause its tick() method to be called in `timeout` milliseconds. The return value of the tick() method is then used to install a new timeout for `module`. This proceeds until the tick() method returns -1, b_module_ticker_stop() is called or the module is stopped.

You may only call this function for a BModule that is currently running.

`module` : | a BModule object
`timeout` : | the timeout interval in milliseconds

### b_module_ticker_stop ()

    void        b_module_ticker_stop            (BModule *module);

Stops the ticker for `module`. If there is a pending timeout for `module`, it is removed.

You may only call this function for a BModule that is currently running.

`module` : | a BModule object

### b_module_request_stop ()

    void        b_module_request_stop           (BModule *module);

This function causes the module to be stopped. This is for example used when a game module decides that the game is over.

You may only call this function for a BModule that is currently running.

`module` : | a BModule object

### b_module_paint ()

    void        b_module_paint                  (BModule *module);

This function causes a repaint of the screen.

`module` : | a BModule object

## Properties

"`lifetime`" (gint : Write / Construct) | Maximum time a module is allowed to run (in milliseconds).
"`speed`" (gdouble : Write / Construct) | Allows to tune the playback speed.

## Signals

### The "start" signal

    void        user_function                  (BModule *bmodule,
                                                gpointer user_data);

`bmodule` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "stop" signal

    void        user_function                  (BModule *bmodule,
                                                gpointer user_data);

`bmodule` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.