Struct BufferDiff 

pub struct BufferDiff { /* private fields */ }

The diff between two buffers.

Contains the list of (x, y) positions where cells differ.

Implementations

impl BufferDiff

pub fn new() -> Self

Create an empty diff.

pub fn with_capacity(capacity: usize) -> Self

Create a diff with pre-allocated capacity.

pub fn full(width: u16, height: u16) -> Self

Create a diff that marks every cell as changed.

Useful for full-screen redraws where the previous buffer is unknown (e.g., after resize or initial present).

pub fn compute(old: &Buffer, new: &Buffer) -> Self

Compute the diff between two buffers.

Uses row-major scan for cache efficiency. Both buffers must have the same dimensions.

Optimizations

• Row-skip fast path: unchanged rows are detected via slice equality and skipped entirely. For typical UI updates where most rows are static, this eliminates the majority of per-cell work.
• Blockwise row scan: rows with sparse edits are scanned in coarse blocks, skipping unchanged blocks and only diving into the blocks that differ.
• Direct slice iteration: row slices are computed once per row instead of calling get_unchecked(x, y) per cell, eliminating repeated y * width + x index arithmetic.
• Branchless cell comparison: bits_eq uses bitwise AND to avoid branch mispredictions in the inner loop.

Panics

Debug-asserts that both buffers have identical dimensions.

pub fn compute_into(&mut self, old: &Buffer, new: &Buffer)

Compute the diff into an existing buffer to reuse allocation.

pub fn compute_dirty(old: &Buffer, new: &Buffer) -> Self

Compute the diff between two buffers using dirty-row hints.

Only rows marked dirty in new are compared cell-by-cell. Clean rows are skipped entirely (O(1) per clean row).

Soundness precondition

new’s content at the time of its last clear_dirty() / reset_for_frame() must have been identical to old. The dirty state (rows, spans, per-cell bits) records mutations since that point, and this path narrows the scan not just to dirty rows but to the recorded dirty spans/tiles within them — so any old-vs-new difference that is not also a recorded mutation is silently missed. The row-level invariant alone (“changed rows are dirty”) is NOT sufficient. The production writer satisfies the precondition by diffing consecutive frames of one buffer lineage whose baseline was fully dirty.

False positives (marking a row/span dirty when it didn’t actually change) are safe — they only cost the per-cell scan for that region.

pub fn compute_dirty_into(&mut self, old: &Buffer, new: &Buffer)

Compute the dirty-row diff into an existing buffer to reuse allocation.

Same soundness precondition as compute_dirty: new’s dirty state must have been cleared while its content was identical to old.

pub fn compute_certified_into( &mut self, old: &Buffer, new: &Buffer, hint: DiffSkipHint, )

Compute the diff with a certificate-based skip hint.

The caller (typically the runtime loop) evaluates a render certificate and passes the result as a DiffSkipHint. This method shortcuts the diff computation when the certificate allows it:

• FullDiff: performs the standard dirty-diff computation.
• SkipDiff: clears changes (no work to present). The caller must ensure that old and new buffers are identical when issuing this hint.
• NarrowToRows(rows): only diffs the specified rows, skipping all others even if marked dirty. Useful when the certificate identifies exactly which rows changed.

Safety invariant

Issuing SkipDiff when buffers differ produces stale frames. The certificate evaluator must guarantee correctness — this method trusts the hint without verification. The FullDiff arm delegates to compute_dirty_into and inherits its baseline-equals-old precondition. NarrowToRows rows are processed in ascending unique order (the method sorts/dedups defensively) so the change list keeps the sorted-unique invariant runs() requires.

Tracing

Emits a tracing event when a skip or narrow is applied, including the hint type and resulting change count for evidence logging.

pub fn fill_full(&mut self, width: u16, height: u16)

Populate the diff with all cells (full redraw) reusing existing capacity.

pub fn len(&self) -> usize

Number of changed cells.

pub fn is_empty(&self) -> bool

Check if no cells changed.

pub fn changes(&self) -> &[(u16, u16)]

Get the list of changed positions.

pub fn last_tile_stats(&self) -> Option<TileDiffStats>

Access the last tile diagnostics from a dirty diff pass.

pub fn tile_config_mut(&mut self) -> &mut TileDiffConfig

Mutably access tile diff configuration.

pub fn runs(&self) -> Vec<ChangeRun>

Convert point changes into contiguous runs.

Consecutive x positions on the same row are coalesced into a single run. This enables efficient cursor positioning in the presenter.

pub fn runs_into(&self, out: &mut Vec<ChangeRun>)

Like runs() but writes into a caller-provided buffer, avoiding per-frame allocation when the buffer is reused across frames.

pub fn iter(&self) -> impl Iterator<Item = (u16, u16)> + '_

Iterate over changed positions.

pub fn clear(&mut self)

Clear the diff, removing all recorded changes.

Trait Implementations

impl Clone for BufferDiff

fn clone(&self) -> BufferDiff

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BufferDiff

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BufferDiff

fn default() -> BufferDiff

Returns the “default value” for a type.