Skip to main content

sui_render_wgpu/
text.rs

1use crate::geometry::hash_normalized_analytic_path;
2use crate::geometry::hash_path;
3use crate::text_policy::StemDarkening;
4use crate::text_policy::TextHinting;
5use crate::text_policy::TextRenderMode;
6use std::hash::Hash;
7use sui_core::Path as ScenePath;
8use sui_core::Size;
9use sui_core::Transform;
10use sui_core::Vector;
11use sui_scene::StrokeStyle;
12pub use sui_scene::TextSubpixelOrder;
13use sui_text::ResolvedTextFace;
14use sui_text::TextLayoutCacheSnapshot;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
17pub struct GlyphCacheSnapshot {
18    pub entries: usize,
19    pub hits: usize,
20    pub misses: usize,
21}
22
23impl GlyphCacheSnapshot {
24    pub const fn requests(self) -> usize {
25        self.hits + self.misses
26    }
27
28    pub fn hit_rate(self) -> f64 {
29        let requests = self.requests();
30        if requests == 0 {
31            0.0
32        } else {
33            self.hits as f64 / requests as f64
34        }
35    }
36}
37
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
39pub struct RendererTextCacheSnapshot {
40    pub layout: TextLayoutCacheSnapshot,
41    pub glyph: GlyphCacheSnapshot,
42    pub path: GlyphCacheSnapshot,
43}
44
45#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
46pub(crate) struct TextFrameStats {
47    pub(crate) glyph_instances: usize,
48    pub(crate) glyph_upload_bytes: u64,
49    pub(crate) atlas_miss_count: usize,
50    pub(crate) atlas_miss_time_us: u64,
51}
52
53pub(crate) const TEXT_ATLAS_WIDTH: usize = 2048;
54pub(crate) const TEXT_ATLAS_HEIGHT: usize = 2048;
55pub(crate) const TEXT_ATLAS_PADDING: usize = 2;
56/// Maximum number of atlas pages (texture-array layers) before whole-page LRU eviction kicks in.
57/// Each page is TEXT_ATLAS_WIDTH x TEXT_ATLAS_HEIGHT x 4 bytes (~16 MB); 4 pages -> ~64 MB.
58pub(crate) const TEXT_ATLAS_MAX_PAGES: usize = 4;
59
60#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
61pub(crate) struct GlyphFaceCacheKey {
62    pub(crate) data_ptr: usize,
63    pub(crate) data_len: usize,
64    pub(crate) face_index: u32,
65}
66
67impl GlyphFaceCacheKey {
68    pub(crate) fn new(face: &ResolvedTextFace) -> Self {
69        Self {
70            data_ptr: face.data_ptr(),
71            data_len: face.data_len(),
72            face_index: face.face_index(),
73        }
74    }
75}
76
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
78pub(crate) enum TextAtlasColorMode {
79    Grayscale,
80    LcdSubpixel,
81}
82
83impl From<TextRenderMode> for TextAtlasColorMode {
84    fn from(value: TextRenderMode) -> Self {
85        match value {
86            TextRenderMode::Grayscale => Self::Grayscale,
87            TextRenderMode::LcdSubpixel => Self::LcdSubpixel,
88        }
89    }
90}
91
92#[derive(Debug, Clone, PartialEq, Eq, Hash)]
93pub(crate) struct GlyphCacheKey {
94    pub(crate) face: GlyphFaceCacheKey,
95    pub(crate) glyph_id: u16,
96    pub(crate) scale_bucket: u32,
97    pub(crate) subpixel_offset: GlyphSubpixelOffsetKey,
98    pub(crate) atlas_color_mode: TextAtlasColorMode,
99    pub(crate) subpixel_order: TextSubpixelOrderCacheKey,
100    pub(crate) text_hinting: TextHintingCacheKey,
101    pub(crate) hinting_target: GlyphHintingTarget,
102    pub(crate) stem_darkening: StemDarkeningCacheKey,
103    /// Requested `wght` axis value — different weights of a variable font rasterize to distinct
104    /// outlines and must cache separately. (Static fonts ignore the axis, so this is constant.)
105    pub(crate) weight: u16,
106}
107
108impl GlyphCacheKey {
109    #[allow(clippy::too_many_arguments)]
110    pub(crate) fn new(
111        face: GlyphFaceCacheKey,
112        glyph_id: u16,
113        scale_bucket: u32,
114        subpixel_offset: GlyphSubpixelOffsetKey,
115        text_render_mode: TextRenderMode,
116        text_subpixel_order: TextSubpixelOrder,
117        text_hinting: TextHinting,
118        hinting_target: GlyphHintingTarget,
119        stem_darkening: StemDarkening,
120        weight: u16,
121    ) -> Self {
122        Self {
123            face,
124            glyph_id,
125            scale_bucket,
126            subpixel_offset,
127            atlas_color_mode: TextAtlasColorMode::from(text_render_mode),
128            subpixel_order: TextSubpixelOrderCacheKey::from(text_subpixel_order),
129            text_hinting: TextHintingCacheKey::from(text_hinting),
130            hinting_target,
131            stem_darkening: StemDarkeningCacheKey::from(stem_darkening),
132            weight,
133        }
134    }
135}
136
137#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
138pub(crate) enum TextSubpixelOrderCacheKey {
139    None,
140    Rgb,
141    Bgr,
142}
143
144impl From<TextSubpixelOrder> for TextSubpixelOrderCacheKey {
145    fn from(value: TextSubpixelOrder) -> Self {
146        match value {
147            TextSubpixelOrder::None => Self::None,
148            TextSubpixelOrder::Rgb => Self::Rgb,
149            TextSubpixelOrder::Bgr => Self::Bgr,
150        }
151    }
152}
153
154pub(crate) const GLYPH_SUBPIXEL_VARIANTS_X: u8 = 4;
155pub(crate) const GLYPH_SUBPIXEL_VARIANTS_Y: u8 = 1;
156
157/// Zeno translates outlines, whereas physical subpixel positions translate
158/// sample locations. A BGRA mask therefore needs the opposite offsets: blue
159/// samples to the right, red to the left. Do not infer this from format names.
160pub(crate) const LCD_SUBPIXEL_OFFSET: f32 = 1.0 / 3.0;
161
162pub(crate) fn lcd_bgra_format() -> swash::zeno::Format {
163    swash::zeno::Format::CustomSubpixel([-LCD_SUBPIXEL_OFFSET, 0.0, LCD_SUBPIXEL_OFFSET])
164}
165
166#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
167pub(crate) enum GlyphHintingTarget {
168    None,
169    /// Vertical grid fitting with preserved horizontal outlines and advances.
170    Slight,
171    Symmetric,
172    Asymmetric,
173}
174
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
176pub(crate) struct GlyphSubpixelOffsetKey {
177    pub(crate) x: u8,
178    pub(crate) y: u8,
179}
180
181impl GlyphSubpixelOffsetKey {
182    pub(crate) fn new(x: u8, _y: u8) -> Self {
183        Self {
184            x: x % GLYPH_SUBPIXEL_VARIANTS_X,
185            y: 0,
186        }
187    }
188
189    pub(crate) fn as_swash_offset(self) -> swash::zeno::Vector {
190        swash::zeno::Vector::new(
191            f32::from(self.x) / f32::from(GLYPH_SUBPIXEL_VARIANTS_X),
192            f32::from(self.y) / f32::from(GLYPH_SUBPIXEL_VARIANTS_Y),
193        )
194    }
195}
196
197#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
198pub(crate) enum TextHintingCacheKey {
199    None,
200    Slight { max_ppem_bits: u32 },
201}
202
203impl From<TextHinting> for TextHintingCacheKey {
204    fn from(value: TextHinting) -> Self {
205        match value.normalized() {
206            TextHinting::None => Self::None,
207            TextHinting::Slight { max_ppem } => Self::Slight {
208                max_ppem_bits: max_ppem.to_bits(),
209            },
210        }
211    }
212}
213
214#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
215pub(crate) enum StemDarkeningCacheKey {
216    None,
217    Enabled {
218        max_ppem_bits: u32,
219        amount_bits: u32,
220    },
221}
222
223impl From<StemDarkening> for StemDarkeningCacheKey {
224    fn from(value: StemDarkening) -> Self {
225        match value.normalized() {
226            StemDarkening::None => Self::None,
227            StemDarkening::Enabled { max_ppem, amount } => Self::Enabled {
228                max_ppem_bits: max_ppem.to_bits(),
229                amount_bits: amount.to_bits(),
230            },
231        }
232    }
233}
234
235pub(crate) const GLYPH_SCALE_BUCKETS_PER_UNIT: f32 = 16_384.0;
236
237pub(crate) fn glyph_scale_bucket(scale: f32) -> u32 {
238    ((scale.max(f32::EPSILON) * GLYPH_SCALE_BUCKETS_PER_UNIT)
239        .round()
240        .max(1.0)) as u32
241}
242
243pub(crate) fn glyph_scale_from_bucket(bucket: u32) -> f32 {
244    (bucket.max(1) as f32) / GLYPH_SCALE_BUCKETS_PER_UNIT
245}
246
247#[derive(Debug, Clone, Copy)]
248pub(crate) struct CachedGlyphAtlas {
249    pub(crate) scale: f32,
250    pub(crate) offset: Vector,
251    pub(crate) size: Size,
252    pub(crate) uv_min: [f32; 2],
253    pub(crate) uv_max: [f32; 2],
254    pub(crate) color_mode: TextAtlasColorMode,
255    pub(crate) is_color: bool,
256    /// Which atlas page (texture-array layer) this glyph was rasterized into, or `None` for a
257    /// glyph without ink, which occupies no atlas space and must not keep any page alive.
258    pub(crate) page_index: Option<usize>,
259}
260
261impl CachedGlyphAtlas {
262    /// Which atlas holds this glyph. Color glyphs and LCD masks need RGB; everything else is
263    /// single-channel coverage.
264    pub(crate) fn atlas_kind(&self) -> TextAtlasKind {
265        if self.is_color || self.color_mode == TextAtlasColorMode::LcdSubpixel {
266            TextAtlasKind::Color
267        } else {
268            TextAtlasKind::Mask
269        }
270    }
271}
272
273/// The two glyph atlases. Grayscale coverage, the common case, is stored at one byte per pixel;
274/// color glyphs and LCD subpixel masks need four.
275#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
276pub(crate) enum TextAtlasKind {
277    Mask,
278    Color,
279}
280
281impl TextAtlasKind {
282    pub(crate) const ALL: [Self; 2] = [Self::Mask, Self::Color];
283
284    pub(crate) const fn bytes_per_pixel(self) -> usize {
285        match self {
286            Self::Mask => 1,
287            Self::Color => 4,
288        }
289    }
290
291    /// Value carried in `TextAtlasInstance::coverage_flags[3]` to select the texture.
292    pub(crate) const fn shader_index(self) -> u8 {
293        match self {
294            Self::Mask => 0,
295            Self::Color => 1,
296        }
297    }
298
299    /// Bit for `page` of this atlas in a mask covering both atlases, as kept by retained
300    /// packets. Both atlases together have `2 * TEXT_ATLAS_MAX_PAGES` page slots.
301    pub(crate) const fn page_slot(self, page: usize) -> usize {
302        self.shader_index() as usize * TEXT_ATLAS_MAX_PAGES + page
303    }
304}
305
306/// Number of page slots across both atlases (see [`TextAtlasKind::page_slot`]).
307pub(crate) const TEXT_ATLAS_PAGE_SLOTS: usize = 2 * TEXT_ATLAS_MAX_PAGES;
308
309#[derive(Debug, Clone, Copy, PartialEq, Eq)]
310pub(crate) struct TextAtlasPlacement {
311    pub(crate) x: usize,
312    pub(crate) y: usize,
313}
314
315#[derive(Debug, Clone, Copy, PartialEq, Eq)]
316pub(crate) enum TextAtlasInsertError {
317    Full,
318    TooLarge,
319}
320
321/// One rectangle to copy into an atlas page.
322#[derive(Debug, Clone, PartialEq, Eq)]
323pub(crate) struct TextAtlasWrite {
324    pub(crate) offset: (u32, u32),
325    pub(crate) extent: (u32, u32),
326    pub(crate) pixels: Vec<u8>,
327}
328
329/// Pending CPU->GPU work for one atlas page: an optional clear of the whole layer, then the
330/// rectangles holding glyphs placed since the last upload. The destination page
331/// (texture-array layer) is supplied alongside by `take_uploads`.
332#[derive(Debug, Clone, Default)]
333pub(crate) struct TextAtlasUpload {
334    pub(crate) clear_texture: bool,
335    pub(crate) writes: Vec<TextAtlasWrite>,
336}
337
338impl TextAtlasUpload {
339    pub(crate) fn byte_len(&self) -> usize {
340        self.writes.iter().map(|write| write.pixels.len()).sum()
341    }
342}
343
344#[derive(Debug, Clone)]
345struct PendingGlyph {
346    placement: TextAtlasPlacement,
347    width: usize,
348    height: usize,
349    pixels: Vec<u8>,
350}
351
352/// A single atlas page: a shelf-packing cursor plus the glyphs placed since the last upload.
353/// Pixels live only on the GPU; the multi-page atlas ([`TextAtlasPages`]) holds a collection
354/// of these.
355#[derive(Debug, Clone)]
356pub(crate) struct TextAtlas {
357    pub(crate) width: usize,
358    pub(crate) height: usize,
359    pub(crate) bytes_per_pixel: usize,
360    pending: Vec<PendingGlyph>,
361    pub(crate) clear_texture: bool,
362    pub(crate) generation: u64,
363    pub(crate) cursor: (usize, usize),
364    pub(crate) row_height: usize,
365    /// Frame index of the most recent insert/touch, used for whole-page LRU eviction.
366    pub(crate) last_used_frame: u64,
367}
368
369impl TextAtlas {
370    pub(crate) fn new(width: usize, height: usize, bytes_per_pixel: usize) -> Self {
371        Self {
372            width,
373            height,
374            bytes_per_pixel,
375            pending: Vec::new(),
376            clear_texture: false,
377            generation: 1,
378            cursor: (TEXT_ATLAS_PADDING, TEXT_ATLAS_PADDING),
379            row_height: 0,
380            last_used_frame: 0,
381        }
382    }
383
384    /// Reset this page so its space can be recycled (used when a page is evicted). Flags the
385    /// GPU layer for a clear and drops glyphs not uploaded yet, so only new glyphs are written.
386    pub(crate) fn clear_for_reuse(&mut self) {
387        self.pending.clear();
388        self.cursor = (TEXT_ATLAS_PADDING, TEXT_ATLAS_PADDING);
389        self.row_height = 0;
390        self.clear_texture = true;
391        self.generation = self.generation.wrapping_add(1);
392        self.last_used_frame = 0;
393    }
394
395    pub(crate) fn allocate(
396        &mut self,
397        width: usize,
398        height: usize,
399    ) -> std::result::Result<TextAtlasPlacement, TextAtlasInsertError> {
400        if width == 0 || height == 0 || width > self.width || height > self.height {
401            return Err(TextAtlasInsertError::TooLarge);
402        }
403
404        if self.cursor.0 + width + TEXT_ATLAS_PADDING > self.width {
405            self.cursor.0 = TEXT_ATLAS_PADDING;
406            self.cursor.1 += self.row_height + TEXT_ATLAS_PADDING;
407            self.row_height = 0;
408        }
409
410        if self.cursor.1 + height + TEXT_ATLAS_PADDING > self.height {
411            return Err(TextAtlasInsertError::Full);
412        }
413
414        let placement = TextAtlasPlacement {
415            x: self.cursor.0,
416            y: self.cursor.1,
417        };
418        self.cursor.0 += width + TEXT_ATLAS_PADDING;
419        self.row_height = self.row_height.max(height);
420        Ok(placement)
421    }
422
423    /// Queue a glyph's pixels (`bytes_per_pixel` each) for upload at an allocated placement.
424    fn write(
425        &mut self,
426        placement: TextAtlasPlacement,
427        width: usize,
428        height: usize,
429        pixels: Vec<u8>,
430    ) {
431        debug_assert_eq!(pixels.len(), width * height * self.bytes_per_pixel);
432        self.pending.push(PendingGlyph {
433            placement,
434            width,
435            height,
436            pixels,
437        });
438    }
439
440    #[cfg(test)]
441    pub(crate) fn insert(
442        &mut self,
443        width: usize,
444        height: usize,
445        pixels: Vec<u8>,
446    ) -> std::result::Result<TextAtlasPlacement, TextAtlasInsertError> {
447        let placement = self.allocate(width, height)?;
448        self.write(placement, width, height, pixels);
449        Ok(placement)
450    }
451
452    /// Drain the glyphs placed since the last call as GPU writes. Glyphs placed side by side on
453    /// one shelf are merged into a single strip, with the padding between them and the space
454    /// below shorter glyphs written as zero. That space can be written over safely: the shelf
455    /// packer never places anything else in a row's span behind its cursor, and glyphs placed
456    /// in earlier frames lie outside the strip.
457    pub(crate) fn take_upload(&mut self) -> Option<TextAtlasUpload> {
458        let clear_texture = std::mem::take(&mut self.clear_texture);
459        if self.pending.is_empty() {
460            return clear_texture.then(|| TextAtlasUpload {
461                clear_texture,
462                writes: Vec::new(),
463            });
464        }
465
466        let bpp = self.bytes_per_pixel;
467        let pending = std::mem::take(&mut self.pending);
468        let mut writes = Vec::new();
469        let mut start = 0;
470        while start < pending.len() {
471            let row_y = pending[start].placement.y;
472            let mut end = start + 1;
473            while end < pending.len() && pending[end].placement.y == row_y {
474                end += 1;
475            }
476            let strip = &pending[start..end];
477            let min_x = strip[0].placement.x;
478            let last = &strip[strip.len() - 1];
479            let width = last.placement.x + last.width - min_x;
480            let height = strip.iter().map(|glyph| glyph.height).max().unwrap_or(0);
481            let pixels = if let [glyph] = strip {
482                // A lone glyph is already the exact strip.
483                glyph.pixels.clone()
484            } else {
485                let mut pixels = vec![0; width * height * bpp];
486                for glyph in strip {
487                    let row_bytes = glyph.width * bpp;
488                    let x = (glyph.placement.x - min_x) * bpp;
489                    for row in 0..glyph.height {
490                        let dst = row * width * bpp + x;
491                        pixels[dst..dst + row_bytes]
492                            .copy_from_slice(&glyph.pixels[row * row_bytes..(row + 1) * row_bytes]);
493                    }
494                }
495                pixels
496            };
497            writes.push(TextAtlasWrite {
498                offset: (min_x as u32, row_y as u32),
499                extent: (width as u32, height as u32),
500                pixels,
501            });
502            start = end;
503        }
504
505        Some(TextAtlasUpload {
506            clear_texture,
507            writes,
508        })
509    }
510}
511
512/// Result of inserting a glyph into the multi-page atlas: where it landed, plus the page that was
513/// cleared to make room (if any) so the caller can drop the glyph-cache entries that pointed into
514/// the now-recycled page.
515#[derive(Debug, Clone, Copy, PartialEq, Eq)]
516pub(crate) struct TextAtlasInsertion {
517    pub(crate) page_index: usize,
518    pub(crate) placement: TextAtlasPlacement,
519    pub(crate) evicted_page: Option<usize>,
520}
521
522impl TextAtlasInsertion {
523    pub(crate) fn placed(page_index: usize, placement: TextAtlasPlacement) -> Self {
524        Self {
525            page_index,
526            placement,
527            evicted_page: None,
528        }
529    }
530
531    pub(crate) fn evicted(page_index: usize, placement: TextAtlasPlacement) -> Self {
532        Self {
533            page_index,
534            placement,
535            evicted_page: Some(page_index),
536        }
537    }
538}
539
540/// A multi-page glyph atlas: a collection of uniformly sized [`TextAtlas`] pages that grows on
541/// demand up to `max_pages`, then recycles the least-recently-used page. Each page maps to one
542/// layer of the GPU texture array. An atlas may have no pages until its first glyph arrives.
543#[derive(Debug, Clone)]
544pub(crate) struct TextAtlasPages {
545    pub(crate) pages: Vec<TextAtlas>,
546    pub(crate) page_width: usize,
547    pub(crate) page_height: usize,
548    pub(crate) bytes_per_pixel: usize,
549    pub(crate) max_pages: usize,
550}
551
552impl TextAtlasPages {
553    /// An atlas with no pages yet; the first insert allocates one.
554    pub(crate) fn new(
555        page_width: usize,
556        page_height: usize,
557        bytes_per_pixel: usize,
558        max_pages: usize,
559    ) -> Self {
560        Self {
561            pages: Vec::new(),
562            page_width,
563            page_height,
564            bytes_per_pixel,
565            max_pages: max_pages.max(1),
566        }
567    }
568
569    pub(crate) fn for_kind(kind: TextAtlasKind) -> Self {
570        Self::new(
571            TEXT_ATLAS_WIDTH,
572            TEXT_ATLAS_HEIGHT,
573            kind.bytes_per_pixel(),
574            TEXT_ATLAS_MAX_PAGES,
575        )
576    }
577
578    /// Number of allocated atlas pages (drives how many texture-array layers are allocated).
579    pub(crate) fn page_count(&self) -> usize {
580        self.pages.len()
581    }
582
583    /// Uniform dimensions of every page, in pixels.
584    pub(crate) fn page_size(&self) -> (u32, u32) {
585        (self.page_width as u32, self.page_height as u32)
586    }
587
588    fn new_page(&self) -> TextAtlas {
589        TextAtlas::new(self.page_width, self.page_height, self.bytes_per_pixel)
590    }
591
592    /// Mark a page as used in `frame` so LRU eviction won't reclaim it prematurely. Called on a
593    /// glyph-cache hit (the insert path stamps the page itself).
594    pub(crate) fn touch_page(&mut self, index: usize, frame: u64) {
595        if let Some(page) = self.pages.get_mut(index) {
596            page.last_used_frame = frame;
597        }
598    }
599
600    /// Insert a rasterized glyph, returning the page it landed on plus its placement within that
601    /// page. Tries existing pages in order, then grows a new page if under budget. At budget it
602    /// recycles the least-recently-used page not touched in `frame`, or returns `Full` if every
603    /// page is in use this frame. `frame` stamps the chosen page for that eviction policy.
604    pub(crate) fn insert(
605        &mut self,
606        width: usize,
607        height: usize,
608        pixels: Vec<u8>,
609        frame: u64,
610    ) -> std::result::Result<TextAtlasInsertion, TextAtlasInsertError> {
611        // A glyph larger than a page can never fit on any page.
612        if width == 0 || height == 0 || width > self.page_width || height > self.page_height {
613            return Err(TextAtlasInsertError::TooLarge);
614        }
615
616        // Allocate first so the pixels move into whichever page has room.
617        let mut target = None;
618        for index in 0..self.pages.len() {
619            match self.pages[index].allocate(width, height) {
620                Ok(placement) => {
621                    target = Some(TextAtlasInsertion::placed(index, placement));
622                    break;
623                }
624                Err(TextAtlasInsertError::TooLarge) => return Err(TextAtlasInsertError::TooLarge),
625                Err(TextAtlasInsertError::Full) => {}
626            }
627        }
628
629        let insertion = match target {
630            Some(insertion) => insertion,
631            None if self.pages.len() < self.max_pages => {
632                let mut page = self.new_page();
633                let placement = page.allocate(width, height)?;
634                self.pages.push(page);
635                TextAtlasInsertion::placed(self.pages.len() - 1, placement)
636            }
637            None => {
638                // At the page budget: evict the least-recently-used page that was NOT touched
639                // this frame. Pages used earlier this frame are off-limits -- glyphs already
640                // emitted this frame point into them, so clearing one would make those draws
641                // sample garbage. This guard is the load-bearing invariant of the eviction scheme.
642                let evict_index = self
643                    .pages
644                    .iter()
645                    .enumerate()
646                    .filter(|(_, page)| page.last_used_frame != frame)
647                    .min_by_key(|(_, page)| page.last_used_frame)
648                    .map(|(index, _)| index);
649                let Some(evict_index) = evict_index else {
650                    // Every page is hot this frame; signal Full so the caller drops this glyph.
651                    return Err(TextAtlasInsertError::Full);
652                };
653                self.pages[evict_index].clear_for_reuse();
654                let placement = self.pages[evict_index].allocate(width, height)?;
655                TextAtlasInsertion::evicted(evict_index, placement)
656            }
657        };
658
659        let page = &mut self.pages[insertion.page_index];
660        page.write(insertion.placement, width, height, pixels);
661        page.last_used_frame = frame;
662        Ok(insertion)
663    }
664
665    /// Drain the pending upload from each page that has one, tagged with its page index
666    /// (the destination texture-array layer).
667    pub(crate) fn take_uploads(&mut self) -> Vec<(usize, TextAtlasUpload)> {
668        let mut uploads = Vec::new();
669        for (index, page) in self.pages.iter_mut().enumerate() {
670            if let Some(upload) = page.take_upload() {
671                uploads.push((index, upload));
672            }
673        }
674        uploads
675    }
676}
677
678/// The mask and color atlases, addressed by kind or by page slot.
679#[derive(Debug, Clone)]
680pub(crate) struct TextAtlases {
681    pub(crate) mask: TextAtlasPages,
682    pub(crate) color: TextAtlasPages,
683}
684
685impl Default for TextAtlases {
686    fn default() -> Self {
687        Self {
688            mask: TextAtlasPages::for_kind(TextAtlasKind::Mask),
689            color: TextAtlasPages::for_kind(TextAtlasKind::Color),
690        }
691    }
692}
693
694impl TextAtlases {
695    pub(crate) fn get(&self, kind: TextAtlasKind) -> &TextAtlasPages {
696        match kind {
697            TextAtlasKind::Mask => &self.mask,
698            TextAtlasKind::Color => &self.color,
699        }
700    }
701
702    pub(crate) fn get_mut(&mut self, kind: TextAtlasKind) -> &mut TextAtlasPages {
703        match kind {
704            TextAtlasKind::Mask => &mut self.mask,
705            TextAtlasKind::Color => &mut self.color,
706        }
707    }
708
709    fn slot(slot: usize) -> (TextAtlasKind, usize) {
710        let kind = if slot < TEXT_ATLAS_MAX_PAGES {
711            TextAtlasKind::Mask
712        } else {
713            TextAtlasKind::Color
714        };
715        (kind, slot % TEXT_ATLAS_MAX_PAGES)
716    }
717
718    /// Generation of the page in `slot` (see [`TextAtlasKind::page_slot`]), if it exists.
719    pub(crate) fn slot_generation(&self, slot: usize) -> Option<u64> {
720        let (kind, page) = Self::slot(slot);
721        self.get(kind).pages.get(page).map(|page| page.generation)
722    }
723
724    pub(crate) fn touch_slot(&mut self, slot: usize, frame: u64) {
725        let (kind, page) = Self::slot(slot);
726        self.get_mut(kind).touch_page(page, frame);
727    }
728}
729
730#[cfg(test)]
731pub(crate) mod page_tests {
732    use super::*;
733
734    fn opaque(width: usize, height: usize) -> Vec<u8> {
735        vec![255u8; width * height * 4]
736    }
737
738    #[test]
739    fn optimization_regression_fresh_atlas_uploads_only_populated_pixels() {
740        let mut atlas = TextAtlas::new(2048, 2048, 4);
741        atlas.insert(12, 18, opaque(12, 18)).unwrap();
742        let upload = atlas.take_upload().unwrap();
743        assert_eq!(
744            upload.byte_len(),
745            12 * 18 * 4,
746            "a tiny glyph uploaded a whole page"
747        );
748        assert!(atlas.take_upload().is_none());
749    }
750
751    #[test]
752    fn mask_pages_store_one_byte_per_pixel() {
753        let mut pages = TextAtlasPages::new(64, 64, 1, 2);
754        assert_eq!(
755            pages.page_count(),
756            0,
757            "an atlas allocates no page before its first glyph"
758        );
759        pages.insert(5, 7, vec![200; 5 * 7], 1).unwrap();
760        let uploads = pages.take_uploads();
761        assert_eq!(uploads.len(), 1);
762        assert_eq!(uploads[0].1.writes[0].extent, (5, 7));
763        assert_eq!(uploads[0].1.byte_len(), 5 * 7);
764    }
765
766    #[test]
767    fn glyphs_on_one_shelf_upload_as_one_strip() {
768        let mut atlas = TextAtlas::new(64, 64, 1);
769        let first = atlas.insert(3, 4, vec![1; 3 * 4]).unwrap();
770        let second = atlas.insert(2, 6, vec![2; 2 * 6]).unwrap();
771        assert_eq!(first.y, second.y);
772        let upload = atlas.take_upload().unwrap();
773        assert_eq!(upload.writes.len(), 1);
774        let strip = &upload.writes[0];
775        let width = second.x + 2 - first.x;
776        assert_eq!(strip.offset, (first.x as u32, first.y as u32));
777        assert_eq!(strip.extent, (width as u32, 6));
778        let at = |x: usize, y: usize| strip.pixels[y * width + x];
779        assert_eq!(at(0, 0), 1);
780        assert_eq!(at(0, 4), 0, "below a shorter glyph is empty");
781        assert_eq!(at(3, 0), 0, "padding between glyphs is empty");
782        assert_eq!(at(second.x - first.x, 5), 2);
783    }
784
785    #[test]
786    fn glyphs_on_different_shelves_upload_separately() {
787        let mut atlas = TextAtlas::new(16, 64, 1);
788        let first = atlas.insert(10, 4, vec![1; 10 * 4]).unwrap();
789        let second = atlas.insert(10, 4, vec![2; 10 * 4]).unwrap();
790        assert_ne!(first.y, second.y);
791        let upload = atlas.take_upload().unwrap();
792        assert_eq!(upload.writes.len(), 2);
793        assert!(upload.writes.iter().all(|write| write.extent == (10, 4)));
794    }
795
796    #[test]
797    fn recycled_page_upload_clears_old_glyphs() {
798        let mut atlas = TextAtlas::new(64, 64, 4);
799        atlas.insert(60, 60, opaque(60, 60)).unwrap();
800        atlas.take_upload().unwrap();
801        let generation = atlas.generation;
802        atlas.clear_for_reuse();
803        atlas.insert(4, 4, opaque(4, 4)).unwrap();
804        let upload = atlas.take_upload().unwrap();
805        assert!(upload.clear_texture);
806        assert_ne!(atlas.generation, generation);
807        assert_eq!(upload.byte_len(), 4 * 4 * 4);
808        atlas.clear_for_reuse();
809        let clear_only = atlas.take_upload().unwrap();
810        assert!(clear_only.clear_texture);
811        assert!(clear_only.writes.is_empty());
812        assert!(atlas.take_upload().is_none());
813    }
814
815    #[test]
816    fn recycling_drops_glyphs_not_uploaded_yet() {
817        let mut atlas = TextAtlas::new(64, 64, 1);
818        atlas.insert(8, 8, vec![1; 64]).unwrap();
819        atlas.clear_for_reuse();
820        let upload = atlas.take_upload().unwrap();
821        assert!(upload.clear_texture);
822        assert!(upload.writes.is_empty());
823    }
824
825    #[test]
826    fn overflow_allocates_second_page() {
827        let mut pages = TextAtlasPages::new(64, 64, 4, 2);
828
829        // First 60x60 fits on page 0; a second can't share the 64-tall page, so it grows.
830        assert_eq!(
831            pages.insert(60, 60, opaque(60, 60), 1).unwrap().page_index,
832            0
833        );
834        assert_eq!(
835            pages.insert(60, 60, opaque(60, 60), 1).unwrap().page_index,
836            1
837        );
838        assert_eq!(pages.page_count(), 2);
839
840        // Both pages are full, we are at the 2-page budget, and every page was touched this same
841        // frame -> nothing is eligible for eviction -> Full.
842        assert_eq!(
843            pages.insert(60, 60, opaque(60, 60), 1),
844            Err(TextAtlasInsertError::Full)
845        );
846    }
847
848    #[test]
849    fn eviction_reuses_lru_page() {
850        let mut pages = TextAtlasPages::new(64, 64, 4, 2);
851
852        // Page 0 last used at frame 1, page 1 at frame 2.
853        assert_eq!(
854            pages.insert(60, 60, opaque(60, 60), 1).unwrap().page_index,
855            0
856        );
857        assert_eq!(
858            pages.insert(60, 60, opaque(60, 60), 2).unwrap().page_index,
859            1
860        );
861
862        // At budget; inserting at frame 3 evicts the LRU page (page 0) and reuses it.
863        let insertion = pages.insert(60, 60, opaque(60, 60), 3).unwrap();
864        assert_eq!(insertion.page_index, 0);
865        assert_eq!(insertion.evicted_page, Some(0));
866        assert_eq!(pages.page_count(), 2);
867    }
868
869    #[test]
870    fn current_frame_page_not_evicted() {
871        let mut pages = TextAtlasPages::new(64, 64, 4, 2);
872
873        // Both pages are used in frame 5.
874        pages.insert(60, 60, opaque(60, 60), 5).unwrap();
875        pages.insert(60, 60, opaque(60, 60), 5).unwrap();
876
877        // A third glyph in frame 5 must NOT evict a page referenced earlier this frame.
878        assert_eq!(
879            pages.insert(60, 60, opaque(60, 60), 5),
880            Err(TextAtlasInsertError::Full)
881        );
882    }
883
884    #[test]
885    fn too_large_glyph_is_rejected() {
886        let mut pages = TextAtlasPages::new(64, 64, 4, 4);
887        assert_eq!(
888            pages.insert(70, 70, opaque(70, 70), 1),
889            Err(TextAtlasInsertError::TooLarge)
890        );
891        assert_eq!(pages.page_count(), 0);
892    }
893
894    #[test]
895    fn take_uploads_returns_per_page() {
896        let mut pages = TextAtlasPages::new(64, 64, 4, 2);
897        pages.insert(60, 60, opaque(60, 60), 1).unwrap();
898        pages.insert(60, 60, opaque(60, 60), 1).unwrap();
899
900        let uploads = pages.take_uploads();
901        let indices: Vec<usize> = uploads.iter().map(|(index, _)| *index).collect();
902        assert_eq!(uploads.len(), 2);
903        assert!(indices.contains(&0) && indices.contains(&1));
904
905        // Pending state is consumed: a second drain yields nothing.
906        assert!(pages.take_uploads().is_empty());
907    }
908}
909
910#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
911pub(crate) enum PathCacheKind {
912    Fill,
913    Stroke {
914        line_width_bits: u32,
915        cap: sui_scene::StrokeCap,
916        join: sui_scene::StrokeJoin,
917    },
918}
919
920#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
921pub(crate) struct PathCacheKey {
922    pub(crate) signature: u64,
923    pub(crate) kind: PathCacheKind,
924    pub(crate) feather_width_bits: u32,
925}
926
927#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
928pub(crate) struct AnalyticPathCacheKey {
929    pub(crate) signature: u64,
930    pub(crate) kind: PathCacheKind,
931    pub(crate) feather_width_bits: u32,
932}
933
934impl AnalyticPathCacheKey {
935    pub(crate) fn fill(path: &ScenePath, transform: Transform, feather_width: f32) -> Self {
936        Self {
937            signature: hash_normalized_analytic_path(path, transform),
938            kind: PathCacheKind::Fill,
939            feather_width_bits: feather_width.to_bits(),
940        }
941    }
942
943    pub(crate) fn stroke(
944        path: &ScenePath,
945        transform: Transform,
946        stroke: StrokeStyle,
947        feather_width: f32,
948    ) -> Self {
949        Self {
950            signature: hash_normalized_analytic_path(path, transform),
951            kind: PathCacheKind::Stroke {
952                line_width_bits: stroke.width.to_bits(),
953                cap: stroke.cap,
954                join: stroke.join,
955            },
956            feather_width_bits: feather_width.to_bits(),
957        }
958    }
959}
960
961impl PathCacheKey {
962    pub(crate) fn fill(path: &ScenePath, transform: Transform, feather_width: f32) -> Self {
963        Self {
964            signature: hash_path(path, transform),
965            kind: PathCacheKind::Fill,
966            feather_width_bits: feather_width.to_bits(),
967        }
968    }
969
970    pub(crate) fn stroke(
971        path: &ScenePath,
972        transform: Transform,
973        stroke: StrokeStyle,
974        feather_width: f32,
975    ) -> Self {
976        Self {
977            signature: hash_path(path, transform),
978            kind: PathCacheKind::Stroke {
979                line_width_bits: stroke.width.to_bits(),
980                cap: stroke.cap,
981                join: stroke.join,
982            },
983            feather_width_bits: feather_width.to_bits(),
984        }
985    }
986}