oxitext-shape — Swash-based text shaper for OxiText

oxitext-shape is the shaping stage of the OxiText pipeline (a HarfBuzz-like step). It turns UTF-8 text plus raw font bytes into ordered oxitext_core::ShapedGlyphs, applying OpenType GSUB/GPOS (ligatures, kerning, marks), right-to-left form selection, vertical CJK substitution (vert/vrt2), and font fallback. The default backend wraps swash; an optional rustybuzz backend is available behind a feature flag.

This crate is 100% Pure Rust and #![forbid(unsafe_code)]. The default shaping path (swash) carries no C/C++ dependencies. Optional features add script-aware itemisation via oxitext-icu (ICU4X) and system-font discovery via oxifont. Shaping consumes types from oxitext-core; downstream, oxitext-layout positions the glyphs and oxitext-raster rasterizes them.

Installation

[dependencies]
oxitext-shape = "0.1.0"

With optional capabilities:

[dependencies]
# rustybuzz alternative backend, ICU4X script itemisation, and system-font lookup
oxitext-shape = { version = "0.1.0", features = ["rustybuzz-backend", "icu", "system-fonts"] }

Quick Start

Keep a single SwashShaper alive across passes to amortise swash's internal caches.

use oxitext_shape::SwashShaper;
use std::sync::Arc;

let font_data: Arc<[u8]> = Arc::from(std::fs::read("font.ttf")?.as_slice());

let mut shaper = SwashShaper::new();
let run = shaper.shape("Hello", Arc::clone(&font_data), 16.0)?;

// Each glyph's x_advance is already in pixels (scaled by the 16px size).
let total: f32 = run.glyphs.iter().map(|g| g.x_advance).sum();
println!("{} glyphs, total advance {total}px", run.glyphs.len());
# Ok::<(), oxitext_core::OxiTextError>(())

Feature-aware shaping with a request builder

use oxitext_shape::{SwashShaper, ShapeRequest, ShapeDirection, ShapeFeature};

let font: Vec<u8> = std::fs::read("font.ttf")?;
let mut shaper = SwashShaper::new();

let req = ShapeRequest::builder()
    .text("file")
    .font_data(&font)
    .px_size(18.0)
    .direction(ShapeDirection::Ltr)
    .feature(ShapeFeature::LIGA)   // standard ligatures
    .feature(ShapeFeature::KERN)   // kerning
    .build()?;

let glyphs = shaper.shape_request(&req)?;
println!("{} shaped glyphs", glyphs.len());
# Ok::<(), Box<dyn std::error::Error>>(())

API Overview

SwashShaper

The primary shaper. Methods that take Arc<[u8]> cooperate with the optional ShapeCache; methods taking &[u8] are lower-level conveniences.

Builder-pattern request types

Results and metadata

Backends — backend module

Shape cache — cache module

Batch shaping — batch module (SwashShaper methods)

Variable fonts — variational module (SwashShaper method)

Script detection — script_detect module

Free functions

System fonts — system_fonts module (feature system-fonts)

ICU4X itemisation (feature icu)

Feature Flags

Error variants

Shaping methods return Result<_, oxitext_core::OxiTextError>; failures use the OxiTextError::Shaping(String) variant (e.g. unparseable font bytes, empty font list, invalid script-run byte range). The request builder returns its own error:

Cross-references

• oxitext — high-level façade combining all stages.
• oxitext-core — the shared ShapedGlyph / ShapedRun / OxiTextError types.
• oxitext-layout — positions ShapedRuns into lines and paragraphs.
• oxitext-raster — rasterizes shaped/positioned glyphs into bitmaps.
• oxitext-icu — ICU4X script itemisation and normalisation used by the icu feature.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)