font.rs

//! The metrics and glyphs of a single font
//!
//! Loads an OpenType file and keeps only the parts that typesetting needs.
//! All measures are converted to em, so font units do not appear from the outside.
//!
//! If there is a MATH table, its values are used. For a typeface without one (such as Times
//! New Roman), equivalents of the TeX defaults are built from the x-height and rule thickness.

use crate::cff::{self, Cff};
use crate::error::Error;
use crate::glyf::{self, Glyf};
use crate::math::{self, Constant, Construction, Table};
use crate::opentype::{self, require};
use crate::outline::{self, Outline};
use std::collections::HashMap;


/// Which form the glyphs are stored in
#[derive(Debug, Clone)]
enum Kind {
    Cff(Cff),
    Glyf(Glyf),
}


/// A loaded font
#[derive(Debug, Clone)]
pub struct Font {
    data: Vec<u8>,
    family: String,
    units_per_em: f64,
    kind: Kind,
    map: HashMap<char, u16>,
    /// The advance of each glyph (em)
    advance: Vec<f64>,
    /// For each glyph, how far it actually reaches up and down (em). (height, depth)
    extent: Vec<(f64, f64)>,
    /// The left and right bearings of each glyph (em). The gap between the ink and the advance
    bearing: Vec<(f64, f64)>,
    table: Table,
    has_math: bool,
}


/// Loads a font file
pub fn load(data: Vec<u8>) -> Result<Font, Error> {
    let (head_at, _) = require(&data, "head")?;
    let shape = opentype::head(&data, head_at)?;
    let units_per_em = shape.units_per_em;
    let (maxp_at, _) = require(&data, "maxp")?;
    let count = opentype::glyph_count(&data, maxp_at)?;
    let (hmtx_at, _) = require(&data, "hmtx")?;
    let (hhea_at, _) = require(&data, "hhea")?;
    let (cmap_at, _) = require(&data, "cmap")?;
    let (name_at, _) = require(&data, "name")?;

    let kind = match opentype::find(&data, "CFF ")? {
        Some((cff_at, _)) => Kind::Cff(cff::parse(&data, cff_at, units_per_em)?),
        None => {
            let (glyf_at, _) = require(&data, "glyf")?;
            let (loca_at, _) = require(&data, "loca")?;

            Kind::Glyf(glyf::new(glyf_at, loca_at, shape.long_loca, count))
        }
    };

    let advance = opentype::advances(&data, hmtx_at, hhea_at, count)?
        .into_iter()
        .map(|width| width / units_per_em)
        .collect();
    let mut font = Font {
        family: opentype::family_name(&data, name_at)?,
        map: opentype::character_map(&data, cmap_at)?,
        units_per_em,
        kind,
        advance,
        extent: Vec::new(),
        bearing: Vec::new(),
        table: Table::default(),
        has_math: false,
        data,
    };

    let (extent, bearing) = measure_all(&font, count)?;
    font.extent = extent;
    font.bearing = bearing;

    match opentype::find(&font.data, "MATH")? {
        Some((math_at, _)) => {
            font.table = math::parse(&font.data, math_at, units_per_em)?;
            font.has_math = true;
        }
        None => font.table = math::with_constant(derived(&font)),
    }

    Ok(font)
}


/// The name of the typeface. It is what goes in CSS font-family
pub fn family(font: &Font) -> &str {
    &font.family
}


/// The fallback for characters that the typeface does not have
///
/// Math typefaces have no kanji or kana. The fallback for such characters inside \text is kept
/// the same in HTML and SVG, so that the same formula does not appear in different typefaces
pub const FALLBACK: &str = "serif";


/// Font coordinate units per em
pub fn units_per_em(font: &Font) -> f64 {
    font.units_per_em
}


/// Whether the font has a MATH table
pub fn has_math(font: &Font) -> bool {
    font.has_math
}


/// The constants for typesetting
pub fn constant(font: &Font) -> &Constant {
    &font.table.constant
}


/// The glyph ID for a character
pub fn glyph_of(font: &Font, character: char) -> Option<u16> {
    font.map.get(&character).copied()
}


/// The advance of a glyph (em)
pub fn advance(font: &Font, glyph: u16) -> f64 {
    font.advance.get(glyph as usize).copied().unwrap_or(0.0)
}


