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 push_with<F: FnOnce() -> Result<ArcCommand, E>, E: Clone + Into<CommandEncoderError>>( &mut self, f: F, ) -> Result<(), EncoderStateError>

Push a command provided by a closure onto the encoder.

If the encoder is in the Self::Recording state, calls the closure to obtain a command, and pushes it onto the encoder. 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(()).

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

Call a closure with the inner command buffer structure.

If the encoder is in the Self::Recording state, calls the provided closure. 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. 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_encoder to put the CommandBuffer back into the Self::Recording state.

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

Unlocks the encoder and puts it back into the Self::Recording state.

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 encoder is in a state other than Self::Locked and a validation error should be raised immediately, returns it in Err, otherwise, stores the error in the encoder and returns Ok(()).

fn finish(&mut self) -> Self

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