Struct ArrayPool 

pub struct ArrayPool {
    array: Array,
    label: Option<String>,
    allocator: Allocator,
    data: Vec<u8>,
    dirty: bool,
    replaced: bool,
}

One array sub-allocated into element ranges, with a CPU mirror of its bytes.

See the module documentation for what a pool is for and how growing works.

Fields

array: Array

The array every range lives in.

label: Option<String>

The label the array is created with, reused when it is replaced.

allocator: Allocator

Where the free elements are.

data: Vec<u8>

The array’s bytes, element for element, kept so a slice can be written without re-reading the GPU resource.

dirty: bool

Whether the mirror holds bytes the array has not received yet.

replaced: bool

Whether the array was replaced since the last Self::upload.

A replacement is what a caller has to act on: every bind group built from the old handle is stale. Reporting it from the upload keeps the check and the copy in one place, so a caller cannot upload without learning that the array moved.

Implementations

impl ArrayPool

pub fn new( device: &Device, label: &str, element_size: u64, initial_elements: u32, max_dimension: Option<u32>, ) -> Self

Create a pool whose array holds initial_elements elements of element_size bytes each.

max_dimension is Some of the device’s [wgpu::Limits::max_texture_dimension_2d] to hold the elements in a texture, or None to hold them in a storage buffer.

Panics

Under the conditions Array::new panics.

pub fn handle(&self) -> ArrayHandle

The bindable handle to the pool’s array.

Cloned rather than borrowed so a caller can move it into the resource graph, which is what makes a replaced array mark the bind groups built from it dirty.

pub fn array(&self) -> &Array

The array itself, for a caller that needs more than the handle.

pub fn capacity(&self) -> u64

How many elements the array can hold.

pub fn allocate(&mut self, device: &Device, count: u32) -> Option<ArrayRange>

Reserves count elements, growing the array if they do not fit.

Returns None only if the pool cannot grow any further (its size would overflow a u32, or it has run out of node slots for its ranges).

Growing replaces the array, so a caller that holds a handle has to read it again — and has to upload before the GPU sees the data the mirror holds.

Panics

If count is zero, since a range covers at least one element.

pub fn release(&mut self, allocation: Allocation)

Hands a range’s elements back to the pool.

Panics

Panics if the allocation was already released.

pub fn write(&mut self, range: ArrayRange, bytes: &[u8])

Write bytes — one element per element_size — into range.

This only fills the CPU mirror; the GPU sees the data once upload runs.

Panics

If bytes is not exactly range’s elements, or if the range does not belong to this pool.

pub fn upload(&mut self, device: &Device, encoder: &mut CommandEncoder) -> bool

Copy the CPU mirror to the array, recording the copy into encoder.

Returns whether the array had to be replaced since the caller last read its handle, which is what says every bind group built from the old one is stale. An upload of an unchanged pool does nothing.

fn reserve(&mut self, device: &Device, end: u32)

Grow the array until it covers end elements.

The mirror is resized with it, so the data already written stays put.

fn grow(&mut self, device: &Device, count: u32) -> Option<()>

Grow the allocator until count elements fit.

Returns None if it cannot grow, leaving the pool unchanged.

Trait Implementations

impl Debug for ArrayPool

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

Formats the value using the given formatter.