1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */

#![allow(unsafe_code)]

use std::os::raw::{c_char, c_int, c_uint, c_void};
use std::sync::LazyLock;
use std::{char, cmp, ptr};

use app_units::Au;
use base::text::is_bidi_control;
use euclid::default::Point2D;
// Eventually we would like the shaper to be pluggable, as many operating systems have their own
// shapers. For now, however, HarfBuzz is a hard dependency.
use harfbuzz_sys::{
    hb_blob_create, hb_blob_t, hb_bool_t, hb_buffer_add_utf8, hb_buffer_create, hb_buffer_destroy,
    hb_buffer_get_glyph_infos, hb_buffer_get_glyph_positions, hb_buffer_get_length,
    hb_buffer_set_direction, hb_buffer_set_script, hb_buffer_t, hb_codepoint_t,
    hb_face_create_for_tables, hb_face_destroy, hb_face_t, hb_feature_t, hb_font_create,
    hb_font_destroy, hb_font_funcs_create, hb_font_funcs_set_glyph_h_advance_func,
    hb_font_funcs_set_nominal_glyph_func, hb_font_funcs_t, hb_font_set_funcs, hb_font_set_ppem,
    hb_font_set_scale, hb_font_t, hb_glyph_info_t, hb_glyph_position_t, hb_ot_layout_get_baseline,
    hb_position_t, hb_shape, hb_tag_t, HB_DIRECTION_LTR, HB_DIRECTION_RTL, HB_MEMORY_MODE_READONLY,
    HB_OT_LAYOUT_BASELINE_TAG_HANGING, HB_OT_LAYOUT_BASELINE_TAG_IDEO_EMBOX_BOTTOM_OR_LEFT,
    HB_OT_LAYOUT_BASELINE_TAG_ROMAN,
};
use log::debug;
use num_traits::Zero;

use crate::platform::font::FontTable;
use crate::{
    fixed_to_float, float_to_fixed, ot_tag, ByteIndex, Font, FontBaseline, FontTableMethods,
    FontTableTag, GlyphData, GlyphId, GlyphStore, ShapingFlags, ShapingOptions, BASE, KERN,
};

const NO_GLYPH: i32 = -1;
const LIGA: u32 = ot_tag!('l', 'i', 'g', 'a');
const HB_OT_TAG_DEFAULT_SCRIPT: u32 = ot_tag!('D', 'F', 'L', 'T');
const HB_OT_TAG_DEFAULT_LANGUAGE: u32 = ot_tag!('d', 'f', 'l', 't');

pub struct ShapedGlyphData {
    count: usize,
    glyph_infos: *mut hb_glyph_info_t,
    pos_infos: *mut hb_glyph_position_t,
}

pub struct ShapedGlyphEntry {
    codepoint: GlyphId,
    advance: Au,
    offset: Option<Point2D<Au>>,
}

impl ShapedGlyphData {
    /// Create a new [`ShapedGlyphData`] from the given HarfBuzz buffer.
    ///
    /// # Safety
    ///
    /// Passing an invalid buffer pointer to this function results in undefined behavior.
    pub unsafe fn new(buffer: *mut hb_buffer_t) -> ShapedGlyphData {
        let mut glyph_count = 0;
        let glyph_infos = hb_buffer_get_glyph_infos(buffer, &mut glyph_count);
        assert!(!glyph_infos.is_null());
        let mut pos_count = 0;
        let pos_infos = hb_buffer_get_glyph_positions(buffer, &mut pos_count);
        assert!(!pos_infos.is_null());
        assert_eq!(glyph_count, pos_count);

        ShapedGlyphData {
            count: glyph_count as usize,
            glyph_infos,
            pos_infos,
        }
    }

    #[inline(always)]
    fn byte_offset_of_glyph(&self, i: usize) -> u32 {
        assert!(i < self.count);

        unsafe {
            let glyph_info_i = self.glyph_infos.add(i);
            (*glyph_info_i).cluster
        }
    }

    pub fn len(&self) -> usize {
        self.count
    }

    pub fn is_empty(&self) -> bool {
        self.count == 0
    }

