Struct CommandBuffer

pub struct CommandBuffer {
    pub(crate) buffer: DispatchCommandBuffer,
    pub(crate) actions: Arc<Mutex<DeferredCommandBufferActions>>,
}

Handle to a command buffer on the GPU.

A CommandBuffer represents a complete sequence of commands that may be submitted to a command queue with Queue::submit. A CommandBuffer is obtained by recording a series of commands to a CommandEncoder and then calling CommandEncoder::finish.

Corresponds to WebGPU GPUCommandBuffer.

Fields

buffer: DispatchCommandBuffer

actions: Arc<Mutex<DeferredCommandBufferActions>>

Deferred actions recorded at encode time, to run at Queue::submit.

Implementations

impl CommandBuffer

pub fn as_custom<T: CommandBufferInterface>(&self) -> Option<&T>

Available on custom only.

Returns custom implementation of CommandBuffer (if custom backend and is internally T)

pub fn map_buffer_on_submit<S: RangeBounds<BufferAddress>>( &self, buffer: &Buffer, mode: MapMode, bounds: S, callback: impl FnOnce(Result<(), BufferAsyncError>) + WasmNotSend + 'static, )

On submission, maps the buffer to host (CPU) memory, making it available for reading or writing via get_mapped_range(). The buffer becomes accessible once the callback is invoked with Ok.

Use this when you need to submit work that uses the buffer before mapping it. Because that submission must happen before calling map_async, this method schedules the mapping for after submission, avoiding extra calls to Buffer::map_async() or BufferSlice::map_async() and letting you start the mapping from a more convenient place.

For the callback to run, either queue.submit(..), instance.poll_all(..), or device.poll(..) must be called elsewhere in the runtime, possibly integrated into an event loop or run on a separate thread.

The callback runs on the thread that first calls one of the above functions after the GPU work completes. There are no restrictions on the code you can run in the callback; however, on native the polling call will not return until the callback finishes, so keep callbacks short (set flags, send messages, etc.).

While a buffer is mapped, it cannot be used by other commands; at any time, either the GPU or the CPU has exclusive access to the buffer’s contents.

Panics

• If bounds is outside the bounds of buffer.
• If bounds has a length less than 1.

Panics During Submit

• If the buffer is already mapped.
• If the buffer’s BufferUsages do not allow the requested MapMode.
• If the endpoints of this slice are not aligned to MAP_ALIGNMENT within the buffer.

pub fn on_submitted_work_done(&self, callback: impl FnOnce() + Send + 'static)

Registers a callback that is invoked when this command buffer’s work finishes executing on the GPU. When this callback runs, all mapped-buffer callbacks registered for the same submission are guaranteed to have been called.

For the callback to run, either queue.submit(..), instance.poll_all(..), or device.poll(..) must be called elsewhere in the runtime, possibly integrated into an event loop or run on a separate thread.

The callback runs on the thread that first calls one of the above functions after the GPU work completes. There are no restrictions on the code you can run in the callback; however, on native the polling call will not return until the callback finishes, so keep callbacks short (set flags, send messages, etc.).

Trait Implementations

impl Debug for CommandBuffer

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

Formats the value using the given formatter.