Struct TextAtlas

pub struct TextAtlas { /* private fields */ }

Multi-page GPU glyph atlas with LRU eviction.

The atlas allocates one 1024-square RGBA8 page eagerly and grows to MAX_ATLAS_PAGES. Pinned pages cannot be reset during a frame. Unpinned eviction clears an entire least-recently-used page, not an individual glyph.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
let _: usize = std::mem::size_of::<TextAtlas>();

Implementations

impl TextAtlas

pub fn new( device: &Device, queue: &Queue, tex_bind_group_layout: &BindGroupLayout, ) -> Self

Creates an atlas, sampler, and the mandatory first 1024-square page.

The supplied bind-group layout must contain a filterable 2D texture at binding 0 and a filtering sampler at binding 1.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn create(device: &wgpu::Device, queue: &wgpu::Queue,
    layout: &wgpu::BindGroupLayout) -> TextAtlas {
    TextAtlas::new(device, queue, layout)
}

pub fn bind_group(&self) -> &BindGroup

Page 0 bind group (always allocated; legacy renderer path).

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn binding(atlas: &TextAtlas) -> &wgpu::BindGroup { atlas.bind_group() }

pub fn page_bind_group(&self, page_idx: u8) -> &BindGroup

Bind group for the given atlas page index.

Panics

Panics if page_idx >= page_count().

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn first(atlas: &TextAtlas) -> &wgpu::BindGroup { atlas.page_bind_group(0) }

pub fn page_count(&self) -> usize

Returns the number of allocated pages, always in 1..=MAX_ATLAS_PAGES.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn pages(atlas: &TextAtlas) -> usize { atlas.page_count() }

pub fn begin_frame(&mut self) -> TextAtlasFrame<'_>

Starts a frame and returns a guard that unpins pages on drop.

Calling this discards the previous frame’s counters and pins, so guards must not conceptually overlap.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn frame(atlas: &mut TextAtlas) { let _guard = atlas.begin_frame(); }

pub fn start_frame(&mut self)

Resets per-frame counters and clears all page pins.

Prefer Self::begin_frame when scoped access is practical.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn start(atlas: &mut TextAtlas) { atlas.start_frame(); }

pub fn finish_frame(&mut self)

Clears page pins without changing counters, glyphs, or allocations.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn finish(atlas: &mut TextAtlas) { atlas.finish_frame(); }

pub fn stats(&self) -> TextAtlasStats

Returns current frame counters with a live page-count snapshot.

Examples

use ailloli_ui_render_wgpu::text::{TextAtlas, TextAtlasStats};
fn stats(atlas: &TextAtlas) -> TextAtlasStats { atlas.stats() }

pub fn get_or_rasterize( &mut self, device: &Device, queue: &Queue, bind_group_layout: &BindGroupLayout, key: GlyphKey, font_data: &[u8], ) -> Option<(u8, Glyph)>

Looks up or rasterizes a glyph without protecting its page from eviction.

Returns (page_index, metrics) or None on raster/allocation failure. Use Self::get_or_rasterize_pinned during frame preparation.

Examples

use ailloli_ui_render_wgpu::text::{GlyphKey, TextAtlas};
fn lookup(atlas: &mut TextAtlas, device: &wgpu::Device, queue: &wgpu::Queue,
    layout: &wgpu::BindGroupLayout, key: GlyphKey, font: &[u8]) {
    let _ = atlas.get_or_rasterize(device, queue, layout, key, font);
}

pub fn get_or_rasterize_pinned( &mut self, device: &Device, queue: &Queue, bind_group_layout: &BindGroupLayout, key: GlyphKey, font_data: &[u8], ) -> Option<(u8, Glyph)>

Looks up or rasterizes a glyph and pins its page for the current frame.

If every page is pinned and full, returns None and increments both evictions_blocked and glyphs_skipped.

Examples

use ailloli_ui_render_wgpu::text::{GlyphKey, TextAtlas};
fn lookup(atlas: &mut TextAtlas, device: &wgpu::Device, queue: &wgpu::Queue,
    layout: &wgpu::BindGroupLayout, key: GlyphKey, font: &[u8]) {
    let _ = atlas.get_or_rasterize_pinned(device, queue, layout, key, font);
}

pub fn record_missing_face(&mut self)

Saturating-increments the missing-face/skip counter.

Examples

use ailloli_ui_render_wgpu::text::TextAtlas;
fn missing(atlas: &mut TextAtlas) { atlas.record_missing_face(); }