Crate parley_engine

Expand description

Parley Engine provides low level APIs for shaping paragraphs of text.

§Usage

Use Analyzer, Analysis, Shaper and ShapedText to shape a paragraph of text into glyphs. Correct reshaping of lines is in progress; in the meantime you can break text at Atom or ShapedCluster boundaries.

Text analysis is performed before shaping, and the same source string must be passed to each stage.

Higher-level users may prefer using parley, which uses this crate and implements layout and styling.

let mut analysis = Analysis::default();
let mut analyzer = Analyzer::default();
let mut shaped_text = ShapedText::default();
let mut shaper = Shaper::default();

let text = "The quick brown ثعلب jumps over the lazy dog.";
let char_count = text.chars().count();
let char_style_indices = vec![0; char_count];

analyzer.analyze(text, &AnalysisOptions::default(), &mut analysis);
shaper.shape_text(
    text,
    &analysis,
    &char_style_indices,
    [Item {
        char_end: char_count.try_into().unwrap(),
        options: ShapeOptions {
            font_size: 16.0,
            language: None,
            features: &[],
            variations: &[],
        },
     }],
     select_font, // Selects fonts covering each cluster.
     &mut shaped_text,
);

for (run_idx, run) in shaped_text.runs().iter().enumerate() {
    let slice = shaped_text.run_slice(run_idx as u32);
    // You can, for example, measure grapheme advances for hit-testing or
    // placing carets.
    for atom in slice.atoms_start() {
        for grapheme in atom.graphemes_start() {
            std::dbg!(grapheme);
        }
    }

    // Or get glyphs for rendering (for simplicity, this iterates clusters in
    // logical order, but for rendering you'd want to reorder runs and clusters
    // according to their `run.bidi_level`).
    for cluster in slice.shaped_clusters_range() {
        for glyph in slice.shaped_cluster_glyphs(cluster) {
            std::dbg!(glyph);
        }
    }
}

§Features

std (enabled by default): This is currently unused and is provided for forward compatibility.
bytemuck: Forwarded to parlance, which then implements traits from bytemuck on its types.

Re-exports§

pub use analysis::Analysis;
pub use analysis::CharInfo;

Modules§

break_overrides: Overrides for line-break opportunities.
itemize: Itemization breaks text into individually-shapeable items.
shape: Text shaping utilities.

Structs§

Analysis: The result of Analyzer::analyze.
AnalysisOptions: Options controlling Analyzer::analyze.
Analyzer: Reusable scratch for Analyzer::analyze.
Atom: An atom of shaped text.
Atoms: An Atom cursor.
CharInfo: Per-character analysis info.
FontData: Owned shareable font resource.
FontInstance: The font instance to shape an item with.
FontInstanceRef: A borrowed FontInstance.
FontMetrics: Metrics that apply to the glyphs of a font.
Glyph: Glyph with an offset and advance.
Grapheme: A grapheme of shaped text.
Graphemes: A Grapheme cursor.
LineBreakConfig: Configuration of line break opportunities for a range of text.
NormalizedCoord: A normalized font coordinate.
ShapeOptions: Shaping options for one item.
ShapedClusterGlyphs: An iterator over the glyphs of a single ShapedCluster, in visual left-to-right order.
ShapedRun: One shaped run, belonging to a ShapedText.
ShapedSlice: A slice of shaped text.
ShapedText: The result of shaping.
Shaper: Reusable scratch to shape text using Self::shape_text.

Enums§

BaseDirection: The paragraph’s base direction.

Traits§

FontSelector: Implements font selection for shaping.