math.rs

//! Reads the OpenType MATH table
//!
//! The font holds every value needed to typeset math: the height of the math axis, rule
//! thicknesses, how much scripts are scaled down and raised, and the gaps around radicals.
//! It also holds the size variants and assemblies that stretchy delimiters are made from.
//!
//! All values are returned in em. Font units do not leave this module.

use crate::error::Error;
use crate::opentype::{read_i16, read_u16};
use std::collections::HashMap;


/// Constants for typesetting math. Values are in em
#[derive(Debug, Clone, Copy, Default, PartialEq)]
pub struct Constant {
    /// The size ratio for scripts
    pub script_percent: f64,
    /// The size ratio for scripts of scripts
    pub script_script_percent: f64,
    /// The minimum height of the delimiters of \left and \right
    pub delimited_min_height: f64,
    /// The height for switching to large operators in display style
    pub display_operator_min_height: f64,

    pub axis_height: f64,
    pub accent_base_height: f64,

    pub subscript_shift_down: f64,
    pub subscript_top_max: f64,
    pub subscript_baseline_drop_min: f64,
    pub superscript_shift_up: f64,
    pub superscript_bottom_min: f64,
    pub superscript_baseline_drop_max: f64,
    pub sub_superscript_gap_min: f64,
    pub superscript_bottom_max_with_subscript: f64,
    pub space_after_script: f64,

    pub upper_limit_gap_min: f64,
    pub upper_limit_baseline_rise_min: f64,
    pub lower_limit_gap_min: f64,
    pub lower_limit_baseline_drop_min: f64,

    pub stack_top_shift_up: f64,
    pub stack_top_display_shift_up: f64,
    pub stack_bottom_shift_down: f64,
    pub stack_bottom_display_shift_down: f64,
    pub stack_gap_min: f64,
    pub stack_display_gap_min: f64,

    pub fraction_numerator_shift_up: f64,
    pub fraction_numerator_display_shift_up: f64,
    pub fraction_denominator_shift_down: f64,
    pub fraction_denominator_display_shift_down: f64,
    pub fraction_numerator_gap_min: f64,
    pub fraction_numerator_display_gap_min: f64,
    pub fraction_rule_thickness: f64,
    pub fraction_denominator_gap_min: f64,
    pub fraction_denominator_display_gap_min: f64,

    pub overbar_vertical_gap: f64,
    pub overbar_rule_thickness: f64,
    pub overbar_extra_ascender: f64,
    pub underbar_vertical_gap: f64,
    pub underbar_rule_thickness: f64,
    pub underbar_extra_descender: f64,

    pub radical_vertical_gap: f64,
    pub radical_display_vertical_gap: f64,
    pub radical_rule_thickness: f64,
    pub radical_extra_ascender: f64,
    pub radical_kern_before_degree: f64,
    pub radical_kern_after_degree: f64,
    /// How far to raise the degree of a radical from the bottom of the radical (percent)
    pub radical_degree_bottom_raise_percent: f64,
}


/// A size variant
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Variant {
    pub glyph: u16,
    /// The length measured in the direction of stretching
    pub measure: f64,
}


/// A part of an assembly
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Part {
    pub glyph: u16,
    pub start_connector: f64,
    pub end_connector: f64,
    pub full_advance: f64,
    /// Whether the part may be repeated any number of times
    pub extender: bool,
}


/// How to stretch one glyph. Size variants, and an assembly for when they are not big enough
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Construction {
    pub variant: Vec<Variant>,
    pub part: Vec<Part>,
}


#[derive(Debug, Clone, Default)]
pub struct Table {
    pub constant: Constant,
    /// The minimum length by which parts overlap
    pub min_overlap: f64,
    italic: HashMap<u16, f64>,
    top_accent: HashMap<u16, f64>,
    vertical: HashMap<u16, Construction>,
    horizontal: HashMap<u16, Construction>,
}


/// Makes a table that holds only the constants, for a typeface without a MATH table
pub fn with_constant(constant: Constant) -> Table {
    Table {constant, ..Table::default()}
}


/// How far an italic glyph extends to the right
pub fn italic_correction(table: &Table, glyph: u16) -> f64 {
    table.italic.get(&glyph).copied().unwrap_or(0.0)
}


/// Where to align an accent horizontally. None if the font does not give one
pub fn top_accent(table: &Table, glyph: u16) -> Option<f64> {
    table.top_accent.get(&glyph).copied()
}


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


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


/// Reads the MATH table. units is the number of font units per em
pub fn parse(data: &[u8], at: usize, units: f64) -> Result<Table, Error> {
    let constant_at = read_u16(data, at + 4)? as usize;
    let glyph_info_at = read_u16(data, at + 6)? as usize;
    let variant_at = read_u16(data, at + 8)? as usize;
    let mut table = Table {
        constant: read_constant(data, at + constant_at, units)?,
        ..Table::default()
    };

    if glyph_info_at != 0 {
        read_glyph_info(data, at + glyph_info_at, units, &mut table)?;
    }

    if variant_at != 0 {
        read_variants(data, at + variant_at, units, &mut table)?;
    }

    Ok(table)
}


