LCD Display Protocols & LED Matrix Libraries

Org Status: 🟢 Active Cloudflare: N/A Last Audited: 2026-04-28

Building a virtual LCD display means understanding the protocols that real displays speak. Whether you’re emulating an HD44780 character LCD in a macOS notch HUD, rendering RGB pixels on a canvas, or accepting commands from existing embedded libraries — the protocols and graphics primitives are the foundation.

This article covers the full stack: from the venerable HD44780 command set through modern RGB LED matrix libraries, color display controllers, graphics primitive APIs, network protocols for remote displays, and practical TypeScript implementations for virtual display engines.

What you’ll learn:

• The complete HD44780 instruction set and how to implement a virtual HD44780 in TypeScript
• How color display controllers (SSD1306, SSD1331, ST7735, ILI9341) structure their command protocols
• The Adafruit GFX graphics primitive API and how to port it to Canvas
• RGB LED matrix libraries: FastLED, SmartMatrix, HUB75, WLED, Pixelblaze
• Existing LED matrix simulators and virtual LCD projects
• How to build a protocol adapter that accepts standard LCD commands over WebSocket
• Color formats (RGB565, RGB888, HSV) and conversion between them
• Practical multi-color display patterns: scrolling text, bar charts, sprites, dashboards

You’ve built a dot-matrix display renderer — a Canvas element drawing 5x7 pixel characters in a grid. It works. But it’s bespoke. Every feature you add (cursor blinking, display shifting, custom characters) is ad-hoc code with no standard behavior to reference.

Meanwhile, the embedded world has decades of established display protocols. The HD44780 has been the standard character LCD controller since the 1980s. Color displays like the ILI9341 and SSD1331 have well-documented command sets. Libraries like Adafruit GFX provide a universal graphics primitive API that works across hundreds of display types.

The gap: these protocols exist for hardware. Nobody has assembled a clear reference for implementing them in software — particularly for a Canvas-based virtual display on macOS.

What changes if you get this right:

• Compatibility: existing LCD client libraries can drive your virtual display
• Completeness: the HD44780 spec tells you exactly what cursor behavior, display shifting, and CGRAM custom characters should do
• Multi-color support: color display protocols give you a roadmap for going beyond monochrome
• Network control: protocol adapters let remote processes push content to your display

1. The HD44780 Command Architecture

The Hitachi HD44780 is the most widely cloned LCD controller in history. Every 16x2 or 20x4 character LCD you’ve seen likely speaks HD44780. Understanding its command set is understanding the lingua franca of character displays.

The HD44780 has two registers accessed via the RS (Register Select) pin:

interface HD44780Registers {
  // RS=0: Instruction Register — accepts commands
  // RS=1: Data Register — accepts character data for DDRAM/CGRAM

  instructionRegister: number; // Write commands here
  dataRegister: number;       // Write display data here
}

interface HD44780State {
  // Display Data RAM — 80 bytes (what's shown on screen)
  ddram: Uint8Array;          // 80 bytes: row1[0..39], row2[64..103]
  ddramAddress: number;       // Current write position (0-79 or 64-103)

  // Character Generator RAM — 64 bytes (custom characters)
  cgram: Uint8Array;          // 64 bytes: 8 characters × 8 rows
  cgramAddress: number;       // Current CGRAM write position

  // Cursor position
  cursorRow: number;
  cursorCol: number;

  // Display control flags
  displayOn: boolean;
  cursorOn: boolean;
  cursorBlink: boolean;

  // Entry mode flags
  incrementMode: boolean;     // true=increment, false=decrement
  displayShift: boolean;      // true=shift display on write

  // Function set
  eightBitMode: boolean;      // true=8-bit, false=4-bit
  twoLineMode: boolean;       // true=2 lines, false=1 line
  largeFont: boolean;         // true=5x10, false=5x8

  // Display shift offset
  shiftOffset: number;

  // Internal
  busyFlag: boolean;
}

Key insight: The HD44780 is fundamentally a state machine. Every command modifies internal state (cursor position, display flags, RAM addresses). A virtual HD44780 is just this state machine plus a renderer that reads DDRAM to produce pixels.

2. Instruction Decoding

The HD44780 uses a priority-encoded instruction format — the highest set bit determines the command:

enum HD44780Command {
  // Bit patterns (RS=0, RW=0 for all writes)
  CLEAR_DISPLAY       = 0x01, // 00000001
  RETURN_HOME         = 0x02, // 0000001x
  ENTRY_MODE_SET      = 0x04, // 000001xx — bits: I/D, S
  DISPLAY_CONTROL     = 0x08, // 00001xxx — bits: D, C, B
  CURSOR_SHIFT        = 0x10, // 0001xxxx — bits: S/C, R/L
  FUNCTION_SET        = 0x20, // 001xxxxx — bits: DL, N, F
  SET_CGRAM_ADDR      = 0x40, // 01xxxxxx — 6-bit address
  SET_DDRAM_ADDR      = 0x80, // 1xxxxxxx — 7-bit address
}

// Decode an instruction byte
function decodeInstruction(byte: number): {
  command: string;
  params: Record<string, boolean | number>;
} {
  if (byte & 0x80) {
    return {
      command: 'SET_DDRAM_ADDR',
      params: { address: byte & 0x7F }
    };
  }
  if (byte & 0x40) {
    return {
      command: 'SET_CGRAM_ADDR',
      params: { address: byte & 0x3F }
    };
  }
  if (byte & 0x20) {
    return {
      command: 'FUNCTION_SET',
      params: {
        eightBit: !!(byte & 0x10),  // DL
        twoLine:  !!(byte & 0x08),  // N
        largeFont: !!(byte & 0x04), // F
      }
    };
  }
  if (byte & 0x10) {
    return {
      command: 'CURSOR_SHIFT',
      params: {
        shiftDisplay: !!(byte & 0x08), // S/C: 1=display, 0=cursor
        shiftRight:   !!(byte & 0x04), // R/L: 1=right, 0=left
      }
    };
  }
  if (byte & 0x08) {
    return {
      command: 'DISPLAY_CONTROL',
      params: {
        displayOn:   !!(byte & 0x04), // D
        cursorOn:    !!(byte & 0x02), // C
        cursorBlink: !!(byte & 0x01), // B
      }
    };
  }
  if (byte & 0x04) {
    return {
      command: 'ENTRY_MODE_SET',
      params: {
        increment:    !!(byte & 0x02), // I/D: 1=increment, 0=decrement
        displayShift: !!(byte & 0x01), // S: 1=shift display on write
      }
    };
  }
  if (byte & 0x02) {
    return { command: 'RETURN_HOME', params: {} };
  }
  if (byte & 0x01) {
    return { command: 'CLEAR_DISPLAY', params: {} };
  }
  return { command: 'NOP', params: {} };
}

