Font

:= {
    handle : FontHandle,
    metrics : FontMetrics,
}

Font handles, metric snapshots, and pure text measurement.

A font pairs an opaque, reference-counted native resource identity with an immutable scalar metric snapshot. Pure application code can retain and measure it without calling the host. Text.Font and Draw.Font name this same type.

stub : Font

Resource-free synthetic monospace font for pure layout tests.

Its handle never resolves to a host resource, so drawing falls back to the platform's built-in font. One fallback glyph advances one unit at a base size of one, making measurements deterministic. Do not use it to test drawing, loading, resource lifetime, or rasterized-font parity.

measure : Font, Measure -> Size

Measure a valid Roc string against the font's immutable metric snapshot.

Pure: this never calls the host, so layout can run in update!, in a package, or in an expect. Newlines advance by the requested size plus line spacing, missing codepoints use the fallback glyph, and spacing counts Unicode codepoints. U+0000 is an ordinary Roc string codepoint.

FontHandle : Font

Opaque native resource identity. Only a host can manufacture a live one, but applications can compare and hash handles they receive.

GlyphMetrics : {
    codepoint : U32,
    advance_x : F32,
    offset_x : F32,
    offset_y : F32,
    width : F32,
    height : F32,
}

Scalar metrics for one glyph, in the atlas's own units.

FontMetrics : {
    base_size : F32,
    line_spacing : F32,
    fallback_index : U64,
    glyphs : List(GlyphMetrics),
}

Immutable atlas and glyph metrics captured when a font is loaded.

Measure : {
    text : Str,
    size : F32,
    spacing : F32,
}

What to measure: text, draw size, and extra spacing between codepoints.

Size : {
    width : F32,
    height : F32,
}

Text measurement result, in the units the requested size was given in.