Enum CommandEncoderStatus

pub(crate) enum CommandEncoderStatus {
    Recording(CommandBufferMutable),
    Locked(CommandBufferMutable),
    Consumed,
    Finished(CommandBufferMutable),
    Error(CommandEncoderError),
    Transitioning,
}

The current state of a command or pass encoder.

In the WebGPU spec, the state of an encoder (open, locked, or ended) is orthogonal to the validity of the encoder. However, this enum does not represent the state of an invalid encoder.

Variants

Recording(CommandBufferMutable)

Ready to record commands. An encoder’s initial state.

Command building methods like command_encoder_clear_buffer and compute_pass_end require the encoder to be in this state.

This corresponds to WebGPU’s “open” state. See https://www.w3.org/TR/webgpu/#encoder-state-open

Locked(CommandBufferMutable)

Locked by a render or compute pass.

This state is entered when a render/compute pass is created, and exited when the pass is ended.

As long as the command encoder is locked, any command building operation on it will fail and put the encoder into the Self::Error state. See https://www.w3.org/TR/webgpu/#encoder-state-locked

Consumed

Finished(CommandBufferMutable)

Command recording is complete, and the buffer is ready for submission.

Global::command_encoder_finish transitions a CommandBuffer from the Recording state into this state.

Global::queue_submit requires that command buffers are in this state.

This corresponds to WebGPU’s “ended” state. See https://www.w3.org/TR/webgpu/#encoder-state-ended

Error(CommandEncoderError)

The command encoder is invalid.

The error that caused the invalidation is stored here, and will be raised by CommandEncoder.finish().

Transitioning

Temporary state used internally by methods on CommandEncoderStatus. Encoder should never be left in this state.

Implementations

impl CommandEncoderStatus

fn record_with<F: FnOnce(&mut CommandBufferMutable) -> Result<(), E>, E: Clone + Into<CommandEncoderError>>( &mut self, f: F, ) -> Result<(), EncoderStateError>

Record commands using the supplied closure.

If the encoder is in the Self::Recording state, calls the closure to record commands. If the closure returns an error, stores that error in the encoder for later reporting when finish() is called. Returns Ok(()) even if the closure returned an error.

If the encoder is not in the Self::Recording state, the closure will not be called and nothing will be recorded. The encoder will be invalidated (if it is not already). If the error is a validation error that should be raised immediately, returns it in Err, otherwise, returns Ok(()).

pub(crate) fn record_as_hal_mut<T, F: FnOnce(Option<&mut CommandBufferMutable>) -> T>( &mut self, f: F, ) -> T

Special version of record used by command_encoder_as_hal_mut. This differs from the regular version in two ways:

1. The recording closure is infallible.
2. The recording closure takes Option<&mut CommandBufferMutable>, and in the case that the encoder is not in a valid state for recording, the closure is still called, with None as its argument.

fn lock_encoder(&mut self) -> Result<(), EncoderStateError>

Locks the encoder by putting it in the Self::Locked state.

Render or compute passes call this on start. At the end of the pass, they call Self::unlock_and_record to put the CommandBuffer back into the Self::Recording state.

fn unlock_and_record<F: FnOnce(&mut CommandBufferMutable) -> Result<(), E>, E: Clone + Into<CommandEncoderError>>( &mut self, f: F, ) -> Result<(), EncoderStateError>

Unlocks the CommandBuffer and puts it back into the Self::Recording state, then records commands using the supplied closure.

This function is the unlocking counterpart to Self::lock_encoder. It is only valid to call this function if the encoder is in the Self::Locked state.

If the closure returns an error, stores that error in the encoder for later reporting when finish() is called. Returns Ok(()) even if the closure returned an error.

If the encoder is not in the Self::Locked state, the closure will not be called and nothing will be recorded. If a validation error should be raised immediately, returns it in Err, otherwise, returns Ok(()).

fn finish(&mut self) -> Self

fn invalidate<E: Clone + Into<CommandEncoderError>>(&mut self, err: E) -> E