3. DDRAM Address Mapping

The HD44780’s DDRAM layout is notoriously non-contiguous. For a 2-line display, row 2 doesn’t start at address 40 — it starts at address 64 (0x40):

// DDRAM layout for common display sizes
const DDRAM_ROW_OFFSETS: Record<string, number[]> = {
  '16x2': [0x00, 0x40],
  '20x4': [0x00, 0x40, 0x14, 0x54],  // Row 3 wraps after row 1!
  '40x2': [0x00, 0x40],
  '20x2': [0x00, 0x40],
  '16x1': [0x00],                      // Some 16x1s are actually 8x2
  '8x2':  [0x00, 0x40],
};

// Convert DDRAM address to row/col
function ddramToPosition(
  address: number,
  cols: number,
  rows: number
): { row: number; col: number } | null {
  const offsets = rows === 4
    ? [0x00, 0x40, 0x00 + cols, 0x40 + cols]
    : [0x00, 0x40];

  for (let row = 0; row < offsets.length; row++) {
    const start = offsets[row];
    if (address >= start && address < start + cols) {
      return { row, col: address - start };
    }
  }
  return null;
}

// Convert row/col to DDRAM address
function positionToDdram(
  row: number,
  col: number,
  cols: number
): number {
  const rowOffsets = [0x00, 0x40, cols, 0x40 + cols];
  return rowOffsets[row] + col;
}

Key insight: The 20x4 display layout is especially tricky — row 3 (index 2) continues from the end of row 1’s DDRAM space, and row 4 (index 3) continues from row 2. This means scrolling a 20x4 display doesn’t work like you’d expect.

4. Color Formats

Moving beyond monochrome, displays use different color encodings. The three you need to know:

// RGB565: 16-bit color (5 red, 6 green, 5 blue)
// Used by: ST7735, ILI9341, Adafruit GFX, most TFT displays
type RGB565 = number; // uint16

// RGB888: 24-bit true color (8 bits per channel)
// Used by: Canvas, CSS, most software rendering
type RGB888 = { r: number; g: number; b: number };

// HSV: Hue-Saturation-Value
// Used by: FastLED, WLED, color animations
type HSV = { h: number; s: number; v: number }; // h: 0-360, s/v: 0-100

function rgb888ToRgb565(r: number, g: number, b: number): RGB565 {
  return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3);
}

function rgb565ToRgb888(color: RGB565): RGB888 {
  const r = ((color >> 11) & 0x1F) << 3;
  const g = ((color >> 5) & 0x3F) << 2;
  const b = (color & 0x1F) << 3;
  // Fill lower bits for full range
  return {
    r: r | (r >> 5),
    g: g | (g >> 6),
    b: b | (b >> 5),
  };
}

function rgb888ToHsv(r: number, g: number, b: number): HSV {
  r /= 255; g /= 255; b /= 255;
  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const d = max - min;

  let h = 0;
  const s = max === 0 ? 0 : d / max;
  const v = max;

  if (d !== 0) {
    switch (max) {
      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
      case g: h = ((b - r) / d + 2) / 6; break;
      case b: h = ((r - g) / d + 4) / 6; break;
    }
  }

  return { h: h * 360, s: s * 100, v: v * 100 };
}

function hsvToRgb888(h: number, s: number, v: number): RGB888 {
  h /= 360; s /= 100; v /= 100;
  const i = Math.floor(h * 6);
  const f = h * 6 - i;
  const p = v * (1 - s);
  const q = v * (1 - f * s);
  const t = v * (1 - (1 - f) * s);

  let r: number, g: number, b: number;
  switch (i % 6) {
    case 0: r = v; g = t; b = p; break;
    case 1: r = q; g = v; b = p; break;
    case 2: r = p; g = v; b = t; break;
    case 3: r = p; g = q; b = v; break;
    case 4: r = t; g = p; b = v; break;
    case 5: r = v; g = p; b = q; break;
    default: r = 0; g = 0; b = 0;
  }

  return {
    r: Math.round(r * 255),
    g: Math.round(g * 255),
    b: Math.round(b * 255),
  };
}

// Named color constants (Adafruit GFX convention, RGB565)
const COLOR = {
  BLACK:   0x0000,
  WHITE:   0xFFFF,
  RED:     0xF800,
  GREEN:   0x07E0,
  BLUE:    0x001F,
  CYAN:    0x07FF,
  MAGENTA: 0xF81F,
  YELLOW:  0xFFE0,
  ORANGE:  0xFD20,
} as const;

Key insight: RGB565 gives green one extra bit because the human eye is most sensitive to green wavelengths. This isn’t arbitrary — it’s perceptual optimization in 16 bits. When converting RGB565 back to RGB888, you must fill the lower bits (not just shift) or you’ll never reach full white (255,255,255).

5. The Graphics Primitive Interface

The Adafruit GFX library established the standard API for drawing on small displays. Every display library in the Arduino ecosystem derives from it. Here’s the interface in TypeScript:

interface GFXDisplay {
  readonly width: number;
  readonly height: number;

  // The one function every display MUST implement
  drawPixel(x: number, y: number, color: number): void;

