Struct TextRun 

pub struct TextRun { /* private fields */ }

Shaped text — built once, re-laid-out cheaply on width changes.

Implements Measure so it can be dropped into a crate::composition::Patch::slot via crate::layout::Cell::measured.

Implementations

impl TextRun

pub fn new(text: &str, style: &TextStyle, dpi: f64) -> Self

Shape text with style at dpi (typically 96 for screen output). The point-size on style is converted to pixels via size_px = size_pt * dpi / 72 before parley shapes the glyphs. Full shaping cost is paid here; later calls to Measure::height_at and draw_text only re-break lines.

Examples found in repository

examples/composition_demo.rs (line 20)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn weighted_text_cell(text: &str, size: f32, weight: u16) -> Cell {
    Cell::measured(TextRun::new(
        text,
        &TextStyle::new(size).weight(weight),
        96.0,
    ))
}

fn color_for_region(region: &str) -> Color {
    match region {
        "panel" => rgb8(40, 50, 70),
        "title" => rgb8(220, 180, 90),
        "subtitle" => rgb8(180, 150, 70),
        "caption" => rgb8(180, 130, 90),
        "axis_left" | "axis_right" | "axis_top" | "axis_bottom" => rgb8(160, 100, 130),
        "axis_left_title" | "axis_right_title" | "axis_top_title" | "axis_bottom_title" => {
            rgb8(200, 120, 160)
        }
        "strip_left" | "strip_right" | "strip_top" | "strip_bottom" => rgb8(90, 140, 180),
        "legend_left" | "legend_right" | "legend_top" | "legend_bottom" => rgb8(110, 180, 140),
        _ => rgb8(120, 120, 120),
    }
}

/// Build an inner patch with axis labels and a panel-axis title. Each
/// `TextRun` provides its own intrinsic width/height to the layout solver.
fn build_inner_patch(id: &str, y_axis_text: &str, y_axis_title: &str, x_axis_title: &str) -> Patch {
    Patch::new(id)
        .slot(Slot::AxisLeft, text_cell(y_axis_text, 12.0))
        .slot(
            Slot::AxisLeftTitle,
            weighted_text_cell(y_axis_title, 13.0, 500),
        )
        .slot(Slot::AxisBottom, text_cell("0  25  50  75  100", 12.0))
        .slot(
            Slot::AxisBottomTitle,
            weighted_text_cell(x_axis_title, 13.0, 500),
        )
        .slot(Slot::Panel, Cell::empty())
}

