package miaou-core

  1. Overview
  2. Docs
package miaou-core
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Miaou_canvas.CanvasSource

Canvas — a driver-agnostic, cell-level 2D surface for TUI rendering.

A canvas is a mutable grid of cells, where each cell holds a UTF-8 grapheme cluster and a style (foreground/background color, bold, dim, underline, reverse).

Canvases can be rendered to ANSI strings via to_ansi for use with the existing view pipeline, or iterated over via iter so that a driver can transfer cells to its own buffer format (e.g. the matrix driver's Matrix_buffer).

Types

Sourcetype style = {
  1. fg : int;
    (*

    Foreground color, -1 = default

    *)
  2. bg : int;
    (*

    Background color, -1 = default

    *)
  3. bold : bool;
  4. dim : bool;
  5. underline : bool;
  6. reverse : bool;
}

Visual style for a single cell.

Colors use 256-color palette indices: -1 means "default terminal color", 0–255 are the standard 256-color palette values.

Sourcetype cell = {
  1. char : string;
  2. style : style;
}

A single cell in the canvas grid.

Sourcetype t

A mutable 2D grid of cells.

Sourcetype border_style =
  1. | Single
  2. | Double
  3. | Rounded
  4. | Ascii
  5. | Heavy

Border drawing styles for draw_box.

Sourcetype border_chars = {
  1. tl : string;
  2. tr : string;
  3. bl : string;
  4. br : string;
  5. h : string;
  6. v : string;
}

Border character set used by draw_box. Exposed so callers can supply custom border glyphs via draw_box_with_chars.

Sourcetype layer = {
  1. canvas : t;
  2. row : int;
  3. col : int;
  4. opaque : bool;
}

Placement and blend mode for one compositing layer.

Constants

Sourceval default_style : style

The default style: no colors (-1), no attributes.

Sourceval empty_cell : cell

An empty cell: a single space with default_style.

Creation

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

create ~rows ~cols allocates a canvas filled with empty_cell.

Dimensions

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

Cell access

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

set_char t ~row ~col ~char ~style sets the cell at (row, col). Out-of-bounds writes are silently ignored.

Sourceval get_cell : t -> row:int -> col:int -> cell

get_cell t ~row ~col returns the cell at (row, col).

Drawing primitives

Sourceval fill_rect : t -> row:int -> col:int -> width:int -> height:int -> char:string -> style:style -> unit

fill_rect t ~row ~col ~width ~height ~char ~style fills a rectangular region. Out-of-bounds portions are clipped.

Sourceval clear : t -> unit

clear t resets every cell to empty_cell.

Sourceval draw_text : t -> row:int -> col:int -> style:style -> string -> unit

draw_text t ~row ~col ~style text writes a plain-text string horizontally starting at (row, col). Each UTF-8 grapheme cluster occupies one cell. The text must not contain ANSI escape sequences. Out-of-bounds portions are clipped.

Sourceval draw_hline : t -> row:int -> col:int -> len:int -> char:string -> style:style -> unit

draw_hline t ~row ~col ~len ~char ~style draws a horizontal line.

Sourceval draw_vline : t -> row:int -> col:int -> len:int -> char:string -> style:style -> unit

draw_vline t ~row ~col ~len ~char ~style draws a vertical line.

Sourceval draw_box : t -> row:int -> col:int -> width:int -> height:int -> border:border_style -> style:style -> unit

draw_box t ~row ~col ~width ~height ~border ~style draws a rectangular border. The border occupies 1 cell on each side, so the interior is (width - 2) x (height - 2). Boxes smaller than 2x2 are silently ignored.

Sourceval draw_box_with_chars : t -> row:int -> col:int -> width:int -> height:int -> chars:border_chars -> style:style -> unit

draw_box_with_chars t ~row ~col ~width ~height ~chars ~style draws a box using custom border characters.

Composition

Sourceval blit : src:t -> dst:t -> row:int -> col:int -> unit

blit ~src ~dst ~row ~col copies non-empty cells from src onto dst at offset (row, col). Only cells whose char is not " " (space) are copied, making spaces transparent. Out-of-bounds portions are clipped.

Sourceval blit_all : src:t -> dst:t -> row:int -> col:int -> unit

blit_all ~src ~dst ~row ~col copies all cells from src onto dst at offset (row, col), including spaces. Out-of-bounds portions are clipped.

Sourceval compose : dst:t -> layers:layer list -> unit

compose ~dst ~layers composites all layers onto dst in list order. Earlier layers are considered behind later layers.

For each layer, opaque = false uses blit (spaces are transparent), while opaque = true uses blit_all (spaces overwrite destination). Out-of-bounds portions are clipped.

Sourceval compose_new : rows:int -> cols:int -> layers:layer list -> t

compose_new ~rows ~cols ~layers creates a new empty canvas and applies compose with layers.

Output

Sourceval to_ansi : t -> string

to_ansi t renders the canvas to an ANSI-escaped string suitable for terminal display. Rows are separated by newlines. Style changes are tracked so that SGR codes are only emitted when the style actually changes between cells.

Sourceval to_ansi_with_defaults : ?default_fg:int -> ?default_bg:int -> t -> string

to_ansi_with_defaults ~default_fg ~default_bg t renders the canvas with fallback colors for cells that don't specify fg/bg (i.e., -1). Use this to ensure canvas content is visible regardless of terminal theme - pass the current theme's text and background colors.

Iteration

Sourceval iter : t -> f:(row:int -> col:int -> cell -> unit) -> unit

iter t ~f calls f ~row ~col cell for every cell in row-major order. This is the primary integration point for drivers: iterate the canvas and transfer cells to the driver's own buffer format.

Border utilities

Sourceval border_chars_of_style : border_style -> border_chars

border_chars_of_style style returns the character set for a given border style.