Skip to main content

text_typeset/shaping/
shaper.rs

1use harfrust::{Buffer, Direction, Feature, ShapeOptions, ShaperFont, Tag};
2
3use crate::font::color::{GlyphPaint, glyph_paint};
4use crate::font::registry::FontRegistry;
5use crate::font::resolve::{
6    FaceStyle, Presentation, ResolvedFont, face_covers, find_fallback_face,
7};
8use crate::font::script_fallback::{ScriptContext, preferred_families};
9use crate::font::synthesis;
10use crate::shaping::emoji;
11use crate::shaping::run::{ShapedGlyph, ShapedRun};
12use crate::types::FontFaceId;
13use crate::types::FontFeature;
14
15/// Convert public [`FontFeature`] toggles into harfrust [`Feature`]s,
16/// applied across the whole shaped string (global range). Script-mandated
17/// features apply regardless; these are the discretionary toggles.
18pub fn to_harfrust_features(features: &[FontFeature]) -> Vec<Feature> {
19    features
20        .iter()
21        .map(|f| Feature::new(Tag::new(&f.tag), f.value, ..))
22        .collect()
23}
24
25/// Read units-per-em for a font face.
26///
27/// `harfrust::FontRef` is a thin wrapper over read-fonts and exposes
28/// the `head` table only through the `read_fonts::TableProvider` trait,
29/// which harfrust doesn't re-export. Since we already depend on swash
30/// for `font_metrics_px` further down, we reuse swash's `Metrics` to
31/// pull UPEM — one less dependency surface to maintain.
32fn units_per_em(bytes: &[u8], face_index: u32) -> Option<u16> {
33    let font_ref = swash::FontRef::from_index(bytes, face_index as usize)?;
34    let upem = font_ref.metrics(&[]).units_per_em;
35    if upem == 0 { None } else { Some(upem) }
36}
37
38/// Text direction for shaping.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
40pub enum TextDirection {
41    /// Auto-detect from text content (default).
42    #[default]
43    Auto,
44    LeftToRight,
45    RightToLeft,
46}
47
48/// Shape a text string with the given resolved font.
49///
50/// Returns a ShapedRun with glyph IDs and pixel-space positions.
51/// The `text_offset` is the byte offset of this text within the block
52/// (used for cluster mapping back to document positions).
53/// Shape a text string with automatic glyph fallback.
54///
55/// After shaping with the primary font, any .notdef glyphs (glyph_id==0)
56/// are detected and re-shaped with fallback fonts. If no fallback font
57/// covers a character, it remains as .notdef (renders as blank space
58/// with correct advance).
59pub fn shape_text(
60    registry: &FontRegistry,
61    resolved: &ResolvedFont,
62    text: &str,
63    text_offset: usize,
64) -> Option<ShapedRun> {
65    shape_text_with_fallback(
66        registry,
67        resolved,
68        text,
69        text_offset,
70        TextDirection::Auto,
71        &[],
72    )
73}
74
75/// Shape text with an explicit direction and glyph fallback.
76///
77/// Like `shape_text`, but caller supplies the direction instead of letting
78/// rustybuzz guess. Used by the bidi-aware layout path, which splits text
79/// into directional runs before shaping.
80pub fn shape_text_with_fallback(
81    registry: &FontRegistry,
82    resolved: &ResolvedFont,
83    text: &str,
84    text_offset: usize,
85    direction: TextDirection,
86    features: &[Feature],
87) -> Option<ShapedRun> {
88    shape_text_in_paragraph(
89        registry,
90        resolved,
91        text,
92        text_offset,
93        direction,
94        features,
95        &ScriptContext::new(text, None),
96        0,
97    )
98}
99
100/// [`shape_text_with_fallback`] for text that is part of a paragraph: the
101/// paragraph and the language its block is in (`context`), and the byte
102/// where `text` starts in the paragraph (`para_pos`), decide which faces
103/// fallback prefers for Han (see [`crate::font::script_fallback`]).
104#[allow(clippy::too_many_arguments)]
105pub(crate) fn shape_text_in_paragraph(
106    registry: &FontRegistry,
107    resolved: &ResolvedFont,
108    text: &str,
109    text_offset: usize,
110    direction: TextDirection,
111    features: &[Feature],
112    context: &ScriptContext<'_>,
113    para_pos: usize,
114) -> Option<ShapedRun> {
115    let mut run = shape_text_directed_in(
116        registry,
117        resolved,
118        text,
119        text_offset,
120        direction,
121        features,
122        context.language_tag(),
123    )?;
124    blank_hard_breaks(text, &mut run);
125
126    // Look for another face for every glyph the primary font lacks (a hard
127    // break is glyph 0 on purpose and needs none) and every emoji it does not
128    // draw in colour.
129    let may_need = run.glyphs.iter().any(|g| g.glyph_id == 0) || emoji::may_contain_emoji(text);
130    let needs = if may_need {
131        fallback_needs(registry, text, &run)
132    } else {
133        Vec::new()
134    };
135    if needs.iter().any(|n| n.needed) {
136        let style = FaceStyle::of_face(registry, resolved.font_face_id, resolved.weight);
137        apply_glyph_fallback(
138            registry,
139            resolved,
140            style,
141            text,
142            text_offset,
143            features,
144            &mut run,
145            &needs,
146            &[resolved.font_face_id],
147            context,
148            para_pos,
149            0,
150        );
151        // A break beside a character the primary font lacks is re-shaped with
152        // it, in a font that may well draw it.
153        blank_hard_breaks(text, &mut run);
154    }
155
156    Some(run)
157}
158
159/// Whether `glyph` stands for a hard line break of `text`, the text its run was shaped
160/// from.
161fn is_hard_break_glyph(text: &str, glyph: &ShapedGlyph) -> bool {
162    text.get(glyph.cluster as usize..)
163        .and_then(|rest| rest.chars().next())
164        .is_some_and(crate::types::is_hard_break)
165}
166
167/// Lay out every hard line break in `run` as nothing: glyph 0, which is never
168/// drawn, with no advance and no offset (see [`crate::types::is_hard_break`]).
169/// Returns how many there are.
170///
171/// A font draws a line separator as it likes (a box, a pilcrow) or not at all,
172/// and gives it whatever advance it likes, which pushed a right-aligned or
173/// centred line off its place by that much.
174fn blank_hard_breaks(text: &str, run: &mut ShapedRun) -> usize {
175    let mut count = 0;
176    for glyph in &mut run.glyphs {
177        if is_hard_break_glyph(text, glyph) {
178            glyph.glyph_id = 0;
179            glyph.x_advance = 0.0;
180            glyph.x_offset = 0.0;
181            glyph.y_offset = 0.0;
182            count += 1;
183        }
184    }
185    if count > 0 {
186        run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
187    }
188    count
189}
190
191/// How deep fallback goes: the part of a span its fallback face does not
192/// draw is handed to another face, and what that one cannot draw to another,
193/// each time with every face tried so far left out. A span of one script
194/// takes one face and a mixed one (Han then Hangul, say) a second; the cap
195/// only bounds a pathological font set.
196const MAX_FALLBACK_DEPTH: usize = 6;
197
198/// What fallback makes of one glyph of a shaped run.
199#[derive(Debug, Clone, Copy)]
200struct FallbackNeed {
201    /// Whether another face is looked for.
202    needed: bool,
203    /// Whether the glyph has no glyph at all (`.notdef`), as against one that
204    /// is drawn but not as it should be (an emoji drawn in monochrome).
205    missing: bool,
206    /// Whether the glyph's cluster asks for emoji presentation.
207    emoji: bool,
208}
209
210/// Decide, glyph by glyph, which glyphs of `run` (shaped from `text`) want
211/// another face: those with no glyph, and those of an emoji cluster drawn
212/// in anything but colour. A hard break needs none.
213fn fallback_needs(registry: &FontRegistry, text: &str, run: &ShapedRun) -> Vec<FallbackNeed> {
214    let emoji = emoji_clusters(text, &run.glyphs);
215    run.glyphs
216        .iter()
217        .zip(emoji)
218        .map(|(glyph, emoji)| {
219            if is_hard_break_glyph(text, glyph) {
220                return FallbackNeed {
221                    needed: false,
222                    missing: false,
223                    emoji,
224                };
225            }
226            let missing = glyph.glyph_id == 0;
227            let not_in_color = emoji
228                && !missing
229                && registry
230                    .get(glyph.font_face_id)
231                    .is_some_and(|entry| glyph_paint(entry, glyph.glyph_id) != GlyphPaint::Color);
232            FallbackNeed {
233                needed: missing || not_in_color,
234                missing,
235                emoji,
236            }
237        })
238        .collect()
239}
240
241/// For each glyph of `glyphs` (shaped from `text`), whether its cluster asks
242/// for emoji presentation (see [`crate::shaping::emoji`]).
243fn emoji_clusters(text: &str, glyphs: &[ShapedGlyph]) -> Vec<bool> {
244    if !emoji::may_contain_emoji(text) {
245        return vec![false; glyphs.len()];
246    }
247    // A cluster runs from its own start to the next start in the text, which
248    // works for an RTL run too, whose glyphs carry descending clusters.
249    let mut starts: Vec<usize> = glyphs.iter().map(|g| g.cluster as usize).collect();
250    starts.sort_unstable();
251    starts.dedup();
252    glyphs
253        .iter()
254        .map(|g| {
255            let start = g.cluster as usize;
256            let end = match starts.binary_search(&start) {
257                Ok(i) => starts.get(i + 1).copied().unwrap_or(text.len()),
258                Err(_) => text.len(),
259            };
260            text.get(start..end).is_some_and(emoji::cluster_wants_emoji)
261        })
262        .collect()
263}
264
265/// Re-shape the glyphs of `run` that need another face in fallback fonts.
266///
267/// Works on **spans** of consecutive glyphs that need one, not on glyphs one
268/// at a time: each span is mapped back to the character range that produced
269/// it and that whole range is re-shaped in the fallback font, then spliced
270/// in.
271///
272/// Shaping a span as a unit is what makes complex scripts survive fallback.
273/// Re-shaping character by character, which this used to do, cannot join
274/// Arabic, because a letter shaped alone has no neighbours and can only take
275/// its isolated form. It also kept only the *first* glyph of each result, so
276/// any letter whose isolated form is a base plus a mark lost the mark. An
277/// Arabic word set in a font without Arabic came out as disconnected,
278/// dotless stumps.
279///
280/// A span is cut where emoji presentation starts or stops, so that an emoji
281/// after CJK text gets a face of its own rather than the CJK font's
282/// `.notdef`. The span is re-shaped in the face found for its first
283/// character, and whatever that face does not draw goes through the same
284/// steps again, with every face tried so far left out: before, a span was
285/// shaped in one face and what that face lacked stayed blank. When the face
286/// found for the first character a span's face lacks draws the whole span,
287/// the span is set in that face instead, so that a word is not split
288/// between two CJK fonts of different designs.
289///
290/// Every face is chosen to match `style`, the weight, style and width of the
291/// text (see [`find_fallback_face`]), and for kana, hangul and Han among the
292/// faces the system ships for their language first, which for Han is found
293/// in `context`, the paragraph `text` starts at byte `para_pos` of (see
294/// [`crate::font::script_fallback`]).
295///
296/// A span is re-shaped with the run's own direction rather than `Auto`, so
297/// the substituted glyphs come back in the same visual order as the ones
298/// around them.
299#[allow(clippy::too_many_arguments)]
300fn apply_glyph_fallback(
301    registry: &FontRegistry,
302    primary: &ResolvedFont,
303    style: FaceStyle,
304    text: &str,
305    text_offset: usize,
306    features: &[Feature],
307    run: &mut ShapedRun,
308    needs: &[FallbackNeed],
309    tried: &[FontFaceId],
310    context: &ScriptContext<'_>,
311    para_pos: usize,
312    depth: usize,
313) {
314    // The faces the fallback table prefers for the character at byte `at` of
315    // `text`.
316    let preferred = |ch: char, at: usize| {
317        preferred_families(
318            ch,
319            context,
320            para_pos + at,
321            registry.default_language(),
322            registry.fallback_platform(),
323        )
324    };
325    // Maximal spans of consecutive glyphs that need a face, cut where emoji
326    // presentation changes. A hard break needs none and so ends a span:
327    // inside one it would choose the span's font, since a span is re-shaped
328    // in the font that draws its first character, and a character beside it
329    // would lose its own.
330    let mut spans: Vec<(std::ops::Range<usize>, bool)> = Vec::new();
331    let mut i = 0;
332    while i < needs.len() {
333        if !needs[i].needed {
334            i += 1;
335            continue;
336        }
337        let start = i;
338        let emoji = needs[i].emoji;
339        while i < needs.len() && needs[i].needed && needs[i].emoji == emoji {
340            i += 1;
341        }
342        spans.push((start..i, emoji));
343    }
344    if spans.is_empty() {
345        return;
346    }
347
348    // Splice from the back so earlier ranges stay valid as lengths change.
349    for (span, emoji) in spans.into_iter().rev() {
350        let any_missing = needs[span.clone()].iter().any(|n| n.missing);
351        let Some((byte_start, byte_end)) = span_char_range(&run.glyphs, &span, text) else {
352            continue;
353        };
354        let Some(slice) = text.get(byte_start..byte_end) else {
355            continue;
356        };
357        let Some(first_char) = slice.chars().next() else {
358            continue;
359        };
360
361        // An emoji drawn in monochrome is left out with the faces tried
362        // already, so the search is for a face that draws it otherwise.
363        let mut excluded: Vec<FontFaceId> = tried.to_vec();
364        for glyph in &run.glyphs[span.clone()] {
365            if !excluded.contains(&glyph.font_face_id) {
366                excluded.push(glyph.font_face_id);
367            }
368        }
369        let presentation = if emoji {
370            Presentation::Emoji
371        } else {
372            Presentation::Text
373        };
374        let Some((mut fallback_id, paint)) = find_fallback_face(
375            registry,
376            first_char,
377            presentation,
378            style,
379            &excluded,
380            preferred(first_char, byte_start),
381        ) else {
382            continue; // no fallback available: leave the span as it is
383        };
384        // An emoji already drawn, if in monochrome, is only worth replacing
385        // by one drawn in colour.
386        if emoji && !any_missing && paint != GlyphPaint::Color {
387            continue;
388        }
389
390        let reshape = |face: FontFaceId| -> Option<(ResolvedFont, ShapedRun)> {
391            let entry = registry.get(face)?;
392            let resolved = ResolvedFont {
393                font_face_id: face,
394                size_px: primary.size_px,
395                face_index: entry.face_index,
396                swash_cache_key: entry.swash_cache_key,
397                scale_factor: primary.scale_factor,
398                weight: primary.weight,
399                italic: primary.italic,
400            };
401            // Clusters come back local to `slice`.
402            let run = shape_text_directed_in(
403                registry,
404                &resolved,
405                slice,
406                text_offset + byte_start,
407                run.direction,
408                features,
409                context.language_tag(),
410            )?;
411            (!run.glyphs.is_empty()).then_some((resolved, run))
412        };
413        let Some((mut fallback_resolved, mut fallback_run)) = reshape(fallback_id) else {
414            continue;
415        };
416        blank_hard_breaks(slice, &mut fallback_run);
417
418        excluded.push(fallback_id);
419        let mut still = fallback_needs(registry, slice, &fallback_run);
420        if !emoji
421            && let Some((at, lacking)) = fallback_run
422                .glyphs
423                .iter()
424                .zip(&still)
425                .find(|(_, n)| n.missing)
426                .and_then(|(g, _)| {
427                    let at = g.cluster as usize;
428                    Some((at, slice.get(at..)?.chars().next()?))
429                })
430            && let Some((whole_id, _)) = find_fallback_face(
431                registry,
432                lacking,
433                Presentation::Text,
434                style,
435                &excluded,
436                preferred(lacking, byte_start + at),
437            )
438            && face_covers(registry, whole_id, slice)
439            && let Some((resolved, mut whole_run)) = reshape(whole_id)
440        {
441            blank_hard_breaks(slice, &mut whole_run);
442            fallback_id = whole_id;
443            fallback_resolved = resolved;
444            fallback_run = whole_run;
445            excluded.push(fallback_id);
446            still = fallback_needs(registry, slice, &fallback_run);
447        }
448
449        if depth < MAX_FALLBACK_DEPTH && still.iter().any(|n| n.needed) {
450            apply_glyph_fallback(
451                registry,
452                &fallback_resolved,
453                style,
454                slice,
455                text_offset + byte_start,
456                features,
457                &mut fallback_run,
458                &still,
459                &excluded,
460                context,
461                para_pos + byte_start,
462                depth + 1,
463            );
464        }
465
466        // Lift the clusters from `slice` into `text` space, which is what the
467        // rest of the pipeline expects of this run. Each glyph keeps the face
468        // it was shaped in, which deeper fallback may have changed.
469        let replacement: Vec<ShapedGlyph> = fallback_run
470            .glyphs
471            .into_iter()
472            .map(|mut g| {
473                g.cluster += byte_start as u32;
474                g
475            })
476            .collect();
477
478        run.glyphs.splice(span, replacement);
479    }
480
481    run.advance_width = run.glyphs.iter().map(|g| g.x_advance).sum();
482}
483
484/// The byte range of `text` that a span of consecutive glyphs covers.
485///
486/// Glyphs sit in visual order, so clusters ascend across an LTR run and
487/// descend across an RTL one. Taking the min and max over the span rather
488/// than its first and last glyph keeps this direction-agnostic.
489///
490/// The span's end is the nearest cluster *after* it among the glyphs outside
491/// it (the start of whatever follows it in the text), or the end of the text
492/// when the span runs to the edge.
493fn span_char_range(
494    glyphs: &[ShapedGlyph],
495    span: &std::ops::Range<usize>,
496    text: &str,
497) -> Option<(usize, usize)> {
498    let inside = glyphs.get(span.clone())?;
499    let start = inside.iter().map(|g| g.cluster as usize).min()?;
500    let last = inside.iter().map(|g| g.cluster as usize).max()?;
501
502    let end = glyphs
503        .iter()
504        .enumerate()
505        .filter(|(i, _)| !span.contains(i))
506        .map(|(_, g)| g.cluster as usize)
507        .filter(|&c| c > last)
508        .min()
509        .unwrap_or(text.len());
510
511    if start >= end || !text.is_char_boundary(start) || !text.is_char_boundary(end) {
512        return None;
513    }
514    Some((start, end))
515}
516
517/// Shape text with an explicit direction.
518pub fn shape_text_directed(
519    registry: &FontRegistry,
520    resolved: &ResolvedFont,
521    text: &str,
522    text_offset: usize,
523    direction: TextDirection,
524    features: &[Feature],
525) -> Option<ShapedRun> {
526    shape_text_directed_in(
527        registry,
528        resolved,
529        text,
530        text_offset,
531        direction,
532        features,
533        None,
534    )
535}
536
537/// The language the shaper is told `tag` (a BCP 47 tag) names, `None` for
538/// no tag. The shaper picks a font's language-specific forms with it
539/// (OpenType `locl`: Serbian and Bulgarian Cyrillic, Romanian comma-below
540/// letters, the Persian and Urdu forms of Arabic letters and digits, a
541/// pan-CJK face's regional glyphs).
542fn shaping_language(tag: Option<&str>) -> Option<harfrust::Language> {
543    tag.map(str::trim)
544        .filter(|t| !t.is_empty())
545        .and_then(|t| t.parse::<harfrust::Language>().ok())
546}
547
548/// [`shape_text_directed`] for text in `language`, a BCP 47 tag.
549#[allow(clippy::too_many_arguments)]
550pub(crate) fn shape_text_directed_in(
551    registry: &FontRegistry,
552    resolved: &ResolvedFont,
553    text: &str,
554    text_offset: usize,
555    direction: TextDirection,
556    features: &[Feature],
557    language: Option<&str>,
558) -> Option<ShapedRun> {
559    let entry = registry.get(resolved.font_face_id)?;
560    let font = entry.shaping_font()?;
561
562    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
563    if upem == 0.0 {
564        return None;
565    }
566    // Shape at physical ppem, then divide results by scale_factor so
567    // downstream layout stays in logical pixels. See ResolvedFont.
568    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
569    let physical_size = resolved.size_px * sf;
570    let physical_scale = physical_size / upem;
571    let inv_sf = 1.0 / sf;
572
573    let mut buffer = Buffer::new();
574    buffer.push_str(text);
575    match direction {
576        TextDirection::LeftToRight => buffer.set_direction(Direction::LeftToRight),
577        TextDirection::RightToLeft => buffer.set_direction(Direction::RightToLeft),
578        TextDirection::Auto => {}
579    }
580    // Set before the guess below, which leaves a language it finds set.
581    buffer.set_language(shaping_language(language));
582    // Always guess, including after an explicit set_direction. The guess
583    // only fills in what is still unset — it assigns `script` when it is
584    // `None` and `direction` when it is `Invalid` — so the caller's
585    // direction survives untouched and the script gets populated.
586    //
587    // That script is what picks the shaper: with `script: None` harfrust
588    // falls back to DEFAULT_SHAPER, which never requests init/medi/fina/
589    // isol, and Arabic comes out in disconnected isolated forms. Setting
590    // it selects ARABIC_SHAPER and the letters join. It also keeps
591    // harfrust from panicking on a still-Invalid direction in the Auto
592    // case, which is why this call used to live in that branch alone.
593    buffer.guess_segment_properties();
594
595    // Resolve the concrete direction (Auto is now decided by the buffer).
596    // Stored on the run so hit-testing knows RTL glyph order.
597    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
598        TextDirection::RightToLeft
599    } else {
600        TextDirection::LeftToRight
601    };
602
603    // The font is opened once per face and cached on the FontEntry, and
604    // it keeps its preprocessed tables, so repeated shape calls (every
605    // relayout/keystroke) reuse them; the ShaperFont over it is cheap.
606    harfrust::shape(
607        &ShaperFont::new(font),
608        &mut buffer,
609        ShapeOptions::new().features(features),
610    )
611    .ok()?;
612
613    let infos = buffer.glyph_infos();
614    let positions = buffer.glyph_positions();
615
616    let mut glyphs = Vec::with_capacity(infos.len());
617    let mut total_advance = 0.0f32;
618
619    for (info, pos) in infos.iter().zip(positions.iter()) {
620        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
621        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
622        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
623        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
624
625        glyphs.push(ShapedGlyph {
626            glyph_id: info.glyph_id as u16,
627            cluster: info.cluster,
628            x_advance,
629            y_advance,
630            x_offset,
631            y_offset,
632            font_face_id: resolved.font_face_id,
633        });
634
635        total_advance += x_advance;
636    }
637    if entry.synthesis().synthesizes_bold(resolved.weight) {
638        total_advance = widen_for_synthetic_bold(&mut glyphs, resolved.size_px);
639    }
640
641    Some(ShapedRun {
642        font_face_id: resolved.font_face_id,
643        size_px: resolved.size_px,
644        weight: resolved.weight,
645        italic: resolved.italic,
646        glyphs,
647        advance_width: total_advance,
648        text_range: text_offset..text_offset + text.len(),
649        direction: resolved_direction,
650        bidi_level: if resolved_direction == TextDirection::RightToLeft {
651            1
652        } else {
653            0
654        },
655        underline_style: crate::types::UnderlineStyle::None,
656        overline: false,
657        strikeout: false,
658        is_link: false,
659        foreground_color: None,
660        underline_color: None,
661        background_color: None,
662        anchor_href: None,
663        tooltip: None,
664        vertical_alignment: crate::types::VerticalAlignment::Normal,
665        image_name: None,
666        image_height: 0.0,
667    })
668}
669
670/// Shape a text string, reusing a harfrust `Buffer` to avoid allocations.
671pub fn shape_text_with_buffer(
672    registry: &FontRegistry,
673    resolved: &ResolvedFont,
674    text: &str,
675    text_offset: usize,
676    buffer: Buffer,
677    features: &[Feature],
678) -> Option<(ShapedRun, Buffer)> {
679    let entry = registry.get(resolved.font_face_id)?;
680    let font = entry.shaping_font()?;
681
682    let upem = units_per_em(entry.bytes(), entry.face_index).unwrap_or(0) as f32;
683    if upem == 0.0 {
684        return None;
685    }
686    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
687    let physical_size = resolved.size_px * sf;
688    let physical_scale = physical_size / upem;
689    let inv_sf = 1.0 / sf;
690
691    let mut buffer = buffer;
692    buffer.push_str(text);
693    // Recycled buffers come back without segment properties; explicitly
694    // guess them so harfrust doesn't panic on Direction::Invalid.
695    buffer.guess_segment_properties();
696
697    let resolved_direction = if buffer.direction() == Direction::RightToLeft {
698        TextDirection::RightToLeft
699    } else {
700        TextDirection::LeftToRight
701    };
702
703    harfrust::shape(
704        &ShaperFont::new(font),
705        &mut buffer,
706        ShapeOptions::new().features(features),
707    )
708    .ok()?;
709
710    let infos = buffer.glyph_infos();
711    let positions = buffer.glyph_positions();
712
713    let mut glyphs = Vec::with_capacity(infos.len());
714    let mut total_advance = 0.0f32;
715
716    for (info, pos) in infos.iter().zip(positions.iter()) {
717        let x_advance = pos.x_advance as f32 * physical_scale * inv_sf;
718        let y_advance = pos.y_advance as f32 * physical_scale * inv_sf;
719        let x_offset = pos.x_offset as f32 * physical_scale * inv_sf;
720        let y_offset = pos.y_offset as f32 * physical_scale * inv_sf;
721
722        glyphs.push(ShapedGlyph {
723            glyph_id: info.glyph_id as u16,
724            cluster: info.cluster,
725            x_advance,
726            y_advance,
727            x_offset,
728            y_offset,
729            font_face_id: resolved.font_face_id,
730        });
731
732        total_advance += x_advance;
733    }
734    if entry.synthesis().synthesizes_bold(resolved.weight) {
735        total_advance = widen_for_synthetic_bold(&mut glyphs, resolved.size_px);
736    }
737
738    let run = ShapedRun {
739        font_face_id: resolved.font_face_id,
740        size_px: resolved.size_px,
741        weight: resolved.weight,
742        italic: resolved.italic,
743        glyphs,
744        advance_width: total_advance,
745        text_range: text_offset..text_offset + text.len(),
746        direction: resolved_direction,
747        bidi_level: if resolved_direction == TextDirection::RightToLeft {
748            1
749        } else {
750            0
751        },
752        underline_style: crate::types::UnderlineStyle::None,
753        overline: false,
754        strikeout: false,
755        is_link: false,
756        foreground_color: None,
757        underline_color: None,
758        background_color: None,
759        anchor_href: None,
760        tooltip: None,
761        vertical_alignment: crate::types::VerticalAlignment::Normal,
762        image_name: None,
763        image_height: 0.0,
764    };
765    let mut run = run;
766    blank_hard_breaks(text, &mut run);
767
768    // Reclaim the buffer for reuse: clearing keeps the allocation and
769    // drops the contents and segment properties.
770    buffer.clear();
771    Some((run, buffer))
772}
773
774/// Widen every advancing glyph by what synthetic bold adds to its outline
775/// (see [`crate::font::synthesis`]), so the layout, the caret and hit testing
776/// measure the glyph as the rasterizer draws it. Returns the run's new
777/// advance.
778fn widen_for_synthetic_bold(glyphs: &mut [ShapedGlyph], size_px: f32) -> f32 {
779    let extra = synthesis::embolden_strength(size_px);
780    for glyph in glyphs.iter_mut().filter(|g| g.x_advance > 0.0) {
781        glyph.x_advance += extra;
782    }
783    glyphs.iter().map(|g| g.x_advance).sum()
784}
785
786#[non_exhaustive]
787pub struct FontMetricsPx {
788    pub ascent: f32,
789    pub descent: f32,
790    pub leading: f32,
791    pub underline_offset: f32,
792    pub strikeout_offset: f32,
793    pub stroke_size: f32,
794}
795
796/// Get font metrics (ascent, descent, leading) scaled to logical pixels.
797///
798/// Scales at `size_px * scale_factor` (physical) and divides by
799/// `scale_factor`, so callers always see logical-pixel metrics.
800pub fn font_metrics_px(registry: &FontRegistry, resolved: &ResolvedFont) -> Option<FontMetricsPx> {
801    let entry = registry.get(resolved.font_face_id)?;
802    let font_ref = swash::FontRef::from_index(entry.bytes(), entry.face_index as usize)?;
803    let sf = resolved.scale_factor.max(f32::MIN_POSITIVE);
804    let physical_size = resolved.size_px * sf;
805    let metrics = font_ref.metrics(&[]).scale(physical_size);
806    let inv_sf = 1.0 / sf;
807
808    Some(FontMetricsPx {
809        ascent: metrics.ascent * inv_sf,
810        descent: metrics.descent * inv_sf,
811        leading: metrics.leading * inv_sf,
812        underline_offset: metrics.underline_offset * inv_sf,
813        strikeout_offset: metrics.strikeout_offset * inv_sf,
814        stroke_size: metrics.stroke_size * inv_sf,
815    })
816}
817
818/// A bidi run: a contiguous range of text with the same direction.
819#[non_exhaustive]
820pub struct BidiRun {
821    pub byte_range: std::ops::Range<usize>,
822    pub direction: TextDirection,
823    /// Visual order index (for reordering after line breaking).
824    pub visual_order: usize,
825    /// UAX #9 embedding level: even is LTR, odd is RTL.
826    ///
827    /// Rule L2 reorders by level, not by direction, and the two are not
828    /// interchangeable: a Latin phrase quoted inside Arabic inside an
829    /// English paragraph sits at level 2, and reordering it as though it
830    /// were level 0 puts it on the wrong side of the Arabic. `direction`
831    /// cannot tell those apart — `level` can.
832    pub level: u8,
833}
834
835/// A paragraph's bidi structure in **logical** order.
836///
837/// [`bidi_runs`] returns runs already reordered for display, which suits
838/// a single-line label that is shaped and painted in one go. The
839/// multi-line editor cannot use that: line breaking is a logical
840/// operation, so runs have to stay in logical order until the breaker has
841/// decided where the lines fall, and only then get reordered *per line*.
842/// Reordering the paragraph up front and breaking afterwards would
843/// scramble any paragraph that wraps.
844#[non_exhaustive]
845pub struct BidiParagraph {
846    /// Runs of uniform embedding level, in logical order.
847    pub runs: Vec<BidiRun>,
848    /// The paragraph embedding level actually used — the explicit base
849    /// direction when one was given, else the rule P2/P3 auto-detection.
850    pub para_level: u8,
851}
852
853impl BidiParagraph {
854    /// The paragraph's base direction, as resolved.
855    pub fn base_direction(&self) -> TextDirection {
856        if self.para_level % 2 == 1 {
857            TextDirection::RightToLeft
858        } else {
859            TextDirection::LeftToRight
860        }
861    }
862}
863
864/// The unicode-bidi paragraph level that expresses `base`.
865///
866/// `None` asks unicode-bidi to auto-detect (rules P2/P3: the first strong
867/// character wins, defaulting to LTR when the text has none). An explicit
868/// level overrides that — which is the point of honouring a stored
869/// paragraph direction, since P2/P3 incorrectly classifies any RTL
870/// paragraph that happens to open with a digit, a Latin acronym or an
871/// opening quote.
872fn base_para_level(base: TextDirection) -> Option<unicode_bidi::Level> {
873    match base {
874        TextDirection::Auto => None,
875        TextDirection::LeftToRight => Some(unicode_bidi::Level::ltr()),
876        TextDirection::RightToLeft => Some(unicode_bidi::Level::rtl()),
877    }
878}
879
880/// The base direction a paragraph of `text` takes.
881///
882/// An explicit `base` is the answer. `Auto` applies UAX #9 rules P2/P3: the
883/// first strongly directional character outside an isolate decides. When
884/// the text has none (it is empty, or only digits, spaces and punctuation),
885/// `neutral` decides, which is how a host gives an empty field the
886/// direction of the language it is for; the algorithm's own answer there is
887/// left to right, which is what `Auto` and `LeftToRight` give.
888///
889/// Never returns `Auto`.
890pub fn resolve_paragraph_direction(
891    text: &str,
892    base: TextDirection,
893    neutral: TextDirection,
894) -> TextDirection {
895    match base {
896        TextDirection::LeftToRight | TextDirection::RightToLeft => base,
897        TextDirection::Auto => match unicode_bidi::get_base_direction(text) {
898            unicode_bidi::Direction::Ltr => TextDirection::LeftToRight,
899            unicode_bidi::Direction::Rtl => TextDirection::RightToLeft,
900            unicode_bidi::Direction::Mixed => match neutral {
901                TextDirection::RightToLeft => TextDirection::RightToLeft,
902                _ => TextDirection::LeftToRight,
903            },
904        },
905    }
906}
907
908/// [`analyze_paragraph`] for a paragraph whose `Auto` direction falls back
909/// on `neutral` when the text has no strongly directional character (see
910/// [`resolve_paragraph_direction`]).
911pub fn analyze_paragraph_with_neutral(
912    text: &str,
913    base: TextDirection,
914    neutral: TextDirection,
915) -> BidiParagraph {
916    let base = match (base, neutral) {
917        (TextDirection::Auto, TextDirection::RightToLeft) => {
918            resolve_paragraph_direction(text, base, neutral)
919        }
920        _ => base,
921    };
922    analyze_paragraph(text, base)
923}
924
925/// Resolve `text`'s bidi structure under an explicit or auto base direction.
926///
927/// Runs come back in logical order, each tagged with its embedding level.
928/// Callers shape each run with its own direction and later reorder the
929/// runs of each line with [`visual_order`].
930pub fn analyze_paragraph(text: &str, base: TextDirection) -> BidiParagraph {
931    use unicode_bidi::BidiInfo;
932
933    if text.is_empty() {
934        return BidiParagraph {
935            runs: Vec::new(),
936            para_level: base_para_level(base).map_or(0, |l| l.number()),
937        };
938    }
939
940    let bidi_info = BidiInfo::new(text, base_para_level(base));
941
942    // A block is one paragraph as far as layout is concerned; if the text
943    // somehow carries a hard break, the first paragraph's level is the
944    // one that governs alignment.
945    let para_level = bidi_info
946        .paragraphs
947        .first()
948        .map(|p| p.level.number())
949        .or_else(|| base_para_level(base).map(|l| l.number()))
950        .unwrap_or(0);
951
952    // Group consecutive characters of equal level. Iterating by
953    // `char_indices` rather than by byte keeps a run boundary from ever
954    // landing inside a multi-byte character.
955    let mut starts: Vec<(usize, u8)> = Vec::new();
956    for (idx, _) in text.char_indices() {
957        let level = bidi_info.levels[idx].number();
958        if starts.last().map(|&(_, l)| l) != Some(level) {
959            starts.push((idx, level));
960        }
961    }
962
963    // Each run ends where the next begins; the last ends with the text.
964    let ends = starts
965        .iter()
966        .skip(1)
967        .map(|&(start, _)| start)
968        .chain(std::iter::once(text.len()));
969
970    let runs: Vec<BidiRun> = starts
971        .iter()
972        .zip(ends)
973        .map(|(&(start, level), end)| BidiRun {
974            byte_range: start..end,
975            direction: if level % 2 == 1 {
976                TextDirection::RightToLeft
977            } else {
978                TextDirection::LeftToRight
979            },
980            // Always 0 here: these runs are in *logical* order and the
981            // block path reorders per line after breaking, so a
982            // paragraph-wide visual index would be both unused and
983            // misleading. `bidi_runs` fills it in for the single-line
984            // path, which does lay a paragraph out in one go.
985            visual_order: 0,
986            level,
987        })
988        .collect();
989
990    BidiParagraph { runs, para_level }
991}
992
993/// Reorder items from logical into visual order per UAX #9 rule L2.
994///
995/// Returns indices into `levels`: `result[0]` is the item to paint
996/// leftmost. L2 reads "from the highest level down to the lowest odd
997/// level, reverse any contiguous sequence of items at that level or
998/// higher", which is what the loop below does literally.
999pub fn visual_order(levels: &[u8]) -> Vec<usize> {
1000    let mut order: Vec<usize> = (0..levels.len()).collect();
1001    let Some(&max) = levels.iter().max() else {
1002        return order;
1003    };
1004    // With no odd level nothing is RTL, so logical order is already visual.
1005    let Some(min_odd) = levels.iter().copied().filter(|l| l % 2 == 1).min() else {
1006        return order;
1007    };
1008
1009    let mut level = max;
1010    while level >= min_odd {
1011        let mut i = 0;
1012        while i < order.len() {
1013            if levels[order[i]] >= level {
1014                let start = i;
1015                while i < order.len() && levels[order[i]] >= level {
1016                    i += 1;
1017                }
1018                order[start..i].reverse();
1019            } else {
1020                i += 1;
1021            }
1022        }
1023        // min_odd is odd, hence >= 1, so this cannot wrap past zero.
1024        level -= 1;
1025    }
1026    order
1027}
1028
1029/// Analyze text for bidirectional content and return directional runs
1030/// in **visual order** per UAX #9 (Unicode Bidirectional Algorithm, rule L2).
1031///
1032/// The returned runs can be shaped independently and concatenated left-to-right
1033/// to produce correctly-ordered mixed-script text (e.g. Latin embedded in
1034/// Arabic). For pure-LTR text, returns a single LTR run. For pure-RTL text,
1035/// returns a single RTL run.
1036pub fn bidi_runs(text: &str) -> Vec<BidiRun> {
1037    use unicode_bidi::BidiInfo;
1038
1039    if text.is_empty() {
1040        return Vec::new();
1041    }
1042
1043    let bidi_info = BidiInfo::new(text, None);
1044    let mut runs = Vec::new();
1045
1046    for para in &bidi_info.paragraphs {
1047        let (levels, level_runs) = bidi_info.visual_runs(para, para.range.clone());
1048        for level_run in level_runs {
1049            if level_run.is_empty() {
1050                continue;
1051            }
1052            let level = levels[level_run.start];
1053            let direction = if level.is_rtl() {
1054                TextDirection::RightToLeft
1055            } else {
1056                TextDirection::LeftToRight
1057            };
1058            let visual_order = runs.len();
1059            runs.push(BidiRun {
1060                byte_range: level_run,
1061                direction,
1062                visual_order,
1063                level: level.number(),
1064            });
1065        }
1066    }
1067
1068    if runs.is_empty() {
1069        runs.push(BidiRun {
1070            byte_range: 0..text.len(),
1071            direction: TextDirection::LeftToRight,
1072            visual_order: 0,
1073            level: 0,
1074        });
1075    }
1076
1077    runs
1078}
1079
1080#[cfg(test)]
1081mod bidi_tests {
1082    use super::*;
1083
1084    const ARABIC: &str = "\u{0643}\u{062A}\u{0628}"; // كتب
1085    const HEBREW: &str = "\u{05E9}\u{05DC}\u{05D5}\u{05DD}"; // שלום
1086
1087    #[test]
1088    fn rule_l2_leaves_all_ltr_text_alone() {
1089        assert_eq!(visual_order(&[0, 0, 0]), vec![0, 1, 2]);
1090        assert_eq!(visual_order(&[]), Vec::<usize>::new());
1091    }
1092
1093    #[test]
1094    fn rule_l2_reverses_a_run_of_rtl() {
1095        // level 0 "a", level 1 RTL, level 0 "b" -> the RTL span reverses
1096        // in place but stays between its neighbours.
1097        assert_eq!(visual_order(&[0, 1, 1, 0]), vec![0, 2, 1, 3]);
1098    }
1099
1100    #[test]
1101    fn rule_l2_nests_an_ltr_island_inside_rtl() {
1102        // An English phrase (level 2) quoted inside Arabic (level 1)
1103        // inside an English paragraph (level 0). The level-2 island must
1104        // keep its own left-to-right order while the level-1 material
1105        // around it reverses — the case `direction` alone cannot express.
1106        let levels = [0, 1, 2, 2, 1, 0];
1107        assert_eq!(visual_order(&levels), vec![0, 4, 2, 3, 1, 5]);
1108    }
1109
1110    #[test]
1111    fn rule_l2_reverses_the_whole_line_in_an_rtl_paragraph() {
1112        // Level 1 throughout with a level-2 Latin word: the paragraph
1113        // reads right-to-left, so logical item 0 paints rightmost.
1114        assert_eq!(visual_order(&[1, 2, 1]), vec![2, 1, 0]);
1115    }
1116
1117    #[test]
1118    fn a_leading_digit_does_not_fool_auto_detection() {
1119        // Worth pinning, because it is easy to assume otherwise: digits
1120        // are type EN, not strong, so rule P2 skips them and finds the
1121        // Arabic. An Arabic paragraph opening with a number needs no
1122        // explicit direction.
1123        let text = "123 \u{0643}\u{062A}\u{0628}";
1124        assert_eq!(analyze_paragraph(text, TextDirection::Auto).para_level, 1);
1125    }
1126
1127    #[test]
1128    fn an_explicit_base_direction_overrides_first_strong_detection() {
1129        // A Latin acronym *is* strong (type L), so rule P2 stops at the
1130        // "NASA" and calls this Arabic paragraph left-to-right — the
1131        // real false detection, and the reason a stored paragraph
1132        // direction has to win over guessing.
1133        let text = "NASA \u{0623}\u{0639}\u{0644}\u{0646}\u{062A}";
1134        assert_eq!(
1135            analyze_paragraph(text, TextDirection::Auto).para_level,
1136            0,
1137            "auto-detection is expected to get this one wrong"
1138        );
1139
1140        let forced = analyze_paragraph(text, TextDirection::RightToLeft);
1141        assert_eq!(forced.para_level, 1);
1142        assert_eq!(forced.base_direction(), TextDirection::RightToLeft);
1143
1144        // And the override genuinely changes the layout, not just the
1145        // recorded level: the Arabic now leads visually. Runs come back
1146        // in logical order, so ask rule L2 which one paints leftmost —
1147        // the same thing a caller laying the paragraph out would do.
1148        let auto = analyze_paragraph(text, TextDirection::Auto);
1149        let first_visual = |p: &BidiParagraph| {
1150            let levels: Vec<u8> = p.runs.iter().map(|r| r.level).collect();
1151            visual_order(&levels).first().map(|&i| p.runs[i].direction)
1152        };
1153        assert_eq!(first_visual(&auto), Some(TextDirection::LeftToRight));
1154        assert_eq!(first_visual(&forced), Some(TextDirection::RightToLeft));
1155    }
1156
1157    #[test]
1158    fn pure_arabic_auto_detects_as_rtl() {
1159        let para = analyze_paragraph(ARABIC, TextDirection::Auto);
1160        assert_eq!(para.base_direction(), TextDirection::RightToLeft);
1161        assert_eq!(para.runs.len(), 1);
1162        assert_eq!(para.runs[0].direction, TextDirection::RightToLeft);
1163        assert_eq!(para.runs[0].byte_range, 0..ARABIC.len());
1164    }
1165
1166    #[test]
1167    fn runs_come_back_in_logical_order_and_cover_the_text() {
1168        // "hello <hebrew> world" — three runs, contiguous, logical order.
1169        let text = format!("hello {HEBREW} world");
1170        let para = analyze_paragraph(&text, TextDirection::Auto);
1171
1172        assert!(para.runs.len() >= 2, "expected a directional split");
1173        assert_eq!(para.runs[0].byte_range.start, 0);
1174        assert_eq!(para.runs.last().unwrap().byte_range.end, text.len());
1175        for pair in para.runs.windows(2) {
1176            assert_eq!(
1177                pair[0].byte_range.end, pair[1].byte_range.start,
1178                "runs must tile the text with no gap or overlap"
1179            );
1180            assert!(
1181                pair[0].byte_range.start < pair[1].byte_range.start,
1182                "runs must be in logical order"
1183            );
1184        }
1185        assert!(
1186            para.runs
1187                .iter()
1188                .any(|r| r.direction == TextDirection::RightToLeft),
1189            "the Hebrew span should have produced an RTL run"
1190        );
1191    }
1192
1193    #[test]
1194    fn run_boundaries_never_split_a_multibyte_character() {
1195        let text = format!("a{ARABIC}b{HEBREW}c");
1196        for run in analyze_paragraph(&text, TextDirection::Auto).runs {
1197            assert!(
1198                text.is_char_boundary(run.byte_range.start)
1199                    && text.is_char_boundary(run.byte_range.end),
1200                "run {:?} splits a character in {text:?}",
1201                run.byte_range
1202            );
1203        }
1204    }
1205
1206    #[test]
1207    fn rule_l2_over_a_real_paragraph_is_a_permutation() {
1208        let text = format!("hello {HEBREW} world {ARABIC} end");
1209        let para = analyze_paragraph(&text, TextDirection::Auto);
1210        let levels: Vec<u8> = para.runs.iter().map(|r| r.level).collect();
1211
1212        let mut seen = visual_order(&levels);
1213        seen.sort_unstable();
1214        assert_eq!(
1215            seen,
1216            (0..para.runs.len()).collect::<Vec<_>>(),
1217            "every run must appear exactly once in the visual order"
1218        );
1219    }
1220
1221    #[test]
1222    fn empty_text_analyzes_without_panicking() {
1223        let para = analyze_paragraph("", TextDirection::RightToLeft);
1224        assert!(para.runs.is_empty());
1225        assert_eq!(para.para_level, 1);
1226    }
1227}
1228
1229#[cfg(test)]
1230mod language_tests {
1231    use super::*;
1232    use crate::font::resolve::resolve_font;
1233
1234    const NOTO_SANS: &[u8] = include_bytes!("../../test-fonts/NotoSans-Variable.ttf");
1235
1236    fn glyphs(text: &str, language: Option<&str>) -> Vec<u16> {
1237        let mut registry = FontRegistry::new_without_system_fonts();
1238        let face = registry.register_font(NOTO_SANS)[0];
1239        registry.set_default_font(face, 16.0);
1240        let resolved = resolve_font(&registry, None, None, None, None, None, 1.0, 1.0).unwrap();
1241        let run = shape_text_in_paragraph(
1242            &registry,
1243            &resolved,
1244            text,
1245            0,
1246            TextDirection::Auto,
1247            &[],
1248            &ScriptContext::in_language(text, language),
1249            0,
1250        )
1251        .unwrap();
1252        run.glyphs.iter().map(|g| g.glyph_id).collect()
1253    }
1254
1255    #[test]
1256    fn the_shaper_is_told_the_language() {
1257        // Noto Sans' `locl` for Romanian draws ş and ţ (cedilla) with the
1258        // comma below Romanian writes; no language, or English, keeps the
1259        // cedilla.
1260        let text = "\u{015F}\u{0163}";
1261        let none = glyphs(text, None);
1262        assert_eq!(glyphs(text, Some("en")), none);
1263        assert_ne!(glyphs(text, Some("ro")), none, "Romanian forms");
1264        assert_eq!(glyphs(text, Some("ro-RO")), glyphs(text, Some("ro")));
1265    }
1266
1267    #[test]
1268    fn a_tag_the_shaper_cannot_read_is_no_language() {
1269        assert_eq!(shaping_language(None), None);
1270        assert_eq!(shaping_language(Some("  ")), None);
1271        assert!(shaping_language(Some("sr-Cyrl")).is_some());
1272    }
1273}