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 prepare_from_shaped(
&mut self,
renderer: &WgpuRenderer,
shaped: &ShapedLine,
layout_budget: TextLayoutBudget,
) -> Result<TextRun2d, PreparedTextError>
pub fn prepare_from_shaped( &mut self, renderer: &WgpuRenderer, shaped: &ShapedLine, layout_budget: TextLayoutBudget, ) -> Result<TextRun2d, PreparedTextError>
Prepares a validated CPU line without invoking the text shaper again.
The line must originate from this exact FontFace (clones share identity)
and TextStyle, including DPI and requested direction. Separately loaded
identical font bytes are intentionally not treated as the same identity.
Text/glyph limits are checked before placement allocation or cache mutation;
raster limits apply to uncached glyphs. Run capacity includes whitespace as
in Self::prepare. The source line is borrowed, never consumed or modified.
Failure may warm bounded atlas entries but preserves all existing runs.
Sourcepub fn update_from_shaped(
&mut self,
renderer: &WgpuRenderer,
run: &mut TextRun2d,
shaped: &ShapedLine,
layout_budget: TextLayoutBudget,
) -> Result<TextUpdateReport, PreparedTextError>
pub fn update_from_shaped( &mut self, renderer: &WgpuRenderer, run: &mut TextRun2d, shaped: &ShapedLine, layout_budget: TextLayoutBudget, ) -> Result<TextUpdateReport, PreparedTextError>
Atomically updates a retained run from already shaped CPU data.
Atlas/run/device identity and CPU font/style provenance are checked first,
even if UTF-8 is unchanged. A compatible unchanged line reports zero work
without consuming or rechecking layout_budget, matching Self::update.
For a changed line, input/output limits are checked without reshaping;
raster limits apply only to new cached glyphs. An error preserves old UTF-8,
metrics, instances and drawable GPU contents. A later error may leave newly
cached glyphs as documented by Self::prepare.
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.