retex_engine/

fonts.rs

//! Fonts as TeX sees them: metrics, parameters (`\fontdimen`), identifiers
//! and font-related assignments (*TeX: The Program* §539–§582, §1252–§1261).
//!
//! Font files are not parsed here. A [`FontLoader`] supplied by the host
//! (the native luaotfload replacement, or a TFM reader) turns a font request
//! into a [`FontInfo`].

use std::collections::HashMap;

use crate::Engine;
use crate::cmd::Cmd;
use crate::eqtb::{Loc, Meaning, Val};
use crate::hash::CsId;
use crate::primitives_gen as pg;

/// Metrics of one character.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct CharMetrics {
    /// Width (sp).
    pub width: i32,
    /// Height (sp).
    pub height: i32,
    /// Depth (sp).
    pub depth: i32,
    /// Italic correction (sp).
    pub italic: i32,
    /// Glyph index in the font file (for the backend).
    pub index: u32,
}

/// A ligature or kerning instruction of a font's lig/kern program.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum LigOp {
    /// Insert a font kern of this amount between the two characters.
    Kern(i32),
    /// A ligature: `op` is TFM's op byte (`=:` 0, `=:|` 1, `|=:` 2,
    /// `|=:|` 3, `=:|>` 5, `|=:>` 6, `|=:|>` 7, `|=:|>>` 11), `chr` the
    /// ligature character.
    Lig {
        /// The operation.
        op: u8,
        /// The character inserted.
        chr: u32,
    },
}

/// One step of a lig/kern program: what to do when `next` follows.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LigKernStep {
    /// The right-hand character (the font's right boundary character for
    /// the right word boundary).
    pub next: u32,
    /// The instruction.
    pub op: LigOp,
}

/// A fast hasher for small integer keys (multiply-rotate, as in rustc's
/// `FxHasher`).
#[derive(Default, Clone, Copy)]
pub struct FxHasher(u64);

impl std::hash::Hasher for FxHasher {
    #[inline]
    fn write(&mut self, bytes: &[u8]) {
        for &b in bytes {
            self.write_u64(u64::from(b));
        }
    }

    #[inline]
    fn write_u32(&mut self, i: u32) {
        self.write_u64(u64::from(i));
    }

    #[inline]
    fn write_u64(&mut self, i: u64) {
        self.0 = (self.0.rotate_left(5) ^ i).wrapping_mul(0x517c_c1b7_2722_0a95);
    }

    #[inline]
    fn finish(&self) -> u64 {
        self.0
    }
}

/// Lig/kern programs by left character.
pub type LigKernMap = HashMap<u32, Box<[LigKernStep]>, std::hash::BuildHasherDefault<FxHasher>>;

/// Key of the left boundary program in [`FontInfo::lig_kern`].
pub const LEFT_BOUNDARY: u32 = 0x11_0000;

/// How a font was loaded.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum FontKind {
    /// `\nullfont`.
    Null,
    /// A TFM font.
    Tfm,
    /// An OpenType font loaded through the luaotfload replacement.
    OpenType,
}

/// Host data attached to a font (e.g. the parsed OpenType font used for
/// shaping and embedding).
#[derive(Clone)]
pub struct FontData(pub std::rc::Rc<dyn std::any::Any>);

impl std::fmt::Debug for FontData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("FontData(..)")
    }
}

/// Host data of a TFM font: the parsed file and its raw bytes (kept for
/// the format file).
#[derive(Debug)]
pub struct TfmData {
    /// The parsed metrics.
    pub tfm: std::rc::Rc<retex_font::tfm::Tfm>,
    /// The file content.
    pub raw: Vec<u8>,
}

/// Wraps a TFM font as font data.
pub fn tfm_font_data(tfm: retex_font::tfm::Tfm, raw: Vec<u8>) -> FontData {
    FontData(std::rc::Rc::new(TfmData {
        tfm: std::rc::Rc::new(tfm),
        raw,
    }))
}

