pub struct TextAtlas2d { /* private fields */ }Expand description
Antialiased font cache for one font, logical EM size, direction and DPI.
Enable the optional text feature. Glyphs never move or disappear: the fixed
atlas returns TextError::AtlasFull instead of evicting live runs. Create a
new atlas and prepare replacement runs before swapping when size or DPI changes.
The input font must be a trusted application asset, not an untrusted-font sandbox.
Draw Self::atlas and TextRun2d::glyph_run with ImageSampling::Linear.
Placements are baseline-relative, in logical pixels. Bitmap coverage is cached
at an integer physical baseline; fractional placement uses bilinear filtering,
not per-subpixel hinting. No fonts are discovered or downloaded automatically.
use sim_engine::{
Color, FontFace, FrameBudget, FramePassOptions, ImageBatchPlacement, ImageSampling,
LogicalPixels, LogicalScreenVector, PhysicalPerLogical, TextAtlas2d,
TextAtlasBudget, TextLayoutBudget, TextStyle, WgpuRenderer,
};
fn draw_label(renderer: &mut WgpuRenderer, font: FontFace)
-> Result<(), Box<dyn std::error::Error>>
{
let style = TextStyle::new(
LogicalPixels::new(24.0)?,
PhysicalPerLogical::new(renderer.scale_factor() as f32)?,
)?;
// Keep these two resources between frames in an application.
let mut atlas = TextAtlas2d::new(renderer, font, style, TextAtlasBudget::default())?;
let label = atlas.prepare(renderer, "Hello, world!", TextLayoutBudget::default())?;
let mut frame = renderer.begin_frame(Color::BLACK, FrameBudget::default())?;
frame.draw_glyph_run_placed(
atlas.atlas(), label.glyph_run(),
ImageBatchPlacement::new(LogicalScreenVector::new(24.0, 80.0), Color::WHITE)?,
ImageSampling::Linear, FramePassOptions::new(0),
)?;
let _report = frame.present()?;
Ok(())
}Implementations§
Source§impl TextAtlas2d
impl TextAtlas2d
Sourcepub fn new(
renderer: &WgpuRenderer,
font: FontFace,
style: TextStyle,
budget: TextAtlasBudget,
) -> Result<Self, TextError>
pub fn new( renderer: &WgpuRenderer, font: FontFace, style: TextStyle, budget: TextAtlasBudget, ) -> Result<Self, TextError>
Creates a fixed-capacity atlas, checking device dimensions before pixel allocation.
Sourcepub const fn atlas(&self) -> &GlyphAtlas2d
pub const fn atlas(&self) -> &GlyphAtlas2d
Returns the atlas to use with a retained glyph-run draw. Use linear sampling.
Sourcepub const fn font(&self) -> &FontFace
pub const fn font(&self) -> &FontFace
Returns the original font, shared cheaply through FontFace::clone.
Sourcepub const fn budget(&self) -> TextAtlasBudget
pub const fn budget(&self) -> TextAtlasBudget
Returns immutable atlas and run limits.
Sourcepub fn cached_glyph_count(&self) -> usize
pub fn cached_glyph_count(&self) -> usize
Returns cached glyph count, including non-drawing spacing glyphs.
Sourcepub fn recovery_memory_bytes(&self) -> usize
pub fn recovery_memory_bytes(&self) -> usize
Returns retained atlas pixels and metadata bytes, excluding shared font data and allocator overhead.
Sourcepub fn gpu_allocation_bytes(&self) -> usize
pub fn gpu_allocation_bytes(&self) -> usize
Returns retained GPU image allocation bytes; runs own separate instance buffers.
Sourcepub fn prepare(
&mut self,
renderer: &WgpuRenderer,
text: &str,
layout_budget: TextLayoutBudget,
) -> Result<TextRun2d, TextError>
pub fn prepare( &mut self, renderer: &WgpuRenderer, text: &str, layout_budget: TextLayoutBudget, ) -> Result<TextRun2d, TextError>
Shapes a line and rasterizes only glyphs missing from this immutable-style cache.
Font/input/output limits apply to shaping; raster limits apply to cache misses. Run capacity is conservatively preflighted for all shaped glyphs, including whitespace, before allocating placements or populating the glyph cache. A failure preserves all existing drawable runs, but may warm the bounded cache with some new glyphs before a later glyph or run allocation fails. There is no implicit atlas growth, eviction, font fallback or wrapping.
Sourcepub fn update(
&mut self,
renderer: &WgpuRenderer,
run: &mut TextRun2d,
text: &str,
layout_budget: TextLayoutBudget,
) -> Result<TextUpdateReport, TextError>
pub fn update( &mut self, renderer: &WgpuRenderer, run: &mut TextRun2d, text: &str, layout_budget: TextLayoutBudget, ) -> Result<TextUpdateReport, TextError>
Replaces a line atomically while reusing its instance-buffer capacity.
Exact unchanged UTF-8 returns immediately after resource-identity validation;
no shaping/raster work occurs, so layout_budget is not consumed or rechecked.
For changed text, a synchronous error preserves the old run/text/metrics,
but may warm atlas entries as documented by Self::prepare.
Sourcepub fn restore(&mut self, renderer: &WgpuRenderer) -> Result<(), TextError>
pub fn restore(&mut self, renderer: &WgpuRenderer) -> Result<(), TextError>
Restores exact atlas pixels on a replacement renderer without rerasterizing.
This replaces the atlas only after successful allocation. Restore each live
run using Self::restore_run before drawing on the replacement renderer.
Sourcepub fn restore_run(
&self,
renderer: &WgpuRenderer,
run: &mut TextRun2d,
) -> Result<(), TextError>
pub fn restore_run( &self, renderer: &WgpuRenderer, run: &mut TextRun2d, ) -> Result<(), TextError>
Restores one live run against this atlas, preserving text and baseline metrics.