Struct ReadbackRing 

pub struct ReadbackRing { /* private fields */ }

Async readback ring buffer with GPU-resident staging buffers.

Implementations

impl ReadbackRing

pub fn new( device: &Device, size: usize, buffer_size: u64, ) -> Result<Self, BackendError>

Construct a ring with N staging buffers.

pub fn record_copy( &self, device: &Device, encoder: &mut CommandEncoder, src_buffer: &Buffer, src_offset: u64, byte_len: u64, ) -> Result<ReadbackTicket, BackendError>

Record a readback copy into the next available ring slot.

The caller must submit the encoder and then arm the returned ticket with Self::arm_ticket. This path lets the main dispatch encoder copy into preallocated ring slots instead of allocating a fresh staging buffer per output.

Errors

Returns BackendError if the byte range cannot be represented, the ring slot is not reusable (an uncollected SLOT_READY/SLOT_ERROR slot or a still-pending slot after a device poll), or the requested readback exceeds slot capacity.

pub fn arm_ticket( &self, ticket: &ReadbackTicket, ) -> Result<(Receiver<MapResult>, Arc<AtomicBool>), BackendError>

Arm a submitted ticket by registering its map_async callback.

Errors

Returns BackendError when ticket does not reference a live slot.

pub fn with_mapped_ticket<R>( &self, ticket: &ReadbackTicket, visitor: impl FnOnce(&[u8]) -> Result<R, BackendError>, ) -> Result<R, BackendError>

Expose a ready ticket’s mapped bytes to visitor, then free the slot.

Errors

Returns BackendError when the ticket is stale, the slot is not ready, or mapped length metadata is inconsistent.

pub fn submit_readback( &self, device: &Device, queue: &Queue, src_buffer: &Buffer, src_offset: u64, byte_len: u64, ) -> Result<usize, BackendError>

Submit a copy from src_buffer at src_offset and mark the slot pending.

src_offset is the byte offset within src_buffer to copy from. Pass 0 to read from the start of the buffer. This mirrors the src_offset parameter accepted by record_copy; callers that need a sub-range of the source buffer must supply a non-zero offset here rather than wrapping a slice (the wgpu copy API requires aligned buffer offsets).

Errors

Returns BackendError if encoder or queue submission fails.

pub fn collect_slot( &self, device: &Device, idx: usize, ) -> Result<Option<Vec<u8>>, BackendError>

Try to collect data from a specific slot.

Errors

Returns BackendError when idx is out of bounds or map_async failed for the slot.

pub fn collect_slot_into( &self, device: &Device, idx: usize, out: &mut Vec<u8>, ) -> Result<Option<usize>, BackendError>

Try to collect data from a specific slot into a caller-owned buffer.

Reusing out avoids an allocation on every ready readback. The buffer is cleared before bytes are appended.

Errors

Returns BackendError when idx is out of bounds or map_async failed for the slot.