package miaou-driver-matrix

  1. Overview
  2. Docs

Module Miaou_driver_matrix.Matrix_bufferSource

Double-buffered terminal grid for the Matrix driver.

Maintains two cell grids (front and back). The back buffer is the write target during rendering, while the front buffer holds the last displayed state for diff computation. After rendering, buffers are swapped via O(1) pointer swap.

Thread-safe: All operations use internal mutex for cross-domain safety.

Sourcetype t
Sourceval create : rows:int -> cols:int -> t

Create a new buffer with given dimensions. Both front and back are initialized to empty cells.

Sourceval resize : t -> rows:int -> cols:int -> unit

Resize the buffer in-place, preserving content where possible. New cells are initialized to empty. Marks buffer as dirty.

Sourceval rows : t -> int

Get number of rows.

Sourceval cols : t -> int

Get number of columns.

Sourceval size : t -> int * int

Get dimensions as (rows, cols) tuple. Thread-safe.

Back Buffer Operations (Write Target)

Sourceval set : t -> row:int -> col:int -> Matrix_cell.t -> unit

Set a cell in the back buffer. Out-of-bounds writes are silently ignored. Thread-safe.

Sourceval set_from : t -> row:int -> col:int -> Matrix_cell.t -> unit

Set cell by copying character and style from another cell. More efficient than set when you have a cell to copy from. Thread-safe.

Sourceval get_back : t -> row:int -> col:int -> Matrix_cell.t

Get a cell from the back buffer. Returns empty cell for out-of-bounds reads. Thread-safe.

Sourceval clear_back : t -> unit

Clear the back buffer (fill with empty cells). Thread-safe.

Sourceval set_char : t -> row:int -> col:int -> char:string -> style:Matrix_cell.style -> unit

Set character and style directly in back buffer. Thread-safe.

Front Buffer Operations (Last Rendered State)

Sourceval get_front : t -> row:int -> col:int -> Matrix_cell.t

Get a cell from the front buffer. Returns empty cell for out-of-bounds reads.

Buffer Management

Sourceval swap : t -> unit

Swap front and back buffers. O(1) pointer swap. Thread-safe.

Sourceval cell_changed : t -> row:int -> col:int -> bool

Check if a cell differs between front and back buffers.

Sourceval mark_all_dirty : t -> unit

Mark all cells as needing redraw (for full refresh after resize). Thread-safe.

Sourceval mark_region_dirty : t -> row_start:int -> row_end:int -> col_start:int -> col_end:int -> unit

Mark a region of cells as needing redraw. Thread-safe. Used for partial refresh and modal regions.

Dirty Flag (for render domain)

Sourceval mark_dirty : t -> unit

Mark buffer as needing render.

Sourceval is_dirty : t -> bool

Check if buffer needs render.

Sourceval clear_dirty : t -> unit

Clear dirty flag after render.

Batch Operations

Sourcetype batch_ops = {
  1. clear : unit -> unit;
    (*

    Clear back buffer

    *)
  2. set_char : row:int -> col:int -> char:string -> style:Matrix_cell.style -> unit;
  3. get : row:int -> col:int -> Matrix_cell.t;
    (*

    Get cell from back buffer

    *)
  4. rows : int;
    (*

    Current row count

    *)
  5. cols : int;
    (*

    Current column count

    *)
}

Record of unlocked operations available within with_back_buffer.

Sourceval with_back_buffer : ?force_full_redraw:bool -> t -> (batch_ops -> 'a) -> 'a

Execute function with buffer lock held. Marks dirty after. The callback receives batch_ops for safe unlocked access. If force_full_redraw is true, clears the front buffer first (atomically, while holding the lock) so all cells appear changed. This avoids race conditions when a full redraw is needed.

Atomic Read Operations (for render domain)

Sourceval with_read_lock : t -> (unit -> 'a) -> 'a

Execute a read operation with the buffer lock held. Use this for atomic diff computation to prevent torn reads.

Sourceval get_front_unlocked : t -> row:int -> col:int -> Matrix_cell.t

Get front cell without locking - use inside with_read_lock.

Sourceval get_back_unlocked : t -> row:int -> col:int -> Matrix_cell.t

Get back cell without locking - use inside with_read_lock.

Sourceval rows_unlocked : t -> int

Get rows without locking - use inside with_read_lock.

Sourceval cols_unlocked : t -> int

Get cols without locking - use inside with_read_lock.

Sourceval swap_unlocked : t -> unit

Swap buffers without locking - use inside with_read_lock.

Sourceval clear_dirty_unlocked : t -> unit

Clear dirty flag without locking - use inside with_read_lock.

Debug/Exit Support

Sourceval dump_to_string : t -> string

Dump front buffer to string with ANSI formatting. Returns the entire screen content with escape codes for colors and styles. Used to preserve screen content in terminal scrollback after exit.