    /// Returns shaped glyph data for one glyph, and updates the y-position of the pen.
    pub fn entry_for_glyph(&self, i: usize, y_pos: &mut Au) -> ShapedGlyphEntry {
        assert!(i < self.count);

        unsafe {
            let glyph_info_i = self.glyph_infos.add(i);
            let pos_info_i = self.pos_infos.add(i);
            let x_offset = Shaper::fixed_to_float((*pos_info_i).x_offset);
            let y_offset = Shaper::fixed_to_float((*pos_info_i).y_offset);
            let x_advance = Shaper::fixed_to_float((*pos_info_i).x_advance);
            let y_advance = Shaper::fixed_to_float((*pos_info_i).y_advance);

            let x_offset = Au::from_f64_px(x_offset);
            let y_offset = Au::from_f64_px(y_offset);
            let x_advance = Au::from_f64_px(x_advance);
            let y_advance = Au::from_f64_px(y_advance);

            let offset = if x_offset.is_zero() && y_offset.is_zero() && y_advance.is_zero() {
                None
            } else {
                // adjust the pen..
                if y_advance > Au::zero() {
                    *y_pos -= y_advance;
                }

                Some(Point2D::new(x_offset, *y_pos - y_offset))
            };

            ShapedGlyphEntry {
                codepoint: (*glyph_info_i).codepoint as GlyphId,
                advance: x_advance,
                offset,
            }
        }
    }
}

#[derive(Debug)]
pub struct Shaper {
    hb_face: *mut hb_face_t,
    hb_font: *mut hb_font_t,
    font: *const Font,
}

// The HarfBuzz API is thread safe as well as our `Font`, so we can make the data
// structures here as thread-safe as well. This doesn't seem to be documented,
// but was expressed as one of the original goals of the HarfBuzz API.
unsafe impl Sync for Shaper {}
unsafe impl Send for Shaper {}

impl Drop for Shaper {
    fn drop(&mut self) {
        unsafe {
            assert!(!self.hb_face.is_null());
            hb_face_destroy(self.hb_face);

            assert!(!self.hb_font.is_null());
            hb_font_destroy(self.hb_font);
        }
    }
}

impl Shaper {
    #[allow(clippy::not_unsafe_ptr_arg_deref)] // Has an unsafe block inside
    pub fn new(font: *const Font) -> Shaper {
        unsafe {
            let hb_face: *mut hb_face_t = hb_face_create_for_tables(
                Some(font_table_func),
                font as *const c_void as *mut c_void,
                None,
            );
            let hb_font: *mut hb_font_t = hb_font_create(hb_face);

            // Set points-per-em. if zero, performs no hinting in that direction.
            let pt_size = (*font).descriptor.pt_size.to_f64_px();
            hb_font_set_ppem(hb_font, pt_size as c_uint, pt_size as c_uint);

            // Set scaling. Note that this takes 16.16 fixed point.
            hb_font_set_scale(
                hb_font,
                Shaper::float_to_fixed(pt_size) as c_int,
                Shaper::float_to_fixed(pt_size) as c_int,
            );

            // configure static function callbacks.
            hb_font_set_funcs(
                hb_font,
                HB_FONT_FUNCS.0,
                font as *mut Font as *mut c_void,
                None,
            );

            Shaper {
                hb_face,
                hb_font,
                font,
            }
        }
    }

    fn float_to_fixed(f: f64) -> i32 {
        float_to_fixed(16, f)
    }

    fn fixed_to_float(i: hb_position_t) -> f64 {
        fixed_to_float(16, i)
    }
}