fn main() {
    let (w, h) = (1200u32, 700u32);
    let dpi = 96.0;

    let inner_a = build_inner_patch("plot_a", "0\n50\n100", "Pressure (kPa)", "Time (s)");
    let inner_b = build_inner_patch(
        "plot_b",
        "0\n10000\n20000\n30000",
        "Particle count",
        "Time (s)",
    );

    // Header carries title + subtitle; footer carries caption. Both have no
    // panel content — their composition rows are sized to chrome height only
    // (Fr(0.0) panel weight so the middle row absorbs all leftover height).
    let header = Patch::new("header")
        .slot(
            Slot::Title,
            weighted_text_cell("Reactor diagnostics", 28.0, 700),
        )
        .slot(
            Slot::Subtitle,
            text_cell("Pressure and particle count over the morning run", 16.0),
        );
    let footer = Patch::new("footer").slot(
        Slot::Caption,
        text_cell("Source: in-line telemetry, smoothed at 1s intervals", 11.0),
    );
    let composed = Composition::empty(3, 1)
        .heights(vec![Track::Fr(0.0), Track::Fr(1.0), Track::Fr(0.0)])
        .place(1, 1, Span::cell(), header)
        .place(2, 1, Span::cell(), beside(inner_a, inner_b))
        .place(3, 1, Span::cell(), footer);

    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = Stroke::new(1.0);
        let text_brush: Brush = rgb8(30, 30, 40).into();

        // Background colour rectangles for chrome.
        for (_id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let color = color_for_region(region);
            let tinted = Color::new([
                color.components[0],
                color.components[1],
                color.components[2],
                0.18,
            ]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tinted),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(color),
                None,
                &path,
                PickId::Skip,
            );
        }

        // Panels on top.
        for (_id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for_region(region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }

        // Draw the actual text. We reach into the patches again to get a
        // `TextRun` reference — the composition layout doesn't hand us the
        // measure values back. For the demo, just rebuild a separate TextRun
        // for each slot keyed by the same text so we can render it.
        for (id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let text = match (id, region) {
                ("header", "title") => "Reactor diagnostics",
                ("header", "subtitle") => "Pressure and particle count over the morning run",
                ("footer", "caption") => "Source: in-line telemetry, smoothed at 1s intervals",
                ("plot_a", "axis_left") => "0\n50\n100",
                ("plot_a", "axis_left_title") => "Pressure (kPa)",
                ("plot_a", "axis_bottom") => "0  25  50  75  100",
                ("plot_a", "axis_bottom_title") => "Time (s)",
                ("plot_b", "axis_left") => "0\n10000\n20000\n30000",
                ("plot_b", "axis_left_title") => "Particle count",
                ("plot_b", "axis_bottom") => "0  25  50  75  100",
                ("plot_b", "axis_bottom_title") => "Time (s)",
                _ => continue,
            };
            let size = match region {
                "title" => 28.0,
                "subtitle" => 16.0,
                "caption" => 11.0,
                "axis_left_title" | "axis_bottom_title" => 13.0,
                _ => 12.0,
            };
            let weight = match region {
                "title" => 700,
                "axis_left_title" | "axis_bottom_title" => 500,
                _ => 400,
            };
            let style = TextStyle::new(size).weight(weight);
            let run = TextRun::new(text, &style, 96.0);
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/composition_demo.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());

    let panel_a = layout.get("plot_a", Slot::Panel).unwrap();
    let panel_b = layout.get("plot_b", Slot::Panel).unwrap();
    let title = layout.get("header", Slot::Title).unwrap();
    println!("plot_a.panel = {:?}", panel_a);
    println!("plot_b.panel = {:?}", panel_b);
    println!("header.title = {:?}", title);
}

examples/nesting_asymmetric.rs (line 22)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn plot(id: &str, title: &str, axis_left: &str, axis_bottom: &str) -> Patch {
    Patch::new(id)
        .slot(Slot::Title, text_cell(title, 16.0))
        .slot(Slot::AxisLeft, text_cell(axis_left, 11.0))
        .slot(Slot::AxisBottom, text_cell(axis_bottom, 11.0))
        .slot(Slot::Panel, Cell::empty())
}

fn color_for_region(region: &str) -> Color {
    match region {
        "panel" => rgb8(40, 60, 90),
        "title" => rgb8(220, 180, 90),
        "axis_left" | "axis_bottom" => rgb8(160, 100, 130),
        _ => rgb8(120, 120, 120),
    }
}

