API reference

aster_blueprint::text_measure

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Text measurement for layout: font asset + size + string -> width, height and baseline as logical lengths.

[Typesetter] owns named fonts and one shaper (the existing aster-ui TextShaper/hudlife-opentype path used by component::label::measured_text). It is a [TextMeasure], so layout::Node::text(..) nodes are measured by the layout pass itself and no caller has to supply a label width.

Real shaping needs the native-fonts feature. Without it [Typesetter::new] returns [LayoutError::NativeFontsRequired] (it never fabricates an estimate), and [NoText] refuses every measurement.

Measurements are cached per (font, size, text), deterministic, and expose graph-ready literals through [TextMetrics::literals] and the pure core.label.width.v1 / core.label.height.v1 kernels for prepared labels.

The typesetter also owns the font fallback chain: the faces a text may use when its own face has no glyph for a cluster (see Typesetter::with_fallbacks and [TextMeasure::split_faces]). The faces are registered by the caller; no font file is bundled or downloaded.

Structs

structaster_blueprint::text_measure::GlyphInfo

pub struct GlyphInfo { /* see fields */ }

One shaped glyph: the cluster it stands for (the byte range of the source), its id and its advance, in the order the shaper produced them.

Public fields

fieldtype
cluster_startusizeThe first byte of the cluster this glyph belongs to.
cluster_endusizeThe byte after the last byte of the cluster.
idu32The glyph id in the font.
advancef64The advance in logical pixels.

Trait implementations: Clone, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::text_measure::NoText

pub struct NoText;

A measurer for trees without text: every measurement is refused.

Trait implementations: Clone, Copy, Debug, Default, TextMeasure

structaster_blueprint::text_measure::TextMetrics

pub struct TextMetrics { /* see fields */ }

Measured single-line text. height = ascent + descent + line_gap, baseline = ascent (the same convention measured_text and the showcase use), so a label painted at the box top has its baseline at baseline.

Public fields

fieldtype
widthf64
heightf64
baselinef64
ascentf64
descentf64

Methods

  • fn literals(&self, prefix: &str) -> Result<Vec<(Symbol, Literal)>, LayoutError> — prefix.width, prefix.height, prefix.baseline as LogicalLength graph parameters, ready for RuntimeInstance/MaterialInstance inputs.

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::text_measure::Typesetter

pub struct Typesetter { /* see fields */ }

Named fonts + a shaper + a measurement cache.

