Struct AtlasArray 

pub struct AtlasArray { /* private fields */ }

The atlas array texture, its view, and the layer count both were created at.

Created lazily by the first frame that makes an image resident, then grown only. The view is kept beside the texture because a bind group is built against it and has to be rebuilt whenever growth replaces the texture — generation is what tells a caller that happened.

Implementations

impl AtlasArray

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

An atlas array of width x height texels with at least two layers due to the floor raised by wgpu-hal 30.0.1’s GLES backend heuristic — one resident layer is still the logical minimum, but a second layer is allocated to work around a target-selection bug in get_info_from_desc (see atlas_texture_descriptor).

pub fn with_layers( device: &Device, width: u32, height: u32, layers: u32, ) -> Self

An atlas array of width x height texels over layers layers.

pub fn texture(&self) -> &Texture

The array texture the shader samples.

pub fn view(&self) -> &TextureView

The D2Array view a bind group binds.

pub fn size(&self) -> (u32, u32)

Extent of each layer, in texels.

pub fn layers(&self) -> u32

How many array layers currently exist.

pub fn layer_view(&self, layer: u32) -> Option<TextureView>

A render-attachment view over one array layer, or None when the array has no such layer.

Minted per use rather than cached alongside view: a layer target is wanted only on a frame that has glyph pixels to rasterize, while the sampling view is bound by every frame, and holding one view per layer for the array’s lifetime would keep a handle alive per layer for a path most frames never take.

pub fn generation(&self) -> u64

How many times growth has replaced the underlying texture.

A bind group built against view stays valid for as long as this value does not change.

pub fn ensure_layers( &mut self, device: &Device, queue: &Queue, layers: u32, ) -> bool

Grow the array to hold at least layers layers, preserving every existing layer’s texels.

Returns whether the texture was replaced — the signal a caller needs to rebuild its bind group. A request at or below the current depth, or one past MAX_ATLAS_INDEX, is a no-op: the encoded-image record cannot name a layer the shader could not address, so refusing here is what keeps an unaddressable layer from being created at all.

The old-to-new copy is recorded into a command encoder of this method’s own and submitted before returning, rather than into the frame’s. That is an ordering requirement rather than a convenience — see the module doc’s Why growth submits a command buffer of its own. Call it before the frame’s atlas writes are issued; anything already queued is flushed by this submit and so lands in the old texture.

pub fn write_region( &self, queue: &Queue, region: AtlasRegion, pixels: &[u8], ) -> bool

Write pixels into region.

pixels must be region’s own extent in premultiplied Rgba8Unorm, row-major and unpadded — exactly what crate::cache::images::ImageUpload carries. A slice that does not match, or a region outside the array, is refused rather than handed to the queue, which would validate it into a device error mid-frame.

pub fn clear_region(&self, queue: &Queue, region: AtlasRegion) -> bool

Clear region to transparent texels.

This is what makes an eviction observable as absence rather than as a stale image: the rectangle a reaped entry gave back is zeroed before a later allocation can hand part of it to something smaller, so a sample that strays into the unwritten remainder reads transparent black rather than the previous tenant’s pixels.

pub fn contains(&self, region: AtlasRegion) -> bool

Whether region lies wholly inside this array.

Trait Implementations

impl Debug for AtlasArray

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

Formats the value using the given formatter.