Struct StagingBelt 

pub struct StagingBelt { /* private fields */ }

Available on crate feature unstable-wgpu-28 only.

Efficiently performs many buffer writes by sharing and reusing temporary buffers.

Internally it uses a ring-buffer of staging buffers that are sub-allocated. Its advantage over Queue::write_buffer_with() is that the individual allocations are cheaper; StagingBelt is most useful when you are writing very many small pieces of data. It can be understood as a sort of arena allocator.

Using a staging belt is slightly complicated, and generally goes as follows:

1. Use StagingBelt::write_buffer() or StagingBelt::allocate() to allocate buffer slices, then write your data to them.
2. Call StagingBelt::finish().
3. Submit all command encoders that were used in step 1.
4. Call StagingBelt::recall().

Implementations

impl StagingBelt

pub fn new(device: Device, chunk_size: u64) -> StagingBelt

Available on crate feature wgpu-28 only.

Create a new staging belt.

The chunk_size is the unit of internal buffer allocation; writes will be sub-allocated within each chunk. Therefore, for optimal use of memory, the chunk size should be:

• larger than the largest single StagingBelt::write_buffer() operation;
• 1-4 times less than the total amount of data uploaded per submission (per StagingBelt::finish()); and
• bigger is better, within these bounds.

pub fn write_buffer( &mut self, encoder: &mut CommandEncoder, target: &Buffer, offset: u64, size: NonZero<u64>, ) -> BufferViewMut

Available on crate feature wgpu-28 only.

Allocate a staging belt slice of size to be copied into the target buffer at the specified offset.

offset and size must be multiples of COPY_BUFFER_ALIGNMENT (as is required by the underlying buffer operations).

The upload will be placed into the provided command encoder. This encoder must be submitted after StagingBelt::finish() is called and before StagingBelt::recall() is called.

If the size is greater than the size of any free internal buffer, a new buffer will be allocated for it. Therefore, the chunk_size passed to StagingBelt::new() should ideally be larger than every such size.

pub fn allocate( &mut self, size: NonZero<u64>, alignment: NonZero<u64>, ) -> BufferSlice<'_>

Available on crate feature wgpu-28 only.

Allocate a staging belt slice with the given size and alignment and return it.

size must be a multiple of COPY_BUFFER_ALIGNMENT (as is required by the underlying buffer operations).

To use this slice, call BufferSlice::get_mapped_range_mut() and write your data into that BufferViewMut. (The view must be dropped before StagingBelt::finish() is called.)

You can then record your own GPU commands to perform with the slice, such as copying it to a texture or executing a compute shader that reads it (whereas StagingBelt::write_buffer() can only write to other buffers). All commands involving this slice must be submitted after StagingBelt::finish() is called and before StagingBelt::recall() is called.

If the size is greater than the space available in any free internal buffer, a new buffer will be allocated for it. Therefore, the chunk_size passed to StagingBelt::new() should ideally be larger than every such size.

The chosen slice will be positioned within the buffer at a multiple of alignment, which may be used to meet alignment requirements for the operation you wish to perform with the slice. This does not necessarily affect the alignment of the BufferViewMut.

pub fn finish(&mut self)

Available on crate feature wgpu-28 only.

Prepare currently mapped buffers for use in a submission.

This must be called before the command encoder(s) provided to StagingBelt::write_buffer() are submitted.

At this point, all the partially used staging buffers are closed (cannot be used for further writes) until after StagingBelt::recall() is called and the GPU is done copying the data from them.

pub fn recall(&mut self)

Available on crate feature wgpu-28 only.

Recall all of the closed buffers back to be reused.

This must only be called after the command encoder(s) provided to StagingBelt::write_buffer() are submitted. Additional calls are harmless. Not calling this as soon as possible may result in increased buffer memory usage.

Trait Implementations

impl Debug for StagingBelt

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

Formats the value using the given formatter.