Skip to main content

docling_pdf/render/font/
mod.rs

1//! PDF fonts for the renderer: a font dictionary becomes a [`LoadedFont`]
2//! that splits strings into codes, gives each code its advance and its glyph
3//! outline in text space, or — for Type 3 — its glyph procedure.
4//!
5//! Glyph programs: TrueType / OpenType (`/FontFile2`, `/FontFile3 /OpenType`)
6//! and bare CFF (`/FontFile3 /Type1C`, `/CIDFontType0C`) through skrifa /
7//! read-fonts (#952 — fontations, the maintained successor of ttf-parser),
8//! Type 1 (`/FontFile`) through [`type1`]. Glyph selection follows ISO
9//! 32000-1 9.6.6 / 9.7.4: a simple font's code goes through `/Differences`,
10//! the base encoding or the program's built-in one to a glyph *name* (Type 1,
11//! CFF) or through the `cmap` subtables to a glyph *index* (TrueType — (3,0)
12//! symbol lookups with the `F0xx` convention, (1,0) by code, (3,1) by the
13//! name's Unicode, `post` names, and the bare code when the font has no
14//! `cmap`); a composite font's code goes through its CMap to a CID and
15//! `/CIDToGIDMap` or the CFF charset to a glyph. A font without a program is
16//! drawn with a host face chosen by [`fallback`].
17
18pub mod cmap;
19pub mod dotsection;
20pub mod encodings;
21pub mod fallback;
22pub mod type1;
23
24use std::cell::RefCell;
25use std::collections::HashMap;
26use std::rc::Rc;
27use std::sync::Arc;
28
29use lopdf::{Dictionary, Document, Object, ObjectId};
30use read_fonts::ps::cff::CffFontRef;
31use read_fonts::TableProvider as _;
32use skrifa::font::charmap::{Encoding, EncodingKind};
33use skrifa::font::glyph::outline::{DrawMemory, DrawOptions, OutlineSource, PathSink};
34use skrifa::font::Font;
35use skrifa::GlyphId;
36
37use super::geom::Mat;
38use super::objects::{
39    as_dict, as_stream, deref, get, get_dict, get_int, get_name, get_num, name, num, nums,
40};
41use cmap::CMap;
42
43/// A glyph outline in the program's own units with its advance.
44pub struct GlyphPath {
45    pub path: Option<tiny_skia::Path>,
46    pub advance: f64,
47}
48
49/// The program that draws the glyphs.
50enum Program {
51    /// TrueType / OpenType (glyf or CFF table).
52    Sfnt {
53        font: Font,
54        /// glyph units → text space: 1/unitsPerEm. For a CFF table that is
55        /// the em the FontMatrix was normalized into (read-fonts folds a
56        /// matrix that is not a plain 1/upem scale into the outline, as
57        /// FreeType does), so the one factor covers both.
58        matrix: Mat,
59        /// CID → glyph index for a CID-keyed CFF inside the sfnt.
60        cid_to_gid: Option<HashMap<u16, u16>>,
61        has_cmap: bool,
62        has_glyf: bool,
63        /// Glyph names of a CFF-flavoured sfnt, for name lookups.
64        names: HashMap<String, u16>,
65    },
66    /// A bare CFF program.
67    Cff {
68        font: Font,
69        matrix: Mat,
70        cid_to_gid: Option<HashMap<u16, u16>>,
71        /// glyph name → glyph index over the charset, built once (the
72        /// program's own lookup by name is a per-call scan).
73        names: HashMap<String, u16>,
74    },
75    Type1 {
76        font: type1::Type1Font,
77        matrix: Mat,
78    },
79    /// A host face standing in for a non-embedded font.
80    Fallback {
81        face: Arc<fallback::FallbackFace>,
82        matrix: Mat,
83    },
84    None,
85}
86
87/// Type 3 glyph procedures.
88pub struct Type3 {
89    pub font_matrix: Mat,
90    pub char_procs: HashMap<String, ObjectId>,
91    pub resources: Option<Dictionary>,
92}
93
94pub struct LoadedFont {
95    pub composite: bool,
96    pub type3: Option<Type3>,
97    program: Program,
98    /// Simple fonts: code → glyph name from `/Encoding` (`/Differences` over
99    /// the base encoding), when the PDF gives one.
100    encoding_names: HashMap<u8, String>,
101    /// The base encoding was named explicitly (`/WinAnsiEncoding`, …).
102    has_base_encoding: bool,
103    /// The font is symbolic (descriptor flag 3) and the PDF names no encoding.
104    symbolic: bool,
105    /// Composite fonts: string → codes → CIDs.
106    cmap: Option<CMap>,
107    cid_to_gid: CidToGid,
108    /// code (simple) or CID (composite) → advance in 1/1000 text space.
109    widths: HashMap<u32, f64>,
110    default_width: Option<f64>,
111    /// Type 3: `/Widths` are in glyph space (through `FontMatrix`).
112    /// `ToUnicode`, for a fallback face's cmap lookups.
113    to_unicode: HashMap<u32, String>,
114    /// CID → Unicode of the font's Adobe collection.
115    collection: Option<&'static [u8]>,
116    /// Standard-14 metrics for a non-embedded font without `/Widths`.
117    std14: Option<crate::std14::Std14Widths>,
118    /// Glyph cache: code/CID → outline in text space (font size 1).
119    cache: RefCell<HashMap<u32, Option<Rc<tiny_skia::Path>>>>,
120    advance_cache: RefCell<HashMap<u32, f64>>,
121    pub vertical: bool,
122    is_dingbats: bool,
123    is_symbol_face: bool,
124}
125
126enum CidToGid {
127    Identity,
128    Map(Vec<u8>),
129}
130
131fn descriptor<'a>(
132    doc: &'a Document,
133    fdict: &'a Dictionary,
134    composite: bool,
135) -> Option<&'a Dictionary> {
136    let owner = if composite {
137        descendant(doc, fdict)?
138    } else {
139        fdict
140    };
141    get_dict(doc, owner, b"FontDescriptor")
142}
143
144fn descendant<'a>(doc: &'a Document, fdict: &'a Dictionary) -> Option<&'a Dictionary> {
145    match get(doc, fdict, b"DescendantFonts")? {
146        Object::Array(a) => a.first().and_then(|o| as_dict(doc, o)),
147        Object::Dictionary(d) => Some(d),
148        _ => None,
149    }
150}
151
152fn base_font_name(doc: &Document, fdict: &Dictionary) -> String {
153    let raw = get_name(doc, fdict, b"BaseFont")
154        .map(|n| String::from_utf8_lossy(n).into_owned())
155        .unwrap_or_default();
156    // Strip an `ABCDEF+` subset prefix.
157    match raw.split_once('+') {
158        Some((pre, rest)) if pre.len() == 6 && pre.bytes().all(|b| b.is_ascii_uppercase()) => {
159            rest.to_string()
160        }
161        _ => raw,
162    }
163}
164
165impl LoadedFont {
166    pub fn load(doc: &Document, fdict: &Dictionary) -> LoadedFont {
167        let subtype = get_name(doc, fdict, b"Subtype").unwrap_or(b"");
168        let composite = subtype == b"Type0";
169        let base_font = base_font_name(doc, fdict);
170        let desc = descriptor(doc, fdict, composite);
171        let flags = desc.and_then(|d| get_int(doc, d, b"Flags"));
172        let symbolic_flag = flags.is_some_and(|f| f & 4 != 0 && f & 32 == 0);
173
174        // --- the embedded program -------------------------------------------
175        let mut program = Program::None;
176        if let Some(d) = desc {
177            if let Some(s) = d.get(b"FontFile2").ok().and_then(|o| as_stream(doc, o)) {
178                if let Ok(data) = s.decompressed_content() {
179                    program = sfnt_program(data).unwrap_or(Program::None);
180                }
181            }
182            if matches!(program, Program::None) {
183                if let Some(s) = d.get(b"FontFile3").ok().and_then(|o| as_stream(doc, o)) {
184                    if let Ok(data) = s.decompressed_content() {
185                        let st = get_name(doc, &s.dict, b"Subtype").unwrap_or(b"");
186                        program = if st == b"OpenType"
187                            || data.starts_with(b"OTTO")
188                            || data.starts_with(&[0, 1, 0, 0])
189                            || data.starts_with(b"true")
190                        {
191                            sfnt_program(data.clone())
192                                .or_else(|| cff_program(data))
193                                .unwrap_or(Program::None)
194                        } else {
195                            cff_program(data.clone())
196                                .or_else(|| sfnt_program(data))
197                                .unwrap_or(Program::None)
198                        };
199                    }
200                }
201            }
202            if matches!(program, Program::None) {
203                if let Some(s) = d.get(b"FontFile").ok().and_then(|o| as_stream(doc, o)) {
204                    if let Ok(data) = s.decompressed_content() {
205                        if let Some(f) = type1::Type1Font::parse(&data) {
206                            let m =
207                                Mat::from_slice(&f.font_matrix).unwrap_or(Mat::scale(0.001, 0.001));
208                            program = Program::Type1 { font: f, matrix: m };
209                        } else if let Some(p) =
210                            cff_program(data.clone()).or_else(|| sfnt_program(data))
211                        {
212                            // Mislabelled programs happen.
213                            program = p;
214                        }
215                    }
216                }
217            }
218        }
219
220        // --- Type 3 ----------------------------------------------------------
221        let type3 = if subtype == b"Type3" {
222            let fm = get(doc, fdict, b"FontMatrix")
223                .and_then(|o| nums(doc, o))
224                .and_then(|v| Mat::from_slice(&v))
225                .unwrap_or(Mat::scale(0.001, 0.001));
226            let mut char_procs = HashMap::new();
227            if let Some(cp) = get_dict(doc, fdict, b"CharProcs") {
228                for (k, v) in cp.iter() {
229                    if let Object::Reference(id) = v {
230                        char_procs.insert(String::from_utf8_lossy(k).into_owned(), *id);
231                    }
232                }
233            }
234            let resources = get_dict(doc, fdict, b"Resources").cloned();
235            Some(Type3 {
236                font_matrix: fm,
237                char_procs,
238                resources,
239            })
240        } else {
241            None
242        };
243
244        // --- encodings -----------------------------------------------------
245        let lower = base_font.to_ascii_lowercase();
246        let is_symbol_face = lower.starts_with("symbol");
247        let is_dingbats = lower.contains("dingbat");
248        let mut encoding_names: HashMap<u8, String> = HashMap::new();
249        let mut has_base_encoding = false;
250        let enc = get(doc, fdict, b"Encoding");
251        let mut cmap = None;
252        if composite {
253            cmap = Some(match enc {
254                Some(Object::Name(n)) => CMap::predefined(n),
255                Some(Object::Stream(s)) => {
256                    let mut c = s
257                        .decompressed_content()
258                        .ok()
259                        .map(|d| CMap::parse(&d))
260                        .unwrap_or_else(CMap::identity_h);
261                    if let Some(Object::Name(n)) = get(doc, &s.dict, b"UseCMap") {
262                        if n.starts_with(b"Identity") && !c.identity {
263                            // Codes not covered map to themselves.
264                        }
265                    }
266                    if get_int(doc, &s.dict, b"WMode") == Some(1) {
267                        c.vertical = true;
268                    }
269                    c
270                }
271                _ => CMap::identity_h(),
272            });
273        } else {
274            let base_table: Option<&'static [(u8, &'static str)]> = match enc {
275                Some(Object::Name(n)) => {
276                    has_base_encoding = true;
277                    encodings::by_name(n)
278                }
279                Some(Object::Dictionary(d)) => match get_name(doc, d, b"BaseEncoding") {
280                    Some(n) => {
281                        has_base_encoding = true;
282                        encodings::by_name(n)
283                    }
284                    None => None,
285                },
286                _ => None,
287            };
288            // The implicit base: Standard for non-symbolic fonts; the face's
289            // own encoding for Symbol/ZapfDingbats; nothing for other
290            // symbolic fonts (their program's built-in encoding applies).
291            let implicit: Option<&'static [(u8, &'static str)]> = if is_symbol_face
292                && matches!(program, Program::None)
293            {
294                Some(encodings::SYMBOL)
295            } else if is_dingbats && matches!(program, Program::None) {
296                Some(encodings::ZAPF_DINGBATS)
297            } else if !symbolic_flag || matches!(program, Program::None | Program::Fallback { .. })
298            {
299                Some(encodings::STANDARD)
300            } else {
301                None
302            };
303            if let Some(t) = base_table.or(implicit) {
304                for &(c, n) in t {
305                    encoding_names.insert(c, n.to_string());
306                }
307            }
308            if let Some(Object::Dictionary(d)) = enc {
309                if let Some(Object::Array(diffs)) = get(doc, d, b"Differences") {
310                    let mut code: i64 = 0;
311                    for el in diffs {
312                        match deref(doc, el) {
313                            Object::Integer(i) => code = *i,
314                            Object::Real(r) => code = *r as i64,
315                            Object::Name(n) => {
316                                if (0..=255).contains(&code) {
317                                    encoding_names.insert(
318                                        code as u8,
319                                        String::from_utf8_lossy(n).into_owned(),
320                                    );
321                                }
322                                code += 1;
323                            }
324                            _ => {}
325                        }
326                    }
327                }
328            }
329        }
330
331        // --- widths ----------------------------------------------------------
332        let mut widths = HashMap::new();
333        let mut default_width = None;
334        if composite {
335            if let Some(dd) = descendant(doc, fdict) {
336                default_width = Some(get_num(doc, dd, b"DW").unwrap_or(1000.0));
337                if let Some(Object::Array(w)) = get(doc, dd, b"W") {
338                    let mut i = 0;
339                    while i < w.len() {
340                        let c = w.get(i).map(|o| deref(doc, o)).and_then(num);
341                        match (c, w.get(i + 1).map(|o| deref(doc, o))) {
342                            (Some(c), Some(Object::Array(list))) => {
343                                for (k, wv) in list.iter().enumerate() {
344                                    if let Some(wv) = num(deref(doc, wv)) {
345                                        widths.insert(c as u32 + k as u32, wv);
346                                    }
347                                }
348                                i += 2;
349                            }
350                            (Some(c1), Some(o2)) => {
351                                if let (Some(c2), Some(wv)) =
352                                    (num(o2), w.get(i + 2).map(|o| deref(doc, o)).and_then(num))
353                                {
354                                    let (c1, c2) = (c1.max(0.0) as u32, c2.max(0.0) as u32);
355                                    if c2 >= c1 && c2 - c1 < 65536 {
356                                        for cid in c1..=c2 {
357                                            widths.insert(cid, wv);
358                                        }
359                                    }
360                                }
361                                i += 3;
362                            }
363                            _ => break,
364                        }
365                    }
366                }
367            }
368        } else {
369            let first = get_int(doc, fdict, b"FirstChar").unwrap_or(0);
370            if let Some(Object::Array(w)) = get(doc, fdict, b"Widths") {
371                for (k, wv) in w.iter().enumerate() {
372                    if let Some(wv) = num(deref(doc, wv)) {
373                        let code = first + k as i64;
374                        if (0..=255).contains(&code) {
375                            widths.insert(code as u32, wv);
376                        }
377                    }
378                }
379                if !w.is_empty() {
380                    default_width = Some(
381                        desc.and_then(|d| get_num(doc, d, b"MissingWidth"))
382                            .unwrap_or(0.0),
383                    );
384                }
385            }
386            if widths.is_empty() {
387                if let Some(mw) = desc.and_then(|d| get_num(doc, d, b"MissingWidth")) {
388                    if mw > 0.0 {
389                        default_width = Some(mw);
390                    }
391                }
392            }
393        }
394        let std14 = if widths.is_empty() && !composite && type3.is_none() {
395            crate::std14::widths_for(base_font.as_bytes())
396        } else {
397            None
398        };
399
400        // --- CID → GID -------------------------------------------------------
401        let mut cid_to_gid = CidToGid::Identity;
402        if composite {
403            if let Some(dd) = descendant(doc, fdict) {
404                if let Some(Object::Stream(s)) = get(doc, dd, b"CIDToGIDMap") {
405                    if let Ok(data) = s.decompressed_content() {
406                        cid_to_gid = CidToGid::Map(data);
407                    }
408                }
409            }
410        }
411
412        // --- fallback face ---------------------------------------------------
413        if matches!(program, Program::None) && type3.is_none() {
414            let ordering_cjk = composite
415                && descendant(doc, fdict)
416                    .and_then(|dd| get_dict(doc, dd, b"CIDSystemInfo"))
417                    .and_then(|si| get(doc, si, b"Ordering"))
418                    .and_then(|o| match o {
419                        Object::String(s, _) => Some(s.clone()),
420                        _ => None,
421                    })
422                    .is_some_and(|o| {
423                        matches!(
424                            o.as_slice(),
425                            b"Japan1" | b"GB1" | b"CNS1" | b"Korea1" | b"KR"
426                        )
427                    });
428            let mut style = fallback::style_for(&base_font, flags, None);
429            if ordering_cjk {
430                style.family = fallback::Family::Cjk;
431            }
432            if let Some(face) = fallback::face(style) {
433                let upem = Some(f64::from(face.font.units_per_em()))
434                    .filter(|u| *u > 0.0)
435                    .unwrap_or(1000.0);
436                program = Program::Fallback {
437                    face,
438                    matrix: Mat::scale(1.0 / upem, 1.0 / upem),
439                };
440            }
441        }
442
443        let to_unicode = get(doc, fdict, b"ToUnicode")
444            .and_then(|o| match o {
445                Object::Stream(s) => s.decompressed_content().ok(),
446                _ => None,
447            })
448            .map(|d| crate::tounicode::parse_tounicode(&d))
449            .unwrap_or_default();
450
451        let collection = cmap
452            .as_ref()
453            .filter(|c| c.identity)
454            .and_then(|_| crate::textparse::cid_collection(doc, fdict));
455
456        let vertical = cmap.as_ref().is_some_and(|c| c.vertical);
457        LoadedFont {
458            composite,
459            type3,
460            program,
461            encoding_names,
462            has_base_encoding,
463            symbolic: symbolic_flag && enc.is_none(),
464            cmap,
465            cid_to_gid,
466            widths,
467            default_width,
468            to_unicode,
469            collection,
470            std14,
471            cache: RefCell::new(HashMap::new()),
472            advance_cache: RefCell::new(HashMap::new()),
473            vertical,
474            is_dingbats,
475            is_symbol_face,
476        }
477    }
478
479    /// Split a string operand into `(code, cid, is_single_byte)`; `cid` is
480    /// the code itself for a simple font.
481    pub fn decode(&self, bytes: &[u8]) -> Vec<(u32, u32, bool)> {
482        match &self.cmap {
483            Some(c) => c
484                .split(bytes)
485                .into_iter()
486                .map(|(code, n)| (code, c.cid(code), n == 1))
487                .collect(),
488            None => bytes
489                .iter()
490                .map(|&b| (u32::from(b), u32::from(b), true))
491                .collect(),
492        }
493    }
494
495    /// The horizontal advance of `cid` (a code for simple fonts) in text
496    /// space (font size 1). Type 3 advances go through the font matrix.
497    pub fn advance(&self, code: u32, cid: u32) -> f64 {
498        let key = if self.composite { cid } else { code };
499        if let Some(a) = self.advance_cache.borrow().get(&key) {
500            return *a;
501        }
502        let a = self.advance_uncached(code, cid);
503        self.advance_cache.borrow_mut().insert(key, a);
504        a
505    }
506
507    fn advance_uncached(&self, code: u32, cid: u32) -> f64 {
508        let key = if self.composite { cid } else { code };
509        if let Some(t3) = &self.type3 {
510            let w = self.widths.get(&key).copied().unwrap_or(0.0);
511            let (ax, _) = t3.font_matrix.apply_vec(w, 0.0);
512            return ax;
513        }
514        if let Some(w) = self.widths.get(&key) {
515            return w / 1000.0;
516        }
517        if let Some(std) = &self.std14 {
518            if let Some(ch) = self.unicode_of(code, cid) {
519                if let Some(w) = std.width(ch) {
520                    return w / 1000.0;
521                }
522            }
523        }
524        if let Some(dw) = self.default_width {
525            if dw > 0.0 || !self.widths.is_empty() {
526                return dw / 1000.0;
527            }
528        }
529        // The program's own advance.
530        if let Some(adv) = self.program_advance(code, cid) {
531            return adv;
532        }
533        if self.default_width.is_some() {
534            return self.default_width.unwrap_or(0.0) / 1000.0;
535        }
536        0.5
537    }
538
539    fn unicode_of(&self, code: u32, cid: u32) -> Option<char> {
540        let key = if self.composite { cid } else { code };
541        if let Some(s) = self
542            .to_unicode
543            .get(&key)
544            .or_else(|| self.to_unicode.get(&code))
545        {
546            return s.chars().next();
547        }
548        if !self.composite {
549            if let Some(n) = self.encoding_names.get(&(code as u8)) {
550                return crate::textparse::glyph_name_to_char(n.as_bytes());
551            }
552            return char::from_u32(code).filter(|c| c.is_ascii_graphic() || *c == ' ');
553        }
554        if self.cmap.as_ref().is_some_and(|c| c.unicode_codes) {
555            return crate::textparse::unicode_cmap_char(code);
556        }
557        self.collection
558            .and_then(|t| crate::textparse::collection_text(t, cid))
559            .and_then(|s| s.chars().next())
560    }
561
562    /// A Type 3 font's procedure name for `code` (its `/Encoding /Differences`).
563    pub fn type3_glyph_name(&self, code: u32) -> Option<String> {
564        self.encoding_names.get(&(code as u8)).cloned()
565    }
566
567    /// The glyph name a simple font's code selects, if the PDF names one.
568    fn glyph_name(&self, code: u32) -> Option<&str> {
569        self.encoding_names.get(&(code as u8)).map(String::as_str)
570    }
571
572    /// The glyph outline for a code, in text space (font size 1), cached.
573    pub fn glyph(&self, code: u32, cid: u32) -> Option<Rc<tiny_skia::Path>> {
574        let key = if self.composite { cid } else { code };
575        if let Some(p) = self.cache.borrow().get(&key) {
576            return p.clone();
577        }
578        let built = self.build_glyph(code, cid).and_then(|g| {
579            let m = self.program_matrix();
580            g.path.and_then(|p| p.transform(m.to_ts())).map(Rc::new)
581        });
582        self.cache.borrow_mut().insert(key, built.clone());
583        built
584    }
585
586    fn program_matrix(&self) -> Mat {
587        match &self.program {
588            Program::Sfnt { matrix, .. }
589            | Program::Cff { matrix, .. }
590            | Program::Type1 { matrix, .. }
591            | Program::Fallback { matrix, .. } => *matrix,
592            Program::None => Mat::scale(0.001, 0.001),
593        }
594    }
595
596    /// Whether the embedded program paints anything for `code`:
597    /// `Some(false)` for a glyph it defines with an empty outline (a space
598    /// glyph), `None` without an embedded program (a substituted face
599    /// decides nothing) or when the glyph is not found. docling-parse 7.24
600    /// asks FreeType the same of a glyph with no Unicode mapping, to tell a
601    /// blank glyph (a word boundary) from a visible one (U+FFFD).
602    pub fn glyph_has_ink(&self, code: u32) -> Option<bool> {
603        if matches!(self.program, Program::None | Program::Fallback { .. }) {
604            return None;
605        }
606        let cid = self.cmap.as_ref().map_or(code, |c| c.cid(code));
607        let g = self.build_glyph(code, cid)?;
608        Some(g.path.is_some())
609    }
610
611    pub fn has_program(&self) -> bool {
612        !matches!(self.program, Program::None)
613    }
614
615    fn program_advance(&self, code: u32, cid: u32) -> Option<f64> {
616        let g = self.build_glyph(code, cid)?;
617        let (ax, _) = self.program_matrix().apply_vec(g.advance, 0.0);
618        Some(ax)
619    }
620
621    fn build_glyph(&self, code: u32, cid: u32) -> Option<GlyphPath> {
622        match &self.program {
623            Program::None => None,
624            Program::Type1 { font, .. } => {
625                let name = self.type1_glyph_name(font, code)?;
626                font.glyph(&name)
627            }
628            Program::Cff {
629                font,
630                cid_to_gid,
631                names,
632                ..
633            } => {
634                let gid = if self.composite {
635                    let gid = match &self.cid_to_gid {
636                        CidToGid::Map(m) => map_cid(m, cid),
637                        CidToGid::Identity => cid,
638                    };
639                    match cid_to_gid {
640                        Some(map) => gid16(*map.get(&(gid as u16))?),
641                        None => gid16(gid as u16),
642                    }
643                } else {
644                    self.cff_simple_gid(font, names, code)?
645                };
646                outline_glyph(font, gid)
647            }
648            Program::Sfnt {
649                font,
650                cid_to_gid,
651                has_cmap,
652                has_glyf,
653                names,
654                ..
655            } => {
656                let gid = if self.composite {
657                    let gid = match &self.cid_to_gid {
658                        CidToGid::Map(m) => map_cid(m, cid),
659                        CidToGid::Identity => cid,
660                    };
661                    match cid_to_gid {
662                        Some(map) => gid16(*map.get(&(gid as u16))?),
663                        None => gid16(gid as u16),
664                    }
665                } else {
666                    self.sfnt_simple_gid(font, names, code, *has_cmap, *has_glyf)?
667                };
668                outline_glyph(font, gid)
669            }
670            Program::Fallback { face, .. } => {
671                let gid = self.fallback_gid(&face.font, code, cid)?;
672                outline_glyph(&face.font, gid)
673            }
674        }
675    }
676
677    fn type1_glyph_name(&self, font: &type1::Type1Font, code: u32) -> Option<String> {
678        let c = code as u8;
679        // /Differences (or an explicit base encoding) first, then the
680        // program's built-in encoding, then Standard.
681        let pdf_name = self.glyph_name(code);
682        let builtin = font.encoding.get(&c).cloned();
683        let candidates: Vec<String> = if self.symbolic && !self.has_base_encoding {
684            // Symbolic without /Encoding: the built-in encoding rules, but a
685            // /Differences entry (already merged into encoding_names) wins.
686            [pdf_name.map(str::to_string), builtin.clone()]
687                .into_iter()
688                .flatten()
689                .collect()
690        } else {
691            [pdf_name.map(str::to_string), builtin.clone()]
692                .into_iter()
693                .flatten()
694                .collect()
695        };
696        for cand in &candidates {
697            if font.has_glyph(cand) {
698                return Some(cand.clone());
699            }
700            // `uniXXXX` / AGL name → the program's own name for that character.
701            if let Some(ch) = crate::textparse::glyph_name_to_char(cand.as_bytes()) {
702                if let Some(n) = self.type1_name_for_char(font, ch) {
703                    return Some(n);
704                }
705            }
706        }
707        if let Some(n) = encodings::lookup(encodings::STANDARD, c) {
708            if font.has_glyph(n) {
709                return Some(n.to_string());
710            }
711        }
712        if let Some(b) = builtin {
713            return Some(b);
714        }
715        None
716    }
717
718    fn type1_name_for_char(&self, font: &type1::Type1Font, ch: char) -> Option<String> {
719        // Reverse AGL over the font's names (small fonts, done rarely).
720        font.glyph_names()
721            .find(|n| crate::textparse::glyph_name_to_char(n.as_bytes()) == Some(ch))
722            .cloned()
723    }
724
725    fn cff_simple_gid(
726        &self,
727        font: &Font,
728        names: &HashMap<String, u16>,
729        code: u32,
730    ) -> Option<GlyphId> {
731        let c = code as u8;
732        let by_name = |n: &str| -> Option<GlyphId> {
733            names
734                .get(n)
735                .map(|g| gid16(*g))
736                .or_else(|| font.glyph_by_name(n))
737        };
738        if let Some(name) = self.glyph_name(code) {
739            if let Some(g) = by_name(name) {
740                return Some(g);
741            }
742            if let Some(ch) = crate::textparse::glyph_name_to_char(name.as_bytes()) {
743                // Another name for the same character (`uni0041` vs `A`).
744                if let Some(std_name) = agl_name(ch) {
745                    if let Some(g) = by_name(std_name) {
746                        return Some(g);
747                    }
748                }
749                let uni = format!("uni{:04X}", ch as u32);
750                if let Some(g) = by_name(&uni) {
751                    return Some(g);
752                }
753                if let Some(g) = names
754                    .iter()
755                    .find(|(n, _)| crate::textparse::glyph_name_to_char(n.as_bytes()) == Some(ch))
756                    .map(|(_, g)| gid16(*g))
757                {
758                    return Some(g);
759                }
760            }
761        }
762        // The program's built-in encoding.
763        if let Some(g) = cff_font(font)
764            .and_then(|cff| cff.encoding())
765            .and_then(|e| e.map(c))
766        {
767            if g.to_u32() != 0 {
768                return Some(g);
769            }
770        }
771        if let Some(n) = encodings::lookup(encodings::STANDARD, c) {
772            if let Some(g) = by_name(n) {
773                return Some(g);
774            }
775        }
776        None
777    }
778
779    fn sfnt_simple_gid(
780        &self,
781        font: &Font,
782        names: &HashMap<String, u16>,
783        code: u32,
784        has_cmap: bool,
785        has_glyf: bool,
786    ) -> Option<GlyphId> {
787        let c = code as u8;
788        // The cmap subtables, each addressable on its own — `map_code` reads
789        // the code as stored in that subtable (no symbol offset, no Mac Roman
790        // conversion) and treats a mapping to glyph 0 as none, which is what
791        // the three lookups below want.
792        let cm = font.charmap();
793        let subtables: Vec<Encoding> = cm.encodings().filter(|e| e.sfnt_ids().is_some()).collect();
794        let symbol_lookup = |code: u32| -> Option<GlyphId> {
795            subtables
796                .iter()
797                .filter(|e| e.sfnt_ids() == Some((3, 0)))
798                .find_map(|e| {
799                    [code, 0xF000 + code, 0xF100 + code, 0xF200 + code]
800                        .into_iter()
801                        .find_map(|probe| cm.map_code(*e, probe))
802                })
803        };
804        let mac_lookup = |code: u32| -> Option<GlyphId> {
805            subtables
806                .iter()
807                .filter(|e| e.sfnt_ids().is_some_and(|(p, _)| p == 1))
808                .find_map(|e| cm.map_code(*e, code))
809        };
810        let unicode_lookup = |ch: char| -> Option<GlyphId> {
811            subtables
812                .iter()
813                .filter(|e| e.kind() == EncodingKind::Unicode)
814                .find_map(|e| cm.map_code(*e, ch as u32))
815        };
816        let name = self.glyph_name(code);
817        let symbolic_path = self.symbolic || !self.has_base_encoding && name.is_none();
818        if symbolic_path {
819            if let Some(g) = symbol_lookup(code) {
820                return Some(g);
821            }
822            if let Some(g) = mac_lookup(code) {
823                return Some(g);
824            }
825        }
826        if let Some(n) = name {
827            if let Some(ch) = crate::textparse::glyph_name_to_char(n.as_bytes()) {
828                if let Some(g) = unicode_lookup(ch) {
829                    return Some(g);
830                }
831                if let Some(g) = symbol_lookup(ch as u32) {
832                    return Some(g);
833                }
834            }
835            if let Some(g) = names
836                .get(n)
837                .map(|g| gid16(*g))
838                .or_else(|| font.glyph_by_name(n))
839            {
840                if g.to_u32() != 0 {
841                    return Some(g);
842                }
843            }
844            // `gXX` / `glyphXX` / `index XX` names address glyphs directly.
845            if let Some(g) = gid_from_name(n) {
846                return Some(gid16(g));
847            }
848        }
849        if !symbolic_path {
850            if let Some(g) = symbol_lookup(code) {
851                return Some(g);
852            }
853            if let Some(g) = mac_lookup(code) {
854                return Some(g);
855            }
856        }
857        if let Some(std) = encodings::lookup(encodings::STANDARD, c) {
858            if let Some(ch) = crate::textparse::glyph_name_to_char(std.as_bytes()) {
859                if let Some(g) = unicode_lookup(ch) {
860                    return Some(g);
861                }
862            }
863        }
864        if !has_cmap || subtables.is_empty() {
865            // No usable cmap: the code is the glyph index.
866            let _ = has_glyf;
867            return Some(gid16(code as u16));
868        }
869        None
870    }
871
872    fn fallback_gid(&self, font: &Font, code: u32, cid: u32) -> Option<GlyphId> {
873        let cm = font.charmap();
874        // Symbol / Dingbats faces are addressed by glyph name.
875        if !self.composite && (self.is_symbol_face || self.is_dingbats) {
876            if let Some(n) = self.glyph_name(code) {
877                if let Some(g) = font.glyph_by_name(n) {
878                    return Some(g);
879                }
880            }
881        }
882        if !self.composite {
883            if let Some(n) = self.glyph_name(code) {
884                if let Some(ch) = crate::textparse::glyph_name_to_char(n.as_bytes()) {
885                    if let Some(g) = cm.map_unicode(ch) {
886                        return Some(g);
887                    }
888                }
889                if let Some(g) = font.glyph_by_name(n) {
890                    return Some(g);
891                }
892            }
893        }
894        let ch = self.unicode_of(code, cid)?;
895        cm.map_unicode(ch)
896    }
897}
898
899/// A 16-bit glyph index as the font model's identifier.
900fn gid16(g: u16) -> GlyphId {
901    GlyphId::new(u32::from(g))
902}
903
904/// The CFF program behind `font` — a bare CFF, or an OpenType `CFF ` table.
905fn cff_font(font: &Font) -> Option<&CffFontRef<'_>> {
906    font.outline_glyphs().cff_font()
907}
908
909fn map_cid(map: &[u8], cid: u32) -> u32 {
910    let i = cid as usize * 2;
911    match (map.get(i), map.get(i + 1)) {
912        (Some(hi), Some(lo)) => (u32::from(*hi) << 8) | u32::from(*lo),
913        _ => 0,
914    }
915}
916
917fn gid_from_name(n: &str) -> Option<u16> {
918    for prefix in ["glyph", "index", "cid", "g", "G"] {
919        if let Some(rest) = n.strip_prefix(prefix) {
920            if !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_digit()) {
921                return rest.parse().ok();
922            }
923        }
924    }
925    None
926}
927
928/// The Standard-encoding name of a character (the reverse of the AGL subset
929/// used here), for CFF fonts named by convention.
930fn agl_name(ch: char) -> Option<&'static str> {
931    encodings::STANDARD
932        .iter()
933        .chain(encodings::WIN_ANSI.iter())
934        .find(|(_, n)| crate::textparse::glyph_name_to_char(n.as_bytes()) == Some(ch))
935        .map(|(_, n)| *n)
936}
937
938struct Builder(tiny_skia::PathBuilder);
939
940impl PathSink for Builder {
941    fn move_to(&mut self, x: f32, y: f32) {
942        self.0.move_to(x, y);
943    }
944    fn line_to(&mut self, x: f32, y: f32) {
945        self.0.line_to(x, y);
946    }
947    fn quad_to(&mut self, x1: f32, y1: f32, x: f32, y: f32) {
948        self.0.quad_to(x1, y1, x, y);
949    }
950    fn curve_to(&mut self, x1: f32, y1: f32, x2: f32, y2: f32, x: f32, y: f32) {
951        self.0.cubic_to(x1, y1, x2, y2, x, y);
952    }
953    fn close(&mut self) {
954        self.0.close();
955    }
956}
957
958/// The outline of `gid` in font units with its advance: `hmtx`'s where the
959/// program has one, the charstring's for a bare CFF. `None` for a glyph index
960/// the program does not have; a glyph that fails part-way through keeps what
961/// it drew, as the renderer always did.
962fn outline_glyph(font: &Font, gid: GlyphId) -> Option<GlyphPath> {
963    if gid.to_u32() >= font.num_glyphs() {
964        return None;
965    }
966    let mut b = Builder(tiny_skia::PathBuilder::new());
967    let mut dx = 0.0f32;
968    if let Some(glyph) = font.outline_glyphs().get(gid) {
969        let _ = glyph.draw(&DrawOptions::new(), DrawMemory::Scratch, &mut b);
970        if glyph.source() == OutlineSource::Glyf {
971            dx = glyf_lsb_shift(font, gid);
972        }
973    }
974    let path = b.0.finish().and_then(|p| {
975        if dx == 0.0 {
976            Some(p)
977        } else {
978            p.transform(tiny_skia::Transform::from_translate(dx, 0.0))
979        }
980    });
981    let advance = f64::from(font.glyph_metrics().h_advance(gid));
982    Some(GlyphPath { path, advance })
983}
984
985/// How far read-fonts moved a `glyf` outline from its stored coordinates:
986/// like FreeType, it translates every TrueType glyph so that its xMin lands
987/// on `hmtx`'s left side bearing (the first phantom point, `lsb − xMin`).
988/// A well-formed font (`head` flag 1) keeps the two equal and the shift is
989/// zero; the subsetted fonts PDF producers embed often do not — a bold
990/// Helvetica subset in the corpus has its hyphen 50 units apart — and the
991/// stored coordinates are what ttf-parser drew, what docling-parse draws,
992/// and so what the renders are measured against. The shift is undone.
993fn glyf_lsb_shift(font: &Font, gid: GlyphId) -> f32 {
994    let tables = font.tables();
995    let (Ok(glyf), Ok(loca), Ok(hmtx)) = (tables.glyf(), tables.loca(None), tables.hmtx()) else {
996        return 0.0;
997    };
998    let Some(lsb) = hmtx.side_bearing(gid) else {
999        return 0.0;
1000    };
1001    // An empty glyph (no outline data) is placed at xMin = 0, as FreeType does.
1002    let x_min = loca
1003        .get_glyf(gid, &glyf)
1004        .ok()
1005        .flatten()
1006        .map(|g| g.x_min())
1007        .unwrap_or(0);
1008    f32::from(x_min) - f32::from(lsb)
1009}
1010
1011/// glyph units → text space for a program: 1/unitsPerEm. For a CFF program
1012/// the em is the one read-fonts normalized the FontMatrix into (a matrix
1013/// that is not a plain scale is applied to the outline itself), so the plain
1014/// factor is exact for both; a degenerate em falls back to 1/1000.
1015fn em_matrix(font: &Font) -> Mat {
1016    let upem = f64::from(font.units_per_em());
1017    if upem.is_finite() && upem > 0.0 {
1018        Mat::scale(1.0 / upem, 1.0 / upem)
1019    } else {
1020        Mat::scale(0.001, 0.001)
1021    }
1022}
1023
1024fn sfnt_program(mut data: Vec<u8>) -> Option<Program> {
1025    dotsection::strip_sfnt(&mut data);
1026    let font = Font::new(data, 0)?;
1027    if !matches!(font.kind(), skrifa::font::Kind::Sfnt(..)) {
1028        return None;
1029    }
1030    let outlines = font.outline_glyphs();
1031    let has_glyf = outlines.source() == Some(OutlineSource::Glyf);
1032    let has_cmap = font.charmap().encodings().any(|e| e.sfnt_ids().is_some());
1033    let (cid_to_gid, names) = match outlines.cff_font() {
1034        Some(cff) if !has_glyf => (cid_map(cff), cff_names(cff)),
1035        _ => (None, HashMap::new()),
1036    };
1037    let matrix = em_matrix(&font);
1038    Some(Program::Sfnt {
1039        font,
1040        matrix,
1041        cid_to_gid,
1042        has_cmap,
1043        has_glyf,
1044        names,
1045    })
1046}
1047
1048fn cff_program(mut data: Vec<u8>) -> Option<Program> {
1049    dotsection::strip(&mut data);
1050    let font = Font::new(data, 0)?;
1051    if !matches!(font.kind(), skrifa::font::Kind::Cff(..)) {
1052        return None;
1053    }
1054    let (cid_to_gid, names) = match cff_font(&font) {
1055        Some(cff) => (cid_map(cff), cff_names(cff)),
1056        None => (None, HashMap::new()),
1057    };
1058    let matrix = em_matrix(&font);
1059    Some(Program::Cff {
1060        font,
1061        matrix,
1062        cid_to_gid,
1063        names,
1064    })
1065}
1066
1067/// glyph name → glyph index over the whole charset (name-keyed fonts only).
1068fn cff_names(cff: &CffFontRef<'_>) -> HashMap<String, u16> {
1069    let mut map = HashMap::new();
1070    if cff.is_cid() {
1071        return map;
1072    }
1073    let Some(charset) = cff.charset() else {
1074        return map;
1075    };
1076    for g in 0..cff.num_glyphs().min(u32::from(u16::MAX)) {
1077        let Some(sid) = charset.string_id(GlyphId::new(g)) else {
1078            continue;
1079        };
1080        if let Some(n) = cff.string(sid) {
1081            map.entry(String::from_utf8_lossy(n).into_owned())
1082                .or_insert(g as u16);
1083        }
1084    }
1085    map
1086}
1087
1088/// CID → GID for a CID-keyed CFF (`None` for a name-keyed one): the charset
1089/// of a CID-keyed font maps each glyph to its CID.
1090fn cid_map(cff: &CffFontRef<'_>) -> Option<HashMap<u16, u16>> {
1091    if !cff.is_cid() {
1092        return None;
1093    }
1094    let charset = cff.charset()?;
1095    let n = cff.num_glyphs().min(u32::from(u16::MAX));
1096    let mut map = HashMap::with_capacity(n as usize);
1097    for g in 0..n {
1098        if let Some(cid) = charset.string_id(GlyphId::new(g)) {
1099            map.entry(cid.to_u16()).or_insert(g as u16);
1100        }
1101    }
1102    Some(map)
1103}
1104
1105/// A per-document font cache keyed by the font dictionary's object id.
1106#[derive(Default)]
1107pub struct FontCache {
1108    by_id: HashMap<ObjectId, Rc<LoadedFont>>,
1109    /// Direct (unreferenced) font dictionaries, keyed by their debug print.
1110    by_repr: HashMap<String, Rc<LoadedFont>>,
1111}
1112
1113impl FontCache {
1114    pub fn get(&mut self, doc: &Document, obj: &Object) -> Option<Rc<LoadedFont>> {
1115        match obj {
1116            Object::Reference(id) => {
1117                if let Some(f) = self.by_id.get(id) {
1118                    return Some(f.clone());
1119                }
1120                let d = as_dict(doc, obj)?;
1121                let f = Rc::new(LoadedFont::load(doc, d));
1122                self.by_id.insert(*id, f.clone());
1123                Some(f)
1124            }
1125            Object::Dictionary(d) => {
1126                let key = format!("{d:?}");
1127                if let Some(f) = self.by_repr.get(&key) {
1128                    return Some(f.clone());
1129                }
1130                let f = Rc::new(LoadedFont::load(doc, d));
1131                self.by_repr.insert(key, f.clone());
1132                Some(f)
1133            }
1134            _ => None,
1135        }
1136    }
1137}
1138
1139#[allow(dead_code)]
1140fn _unused(_: &Dictionary) -> Option<&[u8]> {
1141    None.and_then(name)
1142}
1143
1144#[cfg(test)]
1145mod tests {
1146    use super::LoadedFont;
1147    use lopdf::{dictionary, Document, Object};
1148
1149    #[test]
1150    #[cfg(feature = "cid-collections")]
1151    fn collection_cids_have_a_character() {
1152        let type0 = dictionary! {
1153            "Type" => "Font",
1154            "Subtype" => "Type0",
1155            "BaseFont" => "Test-Font-Light",
1156            "Encoding" => "Identity-H",
1157            "DescendantFonts" => vec![Object::Dictionary(dictionary! {
1158                "Type" => "Font",
1159                "Subtype" => "CIDFontType0",
1160                "BaseFont" => "Test-Font-Light",
1161                "CIDSystemInfo" => dictionary! {
1162                    "Registry" => Object::string_literal("Adobe"),
1163                    "Ordering" => Object::string_literal("Japan1"),
1164                    "Supplement" => 2,
1165                },
1166            })],
1167        };
1168        let font = LoadedFont::load(&Document::with_version("1.4"), &type0);
1169        assert_eq!(font.unicode_of(0x0CD4, 0x0CD4), Some('日'));
1170        assert_eq!(font.unicode_of(0x4507, 0x4507), Some('𢭏'));
1171    }
1172
1173    #[test]
1174    fn utf16_codes_have_a_character_and_one_advance() {
1175        let type0 = dictionary! {
1176            "Type" => "Font",
1177            "Subtype" => "Type0",
1178            "Encoding" => "UniJIS-UTF16-H",
1179            "DescendantFonts" => vec![Object::Dictionary(dictionary! {
1180                "Subtype" => "CIDFontType0",
1181                "DW" => 1000,
1182            })],
1183        };
1184        let font = LoadedFont::load(&Document::with_version("1.4"), &type0);
1185        let codes = font.decode(&[0x65, 0xe5, 0xd8, 0x42, 0xdf, 0xb7, 0x8a, 0x9e]);
1186        assert_eq!(
1187            codes,
1188            vec![
1189                (0x65e5, 0x65e5, false),
1190                (0xd842dfb7, 0xd842dfb7, false),
1191                (0x8a9e, 0x8a9e, false)
1192            ]
1193        );
1194        assert_eq!(font.unicode_of(0xd842dfb7, 0xd842dfb7), Some('𠮷'));
1195        assert_eq!(font.advance(0xd842dfb7, 0xd842dfb7), 1.0);
1196    }
1197}