Struct GlyphAtlas 

pub struct GlyphAtlas {
    eviction_config: GlyphCacheConfig,
    static_entries: HashMap<GlyphCacheKey, GlyphCacheEntry, FixedState>,
    variable_entries: HashMap<SmallVec<[NormalizedCoord; 4]>, HashMap<GlyphCacheKey, GlyphCacheEntry, FixedState>, FixedState>,
    serial: u64,
    last_eviction_serial: u64,
    entry_count: usize,
    pending_uploads: Vec<PendingBitmapUpload>,
    pending_clear_rects: Vec<PendingClearRect>,
    pending_atlas_commands: SmallVec<[Option<AtlasCommandRecorder>; 1]>,
    cache_hits: u64,
    cache_misses: u64,
}

Core glyph atlas cache data shared by all renderer backends.

Contains the cache entries, LRU tracking, pending uploads, and statistics. Does not own any pixel storage — that responsibility belongs to the concrete wrapper types provided by the integrating renderer crate.

Fields

eviction_config: GlyphCacheConfig

Eviction configuration.

static_entries: HashMap<GlyphCacheKey, GlyphCacheEntry, FixedState>

Entries for non-variable fonts.

variable_entries: HashMap<SmallVec<[NormalizedCoord; 4]>, HashMap<GlyphCacheKey, GlyphCacheEntry, FixedState>, FixedState>

Entries for variable fonts, keyed by variation coordinates.

serial: u64

Current frame serial for LRU tracking.

last_eviction_serial: u64

Serial of last eviction pass.

entry_count: usize

Total cached glyph count (across all maps).

pending_uploads: Vec<PendingBitmapUpload>

Bitmap glyphs awaiting GPU upload.

pending_clear_rects: Vec<PendingClearRect>

Atlas regions that must be cleared to transparent before compositing.

pending_atlas_commands: SmallVec<[Option<AtlasCommandRecorder>; 1]>

Outline and COLR glyph commands awaiting replay, indexed by atlas page. Uses SmallVec with inline capacity of 1 because most applications use a single atlas page; the common case avoids heap allocation entirely.

cache_hits: u64

Number of cache hits since last clear_stats().

cache_misses: u64

Number of cache misses since last clear_stats().

Implementations

impl GlyphAtlas

pub fn new() -> Self

Creates a new empty core cache with default eviction settings.

pub fn with_config(eviction_config: GlyphCacheConfig) -> Self

Creates a new empty core cache with custom eviction settings.

pub fn config(&self) -> &GlyphCacheConfig

Returns a reference to the cache configuration.

pub fn get(&mut self, key: &GlyphCacheKey) -> Option<AtlasSlot>

Look up a cached glyph.

pub fn insert_entry( &mut self, image_cache: &mut ImageCache, key: GlyphCacheKey, raster_metrics: RasterMetrics, ) -> Option<AtlasSlot>

Allocate atlas space and insert a cache entry.

Returns the allocated AtlasSlot on success.

pub fn insert( &mut self, image_cache: &mut ImageCache, key: GlyphCacheKey, raster_metrics: RasterMetrics, ) -> Option<(AtlasSlot, &mut AtlasCommandRecorder)>

Allocate atlas space, insert a cache entry, and return the page recorder.

pub fn drain_pending_uploads( &mut self, ) -> impl Iterator<Item = PendingBitmapUpload> + '_

Drain all pending bitmap uploads, keeping the allocation for reuse.

pub fn drain_pending_clear_rects( &mut self, ) -> impl Iterator<Item = PendingClearRect> + '_

Drain all pending clear rects, keeping the allocation for reuse.

pub fn push_pending_upload( &mut self, image_id: ImageId, pixmap: Arc<Pixmap>, atlas_slot: AtlasSlot, )

Queue a bitmap pixmap for later processing.

pub fn replay_pending_atlas_commands( &mut self, f: impl FnMut(&mut AtlasCommandRecorder), )

Replay all pending atlas command recorders (one per dirty page).

The closure receives each non-empty recorder by mutable reference. After the closure returns, the recorder’s commands are cleared but the allocation is kept for reuse next frame.

pub fn recorder_for_page( &mut self, page_index: u32, atlas_width: u16, atlas_height: u16, ) -> &mut AtlasCommandRecorder

Get (or create) the command recorder for the given atlas page.

pub fn maintain(&mut self, image_cache: &mut ImageCache)

Advance the frame counter and potentially evict old entries.

fn tick(&mut self)

Advance the frame counter.

fn evict_old_entries(&mut self, image_cache: &mut ImageCache)

Evict entries that haven’t been used recently.

For each evicted entry, queues a PendingClearRect covering the full padded atlas region. The application must drain these via drain_pending_clear_rects and zero each region so that stale pixel data doesn’t bleed through when the slot is later reused and composited with SrcOver.

pub fn clear(&mut self)

Clear all cache entries, pending work queues, and statistics.

pub fn len(&self) -> usize

Get the number of cached glyphs.

pub fn is_empty(&self) -> bool

Returns true if the cache contains no entries.

pub fn cache_hits(&self) -> u64

Get the number of cache hits since last clear_stats().

pub fn cache_misses(&self) -> u64

Get the number of cache misses since last clear_stats().

pub fn clear_stats(&mut self)

Reset cache hit/miss counters without clearing the cache itself.

impl GlyphAtlas

pub fn stats(&self, page_count: usize) -> GlyphCacheStats

Get detailed statistics about cached glyphs.

pub fn log_hit_miss_stats(&self)

Log cache hit/miss statistics at debug level.

pub fn log_atlas_stats(&self, page_count: usize)

Log detailed atlas statistics at debug level.

pub fn all_keys(&self) -> impl Iterator<Item = &GlyphCacheKey>

Returns all cached glyph keys (for debugging).

pub fn log_keys_grouped(&self)

Log all cached keys grouped by glyph ID at debug level.

This is useful for understanding why the same glyph appears multiple times in the atlas (e.g., different subpixel positions or sizes).

Trait Implementations

impl Debug for GlyphAtlas

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GlyphAtlas

fn default() -> Self

Returns the “default value” for a type.