Struct wgpu::util::StagingBelt

pub struct StagingBelt { /* private fields */ }

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

Internally it uses a ring-buffer of staging buffers that are sub-allocated. It has an advantage over Queue::write_buffer() in a way that it returns a mutable slice, which you can fill to avoid an extra data copy.

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

1. Write to buffers that need writing to using StagingBelt::write_buffer().
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(chunk_size: BufferAddress) -> Self

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: BufferAddress,
    size: BufferSize,
    device: &Device
) -> BufferViewMut<'_>

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

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 finish(&mut self)

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)

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

Formats the value using the given formatter.