/// A loaded font.
#[derive(Clone, Debug)]
pub struct FontInfo {
    /// The name as `\fontname` prints it.
    pub name: Vec<u8>,
    /// The size (sp).
    pub size: i32,
    /// The design size (sp).
    pub design_size: i32,
    /// The TFM checksum (or the `checksum` of a Lua font table), written
    /// to DVI font definitions.
    pub checksum: u32,
    /// Font parameters; `params[k]` is `\fontdimen k` (index 0 unused).
    pub params: Vec<i32>,
    /// Character metrics.
    pub chars: HashMap<u32, CharMetrics, crate::hash::FastHash>,
    /// `\hyphenchar`.
    pub hyphen_char: i32,
    /// `\skewchar`.
    pub skew_char: i32,
    /// The kind of font.
    pub kind: FontKind,
    /// Opaque handle for the loader/backend (e.g. index of the parsed
    /// OpenType font and its feature set).
    pub handle: u64,
    /// Per-character `\lpcode`, `\rpcode`, `\efcode`, `\tagcode`.
    pub char_codes: [HashMap<u32, i32>; 4],
    /// `\ignoreligaturesinfont` and other per-font integers.
    pub ignore_ligatures: i32,
    /// Host data (shaping, embedding).
    pub data: Option<FontData>,
    /// Lig/kern programs by left character; only the first step for each
    /// right character is kept. [`LEFT_BOUNDARY`] holds the left boundary
    /// program.
    pub lig_kern: LigKernMap,
    /// The right boundary character (TFM's `bchar`), if any.
    pub right_boundary: Option<u32>,
    /// Font expansion parameters (`\expandglyphsinfont`), if expandable.
    pub expansion: Option<crate::expansion::FontExpansion>,
    /// The OpenType `MathConstants` (in scaled points, or percent), for
    /// fonts loaded with a MATH table; they set the `\Umath…` parameters
    /// when the font is assigned to a math family.
    pub math_constants: Option<std::rc::Rc<MathConstants>>,
    /// Per-character OpenType math data (variants, extensible parts, top
    /// accent attachments), for math fonts.
    pub math_chars: Option<std::rc::Rc<HashMap<u32, MathCharInfo>>>,
    /// The size requested by `\font` (positive `at` size, or minus the
    /// `scaled` factor); `i32::MIN` if not loaded by `\font`.
    pub size_spec: i32,
    /// How to draw the characters, for a TFM font that has a virtual
    /// font (`.vf`) of the same name.
    pub vf: Option<std::rc::Rc<VirtualFont>>,
}

/// The drawing instructions of a virtual font at the size it was loaded
/// at: shipping out a character runs its packet instead of drawing it.
#[derive(Debug, Default)]
pub struct VirtualFont {
    /// The engine font of each local font (0, the null font, if it could
    /// not be loaded).
    pub fonts: Vec<u32>,
    /// The packet of each character, in sp.
    pub packets: HashMap<u32, Box<[retex_font::vf::Command]>, crate::hash::FastHash>,
}

/// How deeply virtual fonts may refer to other virtual fonts.
const VF_MAX_DEPTH: u32 = 8;

/// One part of an extensible OpenType math character (scaled points).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ExtPart {
    /// The character of the part.
    pub code: u32,
    /// Start connector length.
    pub start: i32,
    /// End connector length.
    pub end: i32,
    /// Full advance.
    pub advance: i32,
    /// Whether the part is repeatable.
    pub extender: bool,
}

/// The OpenType math data of a character.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct MathCharInfo {
    /// The next larger variant.
    pub next: Option<u32>,
    /// The top accent attachment point.
    pub top_accent: Option<i32>,
    /// Vertical extensible parts, bottom first.
    pub vert: Option<std::rc::Rc<[ExtPart]>>,
    /// Horizontal extensible parts, left first.
    pub horiz: Option<std::rc::Rc<[ExtPart]>>,
}

/// Named OpenType math constants (luaotfload's `MathConstants`).
pub type MathConstants = HashMap<String, i32>;

impl Default for FontInfo {
    fn default() -> Self {
        FontInfo::null()
    }
}

impl FontInfo {
    /// The null font: no characters, seven zero parameters.
    pub fn null() -> Self {
        FontInfo {
            name: b"nullfont".to_vec(),
            size: 0,
            design_size: 0,
            checksum: 0,
            params: vec![0; 8],
            chars: HashMap::default(),
            hyphen_char: '-' as i32,
            skew_char: -1,
            kind: FontKind::Null,
            handle: 0,
            char_codes: Default::default(),
            ignore_ligatures: 0,
            lig_kern: LigKernMap::default(),
            right_boundary: None,
            math_constants: None,
            math_chars: None,
            size_spec: i32::MIN,
            data: None,
            expansion: None,
            vf: None,
        }
    }
}

