Struct SlabAllocator 

pub struct SlabAllocator<I>
where
    I: SlabItem,
{
    pub slabs: HashMap<SlabId<I>, Slab<I>>,
    pub key_to_slab: HashMap<I::Key, SlabId<I>>,
    pub extra_buffer_usages: BufferUsages,
    /* private fields */
}

A general-purpose allocator that manages a set of GPU buffer slabs.

You can use this allocator to pack data that needs to be accessible by the GPU into a small set of buffers, known as slabs. Each individual slab is expected to contain homogeneous data of a single type. However, you can use a single allocator to manage multiple slabs, each of which can have a different data layout. Objects managed by the allocator are referenced with a key that you can define.

To use this allocator, implement the SlabItem trait; see the documentation of that trait for details.

For performance, you’ll want to batch your allocation and deallocation operations to be performed at a single point in the frame. To perform allocation, call Self::stage_allocation to obtain an AllocationStage, call AllocationStage::allocate to allocate individual objects, and then commit the allocation transaction using AllocationStage::commit. Likewise, to perform deallocation, call Self::stage_deallocation to obtain a DeallocationStage, call DeallocationStage::free to free objects, and then call DeallocationStage::commit. Once you’ve committed an allocation stage, you can copy new data into the slabs via Self::copy_element_data.

Within each slab, or hardware buffer, the underlying allocation algorithm is offset_allocator, a Rust port of Sebastian Aaltonen’s hard-real-time C++ OffsetAllocator. Slabs start small and then grow as their contents fill up, up to a maximum size limit. To reduce fragmentation, objects that are too large bypass this system and receive their own buffers.

The SlabAllocatorSettings allows you to tune the behavior of the allocator for better performance with your use case.

See crate::mesh::allocator::MeshAllocator for an example of usage.

Fields

slabs: HashMap<SlabId<I>, Slab<I>>

Holds all buffers and allocators.

key_to_slab: HashMap<I::Key, SlabId<I>>

Maps slab allocation keys to the ID of the slabs that hold their data.

extra_buffer_usages: BufferUsages

Additional buffer usages to add to any vertex or index buffers created.

Implementations

impl<I> SlabAllocator<I>

where I: SlabItem,

pub fn new() -> Self

Creates a new empty slab allocator.

pub fn stage_allocation(&mut self) -> AllocationStage<'_, I>

Creates an AllocationStage, enabling batched allocation of objects in this slab.

Allocation of objects in the slab requires calling this function, calling AllocationStage::allocate on the resulting AllocationStage, and finally calling AllocationStage::commit. Grouping allocations into a batch, preferably at most one per frame, is the most efficient way to perform many allocations at once.

pub fn stage_deallocation(&mut self) -> DeallocationStage<'_, I>

Creates a DeallocationStage, enabling batched deallocation.

Deallocation of objects in the slab requires calling this function, calling DeallocationStage::free on the resulting DeallocationStage, and finally calling DeallocationStage::commit. Grouping deallocations into a batch, preferably at most one per frame, is the most efficient way to perform many deallocations at once.

pub fn buffer_for_slab(&self, slab_id: SlabId<I>) -> Option<&Buffer>

Returns the GPU buffer corresponding to the slab with the given ID if that slab has been uploaded to the GPU.

pub fn slab_allocation_slice( &self, key: &I::Key, slab_id: SlabId<I>, ) -> Option<SlabAllocationBufferSlice<'_, I>>

Given a slab and the key of data located with it, returns the buffer and range of that data within the slab.

pub fn slab_count(&self) -> usize

Get the number of allocated slabs

pub fn slabs_size(&self) -> u64

Get the total size of all allocated slabs

pub fn copy_element_data( &mut self, key: &I::Key, len: usize, fill_data: impl Fn(WriteOnly<'_, [u8]>), render_device: &RenderDevice, render_queue: &RenderQueue, )

Copies data into an allocated slab.

len specifies the size of the data to be copied in bytes. The given fill_data callback is expected to write the data into the given slice; this callback approach avoids a copy.

Trait Implementations

impl<I> Default for SlabAllocator<I>

where I: SlabItem,

fn default() -> Self

Returns the “default value” for a type.