Struct wgpu_core::command::CommandEncoder

pub(crate) struct CommandEncoder {
    raw: Box<dyn DynCommandEncoder>,
    list: Vec<Box<dyn DynCommandBuffer>>,
    is_open: bool,
    hal_label: Option<String>,
}

A raw CommandEncoder, and the raw CommandBuffers built from it.

Each wgpu-core CommandBuffer owns an instance of this type, which is where the commands are actually stored.

This holds a Vec of raw CommandBuffers, not just one. We are not always able to record commands in the order in which they must ultimately be submitted to the queue, but raw command buffers don’t permit inserting new commands into the middle of a recorded stream. However, hal queue submission accepts a series of command buffers at once, so we can simply break the stream up into multiple buffers, and then reorder the buffers. See CommandEncoder::close_and_swap for a specific example of this.

Note that a CommandEncoderId actually refers to a CommandBuffer. Methods that take a command encoder id actually look up the command buffer, and then use its encoder.

Fields

raw: Box<dyn DynCommandEncoder>

The underlying wgpu_hal CommandEncoder.

Successfully executed command buffers’ encoders are saved in a CommandAllocator for recycling.

list: Vec<Box<dyn DynCommandBuffer>>

All the raw command buffers for our owning CommandBuffer, in submission order.

These command buffers were all constructed with raw. The wgpu_hal::CommandEncoder trait forbids these from outliving raw, and requires that we provide all of these when we call raw.reset_all(), so the encoder and its buffers travel together.

is_open: bool

True if raw is in the “recording” state.

See the documentation for wgpu_hal::CommandEncoder for details on the states raw can be in.

hal_label: Option<String>

Implementations

impl CommandEncoder

fn close_and_swap(&mut self, device: &Device) -> Result<(), DeviceError>

Finish the current command buffer, if any, and place it at the second-to-last position in our list.

If we have opened this command encoder, finish its current command buffer, and insert it just before the last element in self.list. If this command buffer is closed, do nothing.

On return, the underlying hal encoder is closed.

What is this for?

The wgpu_hal contract requires that each render or compute pass’s commands be preceded by calls to transition_buffers and transition_textures, to put the resources the pass operates on in the appropriate state. Unfortunately, we don’t know which transitions are needed until we’re done recording the pass itself. Rather than iterating over the pass twice, we note the necessary transitions as we record its commands, finish the raw command buffer for the actual pass, record a new raw command buffer for the transitions, and jam that buffer in just before the pass’s. This is the function that jams in the transitions’ command buffer.

fn close(&mut self, device: &Device) -> Result<(), DeviceError>

Finish the current command buffer, if any, and add it to the end of self.list.

If we have opened this command encoder, finish its current command buffer, and push it onto the end of self.list. If this command buffer is closed, do nothing.

On return, the underlying hal encoder is closed.

pub(crate) fn discard(&mut self)

Discard the command buffer under construction, if any.

The underlying hal encoder is closed, if it was recording.

pub(crate) fn open( &mut self, device: &Device, ) -> Result<&mut dyn DynCommandEncoder, DeviceError>

Begin recording a new command buffer, if we haven’t already.

The underlying hal encoder is put in the “recording” state.

fn open_pass( &mut self, hal_label: Option<&str>, device: &Device, ) -> Result<(), DeviceError>

Begin recording a new command buffer for a render pass, with its own label.

The underlying hal encoder is put in the “recording” state.