Module ring_buffer 

GPU upload ring buffer for streaming vertex/index data.

RingBuffer maintains a single large VERTEX | COPY_DST GPU buffer and a write cursor that advances by align_up(size, alignment) on each allocation. When the cursor would overflow the buffer capacity the entire buffer is reset to offset 0 (a “ring” wrap).

Design

This avoids the per-frame create_buffer_init / create_buffer allocations that otherwise show up in GPU driver heap statistics. Instead, the caller obtains a RingAllocation describing a byte range within the buffer, and uploads data via queue.write_buffer. The GPU reads from the same buffer in the same frame — because wgpu submits command encoders sequentially, write_buffer is guaranteed to be visible before any draw commands issued after the write.

Safety / correctness contract

• Allocations are frame-scoped: all allocations from a frame must be consumed (drawn) within that frame’s command encoder before the next call to reset().
• reset() must be called once per frame before any allocations for that frame. It does NOT wait for GPU work to finish — the caller is responsible for ensuring the GPU has consumed the previous frame’s commands before overwriting the buffer (e.g. by submitting and waiting, or by using double-buffering at the RingBuffer level).

Headless / testing

The ring buffer wraps a real wgpu::Buffer, so tests that need it must acquire a real GPU device. CPU-only tests can use the RingBufferStats type directly without a device.

Structs

RingAllocation

A sub-range allocation within a RingBuffer.

RingBuffer

A streaming GPU vertex/index ring buffer.

RingBufferStats

Lifetime statistics for a RingBuffer.