  // Everything else is built on drawPixel
  drawLine(x0: number, y0: number, x1: number, y1: number, color: number): void;
  drawFastHLine(x: number, y: number, w: number, color: number): void;
  drawFastVLine(x: number, y: number, h: number, color: number): void;

  drawRect(x: number, y: number, w: number, h: number, color: number): void;
  fillRect(x: number, y: number, w: number, h: number, color: number): void;

  drawCircle(x0: number, y0: number, r: number, color: number): void;
  fillCircle(x0: number, y0: number, r: number, color: number): void;

  drawTriangle(
    x0: number, y0: number,
    x1: number, y1: number,
    x2: number, y2: number,
    color: number
  ): void;
  fillTriangle(
    x0: number, y0: number,
    x1: number, y1: number,
    x2: number, y2: number,
    color: number
  ): void;

  drawRoundRect(x: number, y: number, w: number, h: number, radius: number, color: number): void;
  fillRoundRect(x: number, y: number, w: number, h: number, radius: number, color: number): void;

  drawBitmap(x: number, y: number, bitmap: Uint8Array, w: number, h: number, color: number): void;
  drawChar(x: number, y: number, c: string, color: number, bg: number, size: number): void;

  fillScreen(color: number): void;
  setRotation(r: number): void; // 0-3 for 0/90/180/270 degrees

  // Text cursor
  setCursor(x: number, y: number): void;
  setTextColor(fg: number, bg?: number): void;
  setTextSize(s: number): void;
  setTextWrap(wrap: boolean): void;
  print(text: string): void;
  println(text: string): void;

  // Color helper
  color565(r: number, g: number, b: number): number;
}

Pattern 1: Virtual HD44780 Controller

A complete virtual HD44780 that accepts the same byte commands as the real chip. This is the core state machine — pair it with any renderer (Canvas, SwiftUI, terminal).

type HD44780EventType =
  | 'clear'
  | 'home'
  | 'cursor-move'
  | 'display-update'
  | 'display-control'
  | 'shift'
  | 'cgram-update'
  | 'function-set';

type HD44780Event = {
  type: HD44780EventType;
  state: Readonly<VirtualHD44780>;
};

type HD44780Listener = (event: HD44780Event) => void;

class VirtualHD44780 {
  // Memory
  readonly ddram = new Uint8Array(128).fill(0x20);  // Space-filled
  readonly cgram = new Uint8Array(64).fill(0x00);

  // Configuration
  cols: number;
  rows: number;

  // State
  ddramAddress = 0x00;
  cgramAddress = 0x00;
  addressingCgram = false;

  displayOn = true;
  cursorOn = false;
  cursorBlink = false;

  incrementMode = true;
  displayShift = false;

  eightBitMode = true;
  twoLineMode = true;
  largeFont = false;

  shiftOffset = 0;

  private listeners: HD44780Listener[] = [];
  private nibbleBuffer: number | null = null;

  constructor(cols = 16, rows = 2) {
    this.cols = cols;
    this.rows = rows;
  }

  onEvent(listener: HD44780Listener): () => void {
    this.listeners.push(listener);
    return () => {
      this.listeners = this.listeners.filter(l => l !== listener);
    };
  }

  private emit(type: HD44780EventType): void {
    const event: HD44780Event = { type, state: this };
    for (const listener of this.listeners) {
      listener(event);
    }
  }

  // RS=0: Write instruction
  writeInstruction(byte: number): void {
    if (!this.eightBitMode) {
      // 4-bit mode: accumulate two nibbles
      if (this.nibbleBuffer === null) {
        this.nibbleBuffer = (byte & 0xF0);
        return;
      }
      byte = this.nibbleBuffer | ((byte >> 4) & 0x0F);
      this.nibbleBuffer = null;
    }

    this.executeInstruction(byte);
  }

  // RS=1: Write data
  writeData(byte: number): void {
    if (!this.eightBitMode) {
      if (this.nibbleBuffer === null) {
        this.nibbleBuffer = (byte & 0xF0);
        return;
      }
      byte = this.nibbleBuffer | ((byte >> 4) & 0x0F);
      this.nibbleBuffer = null;
    }

    if (this.addressingCgram) {
      this.cgram[this.cgramAddress & 0x3F] = byte;
      this.cgramAddress = (this.cgramAddress + 1) & 0x3F;
      this.emit('cgram-update');
    } else {
      this.ddram[this.ddramAddress & 0x7F] = byte;
      this.advanceCursor();
      this.emit('display-update');
    }
  }

  private executeInstruction(byte: number): void {
    if (byte & 0x80) {
      // Set DDRAM Address
      this.ddramAddress = byte & 0x7F;
      this.addressingCgram = false;
      this.emit('cursor-move');
      return;
    }

    if (byte & 0x40) {
      // Set CGRAM Address
      this.cgramAddress = byte & 0x3F;
      this.addressingCgram = true;
      this.emit('cursor-move');
      return;
    }

    if (byte & 0x20) {
      // Function Set
      this.eightBitMode = !!(byte & 0x10);
      this.twoLineMode = !!(byte & 0x08);
      this.largeFont = !!(byte & 0x04);
      this.emit('function-set');
      return;
    }

    if (byte & 0x10) {
      // Cursor or Display Shift
      const shiftDisplay = !!(byte & 0x08);
      const shiftRight = !!(byte & 0x04);

      if (shiftDisplay) {
        this.shiftOffset += shiftRight ? 1 : -1;
      } else {
        if (shiftRight) {
          this.ddramAddress = (this.ddramAddress + 1) & 0x7F;
        } else {
          this.ddramAddress = (this.ddramAddress - 1) & 0x7F;
        }
      }
      this.emit('shift');
      return;
    }

    if (byte & 0x08) {
      // Display On/Off Control
      this.displayOn = !!(byte & 0x04);
      this.cursorOn = !!(byte & 0x02);
      this.cursorBlink = !!(byte & 0x01);
      this.emit('display-control');
      return;
    }

    if (byte & 0x04) {
      // Entry Mode Set
      this.incrementMode = !!(byte & 0x02);
      this.displayShift = !!(byte & 0x01);
      this.emit('display-control');
      return;
    }

    if (byte & 0x02) {
      // Return Home
      this.ddramAddress = 0x00;
      this.shiftOffset = 0;
      this.emit('home');
      return;
    }

    if (byte & 0x01) {
      // Clear Display
      this.ddram.fill(0x20);
      this.ddramAddress = 0x00;
      this.shiftOffset = 0;
      this.incrementMode = true;
      this.emit('clear');
      return;
    }
  }

