Struct SpriteCache 

pub struct SpriteCache { /* private fields */ }

Cache of decoded sprites, keyed by Unicode codepoint.

Reload / hot-swap is not supported

load is append-only: it decodes a tileset and merges its sprites into the existing map, with later registrations winning on codepoint collision (see load docs). There is no unload or clear, and nothing observes or invalidates sprites already handed out via get.

This is a deliberate scope decision, not an oversight: games generally don’t hot-swap tilesets at runtime, and a SpriteCache is only ever populated once, when a backend is built. If you need to iterate on a sprite sheet (e.g. during dev-mode asset editing) or otherwise want a tileset change to take effect, rebuild the whole renderer from a fresh backend configuration rather than mutating an existing cache in place.

Implementations

impl SpriteCache

pub const fn new() -> Self

Creates an empty sprite cache.

pub fn get(&self, ch: char) -> Option<&Sprite>

Returns the sprite for ch, if registered.

pub fn iter(&self) -> impl ExactSizeIterator<Item = (char, &Sprite)>

Iterates every registered (codepoint, sprite) in codepoint order.

Used by GPU backends to build a sprite atlas from the whole decoded set (the software backend only ever needs per-glyph get at blit time).

pub fn is_empty(&self) -> bool

Whether any sprite is registered.

pub fn from_tilesets(opts: &[TilesetOptions]) -> Result<Self, TilesetError>

Builds a cache by loading every tileset in opts, in order.

This is what both pixel backends call from their builder’s build/into_renderer instead of each looping over their own configured tilesets by hand; later tilesets win on codepoint collision, same as calling load directly in a loop.

Errors

Returns the first TilesetError any tileset’s load call fails with; no later tileset is loaded once one fails.

pub fn load(&mut self, opts: &TilesetOptions) -> Result<(), TilesetError>

Loads a tileset, decoding the sprite sheet and inserting all sprites.

On codepoint collision, the new sprite replaces the old one and a message is logged via log::warn. Unlike warn_sprite_needs_span and warn_tint_needs_sprite, this warning is not gated behind dev_only!: it fires at most once per tileset load rather than once per frame, so it needs no seen dedup table and has no redraw-loop cost, and it reports a tileset/codepage authoring mistake a consumer may want visible even in a shipped build. See the “Load-time versus per-frame” section of retroglyph_core::dev’s module docs.

Errors

Returns TilesetError::ImageDecode if the bytes are not a valid image, TilesetError::ZeroTileSize if opts.tile_width or opts.tile_height is 0, TilesetError::InvalidDimensions if the decoded image dimensions are not evenly divisible by the tile size, or TilesetError::TooManyColumns if opts.columns declares more columns than the image actually has at opts.tile_width.

Trait Implementations

impl Debug for SpriteCache

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

Formats the value using the given formatter.

impl Default for SpriteCache

fn default() -> Self

Returns the “default value” for a type.