epaint/text/
font.rs

1use std::collections::BTreeMap;
2use std::sync::Arc;
3
4use emath::{vec2, Vec2};
5
6use crate::{
7    mutex::{Mutex, RwLock},
8    text::FontTweak,
9    TextureAtlas,
10};
11
12// ----------------------------------------------------------------------------
13
14#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
15#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
16pub struct UvRect {
17    /// X/Y offset for nice rendering (unit: points).
18    pub offset: Vec2,
19
20    /// Screen size (in points) of this glyph.
21    /// Note that the height is different from the font height.
22    pub size: Vec2,
23
24    /// Top left corner UV in texture.
25    pub min: [u16; 2],
26
27    /// Bottom right corner (exclusive).
28    pub max: [u16; 2],
29}
30
31impl UvRect {
32    pub fn is_nothing(&self) -> bool {
33        self.min == self.max
34    }
35}
36
37#[derive(Clone, Copy, Debug, PartialEq)]
38pub struct GlyphInfo {
39    /// Used for pair-kerning.
40    ///
41    /// Doesn't need to be unique.
42    /// Use `ab_glyph::GlyphId(0)` if you just want to have an id, and don't care.
43    pub(crate) id: ab_glyph::GlyphId,
44
45    /// Unit: points.
46    pub advance_width: f32,
47
48    /// Texture coordinates.
49    pub uv_rect: UvRect,
50}
51
52impl Default for GlyphInfo {
53    /// Basically a zero-width space.
54    fn default() -> Self {
55        Self {
56            id: ab_glyph::GlyphId(0),
57            advance_width: 0.0,
58            uv_rect: Default::default(),
59        }
60    }
61}
62
63// ----------------------------------------------------------------------------
64
65/// A specific font with a size.
66/// The interface uses points as the unit for everything.
67pub struct FontImpl {
68    name: String,
69    ab_glyph_font: ab_glyph::FontArc,
70
71    /// Maximum character height
72    scale_in_pixels: u32,
73
74    height_in_points: f32,
75
76    // move each character by this much (hack)
77    y_offset_in_points: f32,
78
79    ascent: f32,
80    pixels_per_point: f32,
81    glyph_info_cache: RwLock<ahash::HashMap<char, GlyphInfo>>, // TODO(emilk): standard Mutex
82    atlas: Arc<Mutex<TextureAtlas>>,
83}
84
85impl FontImpl {
86    pub fn new(
87        atlas: Arc<Mutex<TextureAtlas>>,
88        pixels_per_point: f32,
89        name: String,
90        ab_glyph_font: ab_glyph::FontArc,
91        scale_in_pixels: f32,
92        tweak: FontTweak,
93    ) -> Self {
94        assert!(scale_in_pixels > 0.0);
95        assert!(pixels_per_point > 0.0);
96
97        use ab_glyph::{Font, ScaleFont};
98        let scaled = ab_glyph_font.as_scaled(scale_in_pixels);
99        let ascent = scaled.ascent() / pixels_per_point;
100        let descent = scaled.descent() / pixels_per_point;
101        let line_gap = scaled.line_gap() / pixels_per_point;
102
103        // Tweak the scale as the user desired
104        let scale_in_pixels = scale_in_pixels * tweak.scale;
105
106        let baseline_offset = {
107            let scale_in_points = scale_in_pixels / pixels_per_point;
108            scale_in_points * tweak.baseline_offset_factor
109        };
110
111        let y_offset_points = {
112            let scale_in_points = scale_in_pixels / pixels_per_point;
113            scale_in_points * tweak.y_offset_factor
114        } + tweak.y_offset;
115
116        // Center scaled glyphs properly:
117        let height = ascent + descent;
118        let y_offset_points = y_offset_points - (1.0 - tweak.scale) * 0.5 * height;
119
120        // Round to an even number of physical pixels to get even kerning.
121        // See https://github.com/emilk/egui/issues/382
122        let scale_in_pixels = scale_in_pixels.round() as u32;
123
124        // Round to closest pixel:
125        let y_offset_in_points = (y_offset_points * pixels_per_point).round() / pixels_per_point;
126
127        Self {
128            name,
129            ab_glyph_font,
130            scale_in_pixels,
131            height_in_points: ascent - descent + line_gap,
132            y_offset_in_points,
133            ascent: ascent + baseline_offset,
134            pixels_per_point,
135            glyph_info_cache: Default::default(),
136            atlas,
137        }
138    }
139
140    /// Code points that will always be replaced by the replacement character.
141    ///
142    /// See also [`invisible_char`].
143    fn ignore_character(&self, chr: char) -> bool {
144        use crate::text::FontDefinitions;
145
146        if !FontDefinitions::builtin_font_names().contains(&self.name.as_str()) {
147            return false;
148        }
149
150        if self.name == "emoji-icon-font" {
151            // HACK: https://github.com/emilk/egui/issues/1284 https://github.com/jslegers/emoji-icon-font/issues/18
152            // Don't show the wrong fullwidth capital letters:
153            if 'S' <= chr && chr <= 'Y' {
154                return true;
155            }
156        }
157
158        matches!(
159            chr,
160            // Strip out a religious symbol with secondary nefarious interpretation:
161            '\u{534d}' | '\u{5350}' |
162
163            // Ignore ubuntu-specific stuff in `Ubuntu-Light.ttf`:
164            '\u{E0FF}' | '\u{EFFD}' | '\u{F0FF}' | '\u{F200}'
165        )
166    }
167
168    /// An un-ordered iterator over all supported characters.
169    fn characters(&self) -> impl Iterator<Item = char> + '_ {
170        use ab_glyph::Font as _;
171        self.ab_glyph_font
172            .codepoint_ids()
173            .map(|(_, chr)| chr)
174            .filter(|&chr| !self.ignore_character(chr))
175    }
176
177    /// `\n` will result in `None`
178    fn glyph_info(&self, c: char) -> Option<GlyphInfo> {
179        {
180            if let Some(glyph_info) = self.glyph_info_cache.read().get(&c) {
181                return Some(*glyph_info);
182            }
183        }
184
185        if self.ignore_character(c) {
186            return None; // these will result in the replacement character when rendering
187        }
188
189        if c == '\t' {
190            if let Some(space) = self.glyph_info(' ') {
191                let glyph_info = GlyphInfo {
192                    advance_width: crate::text::TAB_SIZE as f32 * space.advance_width,
193                    ..space
194                };
195                self.glyph_info_cache.write().insert(c, glyph_info);
196                return Some(glyph_info);
197            }
198        }
199
200        if c == '\u{2009}' {
201            // Thin space, often used as thousands deliminator: 1 234 567 890
202            // https://www.compart.com/en/unicode/U+2009
203            // https://en.wikipedia.org/wiki/Thin_space
204
205            if let Some(space) = self.glyph_info(' ') {
206                let em = self.height_in_points; // TODO(emilk): is this right?
207                let advance_width = f32::min(em / 6.0, space.advance_width * 0.5);
208                let glyph_info = GlyphInfo {
209                    advance_width,
210                    ..space
211                };
212                self.glyph_info_cache.write().insert(c, glyph_info);
213                return Some(glyph_info);
214            }
215        }
216
217        if invisible_char(c) {
218            let glyph_info = GlyphInfo::default();
219            self.glyph_info_cache.write().insert(c, glyph_info);
220            return Some(glyph_info);
221        }
222
223        // Add new character:
224        use ab_glyph::Font as _;
225        let glyph_id = self.ab_glyph_font.glyph_id(c);
226
227        if glyph_id.0 == 0 {
228            None // unsupported character
229        } else {
230            let glyph_info = self.allocate_glyph(glyph_id);
231            self.glyph_info_cache.write().insert(c, glyph_info);
232            Some(glyph_info)
233        }
234    }
235
236    #[inline]
237    pub fn pair_kerning(
238        &self,
239        last_glyph_id: ab_glyph::GlyphId,
240        glyph_id: ab_glyph::GlyphId,
241    ) -> f32 {
242        use ab_glyph::{Font as _, ScaleFont};
243        self.ab_glyph_font
244            .as_scaled(self.scale_in_pixels as f32)
245            .kern(last_glyph_id, glyph_id)
246            / self.pixels_per_point
247    }
248
249    /// Height of one row of text in points.
250    #[inline(always)]
251    pub fn row_height(&self) -> f32 {
252        self.height_in_points
253    }
254
255    #[inline(always)]
256    pub fn pixels_per_point(&self) -> f32 {
257        self.pixels_per_point
258    }
259
260    /// This is the distance from the top to the baseline.
261    ///
262    /// Unit: points.
263    #[inline(always)]
264    pub fn ascent(&self) -> f32 {
265        self.ascent
266    }
267
268    fn allocate_glyph(&self, glyph_id: ab_glyph::GlyphId) -> GlyphInfo {
269        assert!(glyph_id.0 != 0);
270        use ab_glyph::{Font as _, ScaleFont};
271
272        let glyph = glyph_id.with_scale_and_position(
273            self.scale_in_pixels as f32,
274            ab_glyph::Point { x: 0.0, y: 0.0 },
275        );
276
277        let uv_rect = self.ab_glyph_font.outline_glyph(glyph).map(|glyph| {
278            let bb = glyph.px_bounds();
279            let glyph_width = bb.width() as usize;
280            let glyph_height = bb.height() as usize;
281            if glyph_width == 0 || glyph_height == 0 {
282                UvRect::default()
283            } else {
284                let glyph_pos = {
285                    let atlas = &mut self.atlas.lock();
286                    let (glyph_pos, image) = atlas.allocate((glyph_width, glyph_height));
287                    glyph.draw(|x, y, v| {
288                        if 0.0 < v {
289                            let px = glyph_pos.0 + x as usize;
290                            let py = glyph_pos.1 + y as usize;
291                            image[(px, py)] = v;
292                        }
293                    });
294                    glyph_pos
295                };
296
297                let offset_in_pixels = vec2(bb.min.x, bb.min.y);
298                let offset =
299                    offset_in_pixels / self.pixels_per_point + self.y_offset_in_points * Vec2::Y;
300                UvRect {
301                    offset,
302                    size: vec2(glyph_width as f32, glyph_height as f32) / self.pixels_per_point,
303                    min: [glyph_pos.0 as u16, glyph_pos.1 as u16],
304                    max: [
305                        (glyph_pos.0 + glyph_width) as u16,
306                        (glyph_pos.1 + glyph_height) as u16,
307                    ],
308                }
309            }
310        });
311        let uv_rect = uv_rect.unwrap_or_default();
312
313        let advance_width_in_points = self
314            .ab_glyph_font
315            .as_scaled(self.scale_in_pixels as f32)
316            .h_advance(glyph_id)
317            / self.pixels_per_point;
318
319        GlyphInfo {
320            id: glyph_id,
321            advance_width: advance_width_in_points,
322            uv_rect,
323        }
324    }
325}
326
327type FontIndex = usize;
328
329// TODO(emilk): rename?
330/// Wrapper over multiple [`FontImpl`] (e.g. a primary + fallbacks for emojis)
331pub struct Font {
332    fonts: Vec<Arc<FontImpl>>,
333
334    /// Lazily calculated.
335    characters: Option<BTreeMap<char, Vec<String>>>,
336
337    replacement_glyph: (FontIndex, GlyphInfo),
338    pixels_per_point: f32,
339    row_height: f32,
340    glyph_info_cache: ahash::HashMap<char, (FontIndex, GlyphInfo)>,
341}
342
343impl Font {
344    pub fn new(fonts: Vec<Arc<FontImpl>>) -> Self {
345        if fonts.is_empty() {
346            return Self {
347                fonts,
348                characters: None,
349                replacement_glyph: Default::default(),
350                pixels_per_point: 1.0,
351                row_height: 0.0,
352                glyph_info_cache: Default::default(),
353            };
354        }
355
356        let pixels_per_point = fonts[0].pixels_per_point();
357        let row_height = fonts[0].row_height();
358
359        let mut slf = Self {
360            fonts,
361            characters: None,
362            replacement_glyph: Default::default(),
363            pixels_per_point,
364            row_height,
365            glyph_info_cache: Default::default(),
366        };
367
368        const PRIMARY_REPLACEMENT_CHAR: char = '◻'; // white medium square
369        const FALLBACK_REPLACEMENT_CHAR: char = '?'; // fallback for the fallback
370
371        let replacement_glyph = slf
372            .glyph_info_no_cache_or_fallback(PRIMARY_REPLACEMENT_CHAR)
373            .or_else(|| slf.glyph_info_no_cache_or_fallback(FALLBACK_REPLACEMENT_CHAR))
374            .unwrap_or_else(|| {
375                #[cfg(feature = "log")]
376                log::warn!(
377                    "Failed to find replacement characters {PRIMARY_REPLACEMENT_CHAR:?} or {FALLBACK_REPLACEMENT_CHAR:?}. Will use empty glyph."
378                );
379                (0, GlyphInfo::default())
380            });
381        slf.replacement_glyph = replacement_glyph;
382
383        slf
384    }
385
386    pub fn preload_characters(&mut self, s: &str) {
387        for c in s.chars() {
388            self.glyph_info(c);
389        }
390    }
391
392    pub fn preload_common_characters(&mut self) {
393        // Preload the printable ASCII characters [32, 126] (which excludes control codes):
394        const FIRST_ASCII: usize = 32; // 32 == space
395        const LAST_ASCII: usize = 126;
396        for c in (FIRST_ASCII..=LAST_ASCII).map(|c| c as u8 as char) {
397            self.glyph_info(c);
398        }
399        self.glyph_info('°');
400        self.glyph_info(crate::text::PASSWORD_REPLACEMENT_CHAR);
401    }
402
403    /// All supported characters, and in which font they are available in.
404    pub fn characters(&mut self) -> &BTreeMap<char, Vec<String>> {
405        self.characters.get_or_insert_with(|| {
406            let mut characters: BTreeMap<char, Vec<String>> = Default::default();
407            for font in &self.fonts {
408                for chr in font.characters() {
409                    characters.entry(chr).or_default().push(font.name.clone());
410                }
411            }
412            characters
413        })
414    }
415
416    #[inline(always)]
417    pub fn round_to_pixel(&self, point: f32) -> f32 {
418        (point * self.pixels_per_point).round() / self.pixels_per_point
419    }
420
421    /// Height of one row of text. In points
422    #[inline(always)]
423    pub fn row_height(&self) -> f32 {
424        self.row_height
425    }
426
427    pub fn uv_rect(&self, c: char) -> UvRect {
428        self.glyph_info_cache
429            .get(&c)
430            .map(|gi| gi.1.uv_rect)
431            .unwrap_or_default()
432    }
433
434    /// Width of this character in points.
435    pub fn glyph_width(&mut self, c: char) -> f32 {
436        self.glyph_info(c).1.advance_width
437    }
438
439    /// Can we display this glyph?
440    pub fn has_glyph(&mut self, c: char) -> bool {
441        self.glyph_info(c) != self.replacement_glyph // TODO(emilk): this is a false negative if the user asks about the replacement character itself 🤦‍♂️
442    }
443
444    /// Can we display all the glyphs in this text?
445    pub fn has_glyphs(&mut self, s: &str) -> bool {
446        s.chars().all(|c| self.has_glyph(c))
447    }
448
449    /// `\n` will (intentionally) show up as the replacement character.
450    fn glyph_info(&mut self, c: char) -> (FontIndex, GlyphInfo) {
451        if let Some(font_index_glyph_info) = self.glyph_info_cache.get(&c) {
452            return *font_index_glyph_info;
453        }
454
455        let font_index_glyph_info = self.glyph_info_no_cache_or_fallback(c);
456        let font_index_glyph_info = font_index_glyph_info.unwrap_or(self.replacement_glyph);
457        self.glyph_info_cache.insert(c, font_index_glyph_info);
458        font_index_glyph_info
459    }
460
461    #[inline]
462    pub(crate) fn font_impl_and_glyph_info(&mut self, c: char) -> (Option<&FontImpl>, GlyphInfo) {
463        if self.fonts.is_empty() {
464            return (None, self.replacement_glyph.1);
465        }
466        let (font_index, glyph_info) = self.glyph_info(c);
467        let font_impl = &self.fonts[font_index];
468        (Some(font_impl), glyph_info)
469    }
470
471    pub(crate) fn ascent(&self) -> f32 {
472        if let Some(first) = self.fonts.first() {
473            first.ascent()
474        } else {
475            self.row_height
476        }
477    }
478
479    fn glyph_info_no_cache_or_fallback(&mut self, c: char) -> Option<(FontIndex, GlyphInfo)> {
480        for (font_index, font_impl) in self.fonts.iter().enumerate() {
481            if let Some(glyph_info) = font_impl.glyph_info(c) {
482                self.glyph_info_cache.insert(c, (font_index, glyph_info));
483                return Some((font_index, glyph_info));
484            }
485        }
486        None
487    }
488}
489
490/// Code points that will always be invisible (zero width).
491///
492/// See also [`FontImpl::ignore_character`].
493#[inline]
494fn invisible_char(c: char) -> bool {
495    if c == '\r' {
496        // A character most vile and pernicious. Don't display it.
497        return true;
498    }
499
500    // See https://github.com/emilk/egui/issues/336
501
502    // From https://www.fileformat.info/info/unicode/category/Cf/list.htm
503
504    // TODO(emilk): heed bidi characters
505
506    matches!(
507        c,
508        '\u{200B}' // ZERO WIDTH SPACE
509            | '\u{200C}' // ZERO WIDTH NON-JOINER
510            | '\u{200D}' // ZERO WIDTH JOINER
511            | '\u{200E}' // LEFT-TO-RIGHT MARK
512            | '\u{200F}' // RIGHT-TO-LEFT MARK
513            | '\u{202A}' // LEFT-TO-RIGHT EMBEDDING
514            | '\u{202B}' // RIGHT-TO-LEFT EMBEDDING
515            | '\u{202C}' // POP DIRECTIONAL FORMATTING
516            | '\u{202D}' // LEFT-TO-RIGHT OVERRIDE
517            | '\u{202E}' // RIGHT-TO-LEFT OVERRIDE
518            | '\u{2060}' // WORD JOINER
519            | '\u{2061}' // FUNCTION APPLICATION
520            | '\u{2062}' // INVISIBLE TIMES
521            | '\u{2063}' // INVISIBLE SEPARATOR
522            | '\u{2064}' // INVISIBLE PLUS
523            | '\u{2066}' // LEFT-TO-RIGHT ISOLATE
524            | '\u{2067}' // RIGHT-TO-LEFT ISOLATE
525            | '\u{2068}' // FIRST STRONG ISOLATE
526            | '\u{2069}' // POP DIRECTIONAL ISOLATE
527            | '\u{206A}' // INHIBIT SYMMETRIC SWAPPING
528            | '\u{206B}' // ACTIVATE SYMMETRIC SWAPPING
529            | '\u{206C}' // INHIBIT ARABIC FORM SHAPING
530            | '\u{206D}' // ACTIVATE ARABIC FORM SHAPING
531            | '\u{206E}' // NATIONAL DIGIT SHAPES
532            | '\u{206F}' // NOMINAL DIGIT SHAPES
533            | '\u{FEFF}' // ZERO WIDTH NO-BREAK SPACE
534    )
535}