pub fn unicode_to_hb_script(script: unicode_script::Script) -> harfbuzz_sys::hb_script_t {
    use harfbuzz_sys::*;
    use unicode_script::Script::*;
    match script {
        Adlam => HB_SCRIPT_ADLAM,
        Ahom => HB_SCRIPT_AHOM,
        Anatolian_Hieroglyphs => HB_SCRIPT_ANATOLIAN_HIEROGLYPHS,
        Arabic => HB_SCRIPT_ARABIC,
        Armenian => HB_SCRIPT_ARMENIAN,
        Avestan => HB_SCRIPT_AVESTAN,
        Balinese => HB_SCRIPT_BALINESE,
        Bamum => HB_SCRIPT_BAMUM,
        Bassa_Vah => HB_SCRIPT_BASSA_VAH,
        Batak => HB_SCRIPT_BATAK,
        Bengali => HB_SCRIPT_BENGALI,
        Bhaiksuki => HB_SCRIPT_BHAIKSUKI,
        Bopomofo => HB_SCRIPT_BOPOMOFO,
        Brahmi => HB_SCRIPT_BRAHMI,
        Braille => HB_SCRIPT_BRAILLE,
        Buginese => HB_SCRIPT_BUGINESE,
        Buhid => HB_SCRIPT_BUHID,
        Canadian_Aboriginal => HB_SCRIPT_CANADIAN_SYLLABICS,
        Carian => HB_SCRIPT_CARIAN,
        Caucasian_Albanian => HB_SCRIPT_CAUCASIAN_ALBANIAN,
        Chakma => HB_SCRIPT_CHAKMA,
        Cham => HB_SCRIPT_CHAM,
        Cherokee => HB_SCRIPT_CHEROKEE,
        Chorasmian => HB_SCRIPT_CHORASMIAN,
        Common => HB_SCRIPT_COMMON,
        Coptic => HB_SCRIPT_COPTIC,
        Cuneiform => HB_SCRIPT_CUNEIFORM,
        Cypriot => HB_SCRIPT_CYPRIOT,
        Cyrillic => HB_SCRIPT_CYRILLIC,
        Deseret => HB_SCRIPT_DESERET,
        Devanagari => HB_SCRIPT_DEVANAGARI,
        Dives_Akuru => HB_SCRIPT_DIVES_AKURU,
        Dogra => HB_SCRIPT_DOGRA,
        Duployan => HB_SCRIPT_DUPLOYAN,
        Egyptian_Hieroglyphs => HB_SCRIPT_EGYPTIAN_HIEROGLYPHS,
        Elbasan => HB_SCRIPT_ELBASAN,
        Elymaic => HB_SCRIPT_ELYMAIC,
        Ethiopic => HB_SCRIPT_ETHIOPIC,
        Georgian => HB_SCRIPT_GEORGIAN,
        Glagolitic => HB_SCRIPT_GLAGOLITIC,
        Gothic => HB_SCRIPT_GOTHIC,
        Grantha => HB_SCRIPT_GRANTHA,
        Greek => HB_SCRIPT_GREEK,
        Gujarati => HB_SCRIPT_GUJARATI,
        Gunjala_Gondi => HB_SCRIPT_GUNJALA_GONDI,
        Gurmukhi => HB_SCRIPT_GURMUKHI,
        Han => HB_SCRIPT_HAN,
        Hangul => HB_SCRIPT_HANGUL,
        Hanifi_Rohingya => HB_SCRIPT_HANIFI_ROHINGYA,
        Hanunoo => HB_SCRIPT_HANUNOO,
        Hatran => HB_SCRIPT_HATRAN,
        Hebrew => HB_SCRIPT_HEBREW,
        Hiragana => HB_SCRIPT_HIRAGANA,
        Imperial_Aramaic => HB_SCRIPT_IMPERIAL_ARAMAIC,
        Inherited => HB_SCRIPT_INHERITED,
        Inscriptional_Pahlavi => HB_SCRIPT_INSCRIPTIONAL_PAHLAVI,
        Inscriptional_Parthian => HB_SCRIPT_INSCRIPTIONAL_PARTHIAN,
        Javanese => HB_SCRIPT_JAVANESE,
        Kaithi => HB_SCRIPT_KAITHI,
        Kannada => HB_SCRIPT_KANNADA,
        Katakana => HB_SCRIPT_KATAKANA,
        Kayah_Li => HB_SCRIPT_KAYAH_LI,
        Kharoshthi => HB_SCRIPT_KHAROSHTHI,
        Khitan_Small_Script => HB_SCRIPT_KHITAN_SMALL_SCRIPT,
        Khmer => HB_SCRIPT_KHMER,
        Khojki => HB_SCRIPT_KHOJKI,
        Khudawadi => HB_SCRIPT_KHUDAWADI,
        Lao => HB_SCRIPT_LAO,
        Latin => HB_SCRIPT_LATIN,
        Lepcha => HB_SCRIPT_LEPCHA,
        Limbu => HB_SCRIPT_LIMBU,
        Linear_A => HB_SCRIPT_LINEAR_A,
        Linear_B => HB_SCRIPT_LINEAR_B,
        Lisu => HB_SCRIPT_LISU,
        Lycian => HB_SCRIPT_LYCIAN,
        Lydian => HB_SCRIPT_LYDIAN,
        Mahajani => HB_SCRIPT_MAHAJANI,
        Makasar => HB_SCRIPT_MAKASAR,
        Malayalam => HB_SCRIPT_MALAYALAM,
        Mandaic => HB_SCRIPT_MANDAIC,
        Manichaean => HB_SCRIPT_MANICHAEAN,
        Marchen => HB_SCRIPT_MARCHEN,
        Masaram_Gondi => HB_SCRIPT_MASARAM_GONDI,
        Medefaidrin => HB_SCRIPT_MEDEFAIDRIN,
        Meetei_Mayek => HB_SCRIPT_MEETEI_MAYEK,
        Mende_Kikakui => HB_SCRIPT_MENDE_KIKAKUI,
        Meroitic_Cursive => HB_SCRIPT_MEROITIC_CURSIVE,
        Meroitic_Hieroglyphs => HB_SCRIPT_MEROITIC_HIEROGLYPHS,
        Miao => HB_SCRIPT_MIAO,
        Modi => HB_SCRIPT_MODI,
        Mongolian => HB_SCRIPT_MONGOLIAN,
        Mro => HB_SCRIPT_MRO,
        Multani => HB_SCRIPT_MULTANI,
        Myanmar => HB_SCRIPT_MYANMAR,
        Nabataean => HB_SCRIPT_NABATAEAN,
        Nandinagari => HB_SCRIPT_NANDINAGARI,
        New_Tai_Lue => HB_SCRIPT_NEW_TAI_LUE,
        Newa => HB_SCRIPT_NEWA,
        Nko => HB_SCRIPT_NKO,
        Nushu => HB_SCRIPT_NUSHU,
        Nyiakeng_Puachue_Hmong => HB_SCRIPT_NYIAKENG_PUACHUE_HMONG,
        Ogham => HB_SCRIPT_OGHAM,
        Ol_Chiki => HB_SCRIPT_OL_CHIKI,
        Old_Hungarian => HB_SCRIPT_OLD_HUNGARIAN,
        Old_Italic => HB_SCRIPT_OLD_ITALIC,
        Old_North_Arabian => HB_SCRIPT_OLD_NORTH_ARABIAN,
        Old_Permic => HB_SCRIPT_OLD_PERMIC,
        Old_Persian => HB_SCRIPT_OLD_PERSIAN,
        Old_Sogdian => HB_SCRIPT_OLD_SOGDIAN,
        Old_South_Arabian => HB_SCRIPT_OLD_SOUTH_ARABIAN,
        Old_Turkic => HB_SCRIPT_OLD_TURKIC,
        Oriya => HB_SCRIPT_ORIYA,
        Osage => HB_SCRIPT_OSAGE,
        Osmanya => HB_SCRIPT_OSMANYA,
        Pahawh_Hmong => HB_SCRIPT_PAHAWH_HMONG,
        Palmyrene => HB_SCRIPT_PALMYRENE,
        Pau_Cin_Hau => HB_SCRIPT_PAU_CIN_HAU,
        Phags_Pa => HB_SCRIPT_PHAGS_PA,
        Phoenician => HB_SCRIPT_PHOENICIAN,
        Psalter_Pahlavi => HB_SCRIPT_PSALTER_PAHLAVI,
        Rejang => HB_SCRIPT_REJANG,
        Runic => HB_SCRIPT_RUNIC,
        Samaritan => HB_SCRIPT_SAMARITAN,
        Saurashtra => HB_SCRIPT_SAURASHTRA,
        Sharada => HB_SCRIPT_SHARADA,
        Shavian => HB_SCRIPT_SHAVIAN,
        Siddham => HB_SCRIPT_SIDDHAM,
        SignWriting => HB_SCRIPT_SIGNWRITING,
        Sinhala => HB_SCRIPT_SINHALA,
        Sogdian => HB_SCRIPT_SOGDIAN,
        Sora_Sompeng => HB_SCRIPT_SORA_SOMPENG,
        Soyombo => HB_SCRIPT_SOYOMBO,
        Sundanese => HB_SCRIPT_SUNDANESE,
        Syloti_Nagri => HB_SCRIPT_SYLOTI_NAGRI,
        Syriac => HB_SCRIPT_SYRIAC,
        Tagalog => HB_SCRIPT_TAGALOG,
        Tagbanwa => HB_SCRIPT_TAGBANWA,
        Tai_Le => HB_SCRIPT_TAI_LE,
        Tai_Tham => HB_SCRIPT_TAI_THAM,
        Tai_Viet => HB_SCRIPT_TAI_VIET,
        Takri => HB_SCRIPT_TAKRI,
        Tamil => HB_SCRIPT_TAMIL,
        Tangut => HB_SCRIPT_TANGUT,
        Telugu => HB_SCRIPT_TELUGU,
        Thaana => HB_SCRIPT_THAANA,
        Thai => HB_SCRIPT_THAI,
        Tibetan => HB_SCRIPT_TIBETAN,
        Tifinagh => HB_SCRIPT_TIFINAGH,
        Tirhuta => HB_SCRIPT_TIRHUTA,
        Ugaritic => HB_SCRIPT_UGARITIC,
        Unknown => HB_SCRIPT_UNKNOWN,
        Vai => HB_SCRIPT_VAI,
        Warang_Citi => HB_SCRIPT_WARANG_CITI,
        Wancho => HB_SCRIPT_WANCHO,
        Yezidi => HB_SCRIPT_YEZIDI,
        Yi => HB_SCRIPT_YI,
        Zanabazar_Square => HB_SCRIPT_ZANABAZAR_SQUARE,
        _ => HB_SCRIPT_UNKNOWN,
    }
}

