Grid viewport

draw_grid infers rectangular board dimensions, draws visible cells, and returns a GridViewport for paths, text, and markers. It supports spacing, centering, absolute x/y origins, board-space camera offsets, and clipped screen regions. Oversized boards anchor at the region’s top left. Empty boards draw nothing; ragged rows are rejected. Offscreen cells do not invoke glyph callbacks.

from bruhanimate import Buffer, draw_grid

buffer = Buffer(10, 30)
grid = draw_grid(buffer, ("S...", ".##.", "...E"), spacing=(2, 1),
                 region=(0, 1, 30, 8))
grid.path(((0, 0), (1, 0), (2, 0)), "*")
grid.put(3, 2, "@")

Glyph styling accepts a mapping or glyph(value, column, row) callback. None is transparent; spaces paint. Use one printable character, optionally ANSI SGR styled. Wide/combining glyphs and cursor controls are rejected. Ambiguous-width glyphs assume one terminal cell. Grid drawing leaves gaps and outside cells alone.

Board coordinates, single-cell styling, and clipped grid drawing.

class bruhanimate.grid.GridViewport(buffer: Buffer, columns: int, rows: int, *, x: int | None = None, y: int | None = None, spacing: tuple[int, int] = (1, 1), camera: tuple[int, int] = (0, 0), region: tuple[int, int, int, int] | None = None)

Map a rectangular board to a clipped screen region.

spacing gives columns/rows between glyph anchors. By default a fitting board centers inside region=(x, y, width, height), or the whole Buffer. Oversized boards anchor at the region’s top left. Explicit x/y are screen coordinates. camera=(column, row) subtracts a board-space offset from that placement.

Use single-cell glyphs, optionally wrapped in ANSI SGR color/reset sequences. Wide glyphs, combining marks, controls, and raw cursor escapes are rejected. Ambiguous-width glyphs (including box drawing) assume a one-cell terminal.

__init__(buffer: Buffer, columns: int, rows: int, *, x: int | None = None, y: int | None = None, spacing: tuple[int, int] = (1, 1), camera: tuple[int, int] = (0, 0), region: tuple[int, int, int, int] | None = None)

classmethod from_rows(buffer: Buffer, rows: Sequence[Sequence[Any]], **layout) → GridViewport

Infer dimensions, rejecting ragged input. Empty boards are allowed.

to_screen(column: int, row: int) → tuple[int, int]

Transform a board point without clipping it.

put(column: int, row: int, glyph: str | None) → bool

Paint a board marker if visible; None is transparent. Return painted.

draw(rows: Sequence[Sequence[Any]], glyph: Mapping[Any, str | None] | Callable[[Any, int, int], str | None] | None = None) → None

Draw visible board cells using a value map or glyph(value, col, row).

Shape is validated before drawing. Offscreen cells never invoke the glyph callback. Without a mapper, None is transparent and other values use str.

path(points: Iterable[tuple[int, int]], glyph: str = '*') → None

Paint supplied board points; does not interpolate between vertices.

text(column: int, row: int, text: str) → None

Paint consecutive board cells, respecting spacing and clipping.

bruhanimate.grid.draw_grid(buffer: Buffer, rows: Sequence[Sequence[Any]], *, glyph=None, **layout) → GridViewport

Draw a rectangular board and return its viewport for paths and markers.