viewport_lib/resources/
font.rs

1//! Font atlas and single-line text layout for overlay rendering.
2//!
3//! This module is the text back-end for [`LabelItem`], [`ScalarBarItem`], and
4//! [`RulerItem`].  It uses [`fontdue`] for glyph rasterization and packs glyphs
5//! into a single GPU texture atlas on demand.
6//!
7//! Public surface: [`FontHandle`] (opaque font identifier) and
8//! [`super::ViewportGpuResources::upload_font`].  Everything else is `pub(crate)`.
9
10use std::collections::HashMap;
11
12/// Default font embedded in the library binary (Inter Regular, SIL OFL 1.1).
13const DEFAULT_FONT_BYTES: &[u8] = include_bytes!("../fonts/Inter-Regular.ttf");
14
15// ---------------------------------------------------------------------------
16// FontHandle : public opaque identifier
17// ---------------------------------------------------------------------------
18
19/// Opaque handle to a font uploaded via
20/// [`ViewportGpuResources::upload_font`](super::ViewportGpuResources::upload_font).
21///
22/// Pass `None` (or omit the field) on overlay items to use the built-in default
23/// font.  Pass `Some(handle)` to use a user-supplied TTF font.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25pub struct FontHandle(pub(crate) usize);
26
27// ---------------------------------------------------------------------------
28// GlyphKey / GlyphEntry : atlas bookkeeping
29// ---------------------------------------------------------------------------
30
31/// Unique key for a rasterized glyph in the atlas.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
33struct GlyphKey {
34    font_index: usize,
35    glyph_index: u16,
36    /// Font size in tenths of a pixel (e.g. 140 = 14.0 px).
37    /// Quantised to avoid unbounded atlas growth from fractional sizes.
38    size_tenths: u32,
39}
40
41/// Location and metrics of a single rasterized glyph in the atlas texture.
42#[derive(Debug, Clone, Copy)]
43struct GlyphEntry {
44    /// Top-left pixel coordinate in the atlas.
45    x: u32,
46    y: u32,
47    /// Rasterized bitmap dimensions.
48    width: u32,
49    height: u32,
50    /// Offset from the pen position to the top-left of the bitmap.
51    offset_x: f32,
52    offset_y: f32,
53}
54
55// ---------------------------------------------------------------------------
56// GlyphQuad / TextLayout : internal layout output
57// ---------------------------------------------------------------------------
58
59/// A positioned, textured quad for one glyph, ready for vertex generation.
60#[derive(Debug, Clone, Copy)]
61pub(crate) struct GlyphQuad {
62    /// Screen-space top-left corner (pixels from top-left of viewport).
63    pub pos: [f32; 2],
64    /// Screen-space size [w, h] in pixels.
65    pub size: [f32; 2],
66    /// UV top-left in the atlas (0..1).
67    pub uv_min: [f32; 2],
68    /// UV bottom-right in the atlas (0..1).
69    pub uv_max: [f32; 2],
70}
71
72/// Layout result for a single-line text string.
73#[derive(Debug, Clone)]
74pub(crate) struct TextLayout {
75    /// One quad per visible glyph (whitespace characters are skipped).
76    pub quads: Vec<GlyphQuad>,
77    /// Total advance width of the laid-out string in pixels.
78    pub total_width: f32,
79    /// Line height in pixels (ascent - descent + line gap at the requested size).
80    pub height: f32,
81}
82
83// ---------------------------------------------------------------------------
84// GlyphAtlas
85// ---------------------------------------------------------------------------
86
87/// A dynamically-growing glyph atlas backed by a single `Rgba8Unorm` texture.
88///
89/// Owned by [`ViewportGpuResources`]; never exposed in the public API.
90pub(crate) struct GlyphAtlas {
91    /// Parsed fontdue fonts.  Index 0 is always the built-in default.
92    fonts: Vec<fontdue::Font>,
93
94    /// Cached rasterized glyphs.
95    entries: HashMap<GlyphKey, GlyphEntry>,
96
97    /// CPU-side atlas pixel data (single-channel alpha, packed row-major).
98    /// Stored as RGBA for direct GPU upload: R=G=B=255, A=coverage.
99    pixels: Vec<[u8; 4]>,
100
101    /// Current atlas dimensions (always square, power of two).
102    size: u32,
103
104    /// Simple row-based packer state.
105    cursor_x: u32,
106    cursor_y: u32,
107    row_height: u32,
108
109    /// GPU texture (recreated when the atlas grows).
110    pub texture: wgpu::Texture,
111    /// View into the atlas texture.
112    pub view: wgpu::TextureView,
113
114    /// Set to `true` whenever new glyphs have been rasterized since the last
115    /// GPU upload.  Cleared by [`GlyphAtlas::upload_if_dirty`].
116    dirty: bool,
117}
118
119impl GlyphAtlas {
120    /// Initial atlas size in pixels (width = height).
121    const INITIAL_SIZE: u32 = 512;
122
123    /// Create a new atlas with the built-in default font pre-loaded.
124    pub fn new(device: &wgpu::Device) -> Self {
125        let default_font =
126            fontdue::Font::from_bytes(DEFAULT_FONT_BYTES, fontdue::FontSettings::default())
127                .expect("built-in default font must parse");
128
129        let size = Self::INITIAL_SIZE;
130        let pixel_count = (size * size) as usize;
131        let pixels = vec![[255, 255, 255, 0]; pixel_count];
132
133        let (texture, view) = Self::create_texture(device, size);
134
135        Self {
136            fonts: vec![default_font],
137            entries: HashMap::new(),
138            pixels,
139            size,
140            cursor_x: 0,
141            cursor_y: 0,
142            row_height: 0,
143            texture,
144            view,
145            dirty: false,
146        }
147    }
148
149    /// Register a user-supplied TTF font.  Returns a [`FontHandle`] that can be
150    /// passed to overlay items.
151    pub fn upload_font(&mut self, ttf_bytes: &[u8]) -> Result<FontHandle, FontError> {
152        let font = fontdue::Font::from_bytes(ttf_bytes, fontdue::FontSettings::default())
153            .map_err(|e| FontError::ParseFailed(e.to_string()))?;
154        let index = self.fonts.len();
155        self.fonts.push(font);
156        Ok(FontHandle(index))
157    }
158
159    /// Lay out a single-line string and return positioned glyph quads.
160    ///
161    /// Glyphs that are not yet in the atlas are rasterized and packed on the
162    /// fly.  Call [`upload_if_dirty`] after all layout calls for the frame to
163    /// push new glyphs to the GPU.
164    pub fn layout_text(
165        &mut self,
166        text: &str,
167        font_size: f32,
168        font: Option<FontHandle>,
169        device: &wgpu::Device,
170    ) -> TextLayout {
171        let font_index = font.map_or(0, |h| h.0);
172        let size_tenths = (font_size * 10.0).round() as u32;
173        let px = font_size;
174
175        let metrics = self.fonts[font_index].horizontal_line_metrics(px);
176        let height = metrics
177            .map(|m| m.ascent - m.descent + m.line_gap)
178            .unwrap_or(px * 1.2);
179
180        let mut quads = Vec::new();
181        let mut pen_x: f32 = 0.0;
182
183        let mut prev_glyph: Option<u16> = None;
184        for ch in text.chars() {
185            let glyph_index = self.fonts[font_index].lookup_glyph_index(ch);
186
187            // Kerning.
188            if let Some(prev) = prev_glyph {
189                if let Some(kern) =
190                    self.fonts[font_index].horizontal_kern_indexed(prev, glyph_index, px)
191                {
192                    pen_x += kern;
193                }
194            }
195            prev_glyph = Some(glyph_index);
196
197            // Get metrics for advance, even for whitespace.
198            let m = self.fonts[font_index].metrics_indexed(glyph_index, px);
199
200            // Only emit a quad for glyphs with visible bitmap area.
201            if m.width > 0 && m.height > 0 {
202                let entry = self.ensure_glyph(device, font_index, glyph_index, size_tenths, px);
203                let atlas_size = self.size as f32;
204
205                quads.push(GlyphQuad {
206                    pos: [pen_x + entry.offset_x, entry.offset_y],
207                    size: [entry.width as f32, entry.height as f32],
208                    uv_min: [entry.x as f32 / atlas_size, entry.y as f32 / atlas_size],
209                    uv_max: [
210                        (entry.x + entry.width) as f32 / atlas_size,
211                        (entry.y + entry.height) as f32 / atlas_size,
212                    ],
213                });
214            }
215
216            pen_x += m.advance_width;
217        }
218
219        TextLayout {
220            quads,
221            total_width: pen_x,
222            height,
223        }
224    }
225
226    /// Lay out text with word wrapping at a maximum width.
227    ///
228    /// Words that exceed `max_width` on their own are not broken: they extend
229    /// past the boundary.  The returned `total_width` is the maximum line width
230    /// actually used.
231    pub fn layout_text_wrapped(
232        &mut self,
233        text: &str,
234        font_size: f32,
235        font: Option<FontHandle>,
236        max_width: f32,
237        device: &wgpu::Device,
238    ) -> TextLayout {
239        let font_index = font.map_or(0, |h| h.0);
240        let px = font_size;
241
242        let metrics = self.fonts[font_index].horizontal_line_metrics(px);
243        let line_height = metrics
244            .map(|m| m.ascent - m.descent + m.line_gap)
245            .unwrap_or(px * 1.2);
246
247        // Split into words and lay out greedily.
248        let words: Vec<&str> = text.split_whitespace().collect();
249        if words.is_empty() {
250            return TextLayout {
251                quads: Vec::new(),
252                total_width: 0.0,
253                height: line_height,
254            };
255        }
256
257        let size_tenths = (px * 10.0).round() as u32;
258        let space_advance = {
259            let gi = self.fonts[font_index].lookup_glyph_index(' ');
260            self.fonts[font_index].metrics_indexed(gi, px).advance_width
261        };
262
263        let mut quads = Vec::new();
264        let mut line_x: f32 = 0.0;
265        let mut line_y: f32 = 0.0;
266        let mut max_line_width: f32 = 0.0;
267        let mut first_on_line = true;
268
269        for word in &words {
270            // Measure the word width.
271            let mut word_quads: Vec<GlyphQuad> = Vec::new();
272            let mut pen_x: f32 = 0.0;
273            let mut prev_glyph: Option<u16> = None;
274
275            for ch in word.chars() {
276                let glyph_index = self.fonts[font_index].lookup_glyph_index(ch);
277                if let Some(prev) = prev_glyph {
278                    if let Some(kern) =
279                        self.fonts[font_index].horizontal_kern_indexed(prev, glyph_index, px)
280                    {
281                        pen_x += kern;
282                    }
283                }
284                prev_glyph = Some(glyph_index);
285                let m = self.fonts[font_index].metrics_indexed(glyph_index, px);
286                if m.width > 0 && m.height > 0 {
287                    let entry = self.ensure_glyph(device, font_index, glyph_index, size_tenths, px);
288                    let atlas_size = self.size as f32;
289                    word_quads.push(GlyphQuad {
290                        pos: [pen_x + entry.offset_x, entry.offset_y],
291                        size: [entry.width as f32, entry.height as f32],
292                        uv_min: [entry.x as f32 / atlas_size, entry.y as f32 / atlas_size],
293                        uv_max: [
294                            (entry.x + entry.width) as f32 / atlas_size,
295                            (entry.y + entry.height) as f32 / atlas_size,
296                        ],
297                    });
298                }
299                pen_x += m.advance_width;
300            }
301            let word_width = pen_x;
302
303            // Wrap if this word doesn't fit on the current line.
304            let test_x = if first_on_line {
305                line_x
306            } else {
307                line_x + space_advance
308            };
309            if !first_on_line && test_x + word_width > max_width {
310                max_line_width = max_line_width.max(line_x);
311                line_x = 0.0;
312                line_y += line_height;
313                first_on_line = true;
314            }
315
316            let start_x = if first_on_line {
317                line_x
318            } else {
319                line_x + space_advance
320            };
321            for mut gq in word_quads {
322                gq.pos[0] += start_x;
323                gq.pos[1] += line_y;
324                quads.push(gq);
325            }
326            line_x = start_x + word_width;
327            first_on_line = false;
328        }
329
330        max_line_width = max_line_width.max(line_x);
331        let total_height = line_y + line_height;
332
333        TextLayout {
334            quads,
335            total_width: max_line_width,
336            height: total_height,
337        }
338    }
339
340    /// Return the font ascent in pixels for the given font index and size.
341    ///
342    /// The ascent is the distance from the baseline to the top of the tallest
343    /// glyph.  Used to position glyph quads relative to a text origin at the
344    /// top-left corner of the bounding box.
345    pub fn font_ascent(&self, font_index: usize, font_size: f32) -> f32 {
346        self.fonts[font_index]
347            .horizontal_line_metrics(font_size)
348            .map(|m| m.ascent)
349            .unwrap_or(font_size * 0.8)
350    }
351
352    /// Upload new glyph data to the GPU if any glyphs were rasterized since
353    /// the last upload.
354    pub fn upload_if_dirty(&mut self, queue: &wgpu::Queue) {
355        if !self.dirty {
356            return;
357        }
358        let flat: Vec<u8> = self.pixels.iter().flat_map(|p| p.iter().copied()).collect();
359        queue.write_texture(
360            wgpu::TexelCopyTextureInfo {
361                texture: &self.texture,
362                mip_level: 0,
363                origin: wgpu::Origin3d::ZERO,
364                aspect: wgpu::TextureAspect::All,
365            },
366            &flat,
367            wgpu::TexelCopyBufferLayout {
368                offset: 0,
369                bytes_per_row: Some(self.size * 4),
370                rows_per_image: Some(self.size),
371            },
372            wgpu::Extent3d {
373                width: self.size,
374                height: self.size,
375                depth_or_array_layers: 1,
376            },
377        );
378        self.dirty = false;
379    }
380
381    // ------------------------------------------------------------------
382    // Private helpers
383    // ------------------------------------------------------------------
384
385    /// Ensure a glyph is in the atlas, rasterizing and packing it if needed.
386    /// Returns the atlas entry.
387    fn ensure_glyph(
388        &mut self,
389        device: &wgpu::Device,
390        font_index: usize,
391        glyph_index: u16,
392        size_tenths: u32,
393        px: f32,
394    ) -> GlyphEntry {
395        let key = GlyphKey {
396            font_index,
397            glyph_index,
398            size_tenths,
399        };
400
401        if let Some(&entry) = self.entries.get(&key) {
402            return entry;
403        }
404
405        // Rasterize.
406        let (metrics, bitmap) = self.fonts[font_index].rasterize_indexed(glyph_index, px);
407        let w = metrics.width as u32;
408        let h = metrics.height as u32;
409
410        if w == 0 || h == 0 {
411            // Whitespace glyph: insert a zero-area entry.
412            let entry = GlyphEntry {
413                x: 0,
414                y: 0,
415                width: 0,
416                height: 0,
417                offset_x: metrics.xmin as f32,
418                offset_y: -(metrics.ymin as f32 + h as f32),
419            };
420            self.entries.insert(key, entry);
421            return entry;
422        }
423
424        // Pack into the atlas (simple row packer with 1px padding).
425        let pad = 1;
426        if self.cursor_x + w + pad > self.size {
427            // Move to next row.
428            self.cursor_y += self.row_height + pad;
429            self.cursor_x = 0;
430            self.row_height = 0;
431        }
432        if self.cursor_y + h + pad > self.size {
433            // Atlas is full : grow.
434            self.grow(device);
435        }
436
437        let x = self.cursor_x;
438        let y = self.cursor_y;
439
440        // Blit coverage into the RGBA pixel buffer.
441        for row in 0..h {
442            for col in 0..w {
443                let src = (row * w + col) as usize;
444                let dst = ((y + row) * self.size + (x + col)) as usize;
445                self.pixels[dst] = [255, 255, 255, bitmap[src]];
446            }
447        }
448        self.dirty = true;
449
450        self.cursor_x = x + w + pad;
451        self.row_height = self.row_height.max(h);
452
453        let entry = GlyphEntry {
454            x,
455            y,
456            width: w,
457            height: h,
458            offset_x: metrics.xmin as f32,
459            offset_y: -(metrics.ymin as f32 + h as f32),
460        };
461        self.entries.insert(key, entry);
462        entry
463    }
464
465    /// Double the atlas size, copying existing pixel data into the new buffer
466    /// and recreating the GPU texture.
467    fn grow(&mut self, device: &wgpu::Device) {
468        let old_size = self.size;
469        let new_size = old_size * 2;
470        tracing::info!(
471            "Growing glyph atlas from {}x{} to {}x{}",
472            old_size,
473            old_size,
474            new_size,
475            new_size
476        );
477
478        let mut new_pixels = vec![[255, 255, 255, 0u8]; (new_size * new_size) as usize];
479        for row in 0..old_size {
480            let src_start = (row * old_size) as usize;
481            let dst_start = (row * new_size) as usize;
482            new_pixels[dst_start..dst_start + old_size as usize]
483                .copy_from_slice(&self.pixels[src_start..src_start + old_size as usize]);
484        }
485
486        self.pixels = new_pixels;
487        self.size = new_size;
488
489        let (texture, view) = Self::create_texture(device, new_size);
490        self.texture = texture;
491        self.view = view;
492        self.dirty = true; // Full re-upload needed.
493    }
494
495    fn create_texture(device: &wgpu::Device, size: u32) -> (wgpu::Texture, wgpu::TextureView) {
496        let texture = device.create_texture(&wgpu::TextureDescriptor {
497            label: Some("glyph_atlas"),
498            size: wgpu::Extent3d {
499                width: size,
500                height: size,
501                depth_or_array_layers: 1,
502            },
503            mip_level_count: 1,
504            sample_count: 1,
505            dimension: wgpu::TextureDimension::D2,
506            format: wgpu::TextureFormat::Rgba8Unorm,
507            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
508            view_formats: &[],
509        });
510        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
511        (texture, view)
512    }
513}
514
515// ---------------------------------------------------------------------------
516// FontError
517// ---------------------------------------------------------------------------
518
519/// Error returned by [`super::ViewportGpuResources::upload_font`].
520#[derive(Debug, Clone, thiserror::Error)]
521pub enum FontError {
522    /// The TTF data could not be parsed.
523    #[error("font parsing failed: {0}")]
524    ParseFailed(String),
525}
526
527// ---------------------------------------------------------------------------
528// ViewportGpuResources integration
529// ---------------------------------------------------------------------------
530
531impl super::ViewportGpuResources {
532    /// Upload a user-supplied TTF font for use with overlay items.
533    ///
534    /// Returns an opaque [`FontHandle`] that can be passed to [`LabelItem`],
535    /// [`ScalarBarItem`], or [`RulerItem`] via their `font` field.  Pass
536    /// `None` on those items to use the built-in default font instead.
537    ///
538    /// The font bytes must be a valid TrueType (`.ttf`) file.
539    pub fn upload_font(&mut self, ttf_bytes: &[u8]) -> Result<FontHandle, FontError> {
540        self.glyph_atlas.upload_font(ttf_bytes)
541    }
542}
viewport_lib/resources/font.rs

viewport_lib/resources/
font.rs
