Enum Extent 

pub enum Extent {
    Sum {
        px: f64,
        inches: f64,
        percent: f64,
    },
    Min(Box<Extent>, Box<Extent>),
    Max(Box<Extent>, Box<Extent>),
    TrackOf {
        grid: CellId,
        axis: Axis,
        track: u16,
        span: u16,
    },
}

A length value. Internally either a linear combination of pixels, inches, and percentage of the containing axis, a deferred min/max of two sub-lengths (because min(absolute, percent) cannot be reduced without knowing the axis size), or a reference to a tagged grid’s resolved track size (which is only known after solve).

Construct via the px / mm / cm / inch / pt / percent associated functions, Extent::min / Extent::max, or Extent::track_of / Extent::tracks_of. Lengths compose with +, -, unary -, * f64, and / f64; addition through Min/Max distributes exactly (min(a, b) + c = min(a+c, b+c)), so arithmetic stays closed without losing structure. TrackOf is opaque to arithmetic — it composes with Min/Max transparently but + / - / * on a tree containing TrackOf panics. Reach a multi-segment sum via Extent::tracks_of’s span parameter.

Physical units (mm, cm, inch, pt) are resolved to pixels via the dpi passed to Grid::solve. percent is taken as a fraction of the relevant axis of the parent’s grid cell area; the constructor argument is 0.0..=1.0 (so Extent::percent(0.5) is “50%”).

Variants

Sum

Linear combination: px + inches * dpi + percent * axis.

Fields

px: f64

DPI-independent pixel offset.

inches: f64

Physical inches; multiplied by dpi at resolution.

percent: f64

Fraction of the containing axis (1.0 = 100%).

Min(Box<Extent>, Box<Extent>)

Pointwise minimum of two lengths, evaluated at resolution time.

Max(Box<Extent>, Box<Extent>)

Pointwise maximum of two lengths, evaluated at resolution time.

TrackOf

Resolves at solve time to the summed resolved size of span consecutive tracks starting at track (1-indexed) on the given axis of the Grid tagged with id == grid. For span > 1 the corresponding gaps between tracks are included.

The solver runs as a damped fixed-point iteration over its width and height passes; on the first iteration TrackOf evaluates to 0 (no prior data); on subsequent iterations it picks up the resolved track size from the previous iteration. Forward references (a track that references a track later in the solve) are handled by iteration; cycles will not converge and exhaust MAX_ITER.

Fields

grid: CellId

Tag of the target Grid (from Grid::id).

axis: Axis

Whether to read column widths or row heights.

track: u16

1-indexed start track within the target grid.

span: u16

Number of consecutive tracks to sum. Treated as 1 if 0.

Implementations

impl Extent

pub const ZERO: Extent

The zero length.

pub const fn px(v: f64) -> Self

Pure pixels (DPI-independent).

pub const fn mm(v: f64) -> Self

Millimeters — v / 25.4 inches.

pub const fn cm(v: f64) -> Self

Centimeters — v / 2.54 inches.

Examples found in repository

examples/layout_demo.rs (line 47)

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

    // Outer: 5 columns × 3 rows of fr(1).
    let mut root = Grid::new(vec![Track::Fr(1.0); 5], vec![Track::Fr(1.0); 3]);

    // Tag every outer cell so we can outline the underlying grid.
    let mut outer_id = 1u64;
    for r in 1..=3u16 {
        for c in 1..=5u16 {
            root.place_mut(Placement::at(r, c), Grid::cell().id(CellId(outer_id)));
            outer_id += 1;
        }
    }

    // Inner 2×2 in row 2, cols 3..=5, with 1cm left + 25% right insets.
    let mut inner = Grid::new(
        [Track::Fr(1.0), Track::Fr(1.0)],
        [Track::Fr(1.0), Track::Fr(1.0)],
    );
    for r in 1..=2u16 {
        for c in 1..=2u16 {
            inner.place_mut(
                Placement::at(r, c),
                Grid::cell().id(CellId(100 + (r as u64) * 2 + c as u64)),
            );
        }
    }
    root.place_mut(
        Placement::at(2, 3).span(1, 3).inset(
            Inset::default()
                .left(Extent::cm(1.0))
                .right(Extent::percent(0.25)),
        ),
        inner,
    );

    // A 2:1 cell in the top-left, expressed via respect + fr weights.
    root.place_mut(
        Placement::at(1, 1),
        Grid::new([Track::Fr(2.0)], [Track::Fr(1.0)])
            .respect()
            .id(CellId(200)),
    );

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

    // Render.
    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let outer_brush: Brush = rgb8(80, 90, 110).into();
        let outer_stroke = Stroke::new(1.0);
        for id in 1..=15u64 {
            if let Some(rect) = layout.rect(CellId(id)) {
                let path: Path = rect.to_path(0.1);
                scene.stroke(
                    &outer_stroke,
                    Affine::IDENTITY,
                    &outer_brush,
                    None,
                    &path,
                    PickId::Skip,
                );
            }
        }

        let inner_brush: Brush = rgb8(240, 180, 60).into();
        let inner_stroke = Stroke::new(2.0);
        for id in [103u64, 104, 105, 106] {
            if let Some(rect) = layout.rect(CellId(id)) {
                let path: Path = rect.to_path(0.1);
                scene.fill(
                    FillRule::NonZero,
                    Affine::IDENTITY,
                    &Brush::Solid(rgb8(245, 220, 160)),
                    None,
                    &path,
                    PickId::Skip,
                );
                scene.stroke(
                    &inner_stroke,
                    Affine::IDENTITY,
                    &inner_brush,
                    None,
                    &path,
                    PickId::Skip,
                );
            }
        }

        let aspect_brush: Brush = rgb8(60, 160, 220).into();
        if let Some(rect) = layout.rect(CellId(200)) {
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &aspect_brush,
                None,
                &path,
                PickId::Skip,
            );
        }
    }

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

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