/// A font request from `\font`.
#[derive(Clone, Debug)]
pub struct FontRequest {
    /// The name as written after `\font\cs=`.
    pub name: Vec<u8>,
    /// Size: positive is `at` (sp), negative is `scaled` (−1000 × factor),
    /// −1000 when unspecified.
    pub size: i32,
}

/// Loads fonts for the engine (LuaTeX's `define_font` callback).
pub trait FontLoader {
    /// Loads the font, or returns `None` if it cannot be found.
    fn load(&mut self, req: &FontRequest) -> Option<FontInfo>;
}

/// The table of loaded fonts.
#[derive(Default)]
pub struct FontTable {
    /// Fonts by id; id 0 is `\nullfont`.
    pub fonts: Vec<FontInfo>,
    /// Identifier control sequence of each font (TeX's `font_id_text`).
    pub id_cs: Vec<CsId>,
    /// The loader, if any.
    pub loader: Option<Box<dyn FontLoader>>,
    /// Dense metric tables for fast lookup of small character codes, by
    /// font id (see [`FontTable::sync_dense`]).
    pub dense: Vec<DenseMetrics>,
}

/// Number of character codes covered by [`DenseMetrics`].
const DENSE_CHARS: usize = 0x800;

/// Metrics of the characters below [`DENSE_CHARS`] in an array.
#[derive(Clone, Debug, Default)]
pub struct DenseMetrics {
    metrics: Box<[CharMetrics]>,
    present: Box<[u64]>,
    /// For characters below 256: (start, length) of their lig/kern program
    /// in `steps`.
    lk: Box<[(u32, u32)]>,
    steps: Box<[LigKernStep]>,
    /// For pairs of characters below 128: index + 1 of their instruction
    /// in `steps` (0 for none).
    pairs: Box<[u16]>,
}

impl FontTable {
    /// Builds the dense tables of fonts added since the last call. Call
    /// before hot loops; the character metrics of a font must not change
    /// afterwards (call [`FontTable::invalidate_dense`] if they do).
    pub fn sync_dense(&mut self) {
        while self.dense.len() < self.fonts.len() {
            let f = &self.fonts[self.dense.len()];
            let mut metrics = vec![CharMetrics::default(); DENSE_CHARS].into_boxed_slice();
            let mut present = vec![0u64; DENSE_CHARS / 64].into_boxed_slice();
            for (&c, m) in &f.chars {
                if (c as usize) < DENSE_CHARS {
                    metrics[c as usize] = *m;
                    present[c as usize / 64] |= 1 << (c % 64);
                }
            }
            let mut lk = Vec::new();
            let mut steps: Vec<LigKernStep> = Vec::new();
            let mut pairs = Vec::new();
            if !f.lig_kern.is_empty() {
                lk = vec![(0u32, 0u32); 256];
                pairs = vec![0u16; 128 * 128];
                for (c, e) in lk.iter_mut().enumerate() {
                    if let Some(p) = f.lig_kern.get(&(c as u32)) {
                        *e = (steps.len() as u32, p.len() as u32);
                        for st in p.iter() {
                            if c < 128 && st.next < 128 && steps.len() < 0xFFFF {
                                pairs[c * 128 + st.next as usize] = steps.len() as u16 + 1;
                            }
                            steps.push(*st);
                        }
                    }
                }
            }
            self.dense.push(DenseMetrics {
                metrics,
                present,
                lk: lk.into_boxed_slice(),
                steps: steps.into_boxed_slice(),
                pairs: pairs.into_boxed_slice(),
            });
        }
    }

    /// Forgets the dense table of font `f` and those after it.
    pub fn invalidate_dense(&mut self, f: u32) {
        self.dense.truncate(f as usize);
    }

    /// The metrics of character `c` in font `f`.
    #[inline]
    pub fn char_metrics(&self, f: u32, c: u32) -> Option<&CharMetrics> {
        if let Some(d) = self.dense.get(f as usize)
            && (c as usize) < DENSE_CHARS
        {
            return if d.present[c as usize / 64] & (1 << (c % 64)) != 0 {
                Some(&d.metrics[c as usize])
            } else {
                None
            };
        }
        self.fonts.get(f as usize)?.chars.get(&c)
    }
}