impl Shaper {
    /// Calculate the layout metrics associated with the given text when painted in a specific
    /// font.
    pub(crate) fn shape_text(&self, text: &str, options: &ShapingOptions, glyphs: &mut GlyphStore) {
        unsafe {
            let hb_buffer: *mut hb_buffer_t = hb_buffer_create();
            hb_buffer_set_direction(
                hb_buffer,
                if options.flags.contains(ShapingFlags::RTL_FLAG) {
                    HB_DIRECTION_RTL
                } else {
                    HB_DIRECTION_LTR
                },
            );

            hb_buffer_set_script(hb_buffer, unicode_to_hb_script(options.script));

            hb_buffer_add_utf8(
                hb_buffer,
                text.as_ptr() as *const c_char,
                text.len() as c_int,
                0,
                text.len() as c_int,
            );

            let mut features = Vec::new();
            if options
                .flags
                .contains(ShapingFlags::IGNORE_LIGATURES_SHAPING_FLAG)
            {
                features.push(hb_feature_t {
                    tag: LIGA,
                    value: 0,
                    start: 0,
                    end: hb_buffer_get_length(hb_buffer),
                })
            }
            if options
                .flags
                .contains(ShapingFlags::DISABLE_KERNING_SHAPING_FLAG)
            {
                features.push(hb_feature_t {
                    tag: KERN,
                    value: 0,
                    start: 0,
                    end: hb_buffer_get_length(hb_buffer),
                })
            }

            hb_shape(
                self.hb_font,
                hb_buffer,
                features.as_mut_ptr(),
                features.len() as u32,
            );
            self.save_glyph_results(text, options, glyphs, hb_buffer);
            hb_buffer_destroy(hb_buffer);
        }
    }

