Skip to main content

TextAtlas2d

Struct TextAtlas2d 

Source
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

Source

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.

Source

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

Source

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.

Source

pub const fn atlas(&self) -> &GlyphAtlas2d

Returns the atlas to use with a retained glyph-run draw. Use linear sampling.

Source

pub const fn style(&self) -> &TextStyle

Returns the immutable font/style/DPI configuration.

Source

pub const fn font(&self) -> &FontFace

Returns the original font, shared cheaply through FontFace::clone.

Source

pub const fn budget(&self) -> TextAtlasBudget

Returns immutable atlas and run limits.

Source

pub fn cached_glyph_count(&self) -> usize

Returns cached glyph count, including non-drawing spacing glyphs.

Source

pub fn recovery_memory_bytes(&self) -> usize

Returns retained atlas pixels and metadata bytes, excluding shared font data and allocator overhead.

Source

pub fn gpu_allocation_bytes(&self) -> usize

Returns retained GPU image allocation bytes; runs own separate instance buffers.

Source

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.

Source

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.

Source

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.

Source

pub fn restore_run( &self, renderer: &WgpuRenderer, run: &mut TextRun2d, ) -> Result<(), TextError>

Restores one live run against this atlas, preserving text and baseline metrics.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> Upcast<T> for T

Source§

fn upcast(&self) -> Option<&T>

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,