Struct StagingBuffer 

pub struct StagingBuffer {
    slots: Vec<Slot>,
}

A pool of staging buffers for one destination buffer, reused across frames.

One of these belongs to each buffer a caller uploads to every frame; see the module docs for the recycling scheme.

Fields

slots: Vec<Slot>

Implementations

impl StagingBuffer

pub fn new() -> Self

A pool holding no staging buffer yet.

pub fn write( &mut self, device: &Device, encoder: &mut CommandEncoder, target: &Buffer, offset: u64, data: &[u8], )

Upload data into target at offset, recording the copy into encoder.

The bytes reach a reused staging buffer by host write and the GPU on the copy, so target needs [wgpu::BufferUsages::COPY_DST] and must not be mapped. offset and the length of data must both be multiples of [wgpu::COPY_BUFFER_ALIGNMENT], as [wgpu::Queue::write_buffer] requires. An empty data records no copy.

Panics

If offset or data.len() is not a multiple of [wgpu::COPY_BUFFER_ALIGNMENT].

pub fn write_texture( &mut self, device: &Device, encoder: &mut CommandEncoder, texture: &Texture, layout: TexelCopyBufferLayout, size: Extent3d, data: &[u8], )

Upload data into texture, recording the copy into encoder.

The image is layout-described and spans size, exactly as [wgpu::Queue::write_texture] takes them, but reaches the texture through a reused staging buffer rather than a fresh one per call. The texture needs [wgpu::TextureUsages::COPY_DST].

layout.bytes_per_row must be a multiple of [wgpu::COPY_BYTES_PER_ROW_ALIGNMENT]: a buffer-to-texture copy requires it, unlike [wgpu::Queue::write_texture], which re-aligns the rows itself. Only layout.offset into the staging buffer is always zero — the data starts there — so a non-zero layout.offset is rejected rather than silently reading from the wrong place. An empty image records no copy.

Panics

If layout.offset is non-zero, if layout.bytes_per_row is set and not a multiple of [wgpu::COPY_BYTES_PER_ROW_ALIGNMENT], or if data is not a multiple of [wgpu::COPY_BUFFER_ALIGNMENT] long.

fn writable_slot(&mut self, device: &Device, size: u64) -> &mut Slot

A buffer of at least size bytes the host may write into.

The smallest writable buffer that fits is preferred, so a buffer grown for one heavy frame does not become the only candidate. A writable buffer too small for the frame is rebuilt in place: the frame outgrew it, and a buffer sized for the largest frame so far is the one later frames will reuse — accumulating one buffer per size ever seen is what makes reuse grow without bound. When every buffer is in flight another is added, so the pool settles at as many buffers as there are frames in flight rather than growing per frame.

pub fn release_idle(&mut self)

Release every staging buffer the host is free to write, keeping only the ones still in flight.

A buffer is kept automatically because it may be the one a later frame reuses, so a pool settles at the frames in flight rather than growing. That also means a frame that needed far more data than the ones after it leaves its buffer behind. Call this once uploads are known to have shrunk — a scene change, a resize — to give the memory back; the pool rebuilds from the frames in flight.

pub fn len(&self) -> usize

How many staging buffers the pool holds.

Mostly useful to a caller deciding whether to release idle buffers.

pub fn is_empty(&self) -> bool

Whether the pool holds no staging buffer at all.

Trait Implementations

impl Default for StagingBuffer

fn default() -> Self

Returns the “default value” for a type.