Module shaping 

Text shaping backend and deterministic shaped-run cache.

This module provides the interface and caching layer for text shaping — the process of converting a sequence of Unicode codepoints into positioned glyphs. Shaping handles script-specific reordering, ligature substitution, and glyph positioning (kerning, mark attachment).

Architecture

TextRun (from script_segmentation)
    │
    ▼
┌───────────────┐
│ ShapingCache   │──cache hit──▶ ShapedRun (cached)
│ (LRU + gen)    │
└───────┬───────┘
        │ cache miss
        ▼
┌───────────────┐
│ TextShaper     │  trait (NoopShaper | RustybuzzShaper)
└───────┬───────┘
        │
        ▼
    ShapedRun

Key schema

The ShapingKey captures all parameters that affect shaping output: text content (hashed), script, direction, style, font identity, font size, and OpenType features. Two runs producing the same ShapingKey are guaranteed to produce identical ShapedRun output.

Invalidation

The cache uses generation-based invalidation. When fonts change (DPR change, zoom, font swap), the generation is bumped and stale entries are lazily evicted on access. This avoids expensive bulk-clear operations.

Example

use ftui_text::shaping::{
    NoopShaper, ShapingCache, FontId, FontFeatures,
};
use ftui_text::script_segmentation::{Script, RunDirection};

let shaper = NoopShaper;
let mut cache = ShapingCache::new(shaper, 1024);

let result = cache.shape(
    "Hello",
    Script::Latin,
    RunDirection::Ltr,
    FontId(0),
    256 * 12, // 12pt in 1/256th units
    &FontFeatures::default(),
);
assert!(!result.glyphs.is_empty());

Structs

FontFeature

A single OpenType feature tag + value.

FontFeatures

A set of OpenType features requested for shaping.

FontId

Opaque identifier for a font face within the application.

NoopShaper

Identity shaper for monospace terminal rendering.

ShapedGlyph

A single positioned glyph from the shaping engine.

ShapedRun

The result of shaping a text run.

ShapingCache

LRU cache for shaped text runs with generation-based invalidation.

ShapingCacheStats

Statistics for the shaping cache.

ShapingKey

Deterministic cache key for shaped glyph output.

Traits

TextShaper

Abstract text shaping backend.