/// The rough advance, height, and depth (em) for placing a character the font does not have
///
/// Characters outside the typeface (Japanese, for example) can appear inside \text. Their
/// outlines cannot be drawn, so they must be placed as text. Only their space is reserved here
pub fn fallback_metric(character: char) -> (f64, f64, f64) {
    if character as u32 >= 0x2e80 {
        (1.0, 0.88, 0.12)
    } else {
        (0.5, 0.7, 0.0)
    }
}


/// The height and depth a glyph covers (em). Depth is positive downward
pub fn extent(font: &Font, glyph: u16) -> (f64, f64) {
    font.extent.get(glyph as usize).copied().unwrap_or((0.0, 0.0))
}


/// The left and right bearings of a glyph (em). The gap up to the left edge of the ink, and
/// the gap from the right edge of the ink to the advance
pub fn bearing(font: &Font, glyph: u16) -> (f64, f64) {
    font.bearing.get(glyph as usize).copied().unwrap_or((0.0, 0.0))
}


/// How far an italic glyph extends to the right (em)
pub fn italic_correction(font: &Font, glyph: u16) -> f64 {
    math::italic_correction(&font.table, glyph)
}


/// Where to align an accent horizontally (em). The glyph's middle if the font does not give one
pub fn accent_center(font: &Font, glyph: u16) -> f64 {
    match math::top_accent(&font.table, glyph) {
        Some(found) => found,
        None => advance(font, glyph) / 2.0,
    }
}


/// How to stretch the glyph vertically
pub fn vertical_growth(font: &Font, glyph: u16) -> Option<&Construction> {
    math::vertical(&font.table, glyph)
}


/// How to stretch the glyph horizontally
pub fn horizontal_growth(font: &Font, glyph: u16) -> Option<&Construction> {
    math::horizontal(&font.table, glyph)
}


/// The minimum length by which the parts of an assembly overlap (em)
pub fn min_overlap(font: &Font) -> f64 {
    font.table.min_overlap
}


/// The outline of a glyph. Coordinates stay in font units, with y pointing up
pub fn outline_of(font: &Font, glyph: u16) -> Outline {
    let found = match &font.kind {
        Kind::Cff(cff) => cff::outline(&font.data, cff, glyph),
        Kind::Glyf(glyf) => glyf::outline(&font.data, glyf, glyph),
    };

    found.unwrap_or_default()
}


type Measured = (Vec<(f64, f64)>, Vec<(f64, f64)>);


fn measure_all(font: &Font, count: usize) -> Result<Measured, Error> {
    let mut extent = Vec::with_capacity(count);
    let mut bearing = Vec::with_capacity(count);

    for glyph in 0..count {
        let drawn = match &font.kind {
            Kind::Cff(cff) => cff::outline(&font.data, cff, glyph as u16)?,
            Kind::Glyf(glyf) => glyf::outline(&font.data, glyf, glyph as u16)?,
        };
        let (left, bottom, right, top) = outline::bounds(&drawn);
        let units = font.units_per_em;
        extent.push((top / units, -bottom / units));

        let advance = font.advance.get(glyph).copied().unwrap_or(0.0);
        bearing.push((left / units, (advance - right / units).max(0.0)));
    }

    Ok((extent, bearing))
}


