sim-engine 0.4.2

A validated high-performance visualization engine for simulations
Documentation
//! Single-font horizontal shaping and bounded grayscale outline rasterization.

mod config;
mod raster;
mod session;
#[cfg(test)]
mod tests;
pub use config::{
    FontBudget, FontBudgetResource, FontError, TextDirection, TextLayoutBudget, TextStyle,
};
use config::{check, reserve};
pub use raster::RasterizedGlyph;
pub use session::{ShapedLineError, TextShapingSession};

/// One owned TTF/OpenType outline face (collection index zero).
///
/// Source bytes are retained once inside ab_glyph; rustybuzz borrows those bytes
/// while shaping. The source Vec capacity is checked before parsing. Font
/// discovery, fallback selection, variable-font axes, color/bitmap glyphs,
/// wrapping and bidi paragraph layout are outside this API.
/// Cloning shares the original bytes and parsed font without copying them.
#[derive(Debug, Clone)]
pub struct FontFace {
    font: std::sync::Arc<ab_glyph::FontVec>,
    source_capacity: usize,
    glyph_count: usize,
}

impl FontFace {
    /// Loads already-read TTF/OTF bytes without duplicating their backing storage.
    /// The caller owns filesystem/network I/O and font licensing.
    pub fn from_bytes(bytes: Vec<u8>, budget: FontBudget) -> Result<Self, FontError> {
        check(
            FontBudgetResource::FontBytes,
            bytes.capacity(),
            budget.max_font_bytes(),
        )?;
        let face =
            rustybuzz::ttf_parser::Face::parse(&bytes, 0).map_err(|_| FontError::InvalidFont)?;
        let tables = face.tables();
        if tables.glyf.is_none() && tables.cff.is_none() && tables.cff2.is_none() {
            return Err(FontError::InvalidFont);
        }
        let glyph_count = usize::from(face.number_of_glyphs());
        check(
            FontBudgetResource::FontGlyphs,
            glyph_count,
            budget.max_font_glyphs(),
        )?;
        if face.units_per_em() == 0 || face.ascender() <= face.descender() {
            return Err(FontError::InvalidFont);
        }
        let source_capacity = bytes.capacity();
        let font = ab_glyph::FontVec::try_from_vec(bytes).map_err(|_| FontError::InvalidFont)?;
        Ok(Self {
            font: std::sync::Arc::new(font),
            source_capacity,
            glyph_count,
        })
    }

    /// Original font bytes, borrowed without an additional owned copy.
    pub fn font_data(&self) -> &[u8] {
        self.font.as_slice()
    }
    /// Source Vec capacity referenced by this handle; clones share it.
    /// Dependency-parsed metadata is excluded.
    pub const fn allocation_bytes(&self) -> usize {
        self.source_capacity
    }
    /// Number of font-local glyph identifiers, including the missing-glyph entry.
    pub const fn glyph_count(&self) -> usize {
        self.glyph_count
    }

    /// Shapes a horizontal single-script directional run at baseline `(0, 0)`.
    ///
    /// Positions/advances use logical pixels, with positive y downward. Kerning,
    /// ligatures and combining-mark offsets come from rustybuzz/OpenType tables.
    /// Auto infers one direction/script, not a mixed-direction bidi paragraph.
    /// Newlines, controls and missing glyphs return errors; spaces retain advance.
    /// DPI changes raster resolution, not logical layout or kerning decisions.
    pub fn shape_line(
        &self,
        text: &str,
        style: &TextStyle,
        budget: &TextLayoutBudget,
    ) -> Result<ShapedLine, FontError> {
        TextShapingSession::new(self, *style, *budget)?.shape_line(text)
    }

    /// Rasterizes one glyph at physical em size and baseline `(0, 0)`.
    /// Outlines are preflighted without allocating curves; pixel bounds and
    /// command counts are checked before bounded curve and coverage allocations.
    /// No hinting or subpixel-position variants are applied. Empty outlines
    /// (for example spaces) return an empty bitmap, not a missing-glyph error.
    pub fn rasterize_glyph(
        &self,
        glyph_id: u16,
        style: &TextStyle,
        budget: &TextLayoutBudget,
    ) -> Result<RasterizedGlyph, FontError> {
        raster::rasterize(self, glyph_id, style, budget)
    }
}