    fn save_glyph_results(
        &self,
        text: &str,
        options: &ShapingOptions,
        glyphs: &mut GlyphStore,
        buffer: *mut hb_buffer_t,
    ) {
        let glyph_data = unsafe { ShapedGlyphData::new(buffer) };
        let glyph_count = glyph_data.len();
        let byte_max = text.len();

        debug!(
            "Shaped text[byte count={}], got back {} glyph info records.",
            byte_max, glyph_count
        );

        // make map of what chars have glyphs
        let mut byte_to_glyph = vec![NO_GLYPH; byte_max];

        debug!("(glyph idx) -> (text byte offset)");
        for i in 0..glyph_data.len() {
            let loc = glyph_data.byte_offset_of_glyph(i) as usize;
            if loc < byte_max {
                byte_to_glyph[loc] = i as i32;
            } else {
                debug!(
                    "ERROR: tried to set out of range byte_to_glyph: idx={}, glyph idx={}",
                    loc, i
                );
            }
            debug!("{} -> {}", i, loc);
        }

        debug!("text: {:?}", text);
        debug!("(char idx): char->(glyph index):");
        for (i, ch) in text.char_indices() {
            debug!("{}: {:?} --> {}", i, ch, byte_to_glyph[i]);
        }

        let mut glyph_span = 0..0;
        let mut byte_range = 0..0;

        let mut y_pos = Au::zero();

        // main loop over each glyph. each iteration usually processes 1 glyph and 1+ chars.
        // in cases with complex glyph-character associations, 2+ glyphs and 1+ chars can be
        // processed.
        while glyph_span.start < glyph_count {
            debug!("Processing glyph at idx={}", glyph_span.start);
            glyph_span.end = glyph_span.start;
            byte_range.end = glyph_data.byte_offset_of_glyph(glyph_span.start) as usize;

            while byte_range.end < byte_max {
                byte_range.end += 1;
                // Extend the byte range to include any following byte without its own glyph.
                while byte_range.end < byte_max && byte_to_glyph[byte_range.end] == NO_GLYPH {
                    byte_range.end += 1;
                }

                // Extend the glyph range to include all glyphs covered by bytes processed so far.
                let mut max_glyph_idx = glyph_span.end;
                for glyph_idx in &byte_to_glyph[byte_range.clone()] {
                    if *glyph_idx != NO_GLYPH {
                        max_glyph_idx = cmp::max(*glyph_idx as usize + 1, max_glyph_idx);
                    }
                }
                if max_glyph_idx > glyph_span.end {
                    glyph_span.end = max_glyph_idx;
                    debug!("Extended glyph span to {:?}", glyph_span);
                }

                // if there's just one glyph, then we don't need further checks.
                if glyph_span.len() == 1 {
                    break;
                }

                // if no glyphs were found yet, extend the char byte range more.
                if glyph_span.is_empty() {
                    continue;
                }

                // If byte_range now includes all the byte offsets found in glyph_span, then we
                // have found a contiguous "cluster" and can stop extending it.
                let mut all_glyphs_are_within_cluster: bool = true;
                for j in glyph_span.clone() {
                    let loc = glyph_data.byte_offset_of_glyph(j) as usize;
                    if !(byte_range.start <= loc && loc < byte_range.end) {
                        all_glyphs_are_within_cluster = false;
                        break;
                    }
                }
                if all_glyphs_are_within_cluster {
                    break;
                }

                // Otherwise, the bytes we have seen so far correspond to a non-contiguous set of
                // glyphs.  Keep extending byte_range until we fill in all the holes in the glyph
                // span or reach the end of the text.
            }

            assert!(!byte_range.is_empty());
            assert!(!glyph_span.is_empty());

            // Now byte_range is the ligature clump formed by the glyphs in glyph_span.
            // We will save these glyphs to the glyph store at the index of the first byte.
            let byte_idx = ByteIndex(byte_range.start as isize);

            if glyph_span.len() == 1 {
                // Fast path: 1-to-1 mapping of byte offset to single glyph.
                //
                // TODO(Issue #214): cluster ranges need to be computed before
                // shaping, and then consulted here.
                // for now, just pretend that every character is a cluster start.
                // (i.e., pretend there are no combining character sequences).
                // 1-to-1 mapping of character to glyph also treated as ligature start.
                //
                // NB: When we acquire the ability to handle ligatures that cross word boundaries,
                // we'll need to do something special to handle `word-spacing` properly.
                let character = text[byte_range.clone()].chars().next().unwrap();
                if is_bidi_control(character) {
                    // Don't add any glyphs for bidi control chars
                } else {
                    let (glyph_id, advance, offset) = if character == '\t' {
                        // Treat tabs in pre-formatted text as a fixed number of spaces. The glyph id does
                        // not matter here as Servo doesn't render any glyphs for whitespace.
                        //
                        // TODO: Proper tab stops. This should happen in layout and be based on the
                        // size of the space character of the inline formatting context.
                        let font = unsafe { &(*self.font) };
                        (
                            font.glyph_index(' ').unwrap_or(0) as hb_codepoint_t,
                            font.metrics.space_advance * 8,
                            Default::default(),
                        )
                    } else {
                        let shape = glyph_data.entry_for_glyph(glyph_span.start, &mut y_pos);
                        let advance =
                            self.advance_for_shaped_glyph(shape.advance, character, options);
                        (shape.codepoint, advance, shape.offset)
                    };

                    let data = GlyphData::new(glyph_id, advance, offset, true, true);
                    glyphs.add_glyph_for_byte_index(byte_idx, character, &data);
                }
            } else {
                // collect all glyphs to be assigned to the first character.
                let mut datas = vec![];

                for glyph_i in glyph_span.clone() {
                    let shape = glyph_data.entry_for_glyph(glyph_i, &mut y_pos);
                    datas.push(GlyphData::new(
                        shape.codepoint,
                        shape.advance,
                        shape.offset,
                        true, // treat as cluster start
                        glyph_i > glyph_span.start,
                    ));
                    // all but first are ligature continuations
                }
                // now add the detailed glyph entry.
                glyphs.add_glyphs_for_byte_index(byte_idx, &datas);
            }

            glyph_span.start = glyph_span.end;
            byte_range.start = byte_range.end;
        }

        // this must be called after adding all glyph data; it sorts the
        // lookup table for finding detailed glyphs by associated char index.
        glyphs.finalize_changes();
    }

