HOME / BRAWL

`brawl:device/matrix`

Overview

The brawl:device/matrix interface defines a portable, minimal LED Matrix API for WebAssembly (WASM) modules. It provides a consistent way to control LED Matrix arrays across diverse embedded targets - ranging from microcontrollers to emulators - while remaining fully compatible with the WASM MVP specification.

Each function follows a simple convention: it returns a signed 32-bit integer, where negative values represent standardized error codes and non-negative values represent valid results or success indicators. This design keeps the ABI deterministic, low-overhead, and portable between environments, enabling WASM applications to interact directly with LED Matrix devices without callbacks, threads, or host-specific extensions.

Implementation Notes

This section outlines the expected behavior and conventions used by the brawl:device/matrix interface. It provides guidance for both host implementers and guest developers to ensure consistent behavior across WASM targets. The underlying implementation (LED Matrix driver) is abstracted from the caller and managed by the host driver.

LED Matrix Dimensions

matrixDimensions() returns the width and height of the LED Matrix array packed into an i32. The high word contains the width whilst the lower word contains the height. To extract the width and height can be done as shown below:

int32_t dims = matrixDimensions();
if (dims >= 0) {
    int32_t width  = (dims >> 16) & 0xFFFF;
    int32_t height =  dims        & 0xFFFF;
}

Operation

To initialize and begin using the LED Matrix, simply call the function matrixInit() - this will initialize the underlying LED Matrix controller and configure background services required for its operation on the host environment. This function should be called before utilizing any other functions, or an MATRIX_ERROR_NOT_INITIALIZED error will be returned.

Individual LED Control

To change the state of individual LED elements within the LED Matrix, use the functions matrixOn() and matrixOff() to toggle between on and off. To clear and to stop any animations on the LED Matrix, simply call the matrixClear() function.

Loading Pixels

The matrixLoadPixels(mem_ptr, width, height) function takes an array of uint8_t elements, where a non zero value represents a pixel being ON and a zero value being OFF. The width and height should match the dimensions of the LED Matrix, on success - the host renders the LED Matrix immediately and stops any current animation.

uint8_t pixels[] = {
    0, 0, 0, 1, 1, 0, 0, 0,
    0, 0, 1, 0, 0, 1, 0, 0,
    0, 1, 0, 0, 0, 0, 1, 0,
    0, 1, 0, 0, 0, 0, 1, 0,
    0, 1, 1, 1, 1, 1, 1, 0,
    0, 1, 0, 0, 0, 0, 1, 0,
    0, 1, 0, 0, 0, 0, 1, 0,
    0, 0, 0, 0, 0, 0, 0, 0
};

matrixInit();
matrixClear();
matrixLoadPixels((int32_t)(uintptr_t)pixels, 8, 8);

The above example (pseudo code) will load the glyph A to an device that provides 8x8 LED Matrix.

Animation Frames

The matrixLoadFrames(mem_ptr, count) reads back-to-back frames from guest memory and transforms as required to the host memory requirements. Each frame consists of bitmap data (packed uint32_t words, row-major, padded to 32-bits), followed by a uint32_t value representing the duration in milliseconds between frames.

Lets consider the 'A' glyph shown earler, and how this would map into packed data (pseudo code).

//  0, 0, 0, 1, 1, 0, 0, 0  == 0x18
//  0, 0, 1, 0, 0, 1, 0, 0  == 0x24
//  0, 1, 0, 0, 0, 0, 1, 0  == 0x42
//  0, 1, 0, 0, 0, 0, 1, 0  == 0x42  // first uint32_t
//
//  0, 1, 1, 1, 1, 1, 1, 0  == 0x7E
//  0, 1, 0, 0, 0, 0, 1, 0  == 0x42
//  0, 1, 0, 0, 0, 0, 1, 0  == 0x42
//  0, 0, 0, 0, 0, 0, 0, 0  == 0x00  // second uint32_t

uint32_t frame_A[] = {
    0x18244242, 0x7E424200, 100      // 8x8 pixel data, 100 ms duration
};

matrixInit();
matrixLoadFrames((int32_t)(uintptr_t)frame_A, 1);

If more than one frame is defined, playback is initiated by calling matrixPlay(loop), a non zero value will loop the playback of the frames. Individual frames can be loaded via matrixRenderFrame() or move between frames using matrixNext(). At any time, the status of the sequence can be checked via matrixSequenceDone() that will return a non zero value when idle or finished and zero if an animation sequence is still active.