/// The value of a MathValueRecord. Its position is given as an index into the list of records
fn value(data: &[u8], base: usize, index: usize, units: f64) -> Result<f64, Error> {
    Ok(read_i16(data, base + index * 4)? as f64 / units)
}


fn read_constant(data: &[u8], at: usize, units: f64) -> Result<Constant, Error> {
    let record = at + 8;
    let take = |index: usize| value(data, record, index, units);

    Ok(Constant {
        script_percent: read_i16(data, at)? as f64 / 100.0,
        script_script_percent: read_i16(data, at + 2)? as f64 / 100.0,
        delimited_min_height: read_u16(data, at + 4)? as f64 / units,
        display_operator_min_height: read_u16(data, at + 6)? as f64 / units,

        axis_height: take(1)?,
        accent_base_height: take(2)?,

        subscript_shift_down: take(4)?,
        subscript_top_max: take(5)?,
        subscript_baseline_drop_min: take(6)?,
        superscript_shift_up: take(7)?,
        superscript_bottom_min: take(9)?,
        superscript_baseline_drop_max: take(10)?,
        sub_superscript_gap_min: take(11)?,
        superscript_bottom_max_with_subscript: take(12)?,
        space_after_script: take(13)?,

        upper_limit_gap_min: take(14)?,
        upper_limit_baseline_rise_min: take(15)?,
        lower_limit_gap_min: take(16)?,
        lower_limit_baseline_drop_min: take(17)?,

        stack_top_shift_up: take(18)?,
        stack_top_display_shift_up: take(19)?,
        stack_bottom_shift_down: take(20)?,
        stack_bottom_display_shift_down: take(21)?,
        stack_gap_min: take(22)?,
        stack_display_gap_min: take(23)?,

        fraction_numerator_shift_up: take(28)?,
        fraction_numerator_display_shift_up: take(29)?,
        fraction_denominator_shift_down: take(30)?,
        fraction_denominator_display_shift_down: take(31)?,
        fraction_numerator_gap_min: take(32)?,
        fraction_numerator_display_gap_min: take(33)?,
        fraction_rule_thickness: take(34)?,
        fraction_denominator_gap_min: take(35)?,
        fraction_denominator_display_gap_min: take(36)?,

        overbar_vertical_gap: take(39)?,
        overbar_rule_thickness: take(40)?,
        overbar_extra_ascender: take(41)?,
        underbar_vertical_gap: take(42)?,
        underbar_rule_thickness: take(43)?,
        underbar_extra_descender: take(44)?,

        radical_vertical_gap: take(45)?,
        radical_display_vertical_gap: take(46)?,
        radical_rule_thickness: take(47)?,
        radical_extra_ascender: take(48)?,
        radical_kern_before_degree: take(49)?,
        radical_kern_after_degree: take(50)?,
        radical_degree_bottom_raise_percent: read_i16(data, record + 51 * 4)? as f64 / 100.0,
    })
}


/// The list of covered glyphs. A position in it is also an index into the list of values
fn coverage(data: &[u8], at: usize) -> Result<Vec<u16>, Error> {
    let mut found = Vec::new();

    match read_u16(data, at)? {
        1 => {
            let count = read_u16(data, at + 2)? as usize;

            for index in 0..count {
                found.push(read_u16(data, at + 4 + index * 2)?);
            }
        }
        2 => {
            let count = read_u16(data, at + 2)? as usize;

            for index in 0..count {
                let record = at + 4 + index * 6;
                let start = read_u16(data, record)?;
                let end = read_u16(data, record + 2)?;

                if start > end {
                    continue;
                }

                for glyph in start..=end {
                    found.push(glyph);
                }
            }
        }
        format => return Err(Error::new(format!("cannot read Coverage format {format}"), at)),
    }

    Ok(found)
}


fn read_glyph_info(data: &[u8], at: usize, units: f64, table: &mut Table) -> Result<(), Error> {
    let italic_at = read_u16(data, at)? as usize;
    let accent_at = read_u16(data, at + 2)? as usize;

    if italic_at != 0 {
        table.italic = read_value_map(data, at + italic_at, units)?;
    }

    if accent_at != 0 {
        table.top_accent = read_value_map(data, at + accent_at, units)?;
    }

    Ok(())
}


/// The covered glyphs, each paired with its value
fn read_value_map(data: &[u8], at: usize, units: f64) -> Result<HashMap<u16, f64>, Error> {
    let coverage_at = read_u16(data, at)? as usize;
    let count = read_u16(data, at + 2)? as usize;

    if coverage_at == 0 {
        return Ok(HashMap::new());
    }

    let glyphs = coverage(data, at + coverage_at)?;
    let mut found = HashMap::with_capacity(count);

    for (index, glyph) in glyphs.into_iter().enumerate() {
        if index >= count {
            break;
        }

        found.insert(glyph, value(data, at + 4, index, units)?);
    }

    Ok(found)
}


