@emeraldproductions/fwb

The Emerald Whiteboard Protocol library is a WebAssembly-powered toolkit designed for high-performance manipulation of pixel grids, drawing primitives, and managing a color shader. Ideal for collaborative whiteboard applications or pixel-based graphics rendering.

Features

• PixelBox: Manage 2D grids of pixels with flexible operations.
• Color Shader: Up to 16 colors, customizable for any use case.
• Drawing Functions: Draw dots, lines, and apply transformations.
• Efficient Encoding: Convert PixelBox to/from raw buffers.
• WebAssembly: Cross-platform performance with easy JavaScript integration.

Installation

Install via NPM:

npm install @emeraldproductions/fwb

Usage

Import the Library

import { PixelBox, RGBA, ProtocolMessage } from "@emeraldproductions/fwb";

API Documentation

PixelBox

The core structure for managing 2D pixel grids.

Constructor

const pixelBox = new PixelBox(width: number, height: number);

• width: Width of the pixel grid (32-bit integer).
• height: Height of the pixel grid (32-bit integer).

Methods

• fromRGBA(rgba: Uint8Array): void

  • Converts an RGBA buffer to a PixelBox.
  • Example:

    pixelBox.fromRGBA(new Uint8Array([255, 0, 0, 255, ...])); // Red pixels

• toRGBA(): Uint8Array

  • Converts the PixelBox back to an RGBA buffer.

• setPixel(x: number, y: number, color: number): void

  • Sets a single pixel at (x, y) to a color from the shader palette.

• getPixel(x: number, y: number): number

  • Retrieves the color index of the pixel at (x, y).

• setShader(shader: Uint8Array): boolean

  • Updates the color shader palette. Must be exactly 48 bytes (16 colors × 3 RGB bytes each).

  Example:

  const shader = new Uint8Array([
      0, 0, 0,        // Black
      255, 255, 255,  // White
      ...             // Other colors
  ]);
  pixelBox.setShader(shader);

• clear(): void

  • Clears the entire pixel grid.

• drawDot(x: number, y: number, radius: number, color: number): void

  • Draws a filled circle (dot) at (x, y) with a given radius and color.

  Example:

  pixelBox.drawDot(50, 50, 5, 3); // A dot at (50, 50) with radius 5, color index 3

• drawLine(x1: number, y1: number, x2: number, y2: number, radius: number, color: number): void

  • Draws a line from (x1, y1) to (x2, y2) with optional thickness (radius).

• apply(pb: PixelBox, x: number, y: number): void

  • Overlays another PixelBox onto the current one starting at (x, y).

ProtocolMessage

Manages protocol-based communication.

Constructor

const message = new ProtocolMessage(instruction: number, payload_type: number);

• instruction: An 8-bit instruction for the message.
• payload_type: Defines the payload type (0 for raw, 1 for vectors, 2 for PixelBox).

Methods

• addBuffer(payload: Uint8Array): void

  • Appends raw data to the message payload.

• buffer (getter)

  • Retrieves the message as a byte array.

• fromBuffer(bytes: Uint8Array): ProtocolMessage

  • Parses a message from a byte array.

RGBA

A utility class for working with RGBA colors.

Constructor

const rgba = new RGBA(r: number, g: number, b: number, a: number);

• r, g, b, a: Red, Green, Blue, and Alpha values (0–255).

Methods

• to_rgb(): RGB
  • Converts the RGBA value to an RGB object (ignoring alpha).

Vector

Represents a vector-based drawing primitive.

Constructor

const vector = new Vector(layer, tool, color, modifier, start_x, start_y, end_x, end_y);

• layer: The drawing layer.
• tool: The drawing tool identifier.
• color: Color index from the shader palette.
• modifier: Tool-specific modifier.
• start_x, start_y: Starting coordinates.
• end_x, end_y: Ending coordinates.

Examples

Drawing a Circle

const pixelBox = new PixelBox(100, 100);
pixelBox.drawDot(50, 50, 10, 2); // Draw a circle at (50, 50) with radius 10, color 2

Setting a Custom Shader

const shader = new Uint8Array([
    0, 0, 0,        // Black
    255, 255, 255,  // White
    128, 128, 128,  // Gray
    ...             // 13 more colors
]);
pixelBox.setShader(shader);

License

This project is licensed under the MIT License.

Let me know if you need further adjustments!