Skip to main content

Module incremental

ftui_layout

Module incremental 

Source
Expand description

Incremental layout engine (bd-3p4y1.3).

Wraps DepGraph and a per-node result cache so that only dirty subtrees are re-evaluated during layout. Clean subtrees return their cached Vec<Rect> in O(1).

§Key Invariant

The output of incremental layout is bit-identical to full layout. The same traversal order (DFS pre-order) and the same computation at each dirty node guarantee isomorphic results.

§Usage

ⓘ
use ftui_layout::incremental::IncrementalLayout;
use ftui_layout::dep_graph::InputKind;

let mut inc = IncrementalLayout::new();

// Build the widget tree.
let root = inc.add_node(None);
let left = inc.add_node(Some(root));
let right = inc.add_node(Some(root));

// First pass: everything computes (cold cache).
inc.propagate();
let root_rects = inc.get_or_compute(root, area, |a| outer_flex.split(a));
let left_rects = inc.get_or_compute(left, root_rects[0], |a| left_flex.split(a));
let right_rects = inc.get_or_compute(right, root_rects[1], |a| right_flex.split(a));

// Only left content changed — right subtree is skipped.
inc.mark_changed(left, InputKind::Content, new_hash);
inc.propagate();
let root_rects2 = inc.get_or_compute(root, area, |a| outer_flex.split(a));
let left_rects2 = inc.get_or_compute(left, root_rects2[0], |a| left_flex.split(a));
let right_rects2 = inc.get_or_compute(right, root_rects2[1], |a| right_flex.split(a));
// right_rects2 was returned from cache without calling right_flex.split().

§Flex Siblings

In flex layouts, changing one child can affect all siblings (because remaining space is redistributed). Use mark_dirty_with_ancestors to dirty a child and all its ancestors. Since parent→child edges already exist (from add_node), dirtying the parent automatically propagates to all siblings during propagate().

§Force-Full Fallback

Call IncrementalLayout::set_force_full to bypass the cache entirely and recompute every node. This is useful for debugging or as an env-var fallback (FRANKENTUI_FULL_LAYOUT=1, wired in bd-3p4y1.6).

Structs§

IncrementalLayout
Incremental layout engine.
IncrementalStats
Statistics for a single incremental layout pass.