Struct re_renderer::allocator::gpu_readback_belt::GpuReadbackBelt

pub struct GpuReadbackBelt {
    chunk_size: u64,
    active_chunks: Vec<Chunk>,
    free_chunks: Vec<Chunk>,
    received_chunks: Vec<Chunk>,
    sender: Sender<Chunk>,
    receiver: Receiver<Chunk>,
    frame_index: u64,
}

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

Internally it uses a ring-buffer of staging buffers that are sub-allocated.

Fields

chunk_size: u64

Minimum size for new buffers.

active_chunks: Vec<Chunk>

Chunks for which the GPU writes are scheduled, but we haven’t mapped them yet.

free_chunks: Vec<Chunk>

Chunks that have been unmapped and are ready for writing by the GPU.

received_chunks: Vec<Chunk>

Chunks that are currently mapped and ready for reading by the CPU.

sender: Sender<Chunk>

When a chunk mapping is successful, it is moved to this sender to be read by the CPU.

receiver: Receiver<Chunk>

Chunks are received here are ready to be read by the CPU.

frame_index: u64

Current frame index, used for keeping track of how old chunks are.

Implementations

impl GpuReadbackBelt

const MIN_ALIGNMENT: u64 = 8u64

All allocations of this allocator will be aligned to at least this size.

Buffer mappings however are currently NOT guaranteed to be aligned to this size! See this issue on Alignment guarantees for mapped buffers.

pub fn new(chunk_size: BufferSize) -> Self

Create a ring buffer for efficient & easy gpu memory readback.

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

• larger than the largest single GpuReadbackBelt::allocate operation;
• 1-4 times less than the total amount of data uploaded per submission
• bigger is better, within these bounds.

TODO(andreas): Adaptive chunk sizes TODO(andreas): Shrinking after usage spikes (e.g. screenshots of different sizes!)

pub fn allocate( &mut self, device: &Device, buffer_pool: &GpuBufferPool, size_in_bytes: BufferAddress, identifier: GpuReadbackIdentifier, user_data: Box<dyn Any + Send + 'static> ) -> GpuReadbackBuffer

Allocates a Gpu writable buffer & cpu readable buffer with a given size.

pub fn after_queue_submit(&mut self)

Prepare used buffers for CPU read.

This should be called after the command encoder(s) used in GpuReadbackBuffer copy operations are submitted.

pub fn begin_frame(&mut self, frame_index: u64)

Should be called at the beginning of a new frame.

Discards stale data that hasn’t been received by GpuReadbackBelt::readback_data for more than a frame.

pub fn readback_data<UserDataType: 'static>( &mut self, identifier: GpuReadbackIdentifier, callback: impl FnOnce(&[u8], Box<UserDataType>) )

Try to receive a pending data readback with the given identifier and the given user data type.

Returns the oldest received data with the given identifier & type. This is almost certainly also the oldest scheduled readback. But there is no strict guarantee for this. It could in theory happen that a readback is scheduled after a previous one, but finishes before it!

ATTENTION: Do NOT assume any alignment on the slice passed to on_data_received. See this issue on Alignment guarantees for mapped buffers.

fn receive_chunks(&mut self)

Check if any new chunks are ready to be read.

fn reuse_chunk(&mut self, chunk: Chunk)

Trait Implementations

impl Debug for GpuReadbackBelt

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

Formats the value using the given formatter.