Struct wgpu::util::StagingBelt
source · pub struct StagingBelt { /* private fields */ }
Expand description
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:
- Write to buffers that need writing to using
StagingBelt::write_buffer()
. - Call
StagingBelt::finish()
. - Submit all command encoders that were used in step 1.
- Call
StagingBelt::recall()
.
Implementations§
source§impl StagingBelt
impl StagingBelt
sourcepub fn new(chunk_size: BufferAddress) -> Self
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.
sourcepub fn write_buffer(
&mut self,
encoder: &mut CommandEncoder,
target: &Buffer,
offset: BufferAddress,
size: BufferSize,
device: &Device
) -> BufferViewMut<'_>
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.
sourcepub fn finish(&mut self)
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.
sourcepub fn recall(&mut self)
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.