    fn advance_for_shaped_glyph(
        &self,
        mut advance: Au,
        character: char,
        options: &ShapingOptions,
    ) -> Au {
        if let Some(letter_spacing) = options.letter_spacing {
            advance += letter_spacing;
        };

        // CSS 2.1 ยง 16.4 states that "word spacing affects each space (U+0020) and non-breaking
        // space (U+00A0) left in the text after the white space processing rules have been
        // applied. The effect of the property on other word-separator characters is undefined."
        // We elect to only space the two required code points.
        if character == ' ' || character == '\u{a0}' {
            // https://drafts.csswg.org/css-text-3/#word-spacing-property
            advance += options.word_spacing;
        }

        advance
    }

    pub fn baseline(&self) -> Option<FontBaseline> {
        unsafe { (*self.font).table_for_tag(BASE)? };

        let mut hanging_baseline = 0;
        let mut alphabetic_baseline = 0;
        let mut ideographic_baseline = 0;

        unsafe {
            hb_ot_layout_get_baseline(
                self.hb_font,
                HB_OT_LAYOUT_BASELINE_TAG_ROMAN,
                HB_DIRECTION_LTR,
                HB_OT_TAG_DEFAULT_SCRIPT,
                HB_OT_TAG_DEFAULT_LANGUAGE,
                &mut alphabetic_baseline as *mut _,
            );

            hb_ot_layout_get_baseline(
                self.hb_font,
                HB_OT_LAYOUT_BASELINE_TAG_HANGING,
                HB_DIRECTION_LTR,
                HB_OT_TAG_DEFAULT_SCRIPT,
                HB_OT_TAG_DEFAULT_LANGUAGE,
                &mut hanging_baseline as *mut _,
            );

            hb_ot_layout_get_baseline(
                self.hb_font,
                HB_OT_LAYOUT_BASELINE_TAG_IDEO_EMBOX_BOTTOM_OR_LEFT,
                HB_DIRECTION_LTR,
                HB_OT_TAG_DEFAULT_SCRIPT,
                HB_OT_TAG_DEFAULT_LANGUAGE,
                &mut ideographic_baseline as *mut _,
            );
        }

        Some(FontBaseline {
            ideographic_baseline: Shaper::fixed_to_float(ideographic_baseline) as f32,
            alphabetic_baseline: Shaper::fixed_to_float(alphabetic_baseline) as f32,
            hanging_baseline: Shaper::fixed_to_float(hanging_baseline) as f32,
        })
    }
}