impl std::fmt::Debug for FontTable {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("FontTable")
            .field("fonts", &self.fonts.len())
            .finish_non_exhaustive()
    }
}

/// The largest `\fontdimen` number retex accepts.
pub const MAX_FONT_DIMEN: i32 = 1 << 20;

impl Engine {
    /// The font info of font `f` (the null font if `f` is invalid).
    pub fn font(&self, f: u32) -> &FontInfo {
        self.fonts
            .fonts
            .get(f as usize)
            .unwrap_or(&self.fonts.fonts[0])
    }

    /// Whether font id `f` exists.
    pub fn font_exists(&self, f: i32) -> bool {
        f >= 0 && (f as usize) < self.fonts.fonts.len()
    }

    /// The identifier control sequence of font `f`.
    pub fn font_id_cs(&self, f: u32) -> CsId {
        self.fonts
            .id_cs
            .get(f as usize)
            .copied()
            .unwrap_or(self.cs.frozen_null_font)
    }

    /// `\fontdimen 6` (quad) of font `f`.
    pub fn quad(&self, f: u32) -> i32 {
        self.font(f).params.get(6).copied().unwrap_or(0)
    }

    /// `\fontdimen 5` (x-height) of font `f`.
    pub fn x_height(&self, f: u32) -> i32 {
        self.font(f).params.get(5).copied().unwrap_or(0)
    }

    /// Whether font `f` has character `c`.
    pub fn font_has_char(&self, f: u32, c: u32) -> bool {
        self.font(f).chars.contains_key(&c)
    }

    /// `\fontcharwd` etc.: `which` is 0 (wd), 1 (ht), 2 (dp), 3 (ic).
    pub fn font_char_dimen(&self, f: u32, c: u32, which: u32) -> i32 {
        match self.font(f).chars.get(&c) {
            Some(m) => match which {
                0 => m.width,
                1 => m.height,
                2 => m.depth,
                _ => m.italic,
            },
            None => 0,
        }
    }

    /// Prints a font name, with ` at …pt` if the size differs from the
    /// design size.
    pub fn print_font_name_and_size(&mut self, f: u32) {
        let (name, size, dsize) = {
            let fi = self.font(f);
            (fi.name.clone(), fi.size, fi.design_size)
        };
        self.printer.print_bytes(&name);
        if size != dsize {
            self.printer.print_str(" at ");
            self.printer.print_scaled(size);
            self.printer.print_str("pt");
        }
    }

    /// Scans a font identifier (`scan_font_ident`).
    pub fn scan_font_ident(&mut self) {
        self.get_nonblank_noncall();
        let f: i32 = match self.cur_cmd {
            Cmd::DefFont => self.eqtb.cur_font.val as i32,
            Cmd::SetFont => self.cur_chr as i32,
            Cmd::DefFamily => {
                let size = self.cur_chr;
                self.scan_math_family();
                let fam = self.cur_val as u32;
                self.eqtb.math_font[(size * crate::eqtb::NUM_FAMILIES as u32 + fam) as usize].val
                    as i32
            }
            _ => {
                self.print_err("Missing font identifier");
                self.help(&[
                    "I was looking for a control sequence whose",
                    "current meaning has been defined by \\font.",
                ]);
                self.back_error();
                0
            }
        };
        self.cur_val = f;
    }

