blockworx_text/

shaper.rs

//! [`Shaper`]: a text engine of our own, so a host without one can still be
//! told where every glyph lands.

use std::cell::RefCell;

use blockworx_geom::{WorldPx, vec2};
use blockworx_paint::text::{Glyph, GlyphId, Layout, TextLayout};
use blockworx_paint::{Font, FontChoice};

use crate::cache::LayoutCache;
use crate::metrics::Metrics;
use crate::rows;

/// The character a shaper reports for a byte it cannot read back.
const UNKNOWN: char = '\u{FFFD}';

/// One typeface, shaped by `harfrust` and broken into rows by the desktop
/// engine's rules — the whole of what [`TextLayout`] asks of a host, with no
/// toolkit under it.
pub struct Shaper {
    typeface: FontChoice,
    metrics: Metrics,
    font: skrifa::FontRef<'static>,
    /// The parsed layout tables. Cached per face, as a layout engine caches
    /// them: building a shaper from them is cheap, parsing them is not.
    data: harfrust::ShaperData,
    laid_out: RefCell<LayoutCache>,
}

impl Shaper {
    /// # Panics
    ///
    /// If the typeface's embedded bytes are not a font this can read.
    #[expect(clippy::expect_used)]
    #[must_use]
    pub fn new(typeface: FontChoice) -> Self {
        let font =
            skrifa::FontRef::from_index(typeface.bytes(), 0).expect("embedded font is valid");
        let data = harfrust::ShaperData::new(&font);
        Self {
            typeface,
            metrics: Metrics::of(typeface),
            font,
            data,
            laid_out: RefCell::default(),
        }
    }

    /// The metrics this engine measures a row by.
    #[must_use]
    pub fn metrics(&self) -> Metrics {
        self.metrics
    }

    /// The glyphs one paragraph of `text` shapes to, in visual order —
    /// identity only, for a consumer that has the positions already.
    #[must_use]
    pub fn glyph_ids(&self, text: &str) -> Vec<GlyphId> {
        self.shape(text).into_iter().map(|glyph| glyph.id).collect()
    }

    fn shape(&self, text: &str) -> Vec<Shaped> {
        let shaper = self.data.shaper(&self.font).build();
        let mut buffer = harfrust::UnicodeBuffer::new();
        buffer.set_flags(
            harfrust::BufferFlags::BEGINNING_OF_TEXT | harfrust::BufferFlags::END_OF_TEXT,
        );
        buffer.push_str(text);
        buffer.guess_segment_properties();
        let shaped = shaper.shape(buffer, harfrust::ShapeOptions::new());
        std::iter::zip(shaped.glyph_infos(), shaped.glyph_positions())
            .map(|(info, pos)| Shaped {
                // harfrust guarantees a shaped `glyph_id` fits in a `u16`.
                id: GlyphId(info.glyph_id as u16),
                cluster: info.cluster as usize,
                advance: pos.x_advance as f32,
            })
            .collect()
    }
}

impl TextLayout for Shaper {
    fn typeface(&self) -> FontChoice {
        self.typeface
    }

    fn layout(&self, text: &str, font: &Font, wrap: WorldPx) -> Layout {
        if let Some(laid_out) = self.laid_out.borrow().get(text, font, wrap) {
            return laid_out.clone();
        }
        let paragraphs = text
            .split('\n')
            .map(|paragraph| place(&self.shape(paragraph), paragraph, self.metrics, font))
            .collect();
        let laid_out = rows::rows_of(paragraphs, wrap, self.metrics, font);
        self.laid_out
            .borrow_mut()
            .put(text, font, wrap, laid_out.clone());
        laid_out
    }
}

/// One glyph as the shaper reports it, in font units.
struct Shaped {
    id: GlyphId,
    /// Where in the paragraph the characters this glyph stands for begin.
    cluster: usize,
    advance: f32,
}

/// The shaped run placed along one endless row, one glyph per *character*:
/// a cluster the shaper folded into fewer glyphs than it has characters is
/// padded out with zero-advance continuations, so cursor arithmetic above
/// this can count characters.
fn place(shaped: &[Shaped], text: &str, metrics: Metrics, font: &Font) -> Vec<Glyph> {
    let mut run = Placing::over(text, metrics, font);
    for glyph in shaped {
        run.place(glyph);
    }
    run.finish()
}

/// The pen walking a shaped run, and the cluster it is in the middle of.
struct Placing<'a> {
    text: &'a str,
    scale: f32,
    ascent: f32,
    pen: f32,
    placed: Vec<Glyph>,
    /// Where in `text` the cluster being placed begins.
    cluster: Option<usize>,
    glyphs_in_cluster: usize,
}

impl<'a> Placing<'a> {
    fn over(text: &'a str, metrics: Metrics, font: &Font) -> Self {
        Self {
            text,
            scale: metrics.scale(font),
            ascent: metrics.ascent(font),
            pen: 0.0,
            placed: Vec::new(),
            cluster: None,
            glyphs_in_cluster: 0,
        }
    }