fn main() {
    let (w, h) = (1200u32, 700u32);
    let dpi = 96.0;

    let row_three = grid(
        1,
        3,
        vec![
            plot("a1", "Series A1", "0\n10\n20", "0  5  10").into(),
            plot("a2", "Series A2", "0\n50\n100", "0  5  10").into(),
            plot("a3", "Series A3", "0\n500\n1000", "0  5  10").into(),
        ],
    );
    let row_two = grid(
        1,
        2,
        vec![
            plot("b1", "Series B1 (wider)", "0\n100\n200\n300", "0   25   50").into(),
            plot("b2", "Series B2 (wider)", "0\n5000\n10000", "0   25   50").into(),
        ],
    );
    let composed = stack(row_three, row_two);
    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = hephaestus::stroke::Stroke::new(1.0);
        let text_brush: Brush = rgb8(20, 20, 30).into();

        // Chrome rects, tinted background.
        for (_id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let c = color_for_region(region);
            let tint = Color::new([c.components[0], c.components[1], c.components[2], 0.20]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tint),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(c),
                None,
                &path,
                PickId::Skip,
            );
        }

        // Panels solid.
        for (_id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for_region(region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }

        // Text labels in chrome.
        for (id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let text = match (id, region) {
                ("a1", "title") => "Series A1",
                ("a2", "title") => "Series A2",
                ("a3", "title") => "Series A3",
                ("b1", "title") => "Series B1 (wider)",
                ("b2", "title") => "Series B2 (wider)",
                ("a1", "axis_left") => "0\n10\n20",
                ("a2", "axis_left") => "0\n50\n100",
                ("a3", "axis_left") => "0\n500\n1000",
                ("b1", "axis_left") => "0\n100\n200\n300",
                ("b2", "axis_left") => "0\n5000\n10000",
                (_, "axis_bottom") if id.starts_with('a') => "0  5  10",
                (_, "axis_bottom") if id.starts_with('b') => "0   25   50",
                _ => continue,
            };
            let size = if region == "title" { 16.0 } else { 11.0 };
            let run = TextRun::new(text, &TextStyle::new(size), 96.0);
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/nesting_asymmetric.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/nesting_chrome_coupling.rs (line 36)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn plain_plot(id: &str) -> Patch {
    Patch::new(id).slot(Slot::Panel, Cell::empty())
}

fn plot_with_axis_top(id: &str, axis_top_text: &str) -> Patch {
    Patch::new(id)
        .slot(Slot::AxisTop, text_cell(axis_top_text, 14.0))
        .slot(Slot::Panel, Cell::empty())
}

fn color_for_region(region: &str) -> Color {
    match region {
        "panel" => rgb8(40, 60, 90),
        "axis_top" => rgb8(200, 100, 130),
        _ => rgb8(120, 120, 120),
    }
}

fn main() {
    let (w, h) = (1400u32, 400u32);
    let dpi = 96.0;

    let plain = plain_plot("plain");
    let nested = grid(
        1,
        3,
        vec![
            plain_plot("c1").into(),
            plot_with_axis_top("c2", "this is a TALL axis_top label\nspanning multiple lines\nto stress chrome propagation").into(),
            plain_plot("c3").into(),
        ],
    );
    let composed = beside(plain, nested);
    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = hephaestus::stroke::Stroke::new(1.0);
        let text_brush: Brush = rgb8(20, 20, 30).into();

        for (_id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let c = color_for_region(region);
            let tint = Color::new([c.components[0], c.components[1], c.components[2], 0.20]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tint),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(c),
                None,
                &path,
                PickId::Skip,
            );
        }
        for (_id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for_region(region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }
        // Label the only chrome that has text content.
        if let Some(rect) = layout.get("c2", Slot::AxisTop) {
            let run = TextRun::new(
                "this is a TALL axis_top label\nspanning multiple lines\nto stress chrome propagation",
                &TextStyle::new(14.0),
                96.0,
            );
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/nesting_chrome_coupling.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());

    // Print the panel y-coordinates so the user can sanity-check that
    // the plain panel starts at the same y as the inner panels even
    // though it has no axis_top.
    let plain_y = layout.get("plain", Slot::Panel).unwrap();
    let c1_y = layout.get("c1", Slot::Panel).unwrap();
    let c2_y = layout.get("c2", Slot::Panel).unwrap();
    let c3_y = layout.get("c3", Slot::Panel).unwrap();
    println!(
        "panel y0: plain={}, c1={}, c2={}, c3={}",
        plain_y.y0, c1_y.y0, c2_y.y0, c3_y.y0
    );
    println!("(all four should be equal — bidirectional sizer coupling at work)");
}

examples/nesting_deep.rs (line 26)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn plain(id: &str) -> Patch {
    Patch::new(id).slot(Slot::Panel, Cell::empty())
}

fn color_for_region(region: &str) -> Color {
    match region {
        "panel" => rgb8(40, 60, 90),
        "axis_top" => rgb8(200, 100, 130),
        "axis_bottom" => rgb8(160, 100, 130),
        _ => rgb8(120, 120, 120),
    }
}

fn main() {
    let (w, h) = (1400u32, 400u32);
    let dpi = 96.0;

    // Deepest level: two plots, the first carries the chrome that needs
    // to propagate all the way up to the root composition.
    let leaf = beside(
        Patch::new("leaf_l")
            .slot(Slot::AxisTop, text_cell("axis_top from deepest leaf", 14.0))
            .slot(Slot::AxisBottom, text_cell("axis_bottom from leaf", 11.0))
            .slot(Slot::Panel, Cell::empty()),
        plain("leaf_r"),
    );
    // Mid level: a plain plot beside the leaf composition.
    let mid = beside(plain("mid"), leaf);
    // Root level: a plain plot beside the mid composition.
    let composed = beside(plain("root"), mid);

    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = hephaestus::stroke::Stroke::new(1.0);
        let text_brush: Brush = rgb8(20, 20, 30).into();

        for (_id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let c = color_for_region(region);
            let tint = Color::new([c.components[0], c.components[1], c.components[2], 0.20]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tint),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(c),
                None,
                &path,
                PickId::Skip,
            );
        }
        for (_id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for_region(region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }

        if let Some(rect) = layout.get("leaf_l", Slot::AxisTop) {
            let run = TextRun::new("axis_top from deepest leaf", &TextStyle::new(14.0), 96.0);
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
        if let Some(rect) = layout.get("leaf_l", Slot::AxisBottom) {
            let run = TextRun::new("axis_bottom from leaf", &TextStyle::new(11.0), 96.0);
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/nesting_deep.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());

    // Print panel y0s so the user can verify alignment across all 3 nesting levels.
    let root_panel = layout.get("root", Slot::Panel).unwrap();
    let mid_panel = layout.get("mid", Slot::Panel).unwrap();
    let leaf_l_panel = layout.get("leaf_l", Slot::Panel).unwrap();
    let leaf_r_panel = layout.get("leaf_r", Slot::Panel).unwrap();
    println!(
        "panel y0: root={}, mid={}, leaf_l={}, leaf_r={}",
        root_panel.y0, mid_panel.y0, leaf_l_panel.y0, leaf_r_panel.y0
    );
    println!("(all four should be equal — propagation across 3 nesting levels)");
}

examples/nesting_faceted_title.rs (line 33)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn weighted_text_cell(text: &str, size: f32, weight: u16) -> Cell {
    Cell::measured(TextRun::new(
        text,
        &TextStyle::new(size).weight(weight),
        96.0,
    ))
}

fn facet(id: &str, axis_left: &str, axis_bottom: &str) -> Patch {
    Patch::new(id)
        .slot(Slot::AxisLeft, text_cell(axis_left, 11.0))
        .slot(Slot::AxisBottom, text_cell(axis_bottom, 11.0))
        .slot(Slot::Panel, Cell::empty())
}

fn color_for_region(region: &str) -> Color {
    match region {
        "panel" => rgb8(40, 60, 90),
        "title" => rgb8(220, 180, 90),
        "subtitle" => rgb8(180, 150, 70),
        "caption" => rgb8(180, 130, 90),
        "axis_left" | "axis_bottom" => rgb8(160, 100, 130),
        _ => rgb8(120, 120, 120),
    }
}

fn main() {
    let (w, h) = (1400u32, 800u32);
    let dpi = 96.0;

    // A 2×3 grid of facets, each with its own axis chrome. The
    // composition is then annotated with shared chrome via `.slot(...)`
    // directly — no wrapper composition, no manual span calculations.
    let mut facet_cells = Vec::new();
    for r in 1..=2 {
        for c in 1..=3 {
            let id = format!("f{}_{}", r, c);
            facet_cells.push(facet(&id, "0\n50\n100", "0  25  50").into());
        }
    }
    let composed = grid(2, 3, facet_cells)
        .id("plot")
        .slot(
            Slot::Title,
            weighted_text_cell("Reactor diagnostics across runs", 26.0, 700),
        )
        .slot(
            Slot::Subtitle,
            text_cell(
                "Each panel: a separate 60-minute run; same scales throughout",
                15.0,
            ),
        )
        .slot(
            Slot::AxisLeftTitle,
            weighted_text_cell("Pressure (kPa)", 14.0, 500),
        )
        .slot(
            Slot::AxisBottomTitle,
            weighted_text_cell("Elapsed time (minutes)", 14.0, 500),
        )
        .slot(
            Slot::Caption,
            text_cell(
                "Source: in-line telemetry, smoothed at 1s; runs ordered chronologically.",
                11.0,
            ),
        );

    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = hephaestus::stroke::Stroke::new(1.0);
        let text_brush: Brush = rgb8(20, 20, 30).into();

        for (_id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let c = color_for_region(region);
            let tint = Color::new([c.components[0], c.components[1], c.components[2], 0.20]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tint),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(c),
                None,
                &path,
                PickId::Skip,
            );
        }
        for (_id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for_region(region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }

        for (id, region, rect) in layout.iter() {
            let (text, size, weight) = match (id, region) {
                ("plot", "title") => ("Reactor diagnostics across runs", 26.0, 700),
                ("plot", "subtitle") => (
                    "Each panel: a separate 60-minute run; same scales throughout",
                    15.0,
                    400,
                ),
                ("plot", "caption") => (
                    "Source: in-line telemetry, smoothed at 1s; runs ordered chronologically.",
                    11.0,
                    400,
                ),
                ("plot", "axis_left_title") => ("Pressure (kPa)", 14.0, 500),
                ("plot", "axis_bottom_title") => ("Elapsed time (minutes)", 14.0, 500),
                (_, "axis_left") => ("0\n50\n100", 11.0, 400),
                (_, "axis_bottom") => ("0  25  50", 11.0, 400),
                _ => continue,
            };
            let run = TextRun::new(text, &TextStyle::new(size).weight(weight), 96.0);
            draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/nesting_faceted_title.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());

    // Sanity check: chrome rects line up with the facet panel band.
    let title = layout.get("plot", Slot::Title).unwrap();
    let caption = layout.get("plot", Slot::Caption).unwrap();
    let axis_left_title = layout.get("plot", Slot::AxisLeftTitle).unwrap();
    let axis_bottom_title = layout.get("plot", Slot::AxisBottomTitle).unwrap();
    let f1_1_panel = layout.get("f1_1", Slot::Panel).unwrap();
    let f1_3_panel = layout.get("f1_3", Slot::Panel).unwrap();
    let f2_3_panel = layout.get("f2_3", Slot::Panel).unwrap();
    println!(
        "plot.title:             x0={:>5.0}  x1={:>5.0}  y0={:>5.0}  y1={:>5.0}",
        title.x0, title.x1, title.y0, title.y1
    );
    println!(
        "plot.caption:           x0={:>5.0}  x1={:>5.0}  y0={:>5.0}  y1={:>5.0}",
        caption.x0, caption.x1, caption.y0, caption.y1
    );
    println!(
        "plot.axis_left_title:   x0={:>5.0}  x1={:>5.0}  y0={:>5.0}  y1={:>5.0}",
        axis_left_title.x0, axis_left_title.x1, axis_left_title.y0, axis_left_title.y1
    );
    println!(
        "plot.axis_bottom_title: x0={:>5.0}  x1={:>5.0}  y0={:>5.0}  y1={:>5.0}",
        axis_bottom_title.x0, axis_bottom_title.x1, axis_bottom_title.y0, axis_bottom_title.y1
    );
    println!(
        "facets panel band:      x0={:>5.0}  x1={:>5.0}  y0={:>5.0}  y1={:>5.0}",
        f1_1_panel.x0, f1_3_panel.x1, f1_1_panel.y0, f2_3_panel.y1
    );
}

examples/nesting_fixed_aspect.rs (line 44)

fn text_cell(text: &str, size: f32) -> Cell {
    Cell::measured(TextRun::new(text, &TextStyle::new(size), 96.0))
}

fn plain(id: &str) -> Patch {
    Patch::new(id).slot(Slot::Panel, Cell::empty())
}

fn fixed_square(id: &str, label: &str) -> Patch {
    // Chrome on a fixed patch is fine — the solver's second iteration
    // picks up the resolved Auto-row heights from iter 0 and reshapes
    // the respected fr distribution to honour the lock anyway. The
    // axis_top here proves it: panels still report ratio = 1.000.
    Patch::new(id)
        .aspect(1.0, 1.0)
        .slot(Slot::AxisTop, text_cell(label, 12.0))
        .slot(Slot::Panel, Cell::empty())
}

fn color_for(id: &str, region: &str) -> Color {
    match (id, region) {
        (_, "panel") if id.starts_with("fixed") => rgb8(80, 140, 80), // green for locked
        (_, "panel") => rgb8(40, 60, 90),                             // blue for flex
        (_, "axis_top") => rgb8(200, 100, 130),
        _ => rgb8(120, 120, 120),
    }
}

fn main() {
    // Wide viewport so the lock-vs-flex difference is obvious.
    let (w, h) = (1600u32, 400u32);
    let dpi = 96.0;

    // Three flex plots in a 2-level beside chain — flex_a is at the
    // outer level beside the deeper composition; flex_b and flex_c sit
    // one level deeper.
    let flex_chain = beside(plain("flex_a"), beside(plain("flex_b"), plain("flex_c")));
    // Both fixed-aspect plots sit in the SAME outermost composition row
    // as the flex chain. `Composition::beside` extends an existing 1-row
    // composition by appending a cell — all five end up as direct
    // siblings of the same outer grid, sharing one panel row.
    let composed = beside(fixed_square("fixed_l", "1:1"), flex_chain)
        .append_col(fixed_square("fixed_r", "1:1"));

    let layout = composed.solve(hephaestus::Size::new(w as f64, h as f64), dpi);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let stroke = hephaestus::stroke::Stroke::new(1.0);
        let text_brush: Brush = rgb8(20, 20, 30).into();

        // Chrome first (axes / etc.).
        for (id, region, rect) in layout.iter() {
            if region == "panel" {
                continue;
            }
            let c = color_for(id, region);
            let tint = Color::new([c.components[0], c.components[1], c.components[2], 0.20]);
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(tint),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(c),
                None,
                &path,
                PickId::Skip,
            );
        }
        // Panels (with green for locked, blue for flex).
        for (id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &Brush::Solid(color_for(id, region)),
                None,
                &path,
                PickId::Skip,
            );
            scene.stroke(
                &stroke,
                Affine::IDENTITY,
                &Brush::Solid(rgb8(255, 255, 255)),
                None,
                &path,
                PickId::Skip,
            );
        }
        // Panel-centre labels noting locked vs flex + actual width:height.
        for (id, region, rect) in layout.iter() {
            if region != "panel" {
                continue;
            }
            let w = rect.x1 - rect.x0;
            let h = rect.y1 - rect.y0;
            let label = if id.starts_with("fixed") {
                format!("{id}\nlocked 1:1\n{w:.0}×{h:.0}")
            } else {
                format!("{id}\nflex\n{w:.0}×{h:.0}")
            };
            let run = TextRun::new(&label, &TextStyle::new(13.0).weight(500), 96.0);
            let brush: Brush = rgb8(255, 255, 255).into();
            draw_text_in_rect(scene, &run, rect, &brush, PickId::Skip);
        }
        // Axis-top labels on the two fixed patches.
        for id in &["fixed_l", "fixed_r"] {
            if let Some(rect) = layout.get(id, Slot::AxisTop) {
                let run = TextRun::new(&format!("{id} 1:1"), &TextStyle::new(12.0), 96.0);
                draw_text_in_rect(scene, &run, rect, &text_brush, PickId::Skip);
            }
        }
    }

    let mut pixels = vec![0u8; (w * h * 4) as usize];
    let bg: Color = rgb8(248, 248, 252);
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");

    let path = std::env::current_dir()
        .unwrap()
        .join("examples/nesting_fixed_aspect.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());

    // Print per-panel widths/heights so the aspect locks are verifiable
    // from a terminal too. All five panels should report the same
    // height (alignment across the outer row); fixed_l and fixed_r
    // additionally have width == height (locked 1:1).
    for id in &["fixed_l", "flex_a", "flex_b", "flex_c", "fixed_r"] {
        let p = layout.get(id, Slot::Panel).unwrap();
        let pw = p.x1 - p.x0;
        let ph = p.y1 - p.y0;
        let ratio = pw / ph;
        let tag = if id.starts_with("fixed") {
            "locked 1:1"
        } else {
            "flex"
        };
        println!("{id:>8} ({tag:>10}):  w={pw:>5.1}  h={ph:>5.1}  ratio={ratio:.3}");
    }
    println!("(all five panels share one outer row → all heights equal;");
    println!(" fixed_l and fixed_r additionally report ratio ≈ 1.000.)");
}

Additional examples can be found in:

• examples/nesting_outer_chrome_propagates.rs

pub fn set_max_width(&self, max_width: f32, alignment: HAlign) -> f32

Re-break lines at max_width pixels, applying alignment to the resulting layout. Equivalent to Measure::height_at(max_width, _) but exposed for callers that want to draw without first running through a composition solve.

alignment controls justification within the wrap box: HAlign::Start leaves every line flush against the leading edge; Center / End / Justify apply the matching direction-aware alignment.

pub fn natural_width(&self) -> f64

Natural unwrapped content width in pixels — the width the text would occupy if laid out on a single line per paragraph break in the source. Computed once at construction; stable regardless of subsequent Self::set_max_width calls. Used by label-style geoms to anchor the text against its intrinsic dimensions.

pub fn natural_height(&self) -> f64

Natural unwrapped content height in pixels. Stable across Self::set_max_width calls.

pub fn current_height(&self) -> f64

Current laid-out height in pixels — reflects the most recent Self::set_max_width / Measure::height_at call. Equals Self::natural_height when no wrap has been requested.

pub fn content_width(&self) -> f64

Actual rendered content width in pixels — the widest line in the current layout. Reflects the most recent line-break, so when Self::set_max_width has been called the result is the actual wrapped width (usually less than the constraint, since parley breaks at word boundaries). When no wrap has been requested the layout is single-line and this matches Self::natural_width.

pub fn baseline_offset(&self) -> f64

Offset from the layout’s top edge to the baseline of the first line, in pixels. Differs from the font’s ascent metric when the resolved line height includes leading — the baseline sits below the typographic ascent by half the leading. Used by chrome labels to convert between baseline-anchored and top-anchored positioning.

pub fn cap_height(&self) -> f64

Cap-height of the first run, in pixels — distance from the baseline to the top of capital letters. Falls back to x_height (and then 0.7 × ascent as a last resort) when the font doesn’t report cap-height. Used by axis / legend label centering: a numeric or uppercase label centered on cap_height looks visually balanced against its tick or swatch, whereas centering on the full natural_height reserves descender space the glyphs don’t occupy and shifts the visual centre off-target.

pub fn last_line_descender(&self) -> f64

Font descender of the last line in the current layout, in pixels. Used by background-rect geoms to apply the ggplot2 geom_label-style padding rebalance — bump top padding up to at least the descender and reduce bottom padding by the same — so visible glyphs centre vertically in the rect even when the last line has no descenders (“men” vs “jay”).

pub fn first_line_ascender_offset(&self) -> f64

Y position of the first line’s ascender top, relative to the layout’s top edge. Equivalent to the top half-leading on the first line — the empty pixels above the visible glyphs that the line-box reserves on its way to line-height.

pub fn last_line_descender_offset_from_top(&self) -> f64

Y position of the last line’s descender bottom, relative to the layout’s top edge. Equivalent to current_height - bottom half-leading on the last line.

pub fn inked_height(&self) -> f64

Inked height of the current layout — from the first line’s ascender top to the last line’s descender bottom, with leading appearing only between lines (not above the first or below the last). The natural text box.

Trait Implementations

impl Measure for TextRun

fn width_hint(&self, _dpi: f64) -> WidthHint

Report this leaf’s intrinsic width — either a stable minimum (WidthHint::Min) or a height-dependent value that opts the leaf into iteration (WidthHint::NeedsHeight).

fn height_at(&self, width: f64, _dpi: f64) -> f64

Report this leaf’s intrinsic height when allocated width pixels.

fn width_at(&self, _height: f64, _dpi: f64) -> f64

Report a width given a resolved height. Consulted only during iteration for cells that returned WidthHint::NeedsHeight. Default 0.0 is correct for content that uses WidthHint::Min.