  private advanceCursor(): void {
    if (this.incrementMode) {
      this.ddramAddress++;
    } else {
      this.ddramAddress--;
    }
    this.ddramAddress &= 0x7F;

    if (this.displayShift) {
      this.shiftOffset += this.incrementMode ? 1 : -1;
    }
  }

  // Convenience: get the visible characters for each row
  getVisibleText(): string[] {
    const result: string[] = [];
    const rowOffsets = this.rows === 4
      ? [0x00, 0x40, this.cols, 0x40 + this.cols]
      : this.rows === 1
        ? [0x00]
        : [0x00, 0x40];

    for (let row = 0; row < this.rows; row++) {
      let text = '';
      for (let col = 0; col < this.cols; col++) {
        const addr = (rowOffsets[row] + col + this.shiftOffset) & 0x7F;
        const charCode = this.ddram[addr];
        // Characters 0-7 are CGRAM custom characters
        if (charCode < 8) {
          text += `\x00`; // Placeholder — renderer handles CGRAM
        } else {
          text += String.fromCharCode(charCode);
        }
      }
      result.push(text);
    }
    return result;
  }

  // Get CGRAM character bitmap (8 rows of 5 bits each)
  getCustomCharacter(index: number): Uint8Array {
    const offset = (index & 0x07) * 8;
    return this.cgram.slice(offset, offset + 8);
  }

  // Get cursor position as row/col
  getCursorPosition(): { row: number; col: number } {
    const rowOffsets = this.rows === 4
      ? [0x00, 0x40, this.cols, 0x40 + this.cols]
      : [0x00, 0x40];

    for (let row = 0; row < rowOffsets.length; row++) {
      const start = rowOffsets[row];
      if (this.ddramAddress >= start && this.ddramAddress < start + this.cols) {
        return { row, col: this.ddramAddress - start };
      }
    }
    return { row: 0, col: this.ddramAddress };
  }

  // Helper: write a string at the current position
  printString(text: string): void {
    for (const char of text) {
      this.writeData(char.charCodeAt(0));
    }
  }

  // Helper: set cursor to row/col
  setCursor(row: number, col: number): void {
    const rowOffsets = [0x00, 0x40, this.cols, 0x40 + this.cols];
    this.writeInstruction(0x80 | (rowOffsets[row] + col));
  }

  // Helper: define a custom character (index 0-7)
  defineCharacter(index: number, bitmap: number[]): void {
    this.writeInstruction(0x40 | ((index & 0x07) << 3));
    for (const row of bitmap) {
      this.writeData(row & 0x1F);
    }
    // Restore DDRAM addressing
    this.addressingCgram = false;
  }
}

Usage — driving the virtual HD44780 like hardware code would:

const lcd = new VirtualHD44780(16, 2);

// Standard initialization sequence (matches real hardware)
lcd.writeInstruction(0x38); // Function Set: 8-bit, 2-line, 5x8 font
lcd.writeInstruction(0x0C); // Display On, Cursor Off, Blink Off
lcd.writeInstruction(0x06); // Entry Mode: Increment, No Shift
lcd.writeInstruction(0x01); // Clear Display

// Write "Hello, World!" on line 1
lcd.printString('Hello, World!');

// Move to line 2, column 0
lcd.setCursor(1, 0);
lcd.printString('HD44780 Virtual');

// Define a custom heart character at index 0
lcd.defineCharacter(0, [
  0b00000,
  0b01010,
  0b11111,
  0b11111,
  0b11111,
  0b01110,
  0b00100,
  0b00000,
]);

// Write the custom character
lcd.setCursor(0, 15);
lcd.writeData(0x00); // Character 0 = our heart

Pattern 2: Canvas-Based Dot Matrix Renderer

A renderer that takes a virtual HD44780 (or any pixel buffer) and draws it on an HTML Canvas with authentic LCD aesthetics — pixel gaps, glow effects, and configurable colors.

interface DotMatrixTheme {
  backgroundColor: string;
  pixelOnColor: string;
  pixelOffColor: string;
  pixelGap: number;         // Gap between dots in pixels
  pixelRadius: number;      // 0=square, >0=rounded
  glowRadius: number;       // 0=no glow, >0=blur radius
  glowColor: string;
  dotShape: 'square' | 'circle';
}

const THEMES: Record<string, DotMatrixTheme> = {
  classicGreen: {
    backgroundColor: '#0a1a0a',
    pixelOnColor: '#33ff33',
    pixelOffColor: '#0a2a0a',
    pixelGap: 1,
    pixelRadius: 0,
    glowRadius: 2,
    glowColor: 'rgba(51, 255, 51, 0.3)',
    dotShape: 'square',
  },
  amberLCD: {
    backgroundColor: '#1a0f00',
    pixelOnColor: '#ffaa00',
    pixelOffColor: '#1a1200',
    pixelGap: 1,
    pixelRadius: 0,
    glowRadius: 2,
    glowColor: 'rgba(255, 170, 0, 0.3)',
    dotShape: 'square',
  },
  blueLED: {
    backgroundColor: '#000a1a',
    pixelOnColor: '#3399ff',
    pixelOffColor: '#001022',
    pixelGap: 1,
    pixelRadius: 1,
    glowRadius: 3,
    glowColor: 'rgba(51, 153, 255, 0.4)',
    dotShape: 'circle',
  },
  rgbMatrix: {
    backgroundColor: '#111111',
    pixelOnColor: '#ffffff',  // Overridden per-pixel for RGB
    pixelOffColor: '#1a1a1a',
    pixelGap: 1,
    pixelRadius: 1,
    glowRadius: 1,
    glowColor: 'rgba(255, 255, 255, 0.2)',
    dotShape: 'circle',
  },
  whiteOnBlue: {
    backgroundColor: '#0000aa',
    pixelOnColor: '#ffffff',
    pixelOffColor: '#0000cc',
    pixelGap: 1,
    pixelRadius: 0,
    glowRadius: 0,
    glowColor: 'transparent',
    dotShape: 'square',
  },
};