/// Callbacks from Harfbuzz when font map and glyph advance lookup needed.
struct FontFuncs(*mut hb_font_funcs_t);

unsafe impl Sync for FontFuncs {}
unsafe impl Send for FontFuncs {}

static HB_FONT_FUNCS: LazyLock<FontFuncs> = LazyLock::new(|| unsafe {
    let hb_funcs = hb_font_funcs_create();
    hb_font_funcs_set_nominal_glyph_func(hb_funcs, Some(glyph_func), ptr::null_mut(), None);
    hb_font_funcs_set_glyph_h_advance_func(
        hb_funcs,
        Some(glyph_h_advance_func),
        ptr::null_mut(),
        None,
    );

    FontFuncs(hb_funcs)
});

extern "C" fn glyph_func(
    _: *mut hb_font_t,
    font_data: *mut c_void,
    unicode: hb_codepoint_t,
    glyph: *mut hb_codepoint_t,
    _: *mut c_void,
) -> hb_bool_t {
    let font: *const Font = font_data as *const Font;
    assert!(!font.is_null());

    unsafe {
        match (*font).glyph_index(char::from_u32(unicode).unwrap()) {
            Some(g) => {
                *glyph = g as hb_codepoint_t;
                true as hb_bool_t
            },
            None => false as hb_bool_t,
        }
    }
}