/// A shaped glyph's font-local identity and baseline-relative logical placement.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ShapedGlyph {
    glyph_id: u16,
    logical_x: f32,
    logical_y: f32,
    cluster: usize,
}

impl ShapedGlyph {
    /// Identifier in the FontFace that produced this line.
    pub const fn glyph_id(self) -> u16 {
        self.glyph_id
    }
    /// Baseline-relative horizontal origin, in logical pixels.
    pub const fn logical_x(self) -> f32 {
        self.logical_x
    }
    /// Baseline-relative vertical origin, in logical pixels, positive downward.
    pub const fn logical_y(self) -> f32 {
        self.logical_y
    }
    /// Original UTF-8 byte offset associated with this shaped cluster.
    pub const fn cluster(self) -> usize {
        self.cluster
    }
}

/// Immutable shaped placement; rasterization and GPU ownership are separate.
#[derive(Debug)]
pub struct ShapedLine {
    font: FontFace,
    style: TextStyle,
    text: String,
    glyphs: Vec<ShapedGlyph>,
    advance: f32,
    ascent: f32,
    descent: f32,
    line_height: f32,
}

impl ShapedLine {
    /// Original UTF-8 input; retained so prepared text needs no second shaping pass.
    pub fn text(&self) -> &str {
        &self.text
    }
    /// Immutable font shared with the original face, not a duplicate byte buffer.
    pub const fn font(&self) -> &FontFace {
        &self.font
    }
    /// Exact em size, DPI and requested direction used for this line.
    pub const fn style(&self) -> &TextStyle {
        &self.style
    }
    /// Checks font identity, exact style and input/output limits without reshaping.
    /// Clones of a face share identity; separately loaded identical bytes do not.
    /// Raster limits apply later when an atlas encounters an uncached glyph.
    pub fn validate_for(
        &self,
        font: &FontFace,
        style: &TextStyle,
        budget: &TextLayoutBudget,
    ) -> Result<(), ShapedLineError> {
        self.validate_provenance(font, style)?;
        check(
            FontBudgetResource::TextBytes,
            self.text.len(),
            budget.max_text_bytes(),
        )?;
        check(
            FontBudgetResource::ShapedGlyphs,
            self.glyphs.len(),
            budget.max_shaped_glyphs(),
        )?;
        Ok(())
    }

    pub(crate) fn validate_provenance(
        &self,
        font: &FontFace,
        style: &TextStyle,
    ) -> Result<(), ShapedLineError> {
        if !std::sync::Arc::ptr_eq(&self.font.font, &font.font) {
            return Err(ShapedLineError::FontMismatch);
        }
        if self.style != *style {
            return Err(ShapedLineError::StyleMismatch);
        }
        Ok(())
    }
    /// Shaper output order. Drawing this sequence at its offsets preserves marks.
    pub fn glyphs(&self) -> &[ShapedGlyph] {
        &self.glyphs
    }
    /// Horizontal pen advance in logical pixels, including whitespace.
    pub const fn advance(&self) -> f32 {
        self.advance
    }
    /// Signed font ascender in logical pixels; normally positive above baseline.
    pub const fn ascent(&self) -> f32 {
        self.ascent
    }
    /// Signed font descender in logical pixels; normally negative below baseline.
    pub const fn descent(&self) -> f32 {
        self.descent
    }
    /// Font-recommended line spacing in logical pixels, including line gap.
    pub const fn line_height(&self) -> f32 {
        self.line_height
    }
    /// Owned UTF-8 and glyph metadata capacity in bytes, excluding the shared font.
    pub fn allocation_bytes(&self) -> usize {
        self.glyphs
            .capacity()
            .saturating_mul(std::mem::size_of::<ShapedGlyph>())
            .saturating_add(self.text.capacity())
    }
}

fn represent(value: f64) -> Result<f32, FontError> {
    let result = value as f32;
    if result.is_finite() {
        Ok(result)
    } else {
        Err(FontError::InvalidGeometry)
    }
}