class DotMatrixRenderer {
  private ctx: CanvasRenderingContext2D;
  private pixelSize: number;
  private theme: DotMatrixTheme;

  constructor(
    private canvas: HTMLCanvasElement,
    private gridWidth: number,   // Total pixel columns
    private gridHeight: number,  // Total pixel rows
    theme: DotMatrixTheme = THEMES.classicGreen,
  ) {
    this.ctx = canvas.getContext('2d')!;
    this.theme = theme;

    // Calculate pixel size to fill canvas
    const cellWidth = canvas.width / gridWidth;
    const cellHeight = canvas.height / gridHeight;
    this.pixelSize = Math.min(cellWidth, cellHeight);
  }

  setTheme(theme: DotMatrixTheme): void {
    this.theme = theme;
  }

  // Render a monochrome pixel buffer (1 = on, 0 = off)
  renderMono(pixels: Uint8Array): void {
    const { ctx, theme, pixelSize, gridWidth, gridHeight } = this;
    const gap = theme.pixelGap;
    const dotSize = pixelSize - gap;

    ctx.fillStyle = theme.backgroundColor;
    ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);

    // Apply glow effect
    if (theme.glowRadius > 0) {
      ctx.save();
      ctx.shadowBlur = theme.glowRadius;
      ctx.shadowColor = theme.glowColor;
    }

    for (let y = 0; y < gridHeight; y++) {
      for (let x = 0; x < gridWidth; x++) {
        const on = pixels[y * gridWidth + x] !== 0;
        ctx.fillStyle = on ? theme.pixelOnColor : theme.pixelOffColor;

        const px = x * pixelSize + gap / 2;
        const py = y * pixelSize + gap / 2;

        if (theme.dotShape === 'circle') {
          ctx.beginPath();
          ctx.arc(px + dotSize / 2, py + dotSize / 2, dotSize / 2, 0, Math.PI * 2);
          ctx.fill();
        } else if (theme.pixelRadius > 0) {
          this.roundRect(px, py, dotSize, dotSize, theme.pixelRadius);
        } else {
          ctx.fillRect(px, py, dotSize, dotSize);
        }
      }
    }

    if (theme.glowRadius > 0) {
      ctx.restore();
    }
  }

  // Render an RGB pixel buffer (3 bytes per pixel: R, G, B)
  renderRGB(pixels: Uint8Array): void {
    const { ctx, theme, pixelSize, gridWidth, gridHeight } = this;
    const gap = theme.pixelGap;
    const dotSize = pixelSize - gap;

    ctx.fillStyle = theme.backgroundColor;
    ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);

    for (let y = 0; y < gridHeight; y++) {
      for (let x = 0; x < gridWidth; x++) {
        const i = (y * gridWidth + x) * 3;
        const r = pixels[i];
        const g = pixels[i + 1];
        const b = pixels[i + 2];

        const isOff = r === 0 && g === 0 && b === 0;

        if (isOff) {
          ctx.fillStyle = theme.pixelOffColor;
        } else {
          ctx.fillStyle = `rgb(${r}, ${g}, ${b})`;
          if (theme.glowRadius > 0) {
            ctx.shadowBlur = theme.glowRadius;
            ctx.shadowColor = `rgba(${r}, ${g}, ${b}, 0.4)`;
          }
        }

        const px = x * pixelSize + gap / 2;
        const py = y * pixelSize + gap / 2;

        if (theme.dotShape === 'circle') {
          ctx.beginPath();
          ctx.arc(px + dotSize / 2, py + dotSize / 2, dotSize / 2, 0, Math.PI * 2);
          ctx.fill();
        } else {
          ctx.fillRect(px, py, dotSize, dotSize);
        }

        ctx.shadowBlur = 0;
      }
    }
  }

  // Render an RGB565 pixel buffer (2 bytes per pixel, big-endian)
  renderRGB565(pixels: Uint16Array): void {
    const rgb = new Uint8Array(pixels.length * 3);
    for (let i = 0; i < pixels.length; i++) {
      const c = pixels[i];
      const { r, g, b } = rgb565ToRgb888(c);
      rgb[i * 3] = r;
      rgb[i * 3 + 1] = g;
      rgb[i * 3 + 2] = b;
    }
    this.renderRGB(rgb);
  }

  private roundRect(
    x: number, y: number, w: number, h: number, r: number
  ): void {
    const ctx = this.ctx;
    ctx.beginPath();
    ctx.moveTo(x + r, y);
    ctx.lineTo(x + w - r, y);
    ctx.quadraticCurveTo(x + w, y, x + w, y + r);
    ctx.lineTo(x + w, y + h - r);
    ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
    ctx.lineTo(x + r, y + h);
    ctx.quadraticCurveTo(x, y + h, x, y + h - r);
    ctx.lineTo(x, y + r);
    ctx.quadraticCurveTo(x, y, x + r, y);
    ctx.fill();
  }
}

Pattern 3: GFX Graphics Primitives on a Pixel Buffer

A TypeScript port of the Adafruit GFX drawing primitives. This operates on an abstract pixel buffer — connect it to a Canvas renderer or any other output.