Methods

  • fn new() -> Result<Self, LayoutError> — A typesetter with the default face set: the premium faces of the default look (a proportional sans, a monospace, an oblique and a display face) and the bundled faces they fall back to. A face that is registered later under the same name replaces the default one.
  • fn with_fallbacks(names: &[&str]) -> Result<Self, LayoutError> — A typesetter with a default fallback chain: the faces a text falls back to when its own face has no glyph for a cluster (the first one that has it wins).
  • fn fallbacks(&self) -> Vec<String> — The default fallback chain.
  • fn generation(&self) -> u64 — The generation of the face set: it changes when a face is added or replaced, or when the default chain changes. A layout cache keys on it, so a new face or a new fallback re-lays out the texts that depend on it (and a frame without a change stays a hit).
  • fn add_fallback(&mut self, name: &str) -> &mut Self — Add a face to the default fallback chain.
  • fn add_font(&mut self, name: &str, font: FontAsset) -> &mut Self — Register an already loaded font under name.
  • fn add_font_bytes(&mut self, name: &str, bytes: &[u8]) -> Result<&mut Self, LayoutError> — Load an OpenType/TrueType font from bytes and register it.
  • fn set_face_weight(&mut self, name: &str, weight: u16) -> &mut Self — Declare the weight class of the face name (a face registered with add_font has none known): 700 and up is bold for the contrast audit and the a11y tree. A later add_font of the name resets it.
  • fn set_face_fallback(&mut self, name: &str, fallback: &str) -> &mut Self — Declare the face a text of name falls back to when it has no glyph for a cluster (the fallback tier of a face): the bundled DejaVu faces cover the glyphs the premium faces lack.
  • fn face_fallback(&self, name: &str) -> Option<String> — The face a text of name falls back to when it has no glyph for a cluster (None: the default chain only).
  • fn face_weight(&self, name: &str) -> Option<u16> — The weight class of the face name when it was loaded from bytes or declared (400 regular, 700 bold).
  • fn add_font_file(&mut self, name: &str, path: impl AsRef<std::path::Path>) -> Result<&mut Self, LayoutError> — Load a font file and register it.
  • fn cache_len(&self) -> usize — Cached measurements currently held (bounded).
  • fn glyphs(&mut self, font: &str, size: f64, text: &str) -> Result<Vec<GlyphInfo>, LayoutError> — The shaped glyphs of text: each glyph's cluster (the byte range of the source it stands for), its id and its advance, in the order the shaper produced them. The clusters are the shaper's, so a caller can place a cut between two of them. A character the face has no glyph for is an error here (layout and painting draw a replacement instead: Typesetter::drawable).
  • fn font(&self, name: &str) -> Option<Rc<FontAsset>> — The face of that name, if it is registered.
  • fn label(&mut self, font: &str, size: f64, color: Srgb8, text: &str, output_scale: f64) -> Result<(Label, TextMetrics), LayoutError> — Prepare a painted [Label] (and its metrics) for text at output_scale, with its baseline at metrics.baseline.
  • fn label_run(&mut self, font: &str, size: f64, color: Srgb8, text: &str, output_scale: f64, dir: Direction) -> Result<(Label, TextMetrics), LayoutError> — Prepare a painted [Label] (and its metrics) for text at output_scale, with its baseline at metrics.baseline, shaped in the direction dir as ONE run (a mixed line is painted run by run: [crate::bidi::runs]).

Trait implementations: TextMeasure

Enums

enumaster_blueprint::text_measure::TextRendering

pub enum TextRendering { Tuned, Classic, Area }

How the text of a screen is rasterized and blended.

Variants

  • Tuned — Quarter-pixel x positions, stem darkening of the small sizes and a linear-light blend with a contrast boost by the luminance of the ink (the earlier default look).
  • Classic — The plain masks of whole-pixel phase and the plain sRGB blend (what text was before the tuning).
  • Area — The default look (chosen over Tuned): Tuned's quarter-pixel placement with exact-area coverage, the x-height fitted to whole pixels at small sizes and a contrast curve for light ink only.

Trait implementations: Clone, Copy, Debug, Eq, Hash, PartialEq, StructuralPartialEq

Traits

traitaster_blueprint::text_measure::TextMeasure

pub trait TextMeasure

Anything that can measure a single line of text.

