Struct Atlas 

pub struct Atlas { /* private fields */ }

A square atlas of glyph coverage, and where each glyph landed.

Holds the texels itself rather than a device texture, so that packing can be exercised and reasoned about without a GPU. Whoever owns the device uploads Atlas::texels when Atlas::is_dirty says something changed.

Implementations

impl Atlas

pub fn new(size: u32) -> Atlas

An empty atlas of size by size texels.

pub fn with_limit(size: u32, limit: u32) -> Atlas

An atlas that may grow up to limit texels on a side.

A limit below the starting size means it never grows, which is a reasonable thing to ask for and not an error.

pub fn size(&self) -> u32

pub fn texels(&self) -> &[u8]

One byte of coverage per texel, row-major from the top.

pub fn is_dirty(&self) -> bool

Whether anything has been added since Atlas::mark_clean.

The upload is the caller’s to make, because only they know which device the texture lives on and when in the frame it is safe to write.

pub fn mark_clean(&mut self)

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn get(&self, key: GlyphKey) -> Option<AtlasRect>

Where a glyph sits, if it is present.

pub fn begin_frame(&mut self)

Begin a new frame, after which glyphs not inserted again are evictable.

Nothing happens here but a counter moving. A caller that never calls it keeps every glyph forever, which is correct rather than a leak: without frame boundaries nothing is stale, and an atlas that filled would be genuinely out of room.

pub fn compactions(&self) -> u64

How many times room has been made by repacking.

Worth reporting because it is the number that says the atlas is too small for the text going through it: a compaction or two as a working set settles is ordinary, and one per frame means every frame is repacking everything.

pub fn growths(&self) -> u64

How many times the atlas has doubled.

Every growth reallocates and repacks everything, so a count that keeps climbing says the atlas started far too small. It settles once the working set fits.

pub fn limit(&self) -> u32

The largest this may grow to.

pub fn insert( &mut self, key: GlyphKey, coverage: &Coverage, ) -> Result<AtlasRect, AtlasError>

Add a glyph, or return where it already is.

Idempotent, so a caller can insert every glyph of every run each frame and pay only for the ones that are new. That is the usage this is for: deciding what is already present is exactly what an atlas is.

Trait Implementations

impl Debug for Atlas

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.