    fn place(&mut self, shaped: &Shaped) {
        if self.cluster.is_some_and(|at| at != shaped.cluster) {
            self.pad(shaped.cluster);
            self.glyphs_in_cluster = 0;
        }
        let chr = self
            .text
            .get(shaped.cluster..)
            .and_then(|rest| rest.chars().next())
            .unwrap_or(UNKNOWN);
        let advance = shaped.advance * self.scale;
        self.placed.push(Glyph {
            chr,
            id: Some(shaped.id),
            pos: vec2(self.pen, self.ascent),
            advance,
            ascent: self.ascent,
        });
        self.pen += advance;
        self.cluster = Some(shaped.cluster);
        self.glyphs_in_cluster += 1;
    }

    /// A continuation for every character of the cluster just closed that the
    /// shaper gave no glyph of its own.
    fn pad(&mut self, end: usize) {
        let text = self.text;
        let Some(folded) = self.cluster.and_then(|at| text.get(at..end)) else {
            return;
        };
        for chr in folded.chars().skip(self.glyphs_in_cluster) {
            self.placed.push(Glyph {
                chr,
                id: None,
                pos: vec2(self.pen, self.ascent),
                advance: 0.0,
                ascent: self.ascent,
            });
        }
    }

    fn finish(mut self) -> Vec<Glyph> {
        self.pad(self.text.len());
        self.placed
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn shaper() -> Shaper {
        Shaper::new(FontChoice::Basic)
    }

    fn font() -> Font {
        Font::canvas(12.0)
    }

    /// The row structure of a layout: what each row ends with, and the
    /// characters on it.
    fn rows_of(laid_out: &Layout) -> Vec<(String, bool)> {
        laid_out
            .rows
            .iter()
            .map(|row| {
                (
                    row.glyphs.iter().map(|glyph| glyph.chr).collect(),
                    row.ends_with_newline,
                )
            })
            .collect()
    }

    /// A width that fits `text` exactly, so a longer run must break.
    fn width_of(shaper: &Shaper, text: &str) -> WorldPx {
        WorldPx::new(shaper.layout(text, &font(), WorldPx::UNBOUNDED).size.x)
    }

    #[test]
    fn an_unwrapped_run_is_one_row() {
        let shaper = shaper();
        let laid_out = shaper.layout("the quick brown fox", &font(), WorldPx::UNBOUNDED);
        assert_eq!(
            rows_of(&laid_out),
            vec![("the quick brown fox".to_owned(), false)]
        );
        assert!(laid_out.size.x > 0.0 && laid_out.size.y > 0.0);
    }

    #[test]
    fn a_paragraph_closes_the_row_it_ends() {
        let shaper = shaper();
        let laid_out = shaper.layout("one\ntwo", &font(), WorldPx::UNBOUNDED);
        assert_eq!(
            rows_of(&laid_out),
            vec![("one".to_owned(), true), ("two".to_owned(), false)]
        );
        assert!(
            (laid_out.size.y - 2.0 * laid_out.rows[0].height).abs() < 1e-3,
            "two rows stand two rows tall"
        );
    }

    #[test]
    fn a_trailing_newline_keeps_an_empty_row() {
        let shaper = shaper();
        let laid_out = shaper.layout("one\n", &font(), WorldPx::UNBOUNDED);
        assert_eq!(
            rows_of(&laid_out),
            vec![("one".to_owned(), true), (String::new(), false)]
        );
    }

    #[test]
    fn an_empty_run_is_one_empty_row_of_full_height() {
        let shaper = shaper();
        let laid_out = shaper.layout("", &font(), WorldPx::UNBOUNDED);
        assert_eq!(rows_of(&laid_out), vec![(String::new(), false)]);
        assert!((laid_out.size.y - shaper.metrics.row_height(&font())).abs() < 1e-3);
        assert_eq!(laid_out.size.x, 0.0);
    }

    #[test]
    fn a_run_wider_than_the_wrap_breaks_at_a_space() {
        let shaper = shaper();
        let wrap = width_of(&shaper, "the quick ");
        let laid_out = shaper.layout("the quick brown fox", &font(), wrap);
        let rows = rows_of(&laid_out);
        assert!(
            rows.len() > 1,
            "a wrapped run takes more than one row: {rows:?}"
        );
        assert!(
            rows.iter().all(|(_, ends)| !ends),
            "no row of one paragraph closes it: {rows:?}"
        );
        let whole: String = rows.iter().map(|(text, _)| text.as_str()).collect();
        assert_eq!(whole, "the quick brown fox", "wrapping drops nothing");
        assert!(
            laid_out.size.x <= wrap.get() + 1e-3,
            "no row is wider than the wrap: {} vs {}",
            laid_out.size.x,
            wrap.get()
        );
    }

    #[test]
    fn a_word_wider_than_the_wrap_breaks_per_character() {
        let shaper = shaper();
        let wrap = width_of(&shaper, "iiii");
        let laid_out = shaper.layout("mmmmmmmmmmmm", &font(), wrap);
        let rows = rows_of(&laid_out);
        assert!(
            rows.len() > 2,
            "a word with nowhere to break is cut up: {rows:?}"
        );
        let whole: String = rows.iter().map(|(text, _)| text.as_str()).collect();
        assert_eq!(whole, "mmmmmmmmmmmm");
    }

    #[test]
    fn wrapping_still_closes_the_paragraphs() {
        let shaper = shaper();
        let wrap = width_of(&shaper, "the quick ");
        let laid_out = shaper.layout("the quick brown fox\nagain", &font(), wrap);
        let rows = rows_of(&laid_out);
        let closed: Vec<bool> = rows.iter().map(|(_, ends)| *ends).collect();
        let last_of_the_first = rows.len() - 2;
        assert!(
            closed[last_of_the_first],
            "the last row of the first paragraph closes it: {rows:?}"
        );
        assert_eq!(
            closed.iter().filter(|ends| **ends).count(),
            1,
            "and it is the only one: {rows:?}"
        );
    }

    #[test]
    fn glyphs_march_rightwards_within_a_row() {
        let shaper = shaper();
        let wrap = width_of(&shaper, "waffle iron ");
        let laid_out = shaper.layout(
            "waffle iron for the office\nand a second paragraph",
            &font(),
            wrap,
        );
        assert!(laid_out.rows.len() > 2, "the run wrapped and broke");
        for row in &laid_out.rows {
            assert!(
                row.glyphs
                    .windows(2)
                    .all(|pair| pair[0].pos.x <= pair[1].pos.x),
                "glyph x never goes backwards: {:?}",
                row.glyphs.iter().map(|g| g.pos.x).collect::<Vec<_>>()
            );
            assert!(
                row.glyphs.first().is_none_or(|glyph| glyph.pos.x == 0.0),
                "every row starts at its own left edge"
            );
        }
    }

    #[test]
    fn a_ligature_is_one_glyph_and_a_continuation() {
        // Roboto's `liga` shapes "fi" into a single glyph, which the layout
        // reports as `'f'` plus a zero-advance `'i'`.
        let shaper = shaper();
        let laid_out = shaper.layout("Config", &font(), WorldPx::UNBOUNDED);
        let glyphs = &laid_out.rows[0].glyphs;
        assert_eq!(
            glyphs.iter().map(|glyph| glyph.chr).collect::<String>(),
            "Config",
            "one glyph per character"
        );
        let heads = glyphs.iter().filter(|glyph| glyph.id.is_some()).count();
        assert_eq!(heads, 5, "C o <fi> g is five glyphs: {glyphs:?}");
        let continuation = glyphs
            .iter()
            .find(|glyph| glyph.id.is_none())
            .expect("the ligature leaves a continuation");
        assert_eq!(continuation.chr, 'i');
        assert_eq!(continuation.advance, 0.0, "a continuation carries no pen");
        assert!(
            glyphs
                .iter()
                .all(|glyph| glyph.advance > 0.0 || glyph.id.is_none()),
            "only a continuation stands still"
        );
    }

    #[test]
    fn a_face_that_substitutes_nothing_keeps_every_character_its_own_glyph() {
        // Iosevka ships `calt` but no default-on code ligatures.
        let shaper = Shaper::new(FontChoice::Monospace);
        let laid_out = shaper.layout("a -> b", &font(), WorldPx::UNBOUNDED);
        assert!(
            laid_out.rows[0]
                .glyphs
                .iter()
                .all(|glyph| glyph.id.is_some()),
            "no continuations: {:?}",
            laid_out.rows[0].glyphs
        );
    }

    #[test]
    fn a_run_laid_out_twice_comes_back_the_same() {
        let shaper = shaper();
        let wrap = WorldPx::new(40.0);
        let text = "the quick brown fox\njumps";
        let once = shaper.layout(text, &font(), wrap);
        assert!(
            shaper.laid_out.borrow().get(text, &font(), wrap).is_some(),
            "the run was remembered"
        );
        let twice = shaper.layout(text, &font(), wrap);
        // Every field of a layout is `Debug`, so this compares all of them.
        assert_eq!(format!("{once:?}"), format!("{twice:?}"));
    }

    #[test]
    fn a_layout_is_filed_under_its_size_and_its_wrap() {
        let shaper = shaper();
        let text = "the quick brown fox";
        let small = shaper.layout(text, &Font::canvas(8.0), WorldPx::UNBOUNDED);
        let large = shaper.layout(text, &Font::canvas(16.0), WorldPx::UNBOUNDED);
        assert!(
            large.size.x > small.size.x,
            "a bigger font is not served the smaller layout"
        );
        let wrapped = shaper.layout(text, &font(), width_of(&shaper, "the quick "));
        let unwrapped = shaper.layout(text, &font(), WorldPx::UNBOUNDED);
        assert!(
            wrapped.rows.len() > unwrapped.rows.len(),
            "a wrap is not served the unwrapped layout"
        );
    }

    #[test]
    fn the_engine_answers_for_the_typeface_it_was_built_from() {
        for choice in FontChoice::ALL {
            let shaper = Shaper::new(choice);
            assert_eq!(shaper.typeface(), choice);
            assert!(
                !shaper.glyph_ids("Ab").is_empty(),
                "{} shapes something",
                choice.display_name()
            );
        }
    }
}