fn read_variants(data: &[u8], at: usize, units: f64, table: &mut Table) -> Result<(), Error> {
    table.min_overlap = read_u16(data, at)? as f64 / units;

    let vertical_coverage = read_u16(data, at + 2)? as usize;
    let horizontal_coverage = read_u16(data, at + 4)? as usize;
    let vertical_count = read_u16(data, at + 6)? as usize;
    let horizontal_count = read_u16(data, at + 8)? as usize;
    let vertical_at = at + 10;
    let horizontal_at = vertical_at + vertical_count * 2;

    if vertical_coverage != 0 {
        table.vertical = read_constructions(
            data,
            at,
            at + vertical_coverage,
            vertical_at,
            vertical_count,
            units,
        )?;
    }

    if horizontal_coverage != 0 {
        table.horizontal = read_constructions(
            data,
            at,
            at + horizontal_coverage,
            horizontal_at,
            horizontal_count,
            units,
        )?;
    }

    Ok(())
}


fn read_constructions(
    data: &[u8],
    base: usize,
    coverage_at: usize,
    list_at: usize,
    count: usize,
    units: f64,
) -> Result<HashMap<u16, Construction>, Error> {
    let glyphs = coverage(data, coverage_at)?;
    let mut found = HashMap::with_capacity(count);

    for (index, glyph) in glyphs.into_iter().enumerate() {
        if index >= count {
            break;
        }

        let offset = read_u16(data, list_at + index * 2)? as usize;

        if offset == 0 {
            continue;
        }

        found.insert(glyph, read_construction(data, base + offset, units)?);
    }

    Ok(found)
}


fn read_construction(data: &[u8], at: usize, units: f64) -> Result<Construction, Error> {
    let assembly_at = read_u16(data, at)? as usize;
    let count = read_u16(data, at + 2)? as usize;
    let mut variant = Vec::with_capacity(count);

    for index in 0..count {
        let record = at + 4 + index * 4;
        variant.push(Variant {
            glyph: read_u16(data, record)?,
            measure: read_u16(data, record + 2)? as f64 / units,
        });
    }

    let part = if assembly_at == 0 {
        Vec::new()
    } else {
        read_assembly(data, at + assembly_at, units)?
    };

    Ok(Construction {variant, part})
}


fn read_assembly(data: &[u8], at: usize, units: f64) -> Result<Vec<Part>, Error> {
    let count = read_u16(data, at + 4)? as usize;
    let mut found = Vec::with_capacity(count);

    for index in 0..count {
        let record = at + 6 + index * 10;
        found.push(Part {
            glyph: read_u16(data, record)?,
            start_connector: read_u16(data, record + 2)? as f64 / units,
            end_connector: read_u16(data, record + 4)? as f64 / units,
            full_advance: read_u16(data, record + 6)? as f64 / units,
            extender: read_u16(data, record + 8)? & 1 != 0,
        });
    }

    Ok(found)
}


#[cfg(test)]
mod tests {
    use super::*;
    use crate::opentype::{character_map, require};

    fn font() -> (Vec<u8>, Table, HashMap<char, u16>) {
        let data = std::fs::read("font/latinmodern-math.otf").expect("cannot read the test font");
        let (math_at, _) = require(&data, "MATH").unwrap();
        let table = parse(&data, math_at, 1000.0).unwrap();
        let (cmap_at, _) = require(&data, "cmap").unwrap();
        let map = character_map(&data, cmap_at).unwrap();

        (data, table, map)
    }

    #[test]
    fn reads_the_constants() {
        let (_, table, _) = font();
        let constant = table.constant;
        assert_eq!(constant.axis_height, 0.25);
        assert_eq!(constant.script_percent, 0.7);
        assert_eq!(constant.script_script_percent, 0.5);
        assert!(constant.fraction_rule_thickness > 0.0);
        assert!(constant.radical_rule_thickness > 0.0);
        assert!(constant.accent_base_height > 0.0);
        assert!(constant.display_operator_min_height > 0.0);
    }

    #[test]
    fn a_paren_can_grow() {
        let (_, table, map) = font();
        let construction = vertical(&table, map[&'(']).expect("the parenthesis has no variants");
        assert!(construction.variant.len() > 3, "variant count: {}", construction.variant.len());

        for pair in construction.variant.windows(2) {
            assert!(pair[1].measure >= pair[0].measure, "the variants are not in order of height");
        }

        assert!(!construction.part.is_empty(), "the parenthesis has no assembly");
        assert!(construction.part.iter().any(|part| part.extender));
    }

    #[test]
    fn the_radical_can_grow() {
        let (_, table, map) = font();
        let construction = vertical(&table, map[&'\u{221a}']).expect("the radical has no variants");
        assert!(!construction.variant.is_empty());
    }

    #[test]
    fn slanted_letters_carry_an_italic_correction() {
        let (_, table, map) = font();
        let slanted = map[&'\u{1d453}'];
        assert!(italic_correction(&table, slanted) > 0.0, "f has no italic correction");
    }

    #[test]
    fn accents_have_an_attachment_point() {
        let (_, table, map) = font();
        assert!(top_accent(&table, map[&'x']).is_some());
    }

    #[test]
    fn the_overlap_is_recorded() {
        let (_, table, _) = font();
        assert!(table.min_overlap > 0.0);
    }
}