Required and provided methods

  • fn measure(&mut self, font: &str, size: f64, text: &str) -> Result<TextMetrics, LayoutError>
  • fn measure_run(&mut self, font: &str, size: f64, text: &str, dir: Direction) -> Result<TextMetrics, LayoutError> — Measure text as ONE run shaped in direction dir (no analysis of the text): a right-to-left run gets a right-to-left base direction. The default measures it as left-to-right.
  • fn measure_dir(&mut self, font: &str, size: f64, text: &str, base: Direction) -> Result<TextMetrics, LayoutError> — Measure a line of text of a paragraph whose base direction is base: the text is split into directional runs ([crate::bidi::runs]: the digits and the Latin of a right-to-left paragraph read left to right, the Arabic of a left-to-right one right to left), each run is shaped with its own direction ([TextMeasure::measure_run]) and the width is their sum. Text with no right-to-left character in a left-to-right paragraph is one run, so it is measured exactly as [TextMeasure::measure] does.
  • fn measure_layout_run(&mut self, font: &str, size: f64, text: &str, dir: Direction) -> Result<TextMetrics, LayoutError> — Layout-facing measurement of one complete directional run. The default keeps measure_run's admission. Native layout may use larger, temporary bounded scratch without changing the raw measurement API or cutting shaping context.
  • fn measure_layout_dir(&mut self, font: &str, size: f64, text: &str, base: Direction) -> Result<TextMetrics, LayoutError> — Layout-facing direction-aware measurement. The default preserves the provider's existing measure_dir override and admission. Native layout extends it with temporary scratch for complete directional runs.
  • fn pair_kerning(&mut self, font: &str, size: f64, left: &str, right: &str, dir: Direction) -> Result<f64, LayoutError> — The pair adjustment, in px, between two runs left and right (the whole pieces, in logical order) of the same face, size and direction that meet and are painted separately (a rich-text colour or style change inside a word). It is the positioning between the glyphs that really end the left piece and really start the right one as each piece is painted (a ligature, a contextual or joining form the piece shapes to is that glyph, never the source characters shaped again without it), never a ligature or a substitution across the boundary, and 0 when the pair of painted edge glyphs cannot be determined. Plus the one letter spacing (tracking) between the two edge clusters: a run is tracked between its own clusters only, so each piece alone lacks the step that the joined run has at the boundary. The default (a measurer that does not shape or track) has neither.
  • fn pair_kerning_layout(&mut self, font: &str, size: f64, left: &str, right: &str, dir: Direction) -> Result<f64, LayoutError> — Layout's painted-edge adjustment. The default is the existing seam contract; a native larger-run path may use temporary scratch for it.
  • fn split_faces(&mut self, primary: &str, _fallbacks: &[String], text: &str) -> Vec<(String, String)> — The faces that render text: each is (face, the part of the text it renders). The pieces are in order and cover the whole text; a face is used for the clusters it has a glyph for. The default: the primary face renders everything (no fallback).
  • fn generation(&self) -> u64 — The generation of the measurer's face set: it changes when a face is added or replaced, or when the fallback chain changes. A layout cache keys on it: a change re-lays out the texts that depend on it, a frame without one stays a hit.

Functions

fnaster_blueprint::text_measure::long_chunks

pub fn long_chunks(text: &str) -> Vec<&str>

The byte ranges measure_long cuts a long text into: at most MEASURE_MAX_BYTES - 100 bytes each, after a space when there is one in the last 120 bytes, else at a grapheme boundary.

Every chunk but the last is a whole number of grapheme clusters (the clusters crate::grapheme cuts): a cluster is never split, so a combining mark keeps its base, a ZWJ sequence keeps its whole and a space never loses the combining mark that extends it.

The byte bound is soft for one case only: when the FIRST grapheme alone is longer than the bound, it is returned whole (never split); the caller remains responsible for its admission limits.

fnaster_blueprint::text_measure::measure_long

pub fn measure_long<M: TextMeasure + ?Sized>(m: &mut M, font: &str, size: f64, text: &str) -> Result<TextMetrics, layout::LayoutError>

[TextMeasure::measure] for a text of any length: over MEASURE_MAX_BYTES it is measured in pieces ([long_chunks]) and the widths add (no kerning across a cut; the height and the baseline are the largest).

fnaster_blueprint::text_measure::set_text_rendering

pub fn set_text_rendering(r: TextRendering)

Choose the text rendering of this thread (the drawings already prepared keep theirs: a cache is keyed by it).

fnaster_blueprint::text_measure::sfnt_weight

pub fn sfnt_weight(bytes: &[u8]) -> Option<u16>

The weight class of an OpenType/TrueType font (usWeightClass of its OS/2 table: 400 regular, 700 bold). None for bytes that are not an sfnt or have no OS/2 table.

fnaster_blueprint::text_measure::text_rendering

pub fn text_rendering() -> TextRendering

The text rendering of this thread (what the typesetters of the thread prepare their drawings for).

Constants

constaster_blueprint::text_measure::MEASURE_MAX_BYTES

pub const MEASURE_MAX_BYTES: usize

The longest text a measurement takes (in bytes).