Trait Atlas 

pub trait Atlas: Sealed {
    // Required methods
    fn get_glyph_id(&mut self, key: &str, style_bits: u16) -> Option<u16>;
    fn get_base_glyph_id(&mut self, key: &str) -> Option<u16>;
    fn cell_size(&self) -> CellSize;
    fn bind(&self, gl: &Context);
    fn underline(&self) -> LineDecoration;
    fn strikethrough(&self) -> LineDecoration;
    fn get_symbol(&self, glyph_id: u16) -> Option<CompactString>;
    fn get_ascii_char(&self, glyph_id: u16) -> Option<char>;
    fn glyph_tracker(&self) -> &GlyphTracker;
    fn glyph_count(&self) -> u32;
    fn flush(&mut self, gl: &Context) -> Result<(), Error>;
    fn recreate_texture(&mut self, gl: &Context) -> Result<(), Error>;
    fn for_each_symbol(&self, f: &mut dyn FnMut(u16, &str));
    fn resolve_glyph_slot(
        &mut self,
        key: &str,
        style_bits: u16,
    ) -> Option<GlyphSlot>;
    fn emoji_bit(&self) -> u32;
    fn delete(&self, gl: &Context);
    fn update_pixel_ratio(
        &mut self,
        gl: &Context,
        pixel_ratio: f32,
    ) -> Result<f32, Error>;
    fn cell_scale_for_dpr(&self, pixel_ratio: f32) -> f32;
    fn texture_cell_size(&self) -> CellSize;
}

Trait defining the interface for font atlases.

This trait is sealed and cannot be implemented outside of beamterm crates.

Methods that may mutate internal state (glyph resolution, cache updates, texture uploads) take &mut self. Read-only accessors take &self.

Required Methods

fn get_glyph_id(&mut self, key: &str, style_bits: u16) -> Option<u16>

Returns the glyph identifier for the given key and style bits.

May mutate internal state (e.g., LRU promotion in dynamic atlases, recording missing glyphs in static atlases).

fn get_base_glyph_id(&mut self, key: &str) -> Option<u16>

Returns the base glyph identifier for the given key.

May mutate internal state (e.g., LRU promotion, missing glyph tracking).

fn cell_size(&self) -> CellSize

Returns the height of the atlas in pixels.

fn bind(&self, gl: &Context)

Binds the font atlas texture to the currently active texture unit.

fn underline(&self) -> LineDecoration

Returns the underline configuration

fn strikethrough(&self) -> LineDecoration

Returns the strikethrough configuration

fn get_symbol(&self, glyph_id: u16) -> Option<CompactString>

Returns the symbol for the given glyph ID, if it exists

fn get_ascii_char(&self, glyph_id: u16) -> Option<char>

Returns the ASCII character for the given glyph ID, if it represents an ASCII char.

This is an optimized path for URL detection that avoids string allocation.

fn glyph_tracker(&self) -> &GlyphTracker

Returns a reference to the glyph tracker for accessing missing glyphs.

fn glyph_count(&self) -> u32

Returns the number of glyphs currently in the atlas.

fn flush(&mut self, gl: &Context) -> Result<(), Error>

Flushes any pending glyph data to the GPU texture.

For dynamic atlases, this rasterizes and uploads queued glyphs that were allocated during [resolve_glyph_slot] calls. Must be called after the atlas texture is bound and before rendering.

For static atlases, this is a no-op since all glyphs are pre-loaded.

Errors

Returns an error if texture upload fails.

fn recreate_texture(&mut self, gl: &Context) -> Result<(), Error>

Recreates the GPU texture after a context loss.

This clears the cache - glyphs will be re-rasterized on next access.

Errors

Returns an error if GPU texture creation fails.

fn for_each_symbol(&self, f: &mut dyn FnMut(u16, &str))

Iterates over all glyph ID to symbol mappings.

Calls the provided closure for each (glyph_id, symbol) pair in the atlas. This is used for debugging and exposing the atlas contents to JavaScript.

fn resolve_glyph_slot( &mut self, key: &str, style_bits: u16, ) -> Option<GlyphSlot>

Resolves a glyph to its texture slot.

For static atlases, performs a lookup and returns None if not found.

For dynamic atlases, allocates a slot if missing and queues for upload. The slot is immediately valid, but [flush] must be called before rendering to populate the texture.

fn emoji_bit(&self) -> u32

Returns the bit position used for emoji detection in the fragment shader.

The glyph ID encodes the base slot index (bits 0-12, masked by 0x1FFF) plus effect/flag bits above that. The emoji bit tells the shader to use texture color (emoji) vs foreground color (regular text).

• StaticFontAtlas returns 12: emoji are at slots >= 4096, so bit 12 is naturally set in their slot address.
• DynamicFontAtlas returns 15: emoji flag is stored in bit 15, outside the 13-bit slot mask, leaving bits 13-14 for underline/strikethrough.

fn delete(&self, gl: &Context)

Deletes the GPU texture resources associated with this atlas.

This method must be called before dropping the atlas to properly clean up GPU resources. Failing to call this will leak GPU memory.

fn update_pixel_ratio( &mut self, gl: &Context, pixel_ratio: f32, ) -> Result<f32, Error>

Updates the pixel ratio for HiDPI rendering.

Returns the effective pixel ratio that should be used for viewport scaling. Each atlas implementation decides how to handle the ratio:

• Static atlas: Returns exact ratio, no internal work needed
• Dynamic atlas: Returns exact ratio, reinitializes with scaled font size

Errors

Returns an error if GPU texture recreation fails during reinitialization.

fn cell_scale_for_dpr(&self, pixel_ratio: f32) -> f32

Returns the cell scale factor for layout calculations at the given DPR.

This determines how cells from cell_size() should be scaled for layout:

• Static atlas: Returns snapped scale values (0.5, 1.0, 2.0, 3.0, etc.) to avoid arbitrary fractional scaling of pre-rasterized glyphs. DPR <= 0.5 snaps to 0.5, otherwise rounds to nearest integer (minimum 1.0).
• Dynamic atlas: Returns 1.0 - glyphs are re-rasterized at the exact DPR, so cell_size() already returns the correctly-scaled physical size

Contract

• Return value is always >= 0.5
• The effective cell size for layout is cell_size() * cell_scale_for_dpr(dpr)
• Static atlases use snapped scaling to preserve glyph sharpness
• Dynamic atlases handle DPR internally via re-rasterization

fn texture_cell_size(&self) -> CellSize

Returns the texture cell size in physical pixels (for fragment shader calculations).

This is used for computing padding fractions in the shader, which need to be based on the actual texture dimensions rather than logical layout dimensions.

• Static atlas: Same as cell_size() (texture is at fixed resolution)
• Dynamic atlas: Physical cell size (before dividing by pixel_ratio)

Implementors

impl Atlas for StaticFontAtlas