    /// Finds a font dimension (`find_font_dimen`); returns its value and
    /// records its location in `font_dimen_loc` for assignments. Unlike
    /// TeX82, LuaTeX extends the parameters of any font (not only the most
    /// recently loaded one) when a parameter beyond the last is read or
    /// written; only `n <= 0` is an error. (LuaTeX dies on absurdly large
    /// `n`; retex reports those as errors too, above [`MAX_FONT_DIMEN`].)
    pub fn find_font_dimen(&mut self, _writing: bool) -> i32 {
        self.scan_int();
        let n = self.cur_val;
        self.scan_font_ident();
        let f = self.cur_val as usize;
        let ok = n > 0 && n <= MAX_FONT_DIMEN;
        if ok {
            let params = &mut self.fonts.fonts[f].params;
            if n as usize >= params.len() {
                params.resize(n as usize + 1, 0);
            }
        }
        if !ok {
            self.print_err("Font ");
            let cs = self.font_id_cs(f as u32);
            let name = self.hash.name(cs).to_vec();
            self.print_esc_bytes(&name);
            self.printer.print_str(" has only ");
            self.printer
                .print_int((self.fonts.fonts[f].params.len() as i64 - 1).max(0));
            self.printer.print_str(" fontdimen parameters");
            self.help(&[
                "To increase the number of font parameters, you must",
                "use \\fontdimen immediately after the \\font is loaded.",
            ]);
            self.error();
            self.font_dimen_loc = None;
            return 0;
        }
        self.font_dimen_loc = Some((f as u32, n as u32));
        self.fonts.fonts[f].params[n as usize]
    }

    /// Stores a `\fontdimen` value found by `find_font_dimen`.
    pub fn set_font_dimen(&mut self, loc: Option<(u32, u32)>, v: i32) {
        if let Some((f, n)) = loc {
            self.fonts.fonts[f as usize].params[n as usize] = v;
        }
    }

    /// `\hyphenchar`, `\skewchar`, `\ignoreligaturesinfont` values.
    pub fn font_int_param(&mut self, f: u32, n: u32) -> i32 {
        match n {
            0 => self.font(f).hyphen_char,
            1 => self.font(f).skew_char,
            2..=5 => {
                self.scan_char_num();
                let c = self.cur_val as u32;
                // \lpcode, \rpcode and \efcode of a character that the
                // font lacks are 0.
                if n < 5 && self.fonts.char_metrics(f, c).is_none() {
                    return 0;
                }
                self.font(f).char_codes[(n - 2) as usize]
                    .get(&c)
                    .copied()
                    .unwrap_or(if n == 4 { 1000 } else { 0 })
            }
            _ => self.font(f).ignore_ligatures,
        }
    }

    /// Sets `\hyphenchar`, `\skewchar`, `\ignoreligaturesinfont`.
    pub fn set_font_int_param(&mut self, f: u32, n: u32, v: i32) {
        if let Some(fi) = self.fonts.fonts.get_mut(f as usize) {
            match n {
                0 => fi.hyphen_char = v,
                1 => fi.skew_char = v,
                _ => fi.ignore_ligatures = v,
            }
        }
    }

    /// Sets `\lpcode`, `\rpcode`, `\efcode`, `\tagcode`. The first three
    /// are not set for characters that the font lacks.
    pub fn set_font_char_code(&mut self, f: u32, n: u32, c: u32, v: i32) {
        if n < 5 && self.fonts.char_metrics(f, c).is_none() {
            return;
        }
        if let Some(fi) = self.fonts.fonts.get_mut(f as usize) {
            fi.char_codes[(n - 2) as usize].insert(c, v);
        }
    }