// Standard 5x7 font (ASCII 32-126), packed as 5 bytes per character
// Each byte is a column, LSB is top row
const FONT_5X7: Uint8Array = new Uint8Array([
  // Space (0x20)
  0x00, 0x00, 0x00, 0x00, 0x00,
  // ! (0x21)
  0x00, 0x00, 0x5F, 0x00, 0x00,
  // " (0x22)
  0x00, 0x07, 0x00, 0x07, 0x00,
  // # (0x23)
  0x14, 0x7F, 0x14, 0x7F, 0x14,
  // $ (0x24)
  0x24, 0x2A, 0x7F, 0x2A, 0x12,
  // % (0x25)
  0x23, 0x13, 0x08, 0x64, 0x62,
  // & (0x26)
  0x36, 0x49, 0x55, 0x22, 0x50,
  // ' (0x27)
  0x00, 0x05, 0x03, 0x00, 0x00,
  // ( (0x28)
  0x00, 0x1C, 0x22, 0x41, 0x00,
  // ) (0x29)
  0x00, 0x41, 0x22, 0x1C, 0x00,
  // * (0x2A)
  0x08, 0x2A, 0x1C, 0x2A, 0x08,
  // + (0x2B)
  0x08, 0x08, 0x3E, 0x08, 0x08,
  // , (0x2C)
  0x00, 0x50, 0x30, 0x00, 0x00,
  // - (0x2D)
  0x08, 0x08, 0x08, 0x08, 0x08,
  // . (0x2E)
  0x00, 0x60, 0x60, 0x00, 0x00,
  // / (0x2F)
  0x20, 0x10, 0x08, 0x04, 0x02,
  // 0 (0x30)
  0x3E, 0x51, 0x49, 0x45, 0x3E,
  // 1 (0x31)
  0x00, 0x42, 0x7F, 0x40, 0x00,
  // 2 (0x32)
  0x42, 0x61, 0x51, 0x49, 0x46,
  // 3 (0x33)
  0x21, 0x41, 0x45, 0x4B, 0x31,
  // 4 (0x34)
  0x18, 0x14, 0x12, 0x7F, 0x10,
  // 5 (0x35)
  0x27, 0x45, 0x45, 0x45, 0x39,
  // 6 (0x36)
  0x3C, 0x4A, 0x49, 0x49, 0x30,
  // 7 (0x37)
  0x01, 0x71, 0x09, 0x05, 0x03,
  // 8 (0x38)
  0x36, 0x49, 0x49, 0x49, 0x36,
  // 9 (0x39)
  0x06, 0x49, 0x49, 0x29, 0x1E,
  // : (0x3A)
  0x00, 0x36, 0x36, 0x00, 0x00,
  // ; (0x3B)
  0x00, 0x56, 0x36, 0x00, 0x00,
  // < (0x3C)
  0x00, 0x08, 0x14, 0x22, 0x41,
  // = (0x3D)
  0x14, 0x14, 0x14, 0x14, 0x14,
  // > (0x3E)
  0x41, 0x22, 0x14, 0x08, 0x00,
  // ? (0x3F)
  0x02, 0x01, 0x51, 0x09, 0x06,
  // @ (0x40)
  0x32, 0x49, 0x79, 0x41, 0x3E,
  // A (0x41)
  0x7E, 0x11, 0x11, 0x11, 0x7E,
  // B (0x42)
  0x7F, 0x49, 0x49, 0x49, 0x36,
  // C (0x43)
  0x3E, 0x41, 0x41, 0x41, 0x22,
  // D (0x44)
  0x7F, 0x41, 0x41, 0x22, 0x1C,
  // E (0x45)
  0x7F, 0x49, 0x49, 0x49, 0x41,
  // F (0x46)
  0x7F, 0x09, 0x09, 0x01, 0x01,
  // G (0x47)
  0x3E, 0x41, 0x41, 0x51, 0x32,
  // H (0x48)
  0x7F, 0x08, 0x08, 0x08, 0x7F,
  // I (0x49)
  0x00, 0x41, 0x7F, 0x41, 0x00,
  // J (0x4A)
  0x20, 0x40, 0x41, 0x3F, 0x01,
  // K (0x4B)
  0x7F, 0x08, 0x14, 0x22, 0x41,
  // L (0x4C)
  0x7F, 0x40, 0x40, 0x40, 0x40,
  // M (0x4D)
  0x7F, 0x02, 0x04, 0x02, 0x7F,
  // N (0x4E)
  0x7F, 0x04, 0x08, 0x10, 0x7F,
  // O (0x4F)
  0x3E, 0x41, 0x41, 0x41, 0x3E,
  // P (0x50)
  0x7F, 0x09, 0x09, 0x09, 0x06,
  // Q (0x51)
  0x3E, 0x41, 0x51, 0x21, 0x5E,
  // R (0x52)
  0x7F, 0x09, 0x19, 0x29, 0x46,
  // S (0x53)
  0x46, 0x49, 0x49, 0x49, 0x31,
  // T (0x54)
  0x01, 0x01, 0x7F, 0x01, 0x01,
  // U (0x55)
  0x3F, 0x40, 0x40, 0x40, 0x3F,
  // V (0x56)
  0x1F, 0x20, 0x40, 0x20, 0x1F,
  // W (0x57)
  0x7F, 0x20, 0x18, 0x20, 0x7F,
  // X (0x58)
  0x63, 0x14, 0x08, 0x14, 0x63,
  // Y (0x59)
  0x03, 0x04, 0x78, 0x04, 0x03,
  // Z (0x5A)
  0x61, 0x51, 0x49, 0x45, 0x43,
]);

class PixelBuffer implements GFXDisplay {
  readonly buffer: Uint16Array; // RGB565 color per pixel
  private cursorX = 0;
  private cursorY = 0;
  private textColor: number = 0xFFFF;
  private textBg: number = 0x0000;
  private textSize = 1;
  private wrap = true;
  private rotation = 0;
  private _width: number;
  private _height: number;

  constructor(
    public readonly width: number,
    public readonly height: number,
  ) {
    this._width = width;
    this._height = height;
    this.buffer = new Uint16Array(width * height);
  }