/// Constants for a typeface without a MATH table. They correspond to the values TeX has used
fn derived(font: &Font) -> Constant {
    let x_height = match font.map.get(&'x') {
        Some(glyph) => font.extent.get(*glyph as usize).map_or(0.45, |found| found.0),
        None => 0.45,
    };
    let rule = 0.04;

    Constant {
        script_percent: 0.7,
        script_script_percent: 0.5,
        delimited_min_height: 1.5,
        display_operator_min_height: 1.35,

        axis_height: x_height / 2.0,
        accent_base_height: x_height,

        subscript_shift_down: 0.25,
        subscript_top_max: 0.8 * x_height,
        subscript_baseline_drop_min: 0.05,
        superscript_shift_up: 0.42,
        superscript_bottom_min: 0.25 * x_height,
        superscript_baseline_drop_max: 0.35,
        sub_superscript_gap_min: 4.0 * rule,
        superscript_bottom_max_with_subscript: 0.8 * x_height,
        space_after_script: 0.05,

        upper_limit_gap_min: 0.2,
        upper_limit_baseline_rise_min: 0.3,
        lower_limit_gap_min: 0.2,
        lower_limit_baseline_drop_min: 0.6,

        stack_top_shift_up: 0.45,
        stack_top_display_shift_up: 0.6,
        stack_bottom_shift_down: 0.55,
        stack_bottom_display_shift_down: 0.7,
        stack_gap_min: 3.0 * rule,
        stack_display_gap_min: 7.0 * rule,

        fraction_numerator_shift_up: 0.45,
        fraction_numerator_display_shift_up: 0.6,
        fraction_denominator_shift_down: 0.55,
        fraction_denominator_display_shift_down: 0.7,
        fraction_numerator_gap_min: rule,
        fraction_numerator_display_gap_min: 3.0 * rule,
        fraction_rule_thickness: rule,
        fraction_denominator_gap_min: rule,
        fraction_denominator_display_gap_min: 3.0 * rule,

        overbar_vertical_gap: 3.0 * rule,
        overbar_rule_thickness: rule,
        overbar_extra_ascender: rule,
        underbar_vertical_gap: 3.0 * rule,
        underbar_rule_thickness: rule,
        underbar_extra_descender: rule,

        radical_vertical_gap: 1.25 * rule,
        radical_display_vertical_gap: rule + 0.25 * x_height,
        radical_rule_thickness: rule,
        radical_extra_ascender: rule,
        radical_kern_before_degree: 0.28,
        radical_kern_after_degree: -0.36,
        radical_degree_bottom_raise_percent: 0.6,
    }
}


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

    pub fn sample() -> Font {
        let data = std::fs::read("font/latinmodern-math.otf").expect("cannot read the test font");

        load(data).expect("cannot load the font")
    }

    #[test]
    fn reads_the_name_and_the_unit() {
        let font = sample();
        assert_eq!(family(&font), "Latin Modern Math");
        assert_eq!(units_per_em(&font), 1000.0);
        assert!(has_math(&font));
    }

    #[test]
    fn measures_letters() {
        let font = sample();
        let x = glyph_of(&font, 'x').unwrap();
        let y = glyph_of(&font, 'y').unwrap();
        assert!(advance(&font, x) > 0.3 && advance(&font, x) < 0.7);
        assert!(extent(&font, x).1.abs() < 0.02, "x has depth");
        assert!(extent(&font, y).1 > 0.1, "y has no depth");
    }

    #[test]
    fn the_constants_come_from_the_font() {
        let font = sample();
        let value = constant(&font);
        assert_eq!(value.axis_height, 0.25);
        assert!(value.fraction_rule_thickness > 0.0 && value.fraction_rule_thickness < 0.1);
        assert!(value.radical_rule_thickness > 0.0);
    }

    #[test]
    fn brackets_know_how_to_grow() {
        let font = sample();
        let paren = glyph_of(&font, '(').unwrap();
        let growth = vertical_growth(&font, paren).unwrap();
        assert!(growth.variant.len() > 3);
        assert!(min_overlap(&font) > 0.0);
    }

    #[test]
    fn brackets_have_little_room_on_the_inside() {
        let font = sample();
        let open = glyph_of(&font, '(').unwrap();
        let (left, right) = bearing(&font, open);
        assert!(left > right, "an opening parenthesis is tighter on the inside");
        assert!(right < 0.1, "space on the inside: {right}");
    }

    #[test]
    fn outlines_come_out_in_font_units() {
        let font = sample();
        let x = glyph_of(&font, 'x').unwrap();
        let drawn = outline_of(&font, x);
        assert!(!drawn.segment.is_empty());
        let (_, _, _, top) = outline::bounds(&drawn);
        assert!((top / units_per_em(&font) - extent(&font, x).0).abs() < 1e-9);
    }

    #[test]
    fn a_font_without_math_gets_derived_constants() {
        let path = "/System/Library/Fonts/Supplemental/Times New Roman.ttf";
        let Ok(data) = std::fs::read(path) else {
            return;
        };
        let font = load(data).unwrap();
        assert!(!has_math(&font));
        assert!(constant(&font).axis_height > 0.15);
        assert!(constant(&font).axis_height < 0.35);
        assert!(extent(&font, glyph_of(&font, 'y').unwrap()).1 > 0.1);
    }
}