//! Text as a coverage image, for brush alphas and decals: each line shaped with harfrust //! (kerning, ligatures, joined scripts), drawn from the font's outlines (skrifa) and filled with //! a non-zero scanline rasterizer, lines centered. use harfrust::{FontRef, ShapeOptions, ShaperData, UnicodeBuffer}; use skrifa::MetadataProvider; use skrifa::instance::{LocationRef, Size}; use skrifa::outline::{DrawSettings, OutlinePen}; /// Longest text drawn (characters). pub const MAX_TEXT_CHARS: usize = 1000; /// Largest side of a text image (texels); bigger layouts are drawn smaller to fit. pub const MAX_TEXT_SIDE: u32 = 4096; /// Vertical samples per texel row. const SUBROWS: usize = 4; /// A shaped glyph: its id and pen position (font units). type Placed = (u32, f32, f32); /// Coverage 0..=255 per texel, rows top to bottom. #[derive(Clone, Debug, PartialEq)] pub struct TextImage { pub width: u32, pub height: u32, pub coverage: Vec, } /// Draw `text` (one or more lines) with face `index` of `font` at `px` texels per em, cropped to /// the ink with a margin of a tenth of an em. pub fn render_text(font: &[u8], index: u32, text: &str, px: f32) -> Result { let text = text.trim_end(); if text.trim().is_empty() { return Err("the text is empty".into()); } if text.chars().count() > MAX_TEXT_CHARS { return Err(format!("the text is longer than {MAX_TEXT_CHARS} characters")); } let font = FontRef::from_index(font, index).map_err(|e| format!("not a usable font: {e}"))?; // Layout in font units; `scale` turns them into texels. let m = font.metrics(Size::unscaled(), LocationRef::default()); let upem = f32::from(m.units_per_em.max(1)); let line = (m.ascent - m.descent + m.leading).max(upem * 0.5); let data = ShaperData::new(&font); let shaper = data.shaper(&font).build(); let mut lines: Vec<(f32, Vec)> = Vec::new(); for t in text.lines() { let mut buffer = UnicodeBuffer::new(); buffer.push_str(t); buffer.guess_segment_properties(); let shaped = shaper.shape(buffer, ShapeOptions::new()); let mut x = 0.0; let mut glyphs = Vec::new(); for (info, pos) in shaped.glyph_infos().iter().zip(shaped.glyph_positions()) { glyphs.push((info.glyph_id, x + pos.x_offset as f32, pos.y_offset as f32)); x += pos.x_advance as f32; } lines.push((x, glyphs)); } let widest = lines.iter().map(|(w, _)| *w).fold(0.0, f32::max); let px = px.clamp(4.0, 1024.0); // Outlines in texels (y down) at the shaped positions, lines centered on the widest. let outlines = font.outline_glyphs(); let mut pen = Edges { scale: px / upem, ..Edges::default() }; for (row, (line_width, glyphs)) in lines.iter().enumerate() { let left = (widest - line_width) * 0.5; for &(id, x, y) in glyphs { let Some(glyph) = outlines.get(skrifa::GlyphId::new(id)) else { continue }; pen.origin = ((left + x) * pen.scale, (line * row as f32 - y) * pen.scale); // A glyph that can't be drawn is left out rather than failing the text. let _ = glyph.draw(DrawSettings::unhinted(Size::unscaled(), LocationRef::default()), &mut pen); pen.close(); } } // The image is the ink's bounds plus the margin (accents and descenders never clip), scaled // down when that is too large. let points = || pen.edges.iter().flat_map(|e| [(e[0], e[1]), (e[2], e[3])]); let lo = points().fold((f32::MAX, f32::MAX), |a, p| (a.0.min(p.0), a.1.min(p.1))); let hi = points().fold((f32::MIN, f32::MIN), |a, p| (a.0.max(p.0), a.1.max(p.1))); if pen.edges.is_empty() || !(lo.0.is_finite() && hi.0.is_finite() && lo.1.is_finite() && hi.1.is_finite()) { return Err("the font draws nothing for this text".into()); } let margin = px * 0.1; let (w, h) = (hi.0 - lo.0 + 2.0 * margin, hi.1 - lo.1 + 2.0 * margin); let fit = (MAX_TEXT_SIDE as f32 / w.max(h)).min(1.0); let edges: Vec<[f32; 4]> = pen .edges .iter() .map(|e| [(e[0] - lo.0 + margin) * fit, (e[1] - lo.1 + margin) * fit, (e[2] - lo.0 + margin) * fit, (e[3] - lo.1 + margin) * fit]) .collect(); let (width, height) = ((w * fit).ceil().max(1.0) as u32, (h * fit).ceil().max(1.0) as u32); Ok(TextImage { width, height, coverage: fill(&edges, width as usize, height as usize) }) } /// Line segments (texel space, y down) collected from glyph outlines: font units times `scale` /// from `origin`, curves flattened. #[derive(Default)] struct Edges { scale: f32, origin: (f32, f32), start: (f32, f32), at: (f32, f32), edges: Vec<[f32; 4]>, } impl Edges { fn map(&self, x: f32, y: f32) -> (f32, f32) { (self.origin.0 + x * self.scale, self.origin.1 - y * self.scale) } fn segment(&mut self, to: (f32, f32)) { if to != self.at { self.edges.push([self.at.0, self.at.1, to.0, to.1]); } self.at = to; } /// Flatten a curve given as a point function of t in 0..1, finer for longer curves. fn curve(&mut self, control_length: f32, point: impl Fn(f32) -> (f32, f32)) { let steps = (control_length.sqrt() * 2.0).clamp(2.0, 64.0) as usize; for i in 1..=steps { self.segment(point(i as f32 / steps as f32)); } } } fn dist(a: (f32, f32), b: (f32, f32)) -> f32 { (a.0 - b.0).hypot(a.1 - b.1) } impl OutlinePen for Edges { fn move_to(&mut self, x: f32, y: f32) { self.close(); self.start = self.map(x, y); self.at = self.start; } fn line_to(&mut self, x: f32, y: f32) { let p = self.map(x, y); self.segment(p); } fn quad_to(&mut self, cx0: f32, cy0: f32, x: f32, y: f32) { let (p0, c, p) = (self.at, self.map(cx0, cy0), self.map(x, y)); self.curve(dist(p0, c) + dist(c, p), |t| { let s = 1.0 - t; (s * s * p0.0 + 2.0 * s * t * c.0 + t * t * p.0, s * s * p0.1 + 2.0 * s * t * c.1 + t * t * p.1) }); } fn curve_to(&mut self, cx0: f32, cy0: f32, cx1: f32, cy1: f32, x: f32, y: f32) { let (p0, c0, c1, p) = (self.at, self.map(cx0, cy0), self.map(cx1, cy1), self.map(x, y)); self.curve(dist(p0, c0) + dist(c0, c1) + dist(c1, p), |t| { let s = 1.0 - t; let (a, b, c, d) = (s * s * s, 3.0 * s * s * t, 3.0 * s * t * t, t * t * t); (a * p0.0 + b * c0.0 + c * c1.0 + d * p.0, a * p0.1 + b * c0.1 + c * c1.1 + d * p.1) }); } fn close(&mut self) { self.segment(self.start); } } /// Non-zero winding coverage of closed `edges` over a `w × h` grid: [`SUBROWS`] scanlines per /// row, each span's ends spread over the texels they cross. fn fill(edges: &[[f32; 4]], w: usize, h: usize) -> Vec { let mut acc = vec![0f32; w * h]; // Edges by their top, and the ones the current scanline may cross. let mut sorted: Vec<[f32; 4]> = edges.iter().copied().filter(|e| e[1] != e[3]).collect(); sorted.sort_by(|a, b| a[1].min(a[3]).total_cmp(&b[1].min(b[3]))); let (mut next, mut active) = (0, Vec::new()); let mut crossings: Vec<(f32, i32)> = Vec::new(); for row in 0..h { for sub in 0..SUBROWS { let y = row as f32 + (sub as f32 + 0.5) / SUBROWS as f32; while let Some(e) = sorted.get(next).filter(|e| e[1].min(e[3]) <= y) { active.push(*e); next += 1; } active.retain(|e| e[1].max(e[3]) > y); crossings.clear(); for &[x0, y0, x1, y1] in &active { if (y0 <= y) != (y1 <= y) { crossings.push((x0 + (y - y0) / (y1 - y0) * (x1 - x0), if y1 > y0 { 1 } else { -1 })); } } crossings.sort_by(|a, b| a.0.total_cmp(&b.0)); let mut winding = 0; for pair in crossings.windows(2) { winding += pair[0].1; if winding != 0 { span(&mut acc[row * w..(row + 1) * w], pair[0].0, pair[1].0); } } } } acc.iter().map(|c| (c / SUBROWS as f32 * 255.0).round().clamp(0.0, 255.0) as u8).collect() } /// Add the covered length of `x0..x1` to each texel of `row`. fn span(row: &mut [f32], x0: f32, x1: f32) { let (x0, x1) = (x0.clamp(0.0, row.len() as f32), x1.clamp(0.0, row.len() as f32)); if x1 <= x0 { return; } for (i, c) in row.iter_mut().enumerate().take(x1.ceil() as usize).skip(x0.floor() as usize) { *c += (x1.min(i as f32 + 1.0) - x0.max(i as f32)).max(0.0); } } #[cfg(test)] mod tests { use super::*; #[test] fn spans_spread_partial_texels() { let mut row = [0.0; 4]; span(&mut row, 0.5, 2.25); assert_eq!(row, [0.5, 1.0, 0.25, 0.0]); // A square drawn either way round fills the same texels. let square = |cw: bool| { let p = [(1.0, 1.0), (3.0, 1.0), (3.0, 3.0), (1.0, 3.0)]; let p: Vec<_> = if cw { p.to_vec() } else { p.iter().rev().copied().collect() }; (0..4).map(|i| [p[i].0, p[i].1, p[(i + 1) % 4].0, p[(i + 1) % 4].1]).collect::>() }; let a = fill(&square(true), 4, 4); assert_eq!(a, fill(&square(false), 4, 4)); assert_eq!((a[5], a[0], a[3 * 4 + 3]), (255, 0, 0), "inside full, outside empty"); } #[test] fn text_is_laid_out_and_filled() { let font = epaint_default_fonts::UBUNTU_LIGHT; let one = render_text(font, 0, "H", 64.0).unwrap(); let two = render_text(font, 0, "HH", 64.0).unwrap(); let lines = render_text(font, 0, "H\nH", 64.0).unwrap(); assert!(two.width > one.width && two.height == one.height); assert!(lines.height > one.height && lines.width == one.width, "lines stack"); let ink = |t: &TextImage| t.coverage.iter().map(|c| u32::from(*c)).sum::(); assert!(ink(&two) > ink(&one) * 19 / 10 && ink(&two) < ink(&one) * 21 / 10, "two H, twice the ink"); assert!(one.coverage.contains(&255) && one.coverage.contains(&0)); // The margin stays clear; huge sizes are drawn to fit. assert!(one.coverage[..one.width as usize].iter().all(|c| *c == 0)); let big = render_text(font, 0, &"W".repeat(400), 1024.0).unwrap(); assert!(big.width <= MAX_TEXT_SIDE && big.height >= 1); } #[test] fn bad_input_is_an_error() { assert!(render_text(b"not a font", 0, "Hi", 64.0).is_err()); assert!(render_text(b"", 0, " ", 64.0).is_err()); assert!(render_text(b"", 0, &"x".repeat(MAX_TEXT_CHARS + 1), 64.0).is_err()); } }