  drawPixel(x: number, y: number, color: number): void {
    // Apply rotation
    [x, y] = this.applyRotation(x, y);
    if (x < 0 || x >= this.width || y < 0 || y >= this.height) return;
    this.buffer[y * this.width + x] = color;
  }

  private applyRotation(x: number, y: number): [number, number] {
    switch (this.rotation) {
      case 1: return [this.width - 1 - y, x];
      case 2: return [this.width - 1 - x, this.height - 1 - y];
      case 3: return [y, this.height - 1 - x];
      default: return [x, y];
    }
  }

  drawLine(x0: number, y0: number, x1: number, y1: number, color: number): void {
    // Bresenham's line algorithm
    const steep = Math.abs(y1 - y0) > Math.abs(x1 - x0);
    if (steep) {
      [x0, y0] = [y0, x0];
      [x1, y1] = [y1, x1];
    }
    if (x0 > x1) {
      [x0, x1] = [x1, x0];
      [y0, y1] = [y1, y0];
    }

    const dx = x1 - x0;
    const dy = Math.abs(y1 - y0);
    let err = dx / 2;
    const ystep = y0 < y1 ? 1 : -1;
    let y = y0;

    for (let x = x0; x <= x1; x++) {
      if (steep) {
        this.drawPixel(y, x, color);
      } else {
        this.drawPixel(x, y, color);
      }
      err -= dy;
      if (err < 0) {
        y += ystep;
        err += dx;
      }
    }
  }

  drawFastHLine(x: number, y: number, w: number, color: number): void {
    for (let i = 0; i < w; i++) this.drawPixel(x + i, y, color);
  }

  drawFastVLine(x: number, y: number, h: number, color: number): void {
    for (let i = 0; i < h; i++) this.drawPixel(x, y + i, color);
  }

  drawRect(x: number, y: number, w: number, h: number, color: number): void {
    this.drawFastHLine(x, y, w, color);
    this.drawFastHLine(x, y + h - 1, w, color);
    this.drawFastVLine(x, y, h, color);
    this.drawFastVLine(x + w - 1, y, h, color);
  }

  fillRect(x: number, y: number, w: number, h: number, color: number): void {
    for (let j = 0; j < h; j++) {
      this.drawFastHLine(x, y + j, w, color);
    }
  }

  drawCircle(x0: number, y0: number, r: number, color: number): void {
    // Midpoint circle algorithm
    let f = 1 - r;
    let ddF_x = 1;
    let ddF_y = -2 * r;
    let x = 0;
    let y = r;

    this.drawPixel(x0, y0 + r, color);
    this.drawPixel(x0, y0 - r, color);
    this.drawPixel(x0 + r, y0, color);
    this.drawPixel(x0 - r, y0, color);

    while (x < y) {
      if (f >= 0) { y--; ddF_y += 2; f += ddF_y; }
      x++; ddF_x += 2; f += ddF_x;

      this.drawPixel(x0 + x, y0 + y, color);
      this.drawPixel(x0 - x, y0 + y, color);
      this.drawPixel(x0 + x, y0 - y, color);
      this.drawPixel(x0 - x, y0 - y, color);
      this.drawPixel(x0 + y, y0 + x, color);
      this.drawPixel(x0 - y, y0 + x, color);
      this.drawPixel(x0 + y, y0 - x, color);
      this.drawPixel(x0 - y, y0 - x, color);
    }
  }

  fillCircle(x0: number, y0: number, r: number, color: number): void {
    this.drawFastVLine(x0, y0 - r, 2 * r + 1, color);
    this.fillCircleHelper(x0, y0, r, 3, 0, color);
  }

  private fillCircleHelper(
    x0: number, y0: number, r: number,
    corners: number, delta: number, color: number
  ): void {
    let f = 1 - r;
    let ddF_x = 1;
    let ddF_y = -2 * r;
    let x = 0;
    let y = r;

    while (x < y) {
      if (f >= 0) { y--; ddF_y += 2; f += ddF_y; }
      x++; ddF_x += 2; f += ddF_x;

      if (corners & 0x1) {
        this.drawFastVLine(x0 + x, y0 - y, 2 * y + 1 + delta, color);
        this.drawFastVLine(x0 + y, y0 - x, 2 * x + 1 + delta, color);
      }
      if (corners & 0x2) {
        this.drawFastVLine(x0 - x, y0 - y, 2 * y + 1 + delta, color);
        this.drawFastVLine(x0 - y, y0 - x, 2 * x + 1 + delta, color);
      }
    }
  }

  drawTriangle(
    x0: number, y0: number,
    x1: number, y1: number,
    x2: number, y2: number,
    color: number
  ): void {
    this.drawLine(x0, y0, x1, y1, color);
    this.drawLine(x1, y1, x2, y2, color);
    this.drawLine(x2, y2, x0, y0, color);
  }

  fillTriangle(
    x0: number, y0: number,
    x1: number, y1: number,
    x2: number, y2: number,
    color: number
  ): void {
    // Sort vertices by Y
    if (y0 > y1) { [x0, x1] = [x1, x0]; [y0, y1] = [y1, y0]; }
    if (y1 > y2) { [x1, x2] = [x2, x1]; [y1, y2] = [y2, y1]; }
    if (y0 > y1) { [x0, x1] = [x1, x0]; [y0, y1] = [y1, y0]; }

    if (y0 === y2) {
      let a = Math.min(x0, x1, x2);
      let b = Math.max(x0, x1, x2);
      this.drawFastHLine(a, y0, b - a + 1, color);
      return;
    }

    const dx01 = x1 - x0, dy01 = y1 - y0;
    const dx02 = x2 - x0, dy02 = y2 - y0;
    const dx12 = x2 - x1, dy12 = y2 - y1;

    let sa = 0, sb = 0;
    let last = y1 === y2 ? y1 : y1 - 1;

    for (let y = y0; y <= last; y++) {
      let a = x0 + Math.floor(sa / dy01);
      let b = x0 + Math.floor(sb / dy02);
      sa += dx01; sb += dx02;
      if (a > b) [a, b] = [b, a];
      this.drawFastHLine(a, y, b - a + 1, color);
    }

    sa = dx12 * (last + 1 - y1);
    sb = dx02 * (last + 1 - y0);
    for (let y = last + 1; y <= y2; y++) {
      let a = x1 + Math.floor(sa / dy12);
      let b = x0 + Math.floor(sb / dy02);
      sa += dx12; sb += dx02;
      if (a > b) [a, b] = [b, a];
      this.drawFastHLine(a, y, b - a + 1, color);
    }
  }