pub const fn inch(v: f64) -> Self

Inches.

pub const fn pt(v: f64) -> Self

Points (1pt = 1/72 inch).

pub const fn percent(v: f64) -> Self

A fraction of the containing axis. 0.5 is 50%.

Examples found in repository

examples/layout_demo.rs (line 48)

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

    // Outer: 5 columns × 3 rows of fr(1).
    let mut root = Grid::new(vec![Track::Fr(1.0); 5], vec![Track::Fr(1.0); 3]);

    // Tag every outer cell so we can outline the underlying grid.
    let mut outer_id = 1u64;
    for r in 1..=3u16 {
        for c in 1..=5u16 {
            root.place_mut(Placement::at(r, c), Grid::cell().id(CellId(outer_id)));
            outer_id += 1;
        }
    }

    // Inner 2×2 in row 2, cols 3..=5, with 1cm left + 25% right insets.
    let mut inner = Grid::new(
        [Track::Fr(1.0), Track::Fr(1.0)],
        [Track::Fr(1.0), Track::Fr(1.0)],
    );
    for r in 1..=2u16 {
        for c in 1..=2u16 {
            inner.place_mut(
                Placement::at(r, c),
                Grid::cell().id(CellId(100 + (r as u64) * 2 + c as u64)),
            );
        }
    }
    root.place_mut(
        Placement::at(2, 3).span(1, 3).inset(
            Inset::default()
                .left(Extent::cm(1.0))
                .right(Extent::percent(0.25)),
        ),
        inner,
    );

    // A 2:1 cell in the top-left, expressed via respect + fr weights.
    root.place_mut(
        Placement::at(1, 1),
        Grid::new([Track::Fr(2.0)], [Track::Fr(1.0)])
            .respect()
            .id(CellId(200)),
    );

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

    // Render.
    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        let outer_brush: Brush = rgb8(80, 90, 110).into();
        let outer_stroke = Stroke::new(1.0);
        for id in 1..=15u64 {
            if let Some(rect) = layout.rect(CellId(id)) {
                let path: Path = rect.to_path(0.1);
                scene.stroke(
                    &outer_stroke,
                    Affine::IDENTITY,
                    &outer_brush,
                    None,
                    &path,
                    PickId::Skip,
                );
            }
        }

        let inner_brush: Brush = rgb8(240, 180, 60).into();
        let inner_stroke = Stroke::new(2.0);
        for id in [103u64, 104, 105, 106] {
            if let Some(rect) = layout.rect(CellId(id)) {
                let path: Path = rect.to_path(0.1);
                scene.fill(
                    FillRule::NonZero,
                    Affine::IDENTITY,
                    &Brush::Solid(rgb8(245, 220, 160)),
                    None,
                    &path,
                    PickId::Skip,
                );
                scene.stroke(
                    &inner_stroke,
                    Affine::IDENTITY,
                    &inner_brush,
                    None,
                    &path,
                    PickId::Skip,
                );
            }
        }

        let aspect_brush: Brush = rgb8(60, 160, 220).into();
        if let Some(rect) = layout.rect(CellId(200)) {
            let path: Path = rect.to_path(0.1);
            scene.fill(
                FillRule::NonZero,
                Affine::IDENTITY,
                &aspect_brush,
                None,
                &path,
                PickId::Skip,
            );
        }
    }

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

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

pub fn min(a: Extent, b: Extent) -> Self

Pointwise minimum of two lengths.

pub fn max(a: Extent, b: Extent) -> Self

Pointwise maximum of two lengths.

pub const fn track_of(grid: CellId, axis: Axis, track: u16) -> Self

Reference the resolved size of a single track in a tagged grid. track is 1-indexed. See Extent::TrackOf.

pub const fn tracks_of(grid: CellId, axis: Axis, start: u16, span: u16) -> Self

Reference the resolved summed size of span consecutive tracks in a tagged grid, starting at start (1-indexed). Gaps between tracks are included. See Extent::TrackOf.

pub fn is_absolute(&self) -> bool

True if this length has no percent term anywhere in its tree and no Extent::TrackOf reference (whose value isn’t known without a prior solve pass). Lengths that are absolute can be resolved to pixels without an axis size or prior resolved tracks (used for intrinsic-size computation in Track::Auto).

Trait Implementations

impl Add for Extent

type Output = Extent

The resulting type after applying the + operator.

fn add(self, rhs: Extent) -> Extent

Performs the + operation.

impl Clone for Extent

fn clone(&self) -> Extent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Extent

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

Formats the value using the given formatter.

impl Default for Extent

fn default() -> Self

Returns the “default value” for a type.

impl Div<f64> for Extent

type Output = Extent

The resulting type after applying the / operator.

fn div(self, k: f64) -> Extent

Performs the / operation.

impl Mul<Extent> for f64

type Output = Extent

The resulting type after applying the * operator.

fn mul(self, l: Extent) -> Extent

Performs the * operation.

impl Mul<f64> for Extent

type Output = Extent

The resulting type after applying the * operator.

fn mul(self, k: f64) -> Extent

Performs the * operation.

impl Neg for Extent

type Output = Extent

The resulting type after applying the - operator.

fn neg(self) -> Extent

Performs the unary - operation.

impl PartialEq for Extent

fn eq(&self, other: &Extent) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Extent

impl Sub for Extent

type Output = Extent

The resulting type after applying the - operator.

fn sub(self, rhs: Extent) -> Extent

Performs the - operation.