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
cells.len() == width * height- Width and height never change after creation
- Scissor stack intersection monotonically decreases on push
- Opacity stack product stays in
[0.0, 1.0] - 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 ∈ DThis 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§
- Adaptive
Double Buffer - Adaptive double-buffered render target with allocation efficiency.
- Adaptive
Stats - Statistics for adaptive buffer allocation.
- Buffer
- A 2D grid of terminal cells.
- Dirty
Span Config - Configuration for dirty-span tracking.
- Dirty
Span Stats - Dirty-span statistics for logging/telemetry.
- Double
Buffer - Double-buffered render target with O(1) swap.
Constants§
- BUFFER_
CHECKSUM_ FNV_ OFFSET_ BASIS - 64-bit FNV-1a offset basis used by
buffer_checksum. - BUFFER_
CHECKSUM_ FNV_ PRIME - 64-bit FNV-1a prime used by
buffer_checksum.
Functions§
- buffer_
cells_ checksum - Compute the 64-bit FNV-1a checksum over a slice of
Cells (16 bytes per cell). - buffer_
checksum - Compute the 64-bit FNV-1a checksum over each cell’s 16 bytes in row-major order.