skrifa/
charmap.rs

1//! Mapping of characters (codepoints, not graphemes) to nominal glyph identifiers.
2//!
3//! If you have never run into character to glyph mapping before
4//! [Glyph IDs and the 'cmap' table](https://rsheeter.github.io/font101/#glyph-ids-and-the-cmap-table)
5//! might be informative.
6//!
7//! The functionality in this module provides a 1-to-1 mapping from Unicode
8//! characters (or [Unicode variation sequences](http://unicode.org/faq/vs.html)) to
9//! nominal or "default" internal glyph identifiers for a given font.
10//! This is a necessary first step, but generally insufficient for proper layout of
11//! [complex text](https://en.wikipedia.org/wiki/Complex_text_layout) or even
12//! simple text containing diacritics and ligatures.
13//!
14//! Comprehensive mapping of characters to positioned glyphs requires a process called
15//! shaping. For more detail, see: [Why do I need a shaping engine?](https://harfbuzz.github.io/why-do-i-need-a-shaping-engine.html)
16
17use read_fonts::{
18    tables::cmap::{
19        self, Cmap, Cmap12, Cmap12Iter, Cmap13, Cmap13Iter, Cmap14, Cmap14Iter, Cmap4, Cmap4Iter,
20        CmapIterLimits, CmapSubtable, EncodingRecord, PlatformId,
21    },
22    types::GlyphId,
23    FontData, FontRef, TableProvider,
24};
25
26pub use read_fonts::tables::cmap::MapVariant;
27
28/// Mapping of characters to nominal glyph identifiers.
29///
30/// The mappings are derived from the [cmap](https://learn.microsoft.com/en-us/typography/opentype/spec/cmap)
31/// table. Depending on the font, the returned mapping may have entries that point to virtual/phantom glyph
32/// ids beyond the `num_glyphs` entry of the `maxp` table, which are only used during the shaping process,
33/// for example.
34///
35/// ## Obtaining a Charmap
36///
37/// Typically a Charmap is acquired by calling [charmap](crate::MetadataProvider::charmap) on a [FontRef].
38///
39/// ## Selection strategy
40///
41/// Fonts may contain multiple subtables in various formats supporting different encodings. The selection
42/// strategy implemented here is designed to choose mappings that capture the broadest available Unicode
43/// coverage:
44///
45/// * Unicode characters: a symbol mapping subtable is selected if available. Otherwise, subtables supporting
46///   the Unicode full repertoire or Basic Multilingual Plane (BMP) are preferred, in that order. Formats
47///   [4](https://learn.microsoft.com/en-us/typography/opentype/spec/cmap#format-4-segment-mapping-to-delta-values)
48///   and [12](https://learn.microsoft.com/en-us/typography/opentype/spec/cmap#format-12-segmented-coverage) are
49///   supported.
50///
51/// * Unicode variation sequences: these are provided by a format
52///   [14](https://learn.microsoft.com/en-us/typography/opentype/spec/cmap#format-14-unicode-variation-sequences)
53///   subtable.
54///
55#[derive(Clone, Default)]
56pub struct Charmap<'a> {
57    codepoint_subtable: Option<CodepointSubtable<'a>>,
58    variant_subtable: Option<Cmap14<'a>>,
59    cmap_limits: CmapIterLimits,
60}
61
62impl<'a> Charmap<'a> {
63    /// Creates a new character map from the given font.
64    pub fn new(font: &FontRef<'a>) -> Self {
65        let Ok(cmap) = font.cmap() else {
66            return Default::default();
67        };
68        let selection = MappingSelection::new(font, &cmap);
69        Self {
70            codepoint_subtable: selection
71                .codepoint_subtable
72                .map(|subtable| CodepointSubtable {
73                    subtable,
74                    is_symbol: selection.mapping_index.codepoint_subtable_is_symbol,
75                }),
76            variant_subtable: selection.variant_subtable,
77            cmap_limits: selection.mapping_index.cmap_limits,
78        }
79    }
80
81    /// Returns true if a suitable Unicode character mapping is available.
82    pub fn has_map(&self) -> bool {
83        self.codepoint_subtable.is_some()
84    }
85
86    /// Returns true if a symbol mapping was selected.
87    pub fn is_symbol(&self) -> bool {
88        self.codepoint_subtable
89            .as_ref()
90            .map(|x| x.is_symbol)
91            .unwrap_or(false)
92    }
93
94    /// Returns true if a Unicode variation sequence mapping is available.
95    pub fn has_variant_map(&self) -> bool {
96        self.variant_subtable.is_some()
97    }
98
99    /// Maps a character to a nominal glyph identifier.
100    ///
101    /// Returns `None` if a mapping does not exist.
102    pub fn map(&self, ch: impl Into<u32>) -> Option<GlyphId> {
103        self.codepoint_subtable.as_ref()?.map(ch.into())
104    }
105
106    /// Returns an iterator over all mappings of codepoint to nominal glyph
107    /// identifiers in the character map.
108    pub fn mappings(&self) -> Mappings<'a> {
109        self.codepoint_subtable
110            .as_ref()
111            .map(|subtable| {
112                Mappings(match &subtable.subtable {
113                    SupportedSubtable::Format4(cmap4) => MappingsInner::Format4(cmap4.iter()),
114                    SupportedSubtable::Format12(cmap12) => {
115                        MappingsInner::Format12(cmap12.iter_with_limits(self.cmap_limits))
116                    }
117                    SupportedSubtable::Format13(cmap13) => {
118                        MappingsInner::Format13(cmap13.iter_with_limits(self.cmap_limits))
119                    }
120                })
121            })
122            .unwrap_or(Mappings(MappingsInner::None))
123    }
124
125    /// Maps a character and variation selector to a nominal glyph identifier.
126    ///
127    /// Returns `None` if a mapping does not exist.
128    pub fn map_variant(&self, ch: impl Into<u32>, selector: impl Into<u32>) -> Option<MapVariant> {
129        self.variant_subtable.as_ref()?.map_variant(ch, selector)
130    }
131
132    /// Returns an iterator over all mappings of character and variation
133    /// selector to nominal glyph identifier in the character map.
134    pub fn variant_mappings(&self) -> VariantMappings<'a> {
135        VariantMappings(
136            self.variant_subtable
137                .clone()
138                .map(|cmap14| cmap14.iter_with_limits(self.cmap_limits)),
139        )
140    }
141}
142
143/// Cacheable indices of selected mapping tables for materializing a character
144/// map.
145///
146/// Since [`Charmap`] carries a lifetime, it is difficult to store in a cache.
147/// This type serves as an acceleration structure that allows for construction
148/// of a character map while skipping the search for the most suitable Unicode
149/// mappings.
150#[derive(Copy, Clone, Default, Debug)]
151pub struct MappingIndex {
152    /// Index of Unicode or symbol mapping subtable.
153    codepoint_subtable: Option<u16>,
154    /// True if the above is a symbol mapping.
155    codepoint_subtable_is_symbol: bool,
156    /// Index of Unicode variation selector subtable.
157    variant_subtable: Option<u16>,
158    /// Limits for iterating a cmap format 12 subtable.
159    cmap_limits: CmapIterLimits,
160}
161
162impl MappingIndex {
163    /// Finds the indices of the most suitable Unicode mapping tables in the
164    /// given font.
165    pub fn new(font: &FontRef) -> Self {
166        let Ok(cmap) = font.cmap() else {
167            return Default::default();
168        };
169        MappingSelection::new(font, &cmap).mapping_index
170    }
171
172    /// Creates a new character map for the given font using the tables referenced by
173    /// the precomputed indices.
174    ///
175    /// The font should be the same as the one used to construct this object.
176    pub fn charmap<'a>(&self, font: &FontRef<'a>) -> Charmap<'a> {
177        let Ok(cmap) = font.cmap() else {
178            return Default::default();
179        };
180        let records = cmap.encoding_records();
181        let data = cmap.offset_data();
182        Charmap {
183            codepoint_subtable: self
184                .codepoint_subtable
185                .and_then(|index| get_subtable(data, records, index))
186                .and_then(SupportedSubtable::new)
187                .map(|subtable| CodepointSubtable {
188                    subtable,
189                    is_symbol: self.codepoint_subtable_is_symbol,
190                }),
191            variant_subtable: self
192                .variant_subtable
193                .and_then(|index| get_subtable(data, records, index))
194                .and_then(|subtable| match subtable {
195                    CmapSubtable::Format14(cmap14) => Some(cmap14),
196                    _ => None,
197                }),
198            cmap_limits: self.cmap_limits,
199        }
200    }
201}
202
203/// Iterator over all mappings of character to nominal glyph identifier
204/// in a character map.
205///
206/// This is created with the [`Charmap::mappings`] method.
207#[derive(Clone)]
208pub struct Mappings<'a>(MappingsInner<'a>);
209
210impl Iterator for Mappings<'_> {
211    type Item = (u32, GlyphId);
212
213    fn next(&mut self) -> Option<Self::Item> {
214        loop {
215            let item = match &mut self.0 {
216                MappingsInner::None => None,
217                MappingsInner::Format4(iter) => iter.next(),
218                MappingsInner::Format12(iter) => iter.next(),
219                MappingsInner::Format13(iter) => iter.next(),
220            }?;
221            if item.1 != GlyphId::NOTDEF {
222                return Some(item);
223            }
224        }
225    }
226}
227
228#[derive(Clone)]
229enum MappingsInner<'a> {
230    None,
231    Format4(Cmap4Iter<'a>),
232    Format12(Cmap12Iter<'a>),
233    Format13(Cmap13Iter<'a>),
234}
235
236/// Iterator over all mappings of character and variation selector to
237/// nominal glyph identifier in a character map.
238///
239/// This is created with the [`Charmap::variant_mappings`] method.
240#[derive(Clone)]
241pub struct VariantMappings<'a>(Option<Cmap14Iter<'a>>);
242
243impl Iterator for VariantMappings<'_> {
244    type Item = (u32, u32, MapVariant);
245
246    fn next(&mut self) -> Option<Self::Item> {
247        self.0.as_mut()?.next()
248    }
249}
250
251fn get_subtable<'a>(
252    data: FontData<'a>,
253    records: &[EncodingRecord],
254    index: u16,
255) -> Option<CmapSubtable<'a>> {
256    records
257        .get(index as usize)
258        .and_then(|record| record.subtable(data).ok())
259}
260
261#[derive(Clone)]
262struct CodepointSubtable<'a> {
263    subtable: SupportedSubtable<'a>,
264    /// True if the subtable is a symbol mapping.
265    is_symbol: bool,
266}
267
268impl CodepointSubtable<'_> {
269    fn map(&self, codepoint: u32) -> Option<GlyphId> {
270        self.map_impl(codepoint).or_else(|| {
271            if self.is_symbol && codepoint <= 0x00FF {
272                // From HarfBuzz:
273                // For symbol-encoded OpenType fonts, we duplicate the
274                // U+F000..F0FF range at U+0000..U+00FF.  That's what
275                // Windows seems to do, and that's hinted about at:
276                // https://docs.microsoft.com/en-us/typography/opentype/spec/recom
277                // under "Non-Standard (Symbol) Fonts".
278                // See <https://github.com/harfbuzz/harfbuzz/blob/453ded05392af38bba9f89587edce465e86ffa6b/src/hb-ot-cmap-table.hh#L1595>
279                self.map_impl(codepoint + 0xF000)
280            } else {
281                None
282            }
283        })
284    }
285
286    fn map_impl(&self, codepoint: u32) -> Option<GlyphId> {
287        let gid = match &self.subtable {
288            SupportedSubtable::Format4(subtable) => subtable.map_codepoint(codepoint),
289            SupportedSubtable::Format12(subtable) => subtable.map_codepoint(codepoint),
290            SupportedSubtable::Format13(subtable) => subtable.map_codepoint(codepoint),
291        }?;
292        (gid != GlyphId::NOTDEF).then_some(gid)
293    }
294}
295
296#[derive(Clone)]
297enum SupportedSubtable<'a> {
298    Format4(Cmap4<'a>),
299    Format12(Cmap12<'a>),
300    Format13(Cmap13<'a>),
301}
302
303impl<'a> SupportedSubtable<'a> {
304    fn new(subtable: CmapSubtable<'a>) -> Option<Self> {
305        Some(match subtable {
306            CmapSubtable::Format4(cmap4) => Self::Format4(cmap4),
307            CmapSubtable::Format12(cmap12) => Self::Format12(cmap12),
308            CmapSubtable::Format13(cmap13) => Self::Format13(cmap13),
309            _ => return None,
310        })
311    }
312
313    fn from_cmap_record(cmap: &Cmap<'a>, record: &cmap::EncodingRecord) -> Option<Self> {
314        Self::new(record.subtable(cmap.offset_data()).ok()?)
315    }
316}
317
318/// The mapping kind of a cmap subtable.
319///
320/// The ordering is significant and determines the priority of subtable
321/// selection (greater is better).
322#[derive(Copy, Clone, PartialEq, PartialOrd)]
323enum MappingKind {
324    None = 0,
325    UnicodeBmp = 1,
326    UnicodeFull = 2,
327    Symbol = 3,
328}
329
330/// The result of searching the cmap table for the "best" available
331/// subtables.
332///
333/// For `codepoint_subtable`, best means either symbol (which is preferred)
334/// or a Unicode subtable with the greatest coverage.
335///
336/// For `variant_subtable`, best means a format 14 subtable.
337struct MappingSelection<'a> {
338    /// The mapping index accelerator that holds indices of the following
339    /// subtables.
340    mapping_index: MappingIndex,
341    /// Either a symbol subtable or the Unicode subtable with the
342    /// greatest coverage.
343    codepoint_subtable: Option<SupportedSubtable<'a>>,
344    /// Subtable that supports mapping Unicode variation sequences.
345    variant_subtable: Option<Cmap14<'a>>,
346}
347
348impl<'a> MappingSelection<'a> {
349    fn new(font: &FontRef<'a>, cmap: &Cmap<'a>) -> Self {
350        const ENCODING_MS_SYMBOL: u16 = 0;
351        const ENCODING_MS_UNICODE_CS: u16 = 1;
352        const ENCODING_APPLE_ID_UNICODE_32: u16 = 4;
353        const ENCODING_APPLE_ID_VARIANT_SELECTOR: u16 = 5;
354        const ENCODING_MS_ID_UCS_4: u16 = 10;
355        let mut mapping_index = MappingIndex::default();
356        let mut mapping_kind = MappingKind::None;
357        let mut codepoint_subtable = None;
358        let mut variant_subtable = None;
359        let mut maybe_choose_subtable = |kind, index, subtable| {
360            if kind > mapping_kind {
361                mapping_kind = kind;
362                mapping_index.codepoint_subtable_is_symbol = kind == MappingKind::Symbol;
363                mapping_index.codepoint_subtable = Some(index as u16);
364                codepoint_subtable = Some(subtable);
365            }
366        };
367        // This generally follows the same strategy as FreeType, searching the encoding
368        // records in reverse and prioritizing UCS-4 subtables over UCS-2.
369        // See <https://gitlab.freedesktop.org/freetype/freetype/-/blob/ac5babe87629107c43f627e2cd17c6cf4f2ecd43/src/base/ftobjs.c#L1370>
370        // The exception is that we prefer a symbol subtable over all others which matches the behavior
371        // of HarfBuzz.
372        // See <https://github.com/harfbuzz/harfbuzz/blob/453ded05392af38bba9f89587edce465e86ffa6b/src/hb-ot-cmap-table.hh#L1818>
373        for (i, record) in cmap.encoding_records().iter().enumerate().rev() {
374            match (record.platform_id(), record.encoding_id()) {
375                (PlatformId::Unicode, ENCODING_APPLE_ID_VARIANT_SELECTOR) => {
376                    // Unicode variation sequences
377                    if let Ok(CmapSubtable::Format14(subtable)) =
378                        record.subtable(cmap.offset_data())
379                    {
380                        if variant_subtable.is_none() {
381                            mapping_index.variant_subtable = Some(i as u16);
382                            variant_subtable = Some(subtable);
383                        }
384                    }
385                }
386                (PlatformId::Windows, ENCODING_MS_SYMBOL) => {
387                    // Symbol
388                    if let Some(subtable) = SupportedSubtable::from_cmap_record(cmap, record) {
389                        maybe_choose_subtable(MappingKind::Symbol, i, subtable);
390                    }
391                }
392                (PlatformId::Windows, ENCODING_MS_ID_UCS_4)
393                | (PlatformId::Unicode, ENCODING_APPLE_ID_UNICODE_32) => {
394                    // Unicode full repertoire
395                    if let Some(subtable) = SupportedSubtable::from_cmap_record(cmap, record) {
396                        maybe_choose_subtable(MappingKind::UnicodeFull, i, subtable);
397                    }
398                }
399                (PlatformId::ISO, _)
400                | (PlatformId::Unicode, _)
401                | (PlatformId::Windows, ENCODING_MS_UNICODE_CS) => {
402                    // Unicode BMP only
403                    if let Some(subtable) = SupportedSubtable::from_cmap_record(cmap, record) {
404                        maybe_choose_subtable(MappingKind::UnicodeBmp, i, subtable);
405                    }
406                }
407                _ => {}
408            }
409        }
410        mapping_index.cmap_limits = CmapIterLimits::default_for_font(font);
411        Self {
412            mapping_index,
413            codepoint_subtable,
414            variant_subtable,
415        }
416    }
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422    use crate::MetadataProvider;
423    use read_fonts::FontRef;
424
425    #[test]
426    fn choose_format_12_over_4() {
427        let font = FontRef::new(font_test_data::CMAP12_FONT1).unwrap();
428        let charmap = font.charmap();
429        assert!(matches!(
430            charmap.codepoint_subtable.unwrap().subtable,
431            SupportedSubtable::Format12(..)
432        ));
433    }
434
435    #[test]
436    fn choose_format_13_over_4() {
437        let font = FontRef::new(font_test_data::TOFU).unwrap();
438        let charmap = font.charmap();
439        assert!(matches!(
440            charmap.codepoint_subtable.unwrap().subtable,
441            SupportedSubtable::Format13(..)
442        ));
443    }
444
445    #[test]
446    fn choose_format_4() {
447        let font = FontRef::new(font_test_data::VAZIRMATN_VAR).unwrap();
448        let charmap = font.charmap();
449        assert!(matches!(
450            charmap.codepoint_subtable.unwrap().subtable,
451            SupportedSubtable::Format4(..)
452        ));
453    }
454
455    #[test]
456    fn choose_symbol() {
457        let font = FontRef::new(font_test_data::CMAP4_SYMBOL_PUA).unwrap();
458        let charmap = font.charmap();
459        assert!(charmap.is_symbol());
460        assert!(matches!(
461            charmap.codepoint_subtable.unwrap().subtable,
462            SupportedSubtable::Format4(..)
463        ));
464    }
465
466    #[test]
467    fn map_format_4() {
468        let font = FontRef::new(font_test_data::VAZIRMATN_VAR).unwrap();
469        let charmap = font.charmap();
470        assert_eq!(charmap.map('A'), Some(GlyphId::new(1)));
471        assert_eq!(charmap.map('À'), Some(GlyphId::new(2)));
472        assert_eq!(charmap.map('`'), Some(GlyphId::new(3)));
473        assert_eq!(charmap.map('B'), None);
474    }
475
476    #[test]
477    fn map_format_12() {
478        let font = FontRef::new(font_test_data::CMAP12_FONT1).unwrap();
479        let charmap = font.charmap();
480        assert_eq!(charmap.map(' '), None);
481        assert_eq!(charmap.map(0x101723_u32), Some(GlyphId::new(1)));
482        assert_eq!(charmap.map(0x101725_u32), Some(GlyphId::new(3)));
483        assert_eq!(charmap.map(0x102523_u32), Some(GlyphId::new(6)));
484        assert_eq!(charmap.map(0x102526_u32), Some(GlyphId::new(9)));
485        assert_eq!(charmap.map(0x102527_u32), Some(GlyphId::new(10)));
486    }
487
488    #[test]
489    fn map_format_13() {
490        let font = FontRef::new(font_test_data::TOFU).unwrap();
491        let charmap = font.charmap();
492        // This font maps U+0002..U+007E to gid 1
493        for ch in 2..0x7F_u32 {
494            assert_eq!(charmap.map(ch), Some(GlyphId::new(1)));
495        }
496    }
497
498    #[test]
499    fn map_symbol_pua() {
500        let font = FontRef::new(font_test_data::CMAP4_SYMBOL_PUA).unwrap();
501        let charmap = font.charmap();
502        assert!(charmap.codepoint_subtable.as_ref().unwrap().is_symbol);
503        assert_eq!(charmap.map(0xF001_u32), Some(GlyphId::new(1)));
504        assert_eq!(charmap.map(0xF002_u32), Some(GlyphId::new(2)));
505        assert_eq!(charmap.map(0xF003_u32), Some(GlyphId::new(3)));
506        assert_eq!(charmap.map(0xF0FE_u32), Some(GlyphId::new(4)));
507        // The following don't exist in the cmap table and are remapped into the U+F000..F0FF range
508        // due to the selection of a symbol mapping subtable.
509        assert_eq!(charmap.map(0x1_u32), Some(GlyphId::new(1)));
510        assert_eq!(charmap.map(0x2_u32), Some(GlyphId::new(2)));
511        assert_eq!(charmap.map(0x3_u32), Some(GlyphId::new(3)));
512        assert_eq!(charmap.map(0xFE_u32), Some(GlyphId::new(4)));
513    }
514
515    #[test]
516    fn map_variants() {
517        use super::MapVariant::*;
518        let font = FontRef::new(font_test_data::CMAP14_FONT1).unwrap();
519        let charmap = font.charmap();
520        let selector = '\u{e0100}';
521        assert_eq!(charmap.map_variant('a', selector), None);
522        assert_eq!(charmap.map_variant('\u{4e00}', selector), Some(UseDefault));
523        assert_eq!(charmap.map_variant('\u{4e06}', selector), Some(UseDefault));
524        assert_eq!(
525            charmap.map_variant('\u{4e08}', selector),
526            Some(Variant(GlyphId::new(25)))
527        );
528        assert_eq!(
529            charmap.map_variant('\u{4e09}', selector),
530            Some(Variant(GlyphId::new(26)))
531        );
532    }
533
534    #[test]
535    fn mappings() {
536        for font_data in [
537            font_test_data::VAZIRMATN_VAR,
538            font_test_data::CMAP12_FONT1,
539            font_test_data::SIMPLE_GLYF,
540            font_test_data::CMAP4_SYMBOL_PUA,
541            font_test_data::TOFU,
542        ] {
543            let font = FontRef::new(font_data).unwrap();
544            let charmap = font.charmap();
545            for (codepoint, glyph_id) in charmap.mappings() {
546                assert_ne!(
547                    glyph_id,
548                    GlyphId::NOTDEF,
549                    "we should never encounter notdef glyphs"
550                );
551                assert_eq!(charmap.map(codepoint), Some(glyph_id));
552            }
553        }
554    }
555
556    #[test]
557    fn variant_mappings() {
558        let font = FontRef::new(font_test_data::CMAP14_FONT1).unwrap();
559        let charmap = font.charmap();
560        for (codepoint, selector, variant) in charmap.variant_mappings() {
561            assert_eq!(charmap.map_variant(codepoint, selector), Some(variant));
562        }
563    }
564}
skrifa/charmap.rs

skrifa/
charmap.rs