extern "C" fn glyph_h_advance_func(
    _: *mut hb_font_t,
    font_data: *mut c_void,
    glyph: hb_codepoint_t,
    _: *mut c_void,
) -> hb_position_t {
    let font: *mut Font = font_data as *mut Font;
    assert!(!font.is_null());

    unsafe {
        let advance = (*font).glyph_h_advance(glyph as GlyphId);
        Shaper::float_to_fixed(advance)
    }
}

// Callback to get a font table out of a font.
extern "C" fn font_table_func(
    _: *mut hb_face_t,
    tag: hb_tag_t,
    user_data: *mut c_void,
) -> *mut hb_blob_t {
    unsafe {
        // NB: These asserts have security implications.
        let font = user_data as *const Font;
        assert!(!font.is_null());

        // TODO(Issue #197): reuse font table data, which will change the unsound trickery here.
        match (*font).table_for_tag(tag as FontTableTag) {
            None => ptr::null_mut(),
            Some(font_table) => {
                // `Box::into_raw` intentionally leaks the FontTable so we don't destroy the buffer
                // while HarfBuzz is using it.  When HarfBuzz is done with the buffer, it will pass
                // this raw pointer back to `destroy_blob_func` which will deallocate the Box.
                let font_table_ptr = Box::into_raw(Box::new(font_table));

                let buf = (*font_table_ptr).buffer();
                // HarfBuzz calls `destroy_blob_func` when the buffer is no longer needed.
                let blob = hb_blob_create(
                    buf.as_ptr() as *const c_char,
                    buf.len() as c_uint,
                    HB_MEMORY_MODE_READONLY,
                    font_table_ptr as *mut c_void,
                    Some(destroy_blob_func),
                );

                assert!(!blob.is_null());
                blob
            },
        }
    }
}

extern "C" fn destroy_blob_func(font_table_ptr: *mut c_void) {
    unsafe {
        drop(Box::from_raw(font_table_ptr as *mut FontTable));
    }
}