Struct GradientCache 

pub struct GradientCache { /* private fields */ }

An LRU cache of baked gradient colour ramps packed into one upload buffer.

Implementations

impl GradientCache

pub fn new(capacity: u32, level: Level) -> Self

Create a cache retaining at most capacity ramps.

pub fn for_texture(layout: GradientTextureLayout, level: Level) -> Self

Create a cache sized for the texture the ramps will be uploaded into.

Capacity is the worst-case entry count for that texture — every ramp baked at MAX_GRADIENT_LUT_SIZE — so the packed buffer cannot outgrow the texture regardless of how complex the cached gradients turn out to be.

pub fn capacity(&self) -> u32

The maximum number of entries retained across a GradientCache::maintain.

pub fn entry_count(&self) -> usize

Number of ramps currently resident.

pub fn luts_size(&self) -> usize

Size of the packed LUT buffer in bytes.

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

The packed LUT bytes, ready to be uploaded as Rgba8Unorm texels.

pub fn is_empty(&self) -> bool

Whether no ramp bytes are packed.

pub fn has_changed(&self) -> bool

Whether the packed bytes have changed since the last upload.

pub fn mark_synced(&mut self)

Record that the packed bytes have been uploaded.

pub fn lookup(&self, gradient: &EncodedGradient) -> Option<CachedRamp>

Look a gradient up without baking it or disturbing LRU order.

pub fn get_or_create_ramp(&mut self, gradient: &EncodedGradient) -> CachedRamp

Return the cached ramp for gradient, baking and packing it on a miss.

Offsets returned within one frame stay valid for that frame: baking only appends, and the compaction that rewrites offsets happens in GradientCache::maintain at the frame boundary.

pub fn maintain(&mut self)

Evict least-recently-used ramps down to GradientCache::capacity.

Call once per frame, after the frame’s paints have been encoded — never mid-frame, since compaction invalidates previously returned offsets.

pub fn take_luts(&mut self) -> Vec<u8>

Take the packed bytes, leaving the cache’s buffer empty.

Paired with GradientCache::restore_luts so an upload can pad the buffer to the texture footprint and hand it back without copying the ramp bytes. The restored buffer must hold the same logical content.

pub fn restore_luts(&mut self, luts: Vec<u8>)

Give back a buffer taken by GradientCache::take_luts.

pub fn begin_upload( &mut self, layout: GradientTextureLayout, ) -> Option<LutUpload<'_>>

Borrow the packed bytes padded out to layout’s full byte footprint, ready to hand to a texel copy.

Returns None when no ramps are packed, and when layout is too small to hold them. The second case is a refusal, logged rather than silently served: padding to a footprint below the packed length would truncate the buffer instead of extending it, uploading a prefix of the ramps under offsets computed for all of them — every gradient past the cut would sample whatever the texture already held. Skipping the upload leaves the previous frame’s texels in place, which is stale but coherent, and leaves has_changed set so the next upload against a large enough layout still happens.

The padding is applied to the cache’s own buffer and undone when the returned LutUpload drops, so a served upload costs one resize rather than a copy of every ramp.

Trait Implementations

impl Debug for GradientCache

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

Formats the value using the given formatter.