    /// `\font\cs=name at size` (`new_font`).
    pub fn new_font(&mut self, global: bool) {
        if self.job_name.is_none() {
            self.open_log_file();
        }
        self.get_r_token();
        let u = self.cur_cs;
        self.define(
            global,
            Loc::Cs(u),
            Val::Meaning(Meaning::prim(Cmd::SetFont, 0)),
        );
        self.scan_optional_equals();
        let name = self.scan_file_name();
        // Scan the font size specification.
        self.files.name_in_progress = true;
        let size: i32 = if self.scan_keyword("at") {
            self.scan_normal_dimen();
            let s = self.cur_val;
            if s <= 0 || s >= 0o1000000000 {
                self.print_err("Improper `at' size (");
                self.printer.print_scaled(s);
                self.printer.print_str("pt), replaced by 10pt");
                self.help(&[
                    "I can only handle fonts at positive sizes that are",
                    "less than 2048pt, so I've changed what you said to 10pt.",
                ]);
                self.error();
                10 * retex_arith::UNITY
            } else {
                s
            }
        } else if self.scan_keyword("scaled") {
            self.scan_int();
            let s = -self.cur_val;
            if self.cur_val <= 0 || self.cur_val > 32768 {
                self.print_err("Illegal magnification has been changed to 1000");
                self.help(&["The magnification ratio must be between 1 and 32768."]);
                self.int_error(self.cur_val);
                -1000
            } else {
                s
            }
        } else {
            -1000
        };
        self.files.name_in_progress = false;
        // Reuse a font loaded with the same name and size request (LuaTeX
        // compares the requests: `at 10pt` does not reuse a font loaded at
        // its design size of 10pt).
        let existing = self
            .fonts
            .fonts
            .iter()
            .enumerate()
            .skip(1)
            .find(|(_, fi)| fi.name == name && fi.size_spec == size)
            .map(|(i, _)| i);
        let f = match existing {
            Some(i) => i as u32,
            None => match self.load_font(&name, size) {
                Some(f) => f,
                None => {
                    self.print_err("Font ");
                    self.sprint_cs(u);
                    self.printer.print_char('=' as u32);
                    self.printer.print_bytes(&name);
                    if size >= 0 {
                        self.printer.print_str(" at ");
                        self.printer.print_scaled(size);
                        self.printer.print_str("pt");
                    } else if size != -1000 {
                        self.printer.print_str(" scaled ");
                        self.printer.print_int(i64::from(-size));
                    }
                    self.printer
                        .print_str(" not loadable: Metric (TFM) file not found");
                    self.help(&[
                        "I wasn't able to read the size data for this font,",
                        "so I will ignore the font specification.",
                        "[Wizards can fix TFM files using TFtoPL/PLtoTF.]",
                        "You might try inserting a different font spec;",
                        "e.g., type `I\\font<same font id>=<substitute font name>'.",
                    ]);
                    self.error();
                    0
                }
            },
        };
        if f != 0 && self.fonts.fonts[f as usize].size_spec == i32::MIN {
            self.fonts.fonts[f as usize].size_spec = size;
        }
        // The identifier text is that of the control sequence used last,
        // also when the font existed already (TeX's `common_ending`).
        if f != 0 {
            let name = self.hash.name(u).to_vec();
            let id = self.hash.new_frozen(&name);
            self.eqtb.ensure_cs(id);
            self.eqtb.cs[id.0 as usize].val = Meaning::prim(Cmd::SetFont, f);
            self.fonts.id_cs[f as usize] = id;
        }
        self.define(
            global,
            Loc::Cs(u),
            Val::Meaning(Meaning::prim(Cmd::SetFont, f)),
        );
    }

    /// Loads a font through the `define_font` callback, or the built-in
    /// loader when no callback is set, and registers it.
    pub fn load_font(&mut self, name: &[u8], size: i32) -> Option<u32> {
        if let Some(h) = self.lua.clone()
            && h.has_callback("define_font")
        {
            return h.define_font(self, name, size);
        }
        let req = FontRequest {
            name: name.to_vec(),
            size,
        };
        if self.fonts.loader.is_none() {
            return self.load_tfm_font(name, size, name);
        }
        let mut loader = self.fonts.loader.take()?;
        let info = loader.load(&req);
        self.fonts.loader = Some(loader);
        let mut info = info?;
        info.hyphen_char = self.eqtb.int(pg::assign_int::DEFAULTHYPHENCHAR);
        info.skew_char = self.eqtb.int(pg::assign_int::DEFAULTSKEWCHAR);
        Some(self.register_font(info))
    }

    /// Adds a loaded font to the font table and returns its id.
    pub fn register_font(&mut self, mut info: FontInfo) -> u32 {
        if info.hyphen_char == i32::MIN {
            info.hyphen_char = self.eqtb.int(pg::assign_int::DEFAULTHYPHENCHAR);
        }
        if info.skew_char == i32::MIN {
            info.skew_char = self.eqtb.int(pg::assign_int::DEFAULTSKEWCHAR);
        }
        self.fonts.fonts.push(info);
        self.fonts.id_cs.push(self.cs.frozen_null_font);
        self.fonts.fonts.len() as u32 - 1
    }

