beamterm_core/gl/
static_atlas.rs

1use std::collections::HashMap;
2
3use beamterm_data::{FontAtlasData, FontStyle, Glyph};
4use compact_str::{CompactString, ToCompactString};
5
6use super::{
7    atlas,
8    atlas::{Atlas, GlyphSlot, GlyphTracker},
9};
10use crate::error::Error;
11
12/// A texture atlas containing font glyphs for efficient GL text rendering.
13///
14/// `StaticFontAtlas` manages a GL 2D texture array where each layer contains a single
15/// character glyph. This design enables efficient instanced rendering of text by
16/// allowing the GPU to select the appropriate character layer for each rendered cell.
17///
18/// # Architecture
19/// The atlas uses a **GL 2D texture array** where:
20/// - Each layer contains one character glyph
21/// - ASCII characters use their ASCII value as the layer index
22/// - Non-ASCII characters are stored in a hash map for layer lookup
23/// - All glyphs have uniform cell dimensions for consistent spacing
24#[derive(Debug)]
25#[must_use = "call `delete(gl)` before dropping to avoid GPU resource leaks"]
26pub struct StaticFontAtlas {
27    /// The underlying texture
28    texture: crate::gl::texture::Texture,
29    /// Symbol to 3d texture index
30    glyph_coords: HashMap<CompactString, u16>,
31    /// Base glyph identifier to symbol mapping
32    symbol_lookup: HashMap<u16, CompactString>,
33    /// The size of each character cell in pixels
34    cell_size: beamterm_data::CellSize,
35    /// Underline configuration
36    underline: beamterm_data::LineDecoration,
37    /// Strikethrough configuration
38    strikethrough: beamterm_data::LineDecoration,
39    /// Tracks glyphs that were requested but not found in the atlas
40    glyph_tracker: GlyphTracker,
41    /// The last assigned halfwidth base glyph ID, before fullwidth
42    last_halfwidth_base_glyph_id: u16,
43    /// Retained atlas data for context loss recovery
44    atlas_data: FontAtlasData,
45}
46
47impl StaticFontAtlas {
48    /// Creates a TextureAtlas from a grid of equal-sized cells
49    pub fn load(gl: &glow::Context, config: FontAtlasData) -> Result<Self, Error> {
50        let texture = crate::gl::texture::Texture::from_font_atlas_data(gl, &config)?;
51
52        let beamterm_data::CellSize { width: cell_width, height: cell_height } = config.cell_size();
53        let mut layers = HashMap::new();
54        let mut symbol_lookup = HashMap::new();
55
56        // we only store the normal-styled glyphs (incl emoji) in the atlas lookup,
57        // as the correct layer id can be derived from the base glyph id plus font style.
58        //
59        // emoji are (currently all) double-width and occupy two consecutive glyph ids,
60        // but we only store the first id in the lookup.
61        config.glyphs().iter()
62            .filter(|g| g.style() == FontStyle::Normal) // only normal style glyphs
63            .filter(|g| !g.is_ascii())                  // only non-ascii glyphs
64            .for_each(|g| {
65                symbol_lookup.insert(g.id(), g.symbol().into());
66                layers.insert(CompactString::from(g.symbol()), g.id());
67            });
68
69        Ok(Self {
70            texture,
71            glyph_coords: layers,
72            last_halfwidth_base_glyph_id: config.max_halfwidth_base_glyph_id(),
73            symbol_lookup,
74            cell_size: beamterm_data::CellSize::new(cell_width, cell_height),
75            underline: config.underline(),
76            strikethrough: config.strikethrough(),
77            glyph_tracker: GlyphTracker::new(),
78            atlas_data: config,
79        })
80    }
81}
82
83impl atlas::sealed::Sealed for StaticFontAtlas {}
84
85impl Atlas for StaticFontAtlas {
86    fn get_glyph_id(&mut self, key: &str, style_bits: u16) -> Option<u16> {
87        let base_id = self.get_base_glyph_id(key)?;
88        Some(base_id | style_bits)
89    }
90
91    /// Returns the base glyph identifier for the given key
92    fn get_base_glyph_id(&mut self, key: &str) -> Option<u16> {
93        if key.len() == 1 {
94            let ch = key.chars().next().unwrap();
95            if ch.is_ascii() {
96                // 0x00..0x7f double as layer
97                let id = ch as u16;
98                return Some(id);
99            }
100        }
101
102        match self.glyph_coords.get(key) {
103            Some(id) => Some(*id),
104            None => {
105                self.glyph_tracker.record_missing(key);
106                None
107            },
108        }
109    }
110
111    fn cell_size(&self) -> beamterm_data::CellSize {
112        beamterm_data::CellSize::new(
113            self.cell_size.width - 2 * FontAtlasData::PADDING,
114            self.cell_size.height - 2 * FontAtlasData::PADDING,
115        )
116    }
117
118    fn bind(&self, gl: &glow::Context) {
119        self.texture.bind(gl);
120    }
121
122    /// Returns the underline configuration
123    fn underline(&self) -> beamterm_data::LineDecoration {
124        self.underline
125    }
126
127    /// Returns the strikethrough configuration
128    fn strikethrough(&self) -> beamterm_data::LineDecoration {
129        self.strikethrough
130    }
131
132    /// Returns the symbol for the given glyph ID, if it exists
133    fn get_symbol(&self, glyph_id: u16) -> Option<CompactString> {
134        let base_glyph_id = if glyph_id & Glyph::EMOJI_FLAG != 0 {
135            glyph_id & Glyph::GLYPH_ID_EMOJI_MASK
136        } else {
137            glyph_id & Glyph::GLYPH_ID_MASK
138        };
139
140        if (0x20..0x80).contains(&base_glyph_id) {
141            // ASCII characters are directly mapped to their code point
142            let ch = base_glyph_id as u8 as char;
143            Some(ch.to_compact_string())
144        } else {
145            self.symbol_lookup.get(&base_glyph_id).cloned()
146        }
147    }
148
149    fn get_ascii_char(&self, glyph_id: u16) -> Option<char> {
150        // Static atlas: ASCII chars 0x20-0x7F have glyph_id == char code
151        if (0x20..0x80).contains(&glyph_id) {
152            Some(glyph_id as u8 as char)
153        } else {
154            None
155        }
156    }
157
158    fn glyph_tracker(&self) -> &GlyphTracker {
159        &self.glyph_tracker
160    }
161
162    fn glyph_count(&self) -> u32 {
163        // ASCII printable characters: 0x20..0x80 (96 characters)
164        let ascii_count = 0x80 - 0x20;
165        // Non-ASCII glyphs stored in symbol_lookup
166        let non_ascii_count = self.symbol_lookup.len() as u32;
167        ascii_count + non_ascii_count
168    }
169
170    fn flush(&mut self, _gl: &glow::Context) -> Result<(), Error> {
171        Ok(()) // static atlas has no pending glyphs
172    }
173
174    /// Recreates the GPU texture after a context loss.
175    ///
176    /// This method rebuilds the texture from the retained atlas data. All glyph
177    /// mappings and other CPU-side state are preserved; only the GPU texture
178    /// handle is recreated.
179    fn recreate_texture(&mut self, gl: &glow::Context) -> Result<(), Error> {
180        // Delete old texture if it exists (may be invalid after context loss)
181        self.texture.delete(gl);
182
183        // Recreate texture from retained atlas data
184        self.texture = crate::gl::texture::Texture::from_font_atlas_data(gl, &self.atlas_data)?;
185
186        Ok(())
187    }
188
189    fn for_each_symbol(&self, f: &mut dyn FnMut(u16, &str)) {
190        // ASCII printable characters (0x20..0x80)
191        for code in 0x20u16..0x80 {
192            let ch = code as u8 as char;
193            let mut buf = [0u8; 4];
194            let s = ch.encode_utf8(&mut buf);
195            f(code, s);
196        }
197        // Non-ASCII glyphs from symbol lookup
198        for (glyph_id, symbol) in &self.symbol_lookup {
199            f(*glyph_id, symbol.as_str());
200        }
201    }
202
203    fn resolve_glyph_slot(&mut self, key: &str, style_bits: u16) -> Option<GlyphSlot> {
204        if key.len() == 1 {
205            let ch = key.chars().next().unwrap();
206            if ch.is_ascii() {
207                // 0x00..0x7f double as layer
208                let id = ch as u16;
209                return Some(GlyphSlot::Normal(id | style_bits));
210            }
211        }
212
213        match self.glyph_coords.get(key) {
214            Some(base_glyph_id) => {
215                let id = base_glyph_id | style_bits;
216                if *base_glyph_id >= self.last_halfwidth_base_glyph_id {
217                    Some(GlyphSlot::Wide(id))
218                } else if id & Glyph::EMOJI_FLAG != 0 {
219                    Some(GlyphSlot::Emoji(id))
220                } else {
221                    Some(GlyphSlot::Normal(id))
222                }
223            },
224            None => {
225                self.glyph_tracker.record_missing(key);
226                None
227            },
228        }
229    }
230
231    /// Returns `0x1FFF` to support the full glyph encoding from `beamterm-atlas`.
232    ///
233    /// This 13-bit mask includes the emoji flag (bit 12) so that emoji base IDs
234    /// can be extracted correctly for symbol lookup and texture coordinate calculation.
235    fn emoji_bit(&self) -> u32 {
236        12
237    }
238
239    fn delete(&self, gl: &glow::Context) {
240        self.texture.delete(gl);
241    }
242
243    fn update_pixel_ratio(&mut self, _gl: &glow::Context, pixel_ratio: f32) -> Result<f32, Error> {
244        // Static atlas doesn't need to do anything - cell scaling is handled by the grid
245        Ok(pixel_ratio)
246    }
247
248    fn cell_scale_for_dpr(&self, pixel_ratio: f32) -> f32 {
249        // snap to specific scale values to avoid arbitrary fractional scaling
250        if pixel_ratio <= 0.5 { 0.5 } else { pixel_ratio.round().max(1.0) }
251    }
252
253    fn texture_cell_size(&self) -> beamterm_data::CellSize {
254        // Static atlas texture size equals cell_size (fixed resolution)
255        self.cell_size()
256    }
257}
beamterm_core/gl/static_atlas.rs

beamterm_core/gl/
static_atlas.rs
