Struct TextureAtlas 

pub struct TextureAtlas {
    pub width: u32,
    pub height: u32,
    /* private fields */
}

Dynamic shelf-based texture atlas with LRU eviction.

Allocation strategy

1. Check the free-list for a first-fit region large enough.
2. Walk existing shelves for one that can accommodate the request.
3. Open a new shelf at the current bottom of the atlas.
4. If all of the above fail, evict the LRU handle and retry once.

Eviction

Evicted regions are pushed onto the free-list; they are re-used on the next allocation attempt. The atlas never compacts its shelf layout.

Fields

width: u32

Atlas width in pixels.

height: u32

Atlas height in pixels.

Implementations

impl TextureAtlas

pub fn new(width: u32, height: u32) -> Self

Construct a new empty atlas of the given dimensions.

pub fn insert(&mut self, w: u32, h: u32) -> Option<AtlasHandle>

Insert a rectangle of size w × h into the atlas.

Returns an AtlasHandle on success, or None if the rectangle is larger than the atlas or all eviction attempts were exhausted.

pub fn get(&self, h: AtlasHandle) -> Option<AtlasRect>

Retrieve the pixel rectangle for the given handle, if still live.

pub fn utilization(&self) -> f32

Fraction of the atlas area occupied by live allocations.

Returns a value in [0.0, 1.0].

pub fn allocation_count(&self) -> usize

Return the number of live (non-evicted) allocations.

pub fn is_fragmented(&self, threshold: f32) -> bool

Return true if atlas utilization has fallen below threshold (0.0–1.0). This indicates significant fragmentation and the caller should consider triggering a defrag/rebuild.

This check is cheap (a single float comparison).

pub fn defrag(&mut self) -> Vec<(AtlasHandle, AtlasRect)>

Rebuild the atlas layout from scratch using only the currently live allocations.

After a defrag, all previously live handles continue to resolve to valid (but potentially repositioned) rectangles. Handles that had already been evicted remain invalid. The GPU texture content is not updated by this call — the caller must re-upload all live texture regions.

Returns a Vec<(AtlasHandle, AtlasRect)> mapping each live handle to its new position, in insertion order. The caller uses this to schedule GPU texture copies.

Complexity

O(n log n) in the number of live allocations.

pub fn defrag_if_fragmented( &mut self, threshold: f32, ) -> Option<Vec<(AtlasHandle, AtlasRect)>>

Check whether utilization is below the given threshold and, if so, perform an in-place defrag.

Returns Some(relocations) if a defrag was performed, None if utilization was already above the threshold.

Example

let mut atlas = TextureAtlas::new(64, 64);
// … insert/evict until fragmented …
if let Some(moves) = atlas.defrag_if_fragmented(0.5) {
    // re-upload the relocated regions
    for (_handle, _new_rect) in moves {}
}

pub fn resize(&mut self, new_width: u32, new_height: u32)

Discard all allocations and reinitialise with new dimensions.

Any existing handles become invalid. Uploading updated GPU texture data is the caller’s responsibility.