1use harfrust::{Buffer, Direction, Feature, ShapeOptions, ShaperFont, Tag};
2
3use crate::font::registry::FontRegistry;
4use crate::font::resolve::ResolvedFont;
5use crate::shaping::run::{ShapedGlyph, ShapedRun};
6use crate::types::FontFeature;
7
8pub fn to_harfrust_features(features: &[FontFeature]) -> Vec<Feature> {
12 features
13 .iter()
14 .map(|f| Feature::new(Tag::new(&f.tag), f.value, ..))
15 .collect()
16}
17
18fn units_per_em(bytes: &[u8], face_index: u32) -> Option<u16> {
26 let font_ref = swash::FontRef::from_index(bytes, face_index as usize)?;
27 let upem = font_ref.metrics(&[]).units_per_em;
28 if upem == 0 { None } else { Some(upem) }
29}
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
33pub enum TextDirection {
34 #[default]
36 Auto,
37 LeftToRight,
38 RightToLeft,
39}
40
41pub fn shape_text(
53 registry: &FontRegistry,
54 resolved: &ResolvedFont,
55 text: &str,
56 text_offset: usize,
57) -> Option<ShapedRun> {
58 shape_text_with_fallback(
59 registry,
60 resolved,
61 text,
62 text_offset,
63 TextDirection::Auto,
64 &[],
65 )
66}
67
68pub fn shape_text_with_fallback(
74 registry: &FontRegistry,
75 resolved: &ResolvedFont,
76 text: &str,
77 text_offset: usize,
78 direction: TextDirection,
79 features: &[Feature],
80) -> Option<ShapedRun> {
81 let mut run = shape_text_directed(registry, resolved, text, text_offset, direction, features)?;
82
83 if run.glyphs.iter().any(|g| g.glyph_id == 0) && !text.is_empty() {
85 apply_glyph_fallback(registry, resolved, text, text_offset, features, &mut run);
86 }
87
88 Some(run)
89}
90
91fn apply_glyph_fallback(
109 registry: &FontRegistry,
110 primary: &ResolvedFont,
111 text: &str,
112 text_offset: usize,
113 features: &[Feature],
114 run: &mut ShapedRun,
115) {
116 use crate::font::resolve::find_fallback_font;
117
118 let mut spans: Vec<std::ops::Range<usize>> = Vec::new();
120 let mut i = 0;
121 while i < run.glyphs.len() {
122 if run.glyphs[i].glyph_id == 0 {
123 let start = i;
124 while i < run.glyphs.len() && run.glyphs[i].glyph_id == 0 {
125 i += 1;
126 }
127 spans.push(start..i);
128 } else {
129 i += 1;
130 }
131 }
132 if spans.is_empty() {
133 return;
134 }
135
136 for span in spans.into_iter().rev() {
138 let Some((byte_start, byte_end)) = notdef_char_range(&run.glyphs, &span, text) else {
139 continue;
140 };
141 let Some(slice) = text.get(byte_start..byte_end) else {
142 continue;
143 };
144 let Some(first_char) = slice.chars().next() else {
145 continue;
146 };
147
148 let Some(fallback_id) = find_fallback_font(registry, first_char, primary.font_face_id)
149 else {
150 continue; };
152 let Some(fallback_entry) = registry.get(fallback_id) else {
153 continue;
154 };
155
156 let fallback_resolved = ResolvedFont {
157 font_face_id: fallback_id,
158 size_px: primary.size_px,
159 face_index: fallback_entry.face_index,
160 swash_cache_key: fallback_entry.swash_cache_key,
161 scale_factor: primary.scale_factor,
162 weight: primary.weight,
163 };
164
165 let Some(fallback_run) = shape_text_directed(
166 registry,
167 &fallback_resolved,
168 slice,
169 text_offset + byte_start,
170 run.direction,
171 features,
172 ) else {
173 continue;
174 };
175 if fallback_run.glyphs.is_empty() {
176 continue;
177 }
178
179 let replacement: Vec<ShapedGlyph> = fallback_run
182 .glyphs
183 .into_iter()
184 .map(|mut g| {
185 g.cluster += byte_start as u32;
186 g.font_face_id = fallback_id;
187 g
188 })
189 .collect();
190
191 run.glyphs.splice(span, replacement);
192 }
193
194 run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
195}
196
197fn notdef_char_range(
207 glyphs: &[ShapedGlyph],
208 span: &std::ops::Range<usize>,
209 text: &str,
210) -> Option<(usize, usize)> {
211 let inside = glyphs.get(span.clone())?;
212 let start = inside.iter().map(|g| g.cluster as usize).min()?;
213 let last = inside.iter().map(|g| g.cluster as usize).max()?;
214
215 let end = glyphs
216 .iter()
217 .enumerate()
218 .filter(|(i, _)| !span.contains(i))
219 .map(|(_, g)| g.cluster as usize)
220 .filter(|&c| c > last)
221 .min()
222 .unwrap_or(text.len());
223
224 if start >= end || !text.is_char_boundary(start) || !text.is_char_boundary(end) {
225 return None;
226 }
227 Some((start, end))
228}
229
230pub fn shape_text_directed(
232 registry: &FontRegistry,
233 resolved: &ResolvedFont,
234 text: &str,
235 text_offset: usize,
236 direction: TextDirection,
237 features: &[Feature],
238) -> Option<ShapedRun> {
239 let entry = registry.get(resolved.font_face_id)?;
240 let font = entry.shaping_font()?;
241
242 let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
243 if upem == 0.0 {
244 return None;
245 }
246 let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
249 let physical_size = resolved.size_px * sf;
250 let physical_scale = physical_size / upem;
251 let inv_sf = 1.0 / sf;
252
253 let mut buffer = Buffer::new();
254 buffer.push_str(text);
255 match direction {
256 TextDirection::LeftToRight => buffer.set_direction(Direction::LeftToRight),
257 TextDirection::RightToLeft => buffer.set_direction(Direction::RightToLeft),
258 TextDirection::Auto => {}
259 }
260 buffer.guess_segment_properties();
272
273 let resolved_direction = if buffer.direction() == Direction::RightToLeft {
276 TextDirection::RightToLeft
277 } else {
278 TextDirection::LeftToRight
279 };
280
281 harfrust::shape(
285 &ShaperFont::new(font),
286 &mut buffer,
287 ShapeOptions::new().features(features),
288 )
289 .ok()?;
290
291 let infos = buffer.glyph_infos();
292 let positions = buffer.glyph_positions();
293
294 let mut glyphs = Vec::with_capacity(infos.len());
295 let mut total_advance = 0.0f32;
296
297 for (info, pos) in infos.iter().zip(positions.iter()) {
298 let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
299 let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
300 let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
301 let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
302
303 glyphs.push(ShapedGlyph {
304 glyph_id: info.glyph_id as u16,
305 cluster: info.cluster,
306 x_advance,
307 y_advance,
308 x_offset,
309 y_offset,
310 font_face_id: resolved.font_face_id,
311 });
312
313 total_advance += x_advance;
314 }
315
316 Some(ShapedRun {
317 font_face_id: resolved.font_face_id,
318 size_px: resolved.size_px,
319 weight: resolved.weight,
320 glyphs,
321 advance_width: total_advance,
322 text_range: text_offset..text_offset + text.len(),
323 direction: resolved_direction,
324 bidi_level: if resolved_direction == TextDirection::RightToLeft {
325 1
326 } else {
327 0
328 },
329 underline_style: crate::types::UnderlineStyle::None,
330 overline: false,
331 strikeout: false,
332 is_link: false,
333 foreground_color: None,
334 underline_color: None,
335 background_color: None,
336 anchor_href: None,
337 tooltip: None,
338 vertical_alignment: crate::types::VerticalAlignment::Normal,
339 image_name: None,
340 image_height: 0.0,
341 })
342}
343
344pub fn shape_text_with_buffer(
346 registry: &FontRegistry,
347 resolved: &ResolvedFont,
348 text: &str,
349 text_offset: usize,
350 buffer: Buffer,
351 features: &[Feature],
352) -> Option<(ShapedRun, Buffer)> {
353 let entry = registry.get(resolved.font_face_id)?;
354 let font = entry.shaping_font()?;
355
356 let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
357 if upem == 0.0 {
358 return None;
359 }
360 let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
361 let physical_size = resolved.size_px * sf;
362 let physical_scale = physical_size / upem;
363 let inv_sf = 1.0 / sf;
364
365 let mut buffer = buffer;
366 buffer.push_str(text);
367 buffer.guess_segment_properties();
370
371 let resolved_direction = if buffer.direction() == Direction::RightToLeft {
372 TextDirection::RightToLeft
373 } else {
374 TextDirection::LeftToRight
375 };
376
377 harfrust::shape(
378 &ShaperFont::new(font),
379 &mut buffer,
380 ShapeOptions::new().features(features),
381 )
382 .ok()?;
383
384 let infos = buffer.glyph_infos();
385 let positions = buffer.glyph_positions();
386
387 let mut glyphs = Vec::with_capacity(infos.len());
388 let mut total_advance = 0.0f32;
389
390 for (info, pos) in infos.iter().zip(positions.iter()) {
391 let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
392 let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
393 let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
394 let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
395
396 glyphs.push(ShapedGlyph {
397 glyph_id: info.glyph_id as u16,
398 cluster: info.cluster,
399 x_advance,
400 y_advance,
401 x_offset,
402 y_offset,
403 font_face_id: resolved.font_face_id,
404 });
405
406 total_advance += x_advance;
407 }
408
409 let run = ShapedRun {
410 font_face_id: resolved.font_face_id,
411 size_px: resolved.size_px,
412 weight: resolved.weight,
413 glyphs,
414 advance_width: total_advance,
415 text_range: text_offset..text_offset + text.len(),
416 direction: resolved_direction,
417 bidi_level: if resolved_direction == TextDirection::RightToLeft {
418 1
419 } else {
420 0
421 },
422 underline_style: crate::types::UnderlineStyle::None,
423 overline: false,
424 strikeout: false,
425 is_link: false,
426 foreground_color: None,
427 underline_color: None,
428 background_color: None,
429 anchor_href: None,
430 tooltip: None,
431 vertical_alignment: crate::types::VerticalAlignment::Normal,
432 image_name: None,
433 image_height: 0.0,
434 };
435
436 buffer.clear();
439 Some((run, buffer))
440}
441
442pub struct FontMetricsPx {
443 pub ascent: f32,
444 pub descent: f32,
445 pub leading: f32,
446 pub underline_offset: f32,
447 pub strikeout_offset: f32,
448 pub stroke_size: f32,
449}
450
451pub fn font_metrics_px(registry: &FontRegistry, resolved: &ResolvedFont) -> Option<FontMetricsPx> {
456 let entry = registry.get(resolved.font_face_id)?;
457 let font_ref = swash::FontRef::from_index(entry.bytes(), entry.face_index as usize)?;
458 let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
459 let physical_size = resolved.size_px * sf;
460 let metrics = font_ref.metrics(&[]).scale(physical_size);
461 let inv_sf = 1.0 / sf;
462
463 Some(FontMetricsPx {
464 ascent: metrics.ascent * inv_sf,
465 descent: metrics.descent * inv_sf,
466 leading: metrics.leading * inv_sf,
467 underline_offset: metrics.underline_offset * inv_sf,
468 strikeout_offset: metrics.strikeout_offset * inv_sf,
469 stroke_size: metrics.stroke_size * inv_sf,
470 })
471}
472
473pub struct BidiRun {
475 pub byte_range: std::ops::Range<usize>,
476 pub direction: TextDirection,
477 pub visual_order: usize,
479 pub level: u8,
487}
488
489pub struct BidiParagraph {
499 pub runs: Vec<BidiRun>,
501 pub para_level: u8,
504}
505
506impl BidiParagraph {
507 pub fn base_direction(&self) -> TextDirection {
509 if self.para_level % 2 == 1 {
510 TextDirection::RightToLeft
511 } else {
512 TextDirection::LeftToRight
513 }
514 }
515}
516
517fn base_para_level(base: TextDirection) -> Option<unicode_bidi::Level> {
526 match base {
527 TextDirection::Auto => None,
528 TextDirection::LeftToRight => Some(unicode_bidi::Level::ltr()),
529 TextDirection::RightToLeft => Some(unicode_bidi::Level::rtl()),
530 }
531}
532
533pub fn analyze_paragraph(text: &str, base: TextDirection) -> BidiParagraph {
539 use unicode_bidi::BidiInfo;
540
541 if text.is_empty() {
542 return BidiParagraph {
543 runs: Vec::new(),
544 para_level: base_para_level(base).map_or(0, |l| l.number()),
545 };
546 }
547
548 let bidi_info = BidiInfo::new(text, base_para_level(base));
549
550 let para_level = bidi_info
554 .paragraphs
555 .first()
556 .map(|p| p.level.number())
557 .or_else(|| base_para_level(base).map(|l| l.number()))
558 .unwrap_or(0);
559
560 let mut starts: Vec<(usize, u8)> = Vec::new();
564 for (idx, _) in text.char_indices() {
565 let level = bidi_info.levels[idx].number();
566 if starts.last().map(|&(_, l)| l) != Some(level) {
567 starts.push((idx, level));
568 }
569 }
570
571 let ends = starts
573 .iter()
574 .skip(1)
575 .map(|&(start, _)| start)
576 .chain(std::iter::once(text.len()));
577
578 let runs: Vec<BidiRun> = starts
579 .iter()
580 .zip(ends)
581 .map(|(&(start, level), end)| BidiRun {
582 byte_range: start..end,
583 direction: if level % 2 == 1 {
584 TextDirection::RightToLeft
585 } else {
586 TextDirection::LeftToRight
587 },
588 visual_order: 0,
594 level,
595 })
596 .collect();
597
598 BidiParagraph { runs, para_level }
599}
600
601pub fn visual_order(levels: &[u8]) -> Vec<usize> {
608 let mut order: Vec<usize> = (0..levels.len()).collect();
609 let Some(&max) = levels.iter().max() else {
610 return order;
611 };
612 let Some(min_odd) = levels.iter().copied().filter(|l| l % 2 == 1).min() else {
614 return order;
615 };
616
617 let mut level = max;
618 while level >= min_odd {
619 let mut i = 0;
620 while i < order.len() {
621 if levels[order[i]] >= level {
622 let start = i;
623 while i < order.len() && levels[order[i]] >= level {
624 i += 1;
625 }
626 order[start..i].reverse();
627 } else {
628 i += 1;
629 }
630 }
631 level -= 1;
633 }
634 order
635}
636
637pub fn bidi_runs(text: &str) -> Vec<BidiRun> {
645 use unicode_bidi::BidiInfo;
646
647 if text.is_empty() {
648 return Vec::new();
649 }
650
651 let bidi_info = BidiInfo::new(text, None);
652 let mut runs = Vec::new();
653
654 for para in &bidi_info.paragraphs {
655 let (levels, level_runs) = bidi_info.visual_runs(para, para.range.clone());
656 for level_run in level_runs {
657 if level_run.is_empty() {
658 continue;
659 }
660 let level = levels[level_run.start];
661 let direction = if level.is_rtl() {
662 TextDirection::RightToLeft
663 } else {
664 TextDirection::LeftToRight
665 };
666 let visual_order = runs.len();
667 runs.push(BidiRun {
668 byte_range: level_run,
669 direction,
670 visual_order,
671 level: level.number(),
672 });
673 }
674 }
675
676 if runs.is_empty() {
677 runs.push(BidiRun {
678 byte_range: 0..text.len(),
679 direction: TextDirection::LeftToRight,
680 visual_order: 0,
681 level: 0,
682 });
683 }
684
685 runs
686}
687
688#[cfg(test)]
689mod bidi_tests {
690 use super::*;
691
692 const ARABIC: &str = "\u{0643}\u{062A}\u{0628}"; const HEBREW: &str = "\u{05E9}\u{05DC}\u{05D5}\u{05DD}"; #[test]
696 fn rule_l2_leaves_all_ltr_text_alone() {
697 assert_eq!(visual_order(&[0, 0, 0]), vec![0, 1, 2]);
698 assert_eq!(visual_order(&[]), Vec::<usize>::new());
699 }
700
701 #[test]
702 fn rule_l2_reverses_a_run_of_rtl() {
703 assert_eq!(visual_order(&[0, 1, 1, 0]), vec![0, 2, 1, 3]);
706 }
707
708 #[test]
709 fn rule_l2_nests_an_ltr_island_inside_rtl() {
710 let levels = [0, 1, 2, 2, 1, 0];
715 assert_eq!(visual_order(&levels), vec![0, 4, 2, 3, 1, 5]);
716 }
717
718 #[test]
719 fn rule_l2_reverses_the_whole_line_in_an_rtl_paragraph() {
720 assert_eq!(visual_order(&[1, 2, 1]), vec![2, 1, 0]);
723 }
724
725 #[test]
726 fn a_leading_digit_does_not_fool_auto_detection() {
727 let text = "123 \u{0643}\u{062A}\u{0628}";
732 assert_eq!(analyze_paragraph(text, TextDirection::Auto).para_level, 1);
733 }
734
735 #[test]
736 fn an_explicit_base_direction_overrides_first_strong_detection() {
737 let text = "NASA \u{0623}\u{0639}\u{0644}\u{0646}\u{062A}";
742 assert_eq!(
743 analyze_paragraph(text, TextDirection::Auto).para_level,
744 0,
745 "auto-detection is expected to get this one wrong"
746 );
747
748 let forced = analyze_paragraph(text, TextDirection::RightToLeft);
749 assert_eq!(forced.para_level, 1);
750 assert_eq!(forced.base_direction(), TextDirection::RightToLeft);
751
752 let auto = analyze_paragraph(text, TextDirection::Auto);
757 let first_visual = |p: &BidiParagraph| {
758 let levels: Vec<u8> = p.runs.iter().map(|r| r.level).collect();
759 visual_order(&levels).first().map(|&i| p.runs[i].direction)
760 };
761 assert_eq!(first_visual(&auto), Some(TextDirection::LeftToRight));
762 assert_eq!(first_visual(&forced), Some(TextDirection::RightToLeft));
763 }
764
765 #[test]
766 fn pure_arabic_auto_detects_as_rtl() {
767 let para = analyze_paragraph(ARABIC, TextDirection::Auto);
768 assert_eq!(para.base_direction(), TextDirection::RightToLeft);
769 assert_eq!(para.runs.len(), 1);
770 assert_eq!(para.runs[0].direction, TextDirection::RightToLeft);
771 assert_eq!(para.runs[0].byte_range, 0..ARABIC.len());
772 }
773
774 #[test]
775 fn runs_come_back_in_logical_order_and_cover_the_text() {
776 let text = format!("hello {HEBREW} world");
778 let para = analyze_paragraph(&text, TextDirection::Auto);
779
780 assert!(para.runs.len() >= 2, "expected a directional split");
781 assert_eq!(para.runs[0].byte_range.start, 0);
782 assert_eq!(para.runs.last().unwrap().byte_range.end, text.len());
783 for pair in para.runs.windows(2) {
784 assert_eq!(
785 pair[0].byte_range.end, pair[1].byte_range.start,
786 "runs must tile the text with no gap or overlap"
787 );
788 assert!(
789 pair[0].byte_range.start < pair[1].byte_range.start,
790 "runs must be in logical order"
791 );
792 }
793 assert!(
794 para.runs
795 .iter()
796 .any(|r| r.direction == TextDirection::RightToLeft),
797 "the Hebrew span should have produced an RTL run"
798 );
799 }
800
801 #[test]
802 fn run_boundaries_never_split_a_multibyte_character() {
803 let text = format!("a{ARABIC}b{HEBREW}c");
804 for run in analyze_paragraph(&text, TextDirection::Auto).runs {
805 assert!(
806 text.is_char_boundary(run.byte_range.start)
807 && text.is_char_boundary(run.byte_range.end),
808 "run {:?} splits a character in {text:?}",
809 run.byte_range
810 );
811 }
812 }
813
814 #[test]
815 fn rule_l2_over_a_real_paragraph_is_a_permutation() {
816 let text = format!("hello {HEBREW} world {ARABIC} end");
817 let para = analyze_paragraph(&text, TextDirection::Auto);
818 let levels: Vec<u8> = para.runs.iter().map(|r| r.level).collect();
819
820 let mut seen = visual_order(&levels);
821 seen.sort_unstable();
822 assert_eq!(
823 seen,
824 (0..para.runs.len()).collect::<Vec<_>>(),
825 "every run must appear exactly once in the visual order"
826 );
827 }
828
829 #[test]
830 fn empty_text_analyzes_without_panicking() {
831 let para = analyze_paragraph("", TextDirection::RightToLeft);
832 assert!(para.runs.is_empty());
833 assert_eq!(para.para_level, 1);
834 }
835}