Trait Atlas 

pub trait Atlas: Sealed {
    // Required methods
    fn get_glyph_id(&self, key: &str, style_bits: u16) -> Option<u16>;
    fn get_base_glyph_id(&self, key: &str) -> Option<u16>;
    fn cell_size(&self) -> (i32, i32);
    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(&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(
        &self,
        key: &str,
        style_bits: u16,
    ) -> Option<GlyphSlot>;
    fn base_lookup_mask(&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) -> (i32, i32);
}

Trait defining the interface for font atlases.

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

Required Methods

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

Returns the glyph identifier for the given key and style bits

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

Returns the base glyph identifier for the given key

fn cell_size(&self) -> (i32, i32)

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(&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.

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(&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 base_lookup_mask(&self) -> u32

Returns the bitmask for extracting the base glyph ID from a styled glyph ID.

The glyph ID encodes both the base glyph index and style/effect flags. This mask isolates the base ID portion, which is used for texture coordinate calculation and symbol reverse-lookup.

Implementation Differences

• StaticFontAtlas returns 0x1FFF (13 bits):

  • Bits 0-9: Base glyph ID (1024 values for regular glyphs)
  • Bits 10-11: Reserved for font style derivation
  • Bit 12: Emoji flag (included in mask for emoji base ID extraction)
  • Supports the full glyph ID encoding scheme from beamterm-atlas

• DynamicFontAtlas returns 0x0FFF (12 bits):

  • Uses a flat slot-based addressing (4096 total slots)
  • Emoji are tracked via GlyphSlot::Emoji variant rather than a flag bit
  • Simpler addressing since glyphs are assigned sequentially at runtime

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

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) -> (i32, i32)

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