ltk/

text_shaping.rs

// SPDX-License-Identifier: LGPL-2.1-only
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>

//! Unicode text processing: BiDi visual reordering folded into
//! HarfBuzz shaping.
//!
//! [`shape_line`] is the main entry point. It takes a logical-order
//! string, a font resolver ("for this codepoint, which
//! `FontHandle` should we use?") and the pixel size, runs the
//! Unicode Bidirectional Algorithm over the input, splits each
//! BiDi run into sub-runs that share a font, calls [`shape_run`]
//! per sub-run, and returns a [`PositionedGlyph`] sequence in
//! visual order. Renderers consume that sequence directly: each
//! `PositionedGlyph` carries the per-font `glyph_id`, the visual
//! advance, and ink offsets, which is exactly what
//! `fontdue::Font::rasterize_indexed` needs to render Arabic
//! connected forms, Devanagari clusters and CJK shaped glyphs
//! correctly.
//!
//! [`shape_run`] is the lower-level entry point — useful in tests
//! and when a caller has already done its own bidi / sub-run
//! splitting.

/// Single shaped glyph returned by [`shape_run`]. Horizontal-only —
/// vertical-script metrics (`y_advance`) and the source-string
/// `cluster` index that rustybuzz also returns are dropped because
/// no caller in the crate consumes them; add them back when a
/// caller actually needs vertical layout or text-edit
/// cluster-aware caret navigation.
pub struct ShapedGlyph
{
	/// Glyph index in the font (not a Unicode codepoint).
	pub glyph_id:  u32,
	/// Horizontal advance in 26.6 fixed-point font units, already scaled
	/// to the requested pixel size.
	pub x_advance: f32,
	/// Horizontal glyph offset from the pen position.
	pub x_offset:  f32,
	/// Vertical glyph offset from the baseline.
	pub y_offset:  f32,
}

/// Per-glyph entry returned by [`shape_line`]. Carries the font that
/// owns the glyph (so the rasterizer caches per font, not just per
/// glyph index) and the visual position relative to the start of the
/// line.
pub struct PositionedGlyph
{
	pub glyph_id:  u32,
	pub font_id:   usize,
	pub x_advance: f32,
	pub x_offset:  f32,
	pub y_offset:  f32,
}

/// Shape `text` for visual rendering. Runs the Unicode Bidirectional
/// Algorithm over the input, then asks `resolve_font(ch)` for the
/// font handle that owns each codepoint, groups consecutive
/// codepoints sharing a font / direction into sub-runs, and
/// calls [`shape_run`] per sub-run. Output is in visual order:
/// concatenating `x_advance` of each glyph yields the rendered line
/// width.
///
/// `resolve_font` is the per-character fallback resolver (typically
/// "primary font if it has the glyph, otherwise walk the system
/// fallback chain"). Returning `None` lets the caller skip the
/// codepoint entirely.
pub fn shape_line<F>( text: &str, px: f32, mut resolve_font: F ) -> Vec<PositionedGlyph>
where
	F: FnMut( char ) -> Option<crate::system_fonts::FontHandle>,
{
	if text.is_empty() { return vec![]; }
	let bidi = unicode_bidi::BidiInfo::new( text, None );
	if bidi.paragraphs.is_empty() { return vec![]; }
	let para = &bidi.paragraphs[0];
	let ( levels, runs ) = bidi.visual_runs( para, para.range.clone() );

	let mut out: Vec<PositionedGlyph> = Vec::with_capacity( text.chars().count() );
	for run in runs
	{
		let is_rtl = levels.get( run.start ).map( |l| l.is_rtl() ).unwrap_or( false );
		let run_text = &text[ run ];
		// Split the BiDi run into sub-runs that share a single font.
		// `resolve_font` is asked once per codepoint; consecutive
		// codepoints whose handle has the same `font` pointer are
		// shaped together.
		let mut current_handle: Option<crate::system_fonts::FontHandle> = None;
		let mut sub_run = String::new();
		let flush = | handle_opt: &Option<crate::system_fonts::FontHandle>, sub_run: &mut String, out: &mut Vec<PositionedGlyph> |
		{
			if sub_run.is_empty() { return; }
			let Some( h ) = handle_opt.as_ref() else { sub_run.clear(); return };
			let glyphs = shape_run( sub_run, &h.bytes, h.face, px, is_rtl );
			let font_id = std::sync::Arc::as_ptr( &h.font ) as usize;
			for g in glyphs
			{
				out.push( PositionedGlyph
				{
					glyph_id:  g.glyph_id,
					font_id,
					x_advance: g.x_advance,
					x_offset:  g.x_offset,
					y_offset:  g.y_offset,
				} );
			}
			sub_run.clear();
		};
		for ch in run_text.chars()
		{
			let handle = resolve_font( ch );
			let same = match ( &current_handle, &handle )
			{
				( Some( a ), Some( b ) ) => std::sync::Arc::ptr_eq( &a.font, &b.font ),
				( None,      None      ) => true,
				_                        => false,
			};
			if !same
			{
				flush( &current_handle, &mut sub_run, &mut out );
				current_handle = handle.clone();
			}
			sub_run.push( ch );
		}
		flush( &current_handle, &mut sub_run, &mut out );
	}
	out
}

/// Shape a text run using rustybuzz (HarfBuzz-compatible shaping) and
/// return the glyph sequence with ink positions.
///
/// `font_bytes` must be the raw bytes of the font file (TrueType or
/// OpenType); `face_index` is 0 for single-face files and the TTC
/// sub-face index otherwise. `px` is the point size in physical pixels.
/// `rtl` selects right-to-left shaping (set from the BiDi run level).
///
/// Returns an empty vec if the font cannot be parsed or the string is
/// empty.
pub fn shape_run( text: &str, font_bytes: &[u8], face_index: u32, px: f32, rtl: bool ) -> Vec<ShapedGlyph>
{
	use rustybuzz::{ UnicodeBuffer, Direction };

	if text.is_empty() { return vec![]; }
	let Some( face ) = rustybuzz::Face::from_slice( font_bytes, face_index ) else
	{
		return vec![];
	};

	let units_per_em = face.units_per_em() as f32;
	if units_per_em <= 0.0 { return vec![]; }
	let scale        = px / units_per_em;

	let mut buf = UnicodeBuffer::new();
	buf.push_str( text );
	buf.set_direction( if rtl { Direction::RightToLeft } else { Direction::LeftToRight } );

	let output = rustybuzz::shape( &face, &[], buf );
	let infos  = output.glyph_infos();
	let pos    = output.glyph_positions();

	infos.iter().zip( pos.iter() ).map( |( info, p )|
	{
		ShapedGlyph
		{
			glyph_id:  info.glyph_id,
			x_advance: p.x_advance as f32 * scale,
			x_offset:  p.x_offset  as f32 * scale,
			y_offset:  p.y_offset  as f32 * scale,
		}
	} ).collect()
}