Error Codes

All brawl:device/matrix functions return a signed 32-bit integer (int32_t), which encodes both result and error information:

Value
`ret < 0`	an error occurred.
`ret == 0`	operation completed successfully (or no value to return).
`ret > 0`	operation succeeded and returned a value (e.g., packed dimensions or sequence state).

All memory access operations are bounds-checked by the host; going outside will return a MATRIX_ERROR_MEMORY_OOB error. All coordinate or index operations are bounds-checked by the host; invalid coordinates return a MATRIX_ERROR_INVALID_ARG error.

Constants

Constant
`MATRIX_MAX_FRAMES`	The maximum number of frames supported.

Matrix Errors

All functions return a signed 32-bit integer (int32_t). If the value is negative, it represents an error code from the table below:

Constant
`MATRIX_ERROR_NOT_INITIALIZED`	The LED Matrix module is not initiaized.
`MATRIX_ERROR_INVALID_ARG`	The argument provided was invalid for the operation requested.
`MATRIX_ERROR_MEMORY_OOB`	The requested operation would result in a MEMORY_OOB Error.

Application Programmer Interface (API)

//--------------------------------------------------------------------------
// brawl:device/matrix

#define MATRIX_MAX_FRAMES  16

// MATRIX errors
enum MATRIX_ERROR {
                           // >= 0           no error
  MATRIX_ERROR_NOT_INITIALIZED = -1,      // LED Matrix not initialized
  MATRIX_ERROR_INVALID_ARG     = -2,      // invalid argument
  MATRIX_ERROR_MEMORY_OOB      = -3       // memory out of bounds
};

LED Matrix Dimensions

int32_t // MATRIX_ERROR|int32_t
matrixDimensions(void);

Operation

int32_t // MATRIX_ERROR|void
matrixInit(void);

int32_t // MATRIX_ERROR|void
matrixOn(int32_t x, int32_t y);

int32_t // MATRIX_ERROR|void
matrixOff(int32_t x, int32_t y);

int32_t // MATRIX_ERROR|void
matrixClear(void);

Loading Pixels

int32_t // MATRIX_ERROR|void
matrixLoadPixels(int32_t mem_ptr, int32_t w, int32_t h);

Animation Frames

int32_t // MATRIX_ERROR|void
matrixLoadFrames(int32_t mem_ptr, int32_t count);

int32_t // MATRIX_ERROR|void
matrixRenderFrame(int32_t index);

int32_t // MATRIX_ERROR|void
matrixPlay(int32_t loop);

int32_t // MATRIX_ERROR|void
matrixNext(void);

int32_t // MATRIX_ERROR|int32_t
matrixSequenceDone(void);

//--------------------------------------------------------------------------

Example - Light up Corners on LED Matrix (C)

#include <stdint.h>
#include <stdio.h>

#include "brawl-device-matrix.h"

static void matrix_err(int32_t rc, const char *what) {
    if (rc < 0) fprintf(stderr, "%s failed: %d\n", what, rc);
}

int main() {

    int32_t dims, width, height;
    int32_t rc;

    // get the matrix dimensions
    dims   = matrixDimensions();
    if (dims < 0) { matrix_err(dims, "matrixDimensions"); return 1; }
    width  = (dims >> 16) & 0xFFFF;
    height =  dims        & 0xFFFF;

    // initialize and clear the LED Matrix
    rc = matrixInit();
    if (rc < 0) { matrix_err(rc, "matrixInit"); return 1; }
    rc = matrixClear();
    if (rc < 0) { matrix_err(rc, "matrixClear"); return 1; }

    // highlight the corner LEDs (guard against 0-sized matrices)
    if ((width > 0) && (height > 0)) {
        rc = matrixOn(0,       0);
        if (rc < 0) { matrix_err(rc, "matrixOn"); return 1; }
        rc = matrixOn(width-1, 0);
        if (rc < 0) { matrix_err(rc, "matrixOn"); return 1; }
        rc = matrixOn(0,       height-1);
        if (rc < 0) { matrix_err(rc, "matrixOn"); return 1; }
        rc = matrixOn(width-1, height-1);
        if (rc < 0) { matrix_err(rc, "matrixOn"); return 1; }
    }

    return 0;
}

Revision

2025-10 (draft)

last modified: Oct 18, 2025