    /// LuaTeX's built-in TFM loader (used when no `define_font` callback
    /// is set, e.g. while building the LaTeX format).
    pub fn load_tfm(&mut self, name: &[u8], size: i32) -> Option<FontInfo> {
        let name_s = String::from_utf8_lossy(name).into_owned();
        let path = self
            .kpse
            .as_ref()?
            .borrow_mut()
            .find_file(&name_s, retex_kpath::FileFormat::Tfm)?;
        let data = self.read_file_recorded(&path)?;
        let tfm = retex_font::tfm::Tfm::parse(&data).ok()?;
        let scaled = tfm.scaled(size);
        let mut params = vec![0; scaled.params.len() + 1];
        params[1..].copy_from_slice(&scaled.params);
        let mut chars =
            HashMap::with_capacity_and_hasher(scaled.chars.len(), crate::hash::FastHash::default());
        for (c, m) in &scaled.chars {
            chars.insert(
                u32::from(*c),
                CharMetrics {
                    width: m[0],
                    height: m[1],
                    depth: m[2],
                    italic: m[3],
                    index: u32::from(*c),
                },
            );
        }
        Some(FontInfo {
            name: name.to_vec(),
            size: scaled.size,
            design_size: tfm.design_size,
            checksum: tfm.checksum,
            params,
            chars,
            hyphen_char: i32::MIN,
            skew_char: i32::MIN,
            kind: FontKind::Tfm,
            handle: 0,
            char_codes: Default::default(),
            ignore_ligatures: 0,
            lig_kern: lig_kern_table(&tfm, &scaled.kerns),
            right_boundary: tfm.bchar.map(u32::from),
            math_constants: None,
            math_chars: None,
            size_spec: i32::MIN,
            data: Some(tfm_font_data(tfm, data)),
            expansion: None,
            vf: None,
        })
    }

    /// Loads TFM font `tfm_name` at `size` and registers it under the name
    /// `font_name` (what `\fontname` shows). If there is a virtual font of
    /// the same name, its local fonts are loaded too (observed in LuaTeX:
    /// right after the font, in definition order, reusing a loaded TFM font
    /// of the same name and size) and its packets are attached.
    pub fn load_tfm_font(&mut self, tfm_name: &[u8], size: i32, font_name: &[u8]) -> Option<u32> {
        self.load_tfm_font_at_depth(tfm_name, size, font_name, 0)
    }

    fn load_tfm_font_at_depth(
        &mut self,
        tfm_name: &[u8],
        size: i32,
        font_name: &[u8],
        depth: u32,
    ) -> Option<u32> {
        let mut info = self.load_tfm(tfm_name, size)?;
        info.name = font_name.to_vec();
        let size = info.size;
        let f = self.register_font(info);
        if depth < VF_MAX_DEPTH {
            self.attach_virtual_font(f, tfm_name, size, depth);
        }
        Some(f)
    }

    /// Reads the VF file `name` for font `f` (loaded at `size`), if there
    /// is one, and loads its local fonts.
    fn attach_virtual_font(&mut self, f: u32, name: &[u8], size: i32, depth: u32) {
        let name_s = String::from_utf8_lossy(name).into_owned();
        let Some(path) = self.kpse.as_ref().and_then(|k| {
            k.borrow_mut()
                .find_file(&name_s, retex_kpath::FileFormat::Vf)
        }) else {
            return;
        };
        let Some(data) = self.read_file_recorded(&path) else {
            return;
        };
        let Ok(vf) = retex_font::vf::Vf::parse(&data) else {
            return;
        };
        let mut fonts = Vec::with_capacity(vf.fonts.len());
        for (i, lf) in vf.fonts.iter().enumerate() {
            let lsize = vf.font_size(i, size);
            let lname = lf.name.as_bytes();
            let existing = (1..self.fonts.fonts.len()).find(|&g| {
                let fi = &self.fonts.fonts[g];
                fi.kind == FontKind::Tfm && fi.size == lsize && fi.name == lname
            });
            let id = match existing {
                Some(g) => g as u32,
                None => self
                    .load_tfm_font_at_depth(lname, lsize, lname, depth + 1)
                    .unwrap_or(0),
            };
            fonts.push(id);
        }
        let mut packets =
            HashMap::with_capacity_and_hasher(vf.packets.len(), crate::hash::FastHash::default());
        for &c in vf.packets.keys() {
            if let Some(cmds) = vf.commands(c, size) {
                packets.insert(c, cmds.into_boxed_slice());
            }
        }
        self.fonts.fonts[f as usize].vf = Some(std::rc::Rc::new(VirtualFont { fonts, packets }));
    }

    /// The lig/kern instruction of font `f` for the pair (`left`, `right`).
    #[inline]
    pub fn lig_kern_step(&self, f: u32, left: u32, right: u32) -> Option<LigOp> {
        if let Some(d) = self.fonts.dense.get(f as usize)
            && left < 256
        {
            if d.lk.is_empty() {
                return None;
            }
            if left < 128 && right < 128 {
                let i = d.pairs[(left * 128 + right) as usize];
                return if i == 0 {
                    None
                } else {
                    Some(d.steps[i as usize - 1].op)
                };
            }
            let (start, len) = d.lk[left as usize];
            return d.steps[start as usize..(start + len) as usize]
                .iter()
                .find(|s| s.next == right)
                .map(|s| s.op);
        }
        let fi = self.font(f);
        if fi.lig_kern.is_empty() {
            return None;
        }
        fi.lig_kern
            .get(&left)?
            .iter()
            .find(|s| s.next == right)
            .map(|s| s.op)
    }

    /// The OpenType math data of character `c` in font `f`, if any.
    pub fn math_char(&self, f: u32, c: u32) -> Option<&MathCharInfo> {
        self.font(f).math_chars.as_ref()?.get(&c)
    }

    /// The TFM data of font `f`, for TeX's ligature/kerning of TFM fonts.
    pub fn tfm_of(&self, f: u32) -> Option<std::rc::Rc<retex_font::tfm::Tfm>> {
        let d = self.font(f).data.as_ref()?;
        d.0.downcast_ref::<TfmData>().map(|t| t.tfm.clone())
    }

    /// `\letterspacefont` (LuaTeX).
    pub fn letterspace_font(&mut self, global: bool) {
        self.get_r_token();
        let u = self.cur_cs;
        self.scan_font_ident();
        let f = self.cur_val as u32;
        self.scan_int();
        let _amount = self.cur_val;
        // Letterspacing is not modelled yet: alias the font.
        self.define(
            global,
            Loc::Cs(u),
            Val::Meaning(Meaning::prim(Cmd::SetFont, f)),
        );
    }

    /// `\copyfont` (LuaTeX).
    pub fn copy_font(&mut self, global: bool) {
        self.get_r_token();
        let u = self.cur_cs;
        self.scan_font_ident();
        let f = self.cur_val as usize;
        let copy = self.fonts.fonts[f].clone();
        self.fonts.fonts.push(copy);
        self.fonts.id_cs.push(self.cs.frozen_null_font);
        let nf = self.fonts.fonts.len() as u32 - 1;
        self.define(
            global,
            Loc::Cs(u),
            Val::Meaning(Meaning::prim(Cmd::SetFont, nf)),
        );
    }
}

/// Converts a TFM lig/kern program into per-character steps (only the
/// first instruction for each right character counts, §545).
pub(crate) fn lig_kern_table(tfm: &retex_font::tfm::Tfm, kerns: &[i32]) -> LigKernMap {
    let nl = tfm.lig_kern.len();
    let read = |start: usize| -> Vec<LigKernStep> {
        let mut steps: Vec<LigKernStep> = Vec::new();
        let mut k = start;
        for _ in 0..nl {
            let Some(w) = tfm.lig_kern.get(k) else { break };
            if w.skip <= 128 {
                let next = u32::from(w.next);
                if !steps.iter().any(|s| s.next == next) {
                    let op = if w.op >= 128 {
                        let ki = 256 * (usize::from(w.op) - 128) + usize::from(w.rem);
                        LigOp::Kern(kerns.get(ki).copied().unwrap_or(0))
                    } else {
                        LigOp::Lig {
                            op: w.op,
                            chr: u32::from(w.rem),
                        }
                    };
                    steps.push(LigKernStep { next, op });
                }
            }
            if w.skip >= 128 {
                break;
            }
            k += usize::from(w.skip) + 1;
        }
        steps
    };
    let mut map = LigKernMap::default();
    for c in u32::from(tfm.bc)..=u32::from(tfm.ec) {
        if let Some(start) = tfm.lig_kern_start(c) {
            let p = read(start);
            if !p.is_empty() {
                map.insert(c, p.into_boxed_slice());
            }
        }
    }
    if let Some(l) = tfm.bchar_label {
        let p = read(l);
        if !p.is_empty() {
            map.insert(LEFT_BOUNDARY, p.into_boxed_slice());
        }
    }
    map
}