Skip to main content

Module buffer

ftui_render

Module buffer 

Source
Expand description

Buffer grid storage.

The Buffer is a 2D grid of Cells representing the terminal display. It provides efficient cell access, scissor (clipping) regions, and opacity stacks for compositing.

§Layout

Cells are stored in row-major order: index = y * width + x.

§Invariants

  1. cells.len() == width * height
  2. Width and height never change after creation
  3. Scissor stack intersection monotonically decreases on push
  4. Opacity stack product stays in [0.0, 1.0]
  5. Scissor/opacity stacks always have at least one element

§Dirty Row Tracking (bd-4kq0.1.1)

§Mathematical Invariant

Let D be the set of dirty rows. The fundamental soundness property:

∀ y ∈ [0, height): if ∃ x such that old(x, y) ≠ new(x, y), then y ∈ D

This ensures the diff algorithm can safely skip non-dirty rows without missing any changes. The invariant is maintained by marking rows dirty on every cell mutation.

§Bookkeeping Cost

  • O(1) per mutation (single array write)
  • O(height) space for dirty bitmap
  • Target: < 2% overhead vs baseline rendering

§Dirty Span Tracking (bd-3e1t.6.2)

Dirty spans refine dirty rows by recording per-row x-ranges of mutations.

§Invariant

∀ (x, y) mutated since last clear, ∃ span in row y with x ∈ [x0, x1)

Spans are sorted, non-overlapping, and merged when overlapping, adjacent, or separated by at most DIRTY_SPAN_MERGE_GAP cells (gap becomes dirty). If a row exceeds DIRTY_SPAN_MAX_SPANS_PER_ROW, it falls back to full-row scan.

Structs§

AdaptiveDoubleBuffer
Adaptive double-buffered render target with allocation efficiency.
AdaptiveStats
Statistics for adaptive buffer allocation.
Buffer
A 2D grid of terminal cells.
DirtySpanConfig
Configuration for dirty-span tracking.
DirtySpanStats
Dirty-span statistics for logging/telemetry.
DoubleBuffer
Double-buffered render target with O(1) swap.