Skip to main content

text/
fallback.rs

1// fallback -- characters a font lacks, drawn with another font (font fallback)
2//
3//   set_fallback_fonts(ids)        (shaping.rs) the app's own chain, tried first; shaping uses
4//                                  it as well
5//   set_system_fallback(on)        then system fonts: the families of FAMILIES (this OS's
6//                                  list: Windows, macOS / iOS, Linux and the rest; after
7//                                  the ';' separated families of
8//                                  jfgui_FALLBACK_FONTS), found with a FontDb of the font
9//                                  folders (scanned on the first missing character; its cache
10//                                  is cache://fontdb.fdb, not with jfgui_FONTDIRS) and loaded
11//                                  when first needed
12//   set_fallback_lang(tag)         the UI language: its fonts (FontConf::lang_families, after
13//                                  jfgui_FALLBACK_FONTS) come before FAMILIES, so Han
14//                                  characters take the language's forms (ja, zh-Hans, zh-Hant,
15//                                  ko) and scripts their usual font
16//   system_fallback() -> bool
17//   fallback_for(cp) -> Option<font id>   the first font of the chain that has cp (remembered
18//                                  per code point, also when none has it)
19//   fallback_active() -> bool      a chain is set (run / shaping only look for fallbacks then)
20//
21// Characters that fonts lack on purpose (controls, zero-width spaces and joiners, bidi marks,
22// variation selectors, tags) never fall back.  Fallback glyphs share the baseline and the
23// pixel size of the run; ascent, descent and line height stay the first font's.
24
25use alloc::collections::BTreeMap;
26use alloc::string::String;
27use alloc::vec::Vec;
28
29use crate::fontconf::FontConf;
30use crate::fontdb::FontDb;
31use crate::Text;
32
33#[cfg(windows)]
34const FAMILIES: &[&str] = &[
35    "Segoe UI", "Segoe UI Symbol", "Segoe UI Emoji", "Segoe UI Historic", "Microsoft YaHei", "Microsoft JhengHei",
36    "Yu Gothic", "Malgun Gothic", "Nirmala UI", "Leelawadee UI", "Ebrima", "Gadugi", "Microsoft Himalaya",
37    "Mongolian Baiti", "Myanmar Text", "Javanese Text", "Sylfaen", "Cambria Math", "Arial", "Times New Roman",
38    "MS Gothic", "SimSun", "Arial Unicode MS",
39];
40
41// macOS and iOS: the families in /System/Library/Fonts (and its Supplemental folder), Latin
42// and symbols first, then Chinese, Japanese, Korean and the other scripts.  PingFang is a
43// downloaded asset on macOS (not in the font folders), Hiragino and Heiti stand in for it.
44// Not here: Apple Color Emoji, whose glyphs are sbix bitmaps (text draws COLR and CBDT only),
45// and the hidden ".SF ..." system faces.
46#[cfg(target_vendor = "apple")]
47const FAMILIES: &[&str] = &[
48    "Helvetica Neue", "Helvetica", "Lucida Grande", "Apple Symbols", "PingFang SC", "Hiragino Sans GB", "Heiti SC",
49    "PingFang TC", "Heiti TC", "Hiragino Sans", "Apple SD Gothic Neo", "AppleGothic", "Thonburi",
50    "Kohinoor Devanagari", "Kohinoor Bangla", "Kohinoor Gujarati", "Kohinoor Telugu", "Tamil Sangam MN",
51    "Geeza Pro", "Arial Hebrew", "Kefa III", "Noto Sans Armenian", "Menlo", "STIX Two Math", "Arial Unicode MS",
52    "Times New Roman", "Arial",
53];
54
55#[cfg(not(any(windows, target_vendor = "apple")))]
56const FAMILIES: &[&str] = &[
57    "DejaVu Sans", "Noto Sans", "Liberation Sans", "Noto Sans CJK SC", "Noto Sans CJK JP", "Noto Sans CJK KR",
58    "Noto Sans CJK TC", "Noto Color Emoji", "Noto Emoji", "Noto Sans Symbols", "Noto Sans Symbols2", "Noto Sans Math",
59    "Noto Sans Arabic", "Noto Sans Hebrew", "Noto Sans Devanagari", "Noto Sans Bengali", "Noto Sans Tamil",
60    "Noto Sans Thai", "Noto Sans Ethiopic", "Noto Sans Armenian", "Noto Sans Georgian", "WenQuanYi Micro Hei",
61    "Droid Sans Fallback", "FreeSans", "FreeSerif", "Unifont", "DejaVu Serif", "DejaVu Sans Mono",
62];
63
64const CACHE_MAX: usize = 8192; // remembered code points
65const NONE: u32 = u32::MAX;
66
67#[derive(Default)]
68pub(crate) struct Fallback {
69    /// the app's chain (set_fallback_fonts)
70    pub(crate) app: Vec<u32>,
71    system: bool,
72    db: Option<FontDb>,
73    /// the system families in order with their font id (-1: not there / failed; 0 + ...:
74    /// loaded); None: not tried yet
75    families: Vec<(String, Option<i32>)>,
76    cache: BTreeMap<u32, u32>,
77    /// set_fallback_lang; the families list is built again when it changes
78    lang: String,
79    built: bool,
80}
81
82/// characters that fonts lack on purpose
83fn never(cp: u32) -> bool {
84    cp < 0x20
85        || (0x7F..=0x9F).contains(&cp)
86        || (0x200B..=0x200F).contains(&cp)
87        || (0x2028..=0x202E).contains(&cp)
88        || (0x2060..=0x206F).contains(&cp)
89        || (0xFE00..=0xFE0F).contains(&cp)
90        || cp == 0xFEFF
91        || (0xE0000..=0xE01EF).contains(&cp)
92}
93
94impl Text {
95    /// look for missing characters in system fonts too (after set_fallback_fonts' chain)
96    pub fn set_system_fallback(&mut self, on: bool) {
97        if self.fb.system != on {
98            self.fb.system = on;
99            self.fb.cache.clear();
100            self.shaping_forget(); // the line shaped last is shaped again (its fallbacks)
101        }
102    }
103
104    /// the language whose fonts the system fallback tries first ("" none)
105    pub fn set_fallback_lang(&mut self, tag: &str) {
106        if self.fb.lang != tag {
107            self.fb.lang = String::from(tag);
108            self.fb.built = false;
109            self.fb.cache.clear();
110        }
111    }
112
113    /// whether system fonts are searched for missing characters
114    pub fn system_fallback(&self) -> bool {
115        self.fb.system
116    }
117
118    /// whether run / shaping look for fallback fonts at all
119    pub fn fallback_active(&self) -> bool {
120        self.fb.system || !self.fb.app.is_empty()
121    }
122
123    // set_fallback_fonts: the app's chain changed
124    pub(crate) fn fallback_app(&mut self, ids: &[u32]) {
125        self.fb.app = ids.to_vec();
126        self.fb.cache.clear();
127    }
128
129    /// the first font of the fallback chain that has cp (None: none has it)
130    pub fn fallback_for(&mut self, cp: u32) -> Option<u32> {
131        if never(cp) || !self.fallback_active() {
132            return None;
133        }
134        if let Some(&id) = self.fb.cache.get(&cp) {
135            return (id != NONE).then_some(id);
136        }
137        let found = self.fallback_search(cp);
138        if self.fb.cache.len() >= CACHE_MAX {
139            self.fb.cache.clear();
140        }
141        self.fb.cache.insert(cp, found.unwrap_or(NONE));
142        found
143    }
144
145    fn fallback_search(&mut self, cp: u32) -> Option<u32> {
146        let app = self.fb.app.clone();
147        if let Some(id) = app.into_iter().find(|&id| self.valid(id) && self.has(id, cp)) {
148            return Some(id);
149        }
150        if !self.fb.system {
151            return None;
152        }
153        self.fallback_scan();
154        for k in 0..self.fb.families.len() {
155            let id = match self.fb.families[k].1 {
156                Some(id) => id,
157                None => {
158                    let fam = self.fb.families[k].0.clone();
159                    let mut db = self.fb.db.take().unwrap_or_default();
160                    let id = db.load(self, &fam, 400, false);
161                    self.fb.db = Some(db);
162                    self.fb.families[k].1 = Some(id);
163                    id
164                }
165            };
166            if id >= 0 && self.has(id as u32, cp) {
167                return Some(id as u32);
168            }
169        }
170        None
171    }
172
173    // the font folders' faces (once) and the family list (again after a language change)
174    fn fallback_scan(&mut self) {
175        if self.fb.db.is_some() {
176            if !self.fb.built {
177                let db = self.fb.db.take().unwrap_or_default();
178                self.fallback_families(&db);
179                self.fb.db = Some(db);
180            }
181            return;
182        }
183        let mut db = FontDb::new();
184        // the cache belongs to the system folders; jfgui_FONTDIRS (tests) scans without it
185        let cache = plat::env("jfgui_FONTDIRS").is_none().then_some("cache://fontdb.fdb");
186        if let Some(c) = cache {
187            db.load_cache(c);
188        }
189        db.scan(0);
190        if let Some(c) = cache {
191            db.save_cache(c);
192        }
193        self.fallback_families(&db);
194        self.fb.db = Some(db);
195    }
196
197    // the installed families of jfgui_FALLBACK_FONTS, the language's and FAMILIES in order
198    fn fallback_families(&mut self, db: &FontDb) {
199        let mut fams: Vec<String> = plat::env("jfgui_FALLBACK_FONTS")
200            .map(|v| v.split(';').map(str::trim).filter(|s| !s.is_empty()).map(String::from).collect())
201            .unwrap_or_default();
202        if !self.fb.lang.is_empty() {
203            fams.extend(FontConf::system().lang_families(&self.fb.lang));
204        }
205        fams.extend(FAMILIES.iter().map(|s| String::from(*s)));
206        let mut seen: Vec<String> = Vec::new();
207        self.fb.families = fams
208            .into_iter()
209            .filter(|f| {
210                let new = !seen.iter().any(|s| s.eq_ignore_ascii_case(f));
211                seen.push(f.clone());
212                new && db.find(f, 400, false).is_some()
213            })
214            .map(|f| (f, None))
215            .collect();
216        self.fb.built = true;
217    }
218}