  drawRoundRect(
    x: number, y: number, w: number, h: number,
    radius: number, color: number
  ): void {
    this.drawFastHLine(x + radius, y, w - 2 * radius, color);
    this.drawFastHLine(x + radius, y + h - 1, w - 2 * radius, color);
    this.drawFastVLine(x, y + radius, h - 2 * radius, color);
    this.drawFastVLine(x + w - 1, y + radius, h - 2 * radius, color);
    // Corners via circle quadrants
    this.drawCircleQuadrant(x + radius, y + radius, radius, 1, color);
    this.drawCircleQuadrant(x + w - radius - 1, y + radius, radius, 2, color);
    this.drawCircleQuadrant(x + w - radius - 1, y + h - radius - 1, radius, 4, color);
    this.drawCircleQuadrant(x + radius, y + h - radius - 1, radius, 8, color);
  }

  fillRoundRect(
    x: number, y: number, w: number, h: number,
    radius: number, color: number
  ): void {
    this.fillRect(x + radius, y, w - 2 * radius, h, color);
    this.fillCircleHelper(x + w - radius - 1, y + radius, radius, 1, h - 2 * radius - 1, color);
    this.fillCircleHelper(x + radius, y + radius, radius, 2, h - 2 * radius - 1, color);
  }

  private drawCircleQuadrant(
    x0: number, y0: number, r: number, quadrant: number, color: number
  ): void {
    let f = 1 - r;
    let ddF_x = 1;
    let ddF_y = -2 * r;
    let x = 0;
    let y = r;

    while (x < y) {
      if (f >= 0) { y--; ddF_y += 2; f += ddF_y; }
      x++; ddF_x += 2; f += ddF_x;

      if (quadrant & 0x1) { this.drawPixel(x0 + x, y0 - y, color); this.drawPixel(x0 + y, y0 - x, color); }
      if (quadrant & 0x2) { this.drawPixel(x0 - y, y0 - x, color); this.drawPixel(x0 - x, y0 - y, color); }
      if (quadrant & 0x4) { this.drawPixel(x0 + x, y0 + y, color); this.drawPixel(x0 + y, y0 + x, color); }
      if (quadrant & 0x8) { this.drawPixel(x0 - y, y0 + x, color); this.drawPixel(x0 - x, y0 + y, color); }
    }
  }

  drawBitmap(
    x: number, y: number, bitmap: Uint8Array,
    w: number, h: number, color: number
  ): void {
    let byteIndex = 0;
    let bit = 0;

    for (let j = 0; j < h; j++) {
      for (let i = 0; i < w; i++) {
        if (i % 8 === 0 && i > 0) byteIndex++;
        if (bitmap[byteIndex] & (0x80 >> (i % 8))) {
          this.drawPixel(x + i, y + j, color);
        }
        bit++;
      }
      byteIndex++;
    }
  }

  drawChar(
    x: number, y: number, c: string,
    color: number, bg: number, size: number
  ): void {
    const charCode = c.charCodeAt(0);
    if (charCode < 0x20 || charCode > 0x7E) return;

    const fontIndex = (charCode - 0x20) * 5;

    for (let col = 0; col < 5; col++) {
      let line = FONT_5X7[fontIndex + col] ?? 0;
      for (let row = 0; row < 8; row++) {
        if (line & 0x01) {
          if (size === 1) {
            this.drawPixel(x + col, y + row, color);
          } else {
            this.fillRect(x + col * size, y + row * size, size, size, color);
          }
        } else if (bg !== color) {
          if (size === 1) {
            this.drawPixel(x + col, y + row, bg);
          } else {
            this.fillRect(x + col * size, y + row * size, size, size, bg);
          }
        }
        line >>= 1;
      }
    }

    // Column gap
    if (bg !== color) {
      if (size === 1) {
        this.drawFastVLine(x + 5, y, 8, bg);
      } else {
        this.fillRect(x + 5 * size, y, size, 8 * size, bg);
      }
    }
  }

  fillScreen(color: number): void {
    this.buffer.fill(color);
  }

  setRotation(r: number): void {
    this.rotation = r & 3;
    if (this.rotation & 1) {
      this._width = this.height;
      this._height = this.width;
    } else {
      this._width = this.width;
      this._height = this.height;
    }
  }

  setCursor(x: number, y: number): void {
    this.cursorX = x;
    this.cursorY = y;
  }

  setTextColor(fg: number, bg?: number): void {
    this.textColor = fg;
    this.textBg = bg ?? fg;
  }

  setTextSize(s: number): void {
    this.textSize = Math.max(1, s);
  }

  setTextWrap(wrap: boolean): void {
    this.wrap = wrap;
  }

  print(text: string): void {
    for (const c of text) {
      if (c === '\n') {
        this.cursorX = 0;
        this.cursorY += this.textSize * 8;
        continue;
      }
      if (c === '\r') {
        this.cursorX = 0;
        continue;
      }

      if (this.wrap && (this.cursorX + this.textSize * 6 > this._width)) {
        this.cursorX = 0;
        this.cursorY += this.textSize * 8;
      }

      this.drawChar(
        this.cursorX, this.cursorY, c,
        this.textColor, this.textBg, this.textSize
      );
      this.cursorX += this.textSize * 6; // 5 pixels + 1 gap
    }
  }

  println(text: string): void {
    this.print(text + '\n');
  }

  color565(r: number, g: number, b: number): number {
    return rgb888ToRgb565(r, g, b);
  }
}