Skip to main content

wgpu_core/command/
mod.rs

1//! # Command Encoding
2//!
3//! TODO: High-level description of command encoding.
4//!
5//! The convention in this module is that functions accepting a [`&mut dyn
6//! hal::DynCommandEncoder`] are low-level helpers and may assume the encoder is
7//! in the open state, ready to encode commands. Encoders that are not open
8//! should be nested within some other container that provides additional
9//! state tracking, like [`InnerCommandEncoder`].
10
11mod allocator;
12mod bind;
13mod bundle;
14mod clear;
15mod compute;
16mod compute_command;
17mod draw;
18mod encoder;
19mod encoder_command;
20pub mod ffi;
21mod memory_init;
22mod pass;
23mod query;
24mod ray_tracing;
25mod render;
26mod render_command;
27mod timestamp_writes;
28mod transfer;
29mod transition_resources;
30
31use alloc::{borrow::ToOwned as _, boxed::Box, string::String, sync::Arc, vec::Vec};
32use core::convert::Infallible;
33use core::mem::{self, ManuallyDrop};
34use core::{ops, panic};
35
36#[cfg(feature = "serde")]
37pub(crate) use self::encoder_command::serde_object_reference_struct;
38#[cfg(any(feature = "trace", feature = "replay"))]
39#[doc(hidden)]
40pub use self::encoder_command::PointerReferences;
41// This module previously did `pub use *` for some of the submodules. When that
42// was removed, every type that was previously public via `use *` was listed
43// here. Some types (in particular `CopySide`) may be exported unnecessarily.
44pub use self::{
45    bundle::{
46        bundle_ffi, CreateRenderBundleError, ExecutionError, RenderBundle, RenderBundleDescriptor,
47        RenderBundleEncoder, RenderBundleEncoderDescriptor, RenderBundleError,
48        RenderBundleErrorInner,
49    },
50    clear::ClearError,
51    compute::{
52        ComputeBasePass, ComputePass, ComputePassDescriptor, ComputePassError,
53        ComputePassErrorInner, DispatchError,
54    },
55    compute_command::ArcComputeCommand,
56    draw::{DrawError, Rect, RenderCommandError},
57    encoder_command::{ArcCommand, ArcReferences, Command, IdReferences, ReferenceType},
58    query::{QueryError, QueryUseError, ResolveError, SimplifiedQueryType},
59    render::{
60        ArcRenderPassColorAttachment, AttachmentError, AttachmentErrorLocation,
61        ColorAttachmentError, ColorAttachments, LoadOp, PassChannel, RenderBasePass, RenderPass,
62        RenderPassColorAttachment, RenderPassDepthStencilAttachment, RenderPassDescriptor,
63        RenderPassError, RenderPassErrorInner, ResolvedPassChannel,
64        ResolvedRenderPassDepthStencilAttachment, StoreOp,
65    },
66    render_command::ArcRenderCommand,
67    transfer::{CopySide, TransferError},
68    transition_resources::TransitionResourcesError,
69};
70pub(crate) use self::{
71    clear::clear_texture,
72    encoder::EncodingState,
73    memory_init::CommandBufferTextureMemoryActions,
74    render::{get_dst_stride_of_indirect_args, get_src_stride_of_indirect_args, VertexState},
75    transfer::{
76        extract_texture_selector, validate_linear_texture_data, validate_texture_buffer_copy,
77        validate_texture_copy_dst_format, validate_texture_copy_range,
78    },
79};
80
81pub(crate) use allocator::CommandAllocator;
82
83/// cbindgen:ignore
84pub use self::{compute_command::ComputeCommand, render_command::RenderCommand};
85
86pub(crate) use timestamp_writes::ArcPassTimestampWrites;
87pub use timestamp_writes::PassTimestampWrites;
88
89use crate::binding_model::BindingError;
90use crate::device::queue::TempResource;
91use crate::device::{Device, DeviceError, MissingFeatures};
92use crate::id::Id;
93use crate::lock::{rank, Mutex};
94use crate::snatch::SnatchGuard;
95
96use crate::init_tracker::BufferInitTrackerAction;
97use crate::ray_tracing::{AsAction, BuildAccelerationStructureError};
98use crate::resource::{
99    DestroyedResourceError, Fallible, InvalidOrDestroyedResourceError, InvalidResourceError,
100    Labeled, ParentDevice as _, QuerySet,
101};
102use crate::track::{DeviceTracker, ResourceUsageCompatibilityError, Tracker, UsageScope};
103use crate::{api_log, global::Global, id, resource_log, Label};
104use crate::{hal_label, LabelHelpers};
105
106use wgt::error::{ErrorType, WebGpuError};
107
108use thiserror::Error;
109
110/// cbindgen:ignore
111pub type TexelCopyBufferInfo = ffi::TexelCopyBufferInfo;
112/// cbindgen:ignore
113pub type TexelCopyTextureInfo = ffi::TexelCopyTextureInfo;
114/// cbindgen:ignore
115pub type CopyExternalImageDestInfo = ffi::CopyExternalImageDestInfo;
116
117const IMMEDIATES_CLEAR_ARRAY: &[u32] = &[0_u32; 64];
118
119pub(crate) struct EncoderErrorState {
120    error: CommandEncoderError,
121
122    #[cfg(feature = "trace")]
123    trace_commands: Option<Vec<Command<PointerReferences>>>,
124}
125
126/// Construct an `EncoderErrorState` with only a `CommandEncoderError` (without
127/// any traced commands).
128///
129/// This is used in cases where pass begin/end were mismatched, if the same
130/// encoder was finished multiple times, or in the status of a command buffer
131/// (in which case the commands were already saved to the trace). In some of
132/// these cases there may be commands that could be saved to the trace, but if
133/// the application is that confused about using encoders, it's not clear
134/// whether it's worth the effort to try and preserve the commands.
135fn make_error_state<E: Into<CommandEncoderError>>(error: E) -> CommandEncoderStatus {
136    CommandEncoderStatus::Error(EncoderErrorState {
137        error: error.into(),
138
139        #[cfg(feature = "trace")]
140        trace_commands: None,
141    })
142}
143
144/// The current state of a command or pass encoder.
145///
146/// In the WebGPU spec, the state of an encoder (open, locked, or ended) is
147/// orthogonal to the validity of the encoder. However, this enum does not
148/// represent the state of an invalid encoder.
149pub(crate) enum CommandEncoderStatus {
150    /// Ready to record commands. An encoder's initial state.
151    ///
152    /// Command building methods like [`command_encoder_clear_buffer`] and
153    /// [`compute_pass_end`] require the encoder to be in this
154    /// state.
155    ///
156    /// This corresponds to WebGPU's "open" state.
157    /// See <https://www.w3.org/TR/webgpu/#encoder-state-open>
158    ///
159    /// [`command_encoder_clear_buffer`]: Global::command_encoder_clear_buffer
160    /// [`compute_pass_end`]: Global::compute_pass_end
161    Recording(CommandBufferMutable),
162
163    /// Locked by a render or compute pass.
164    ///
165    /// This state is entered when a render/compute pass is created,
166    /// and exited when the pass is ended.
167    ///
168    /// As long as the command encoder is locked, any command building operation
169    /// on it will fail and put the encoder into the [`Self::Error`] state. See
170    /// <https://www.w3.org/TR/webgpu/#encoder-state-locked>
171    Locked(CommandBufferMutable),
172
173    Consumed,
174
175    /// Command recording is complete, and the buffer is ready for submission.
176    ///
177    /// [`Global::command_encoder_finish`] transitions a
178    /// `CommandBuffer` from the `Recording` state into this state.
179    ///
180    /// [`Global::queue_submit`] requires that command buffers are
181    /// in this state.
182    ///
183    /// This corresponds to WebGPU's "ended" state.
184    /// See <https://www.w3.org/TR/webgpu/#encoder-state-ended>
185    Finished(CommandBufferMutable),
186
187    /// The command encoder is invalid.
188    ///
189    /// The error that caused the invalidation is stored here, and will
190    /// be raised by `CommandEncoder.finish()`.
191    Error(EncoderErrorState),
192
193    /// Temporary state used internally by methods on `CommandEncoderStatus`.
194    /// Encoder should never be left in this state.
195    Transitioning,
196}
197
198impl CommandEncoderStatus {
199    #[doc(hidden)]
200    fn replay(&mut self, commands: Vec<Command<ArcReferences>>) {
201        let Self::Recording(cmd_buf_data) = self else {
202            panic!("encoder should be in the recording state");
203        };
204        cmd_buf_data.commands.extend(commands);
205    }
206
207    /// Push a command provided by a closure onto the encoder.
208    ///
209    /// If the encoder is in the [`Self::Recording`] state, calls the closure to
210    /// obtain a command, and pushes it onto the encoder. If the closure returns
211    /// an error, stores that error in the encoder for later reporting when
212    /// `finish()` is called. Returns `Ok(())` even if the closure returned an
213    /// error.
214    ///
215    /// If the encoder is not in the [`Self::Recording`] state, the closure will
216    /// not be called and nothing will be recorded. The encoder will be
217    /// invalidated (if it is not already). If the error is a [validation error
218    /// that should be raised immediately][ves], returns it in `Err`, otherwise,
219    /// returns `Ok(())`.
220    ///
221    /// [ves]: https://www.w3.org/TR/webgpu/#abstract-opdef-validate-the-encoder-state
222    fn push_with<F: FnOnce() -> Result<ArcCommand, E>, E: Clone + Into<CommandEncoderError>>(
223        &mut self,
224        f: F,
225    ) -> Result<(), EncoderStateError> {
226        match self {
227            Self::Recording(cmd_buf_data) => {
228                cmd_buf_data.encoder.api.set(EncodingApi::Wgpu);
229                match f() {
230                    Ok(cmd) => cmd_buf_data.commands.push(cmd),
231                    Err(err) => {
232                        self.invalidate(err);
233                    }
234                }
235                Ok(())
236            }
237            Self::Locked(_) => {
238                // Invalidate the encoder and do not record anything, but do not
239                // return an immediate validation error.
240                self.invalidate(EncoderStateError::Locked);
241                Ok(())
242            }
243            // Encoder is ended. Invalidate the encoder, do not record anything,
244            // and return an immediate validation error.
245            Self::Finished(_) => Err(self.invalidate(EncoderStateError::Ended)),
246            Self::Consumed => Err(EncoderStateError::Ended),
247            // Encoder is already invalid. Do not record anything, but do not
248            // return an immediate validation error.
249            Self::Error(_) => Ok(()),
250            Self::Transitioning => unreachable!(),
251        }
252    }
253
254    /// Call a closure with the inner command buffer structure.
255    ///
256    /// If the encoder is in the [`Self::Recording`] state, calls the provided
257    /// closure. If the closure returns an error, stores that error in the
258    /// encoder for later reporting when `finish()` is called. Returns `Ok(())`
259    /// even if the closure returned an error.
260    ///
261    /// If the encoder is not in the [`Self::Recording`] state, the closure will
262    /// not be called. The encoder will be invalidated (if it is not already).
263    /// If the error is a [validation error that should be raised
264    /// immediately][ves], returns it in `Err`, otherwise, returns `Ok(())`.
265    ///
266    /// [ves]: https://www.w3.org/TR/webgpu/#abstract-opdef-validate-the-encoder-state
267    fn with_buffer<
268        F: FnOnce(&mut CommandBufferMutable) -> Result<(), E>,
269        E: Clone + Into<CommandEncoderError>,
270    >(
271        &mut self,
272        api: EncodingApi,
273        f: F,
274    ) -> Result<(), EncoderStateError> {
275        match self {
276            Self::Recording(inner) => {
277                inner.encoder.api.set(api);
278                RecordingGuard { inner: self }.record(f);
279                Ok(())
280            }
281            Self::Locked(_) => {
282                // Invalidate the encoder and do not record anything, but do not
283                // return an immediate validation error.
284                self.invalidate(EncoderStateError::Locked);
285                Ok(())
286            }
287            // Encoder is ended. Invalidate the encoder, do not record anything,
288            // and return an immediate validation error.
289            Self::Finished(_) => Err(self.invalidate(EncoderStateError::Ended)),
290            Self::Consumed => Err(EncoderStateError::Ended),
291            // Encoder is already invalid. Do not record anything, but do not
292            // return an immediate validation error.
293            Self::Error(_) => Ok(()),
294            Self::Transitioning => unreachable!(),
295        }
296    }
297
298    /// Special version of record used by `command_encoder_as_hal_mut`. This
299    /// differs from the regular version in two ways:
300    ///
301    /// 1. The recording closure is infallible.
302    /// 2. The recording closure takes `Option<&mut CommandBufferMutable>`, and
303    ///    in the case that the encoder is not in a valid state for recording, the
304    ///    closure is still called, with `None` as its argument.
305    pub(crate) fn record_as_hal_mut<T, F: FnOnce(Option<&mut CommandBufferMutable>) -> T>(
306        &mut self,
307        f: F,
308    ) -> T {
309        match self {
310            Self::Recording(inner) => {
311                inner.encoder.api.set(EncodingApi::Raw);
312                RecordingGuard { inner: self }.record_as_hal_mut(f)
313            }
314            Self::Locked(_) => {
315                self.invalidate(EncoderStateError::Locked);
316                f(None)
317            }
318            Self::Finished(_) => {
319                self.invalidate(EncoderStateError::Ended);
320                f(None)
321            }
322            Self::Consumed => f(None),
323            Self::Error(_) => f(None),
324            Self::Transitioning => unreachable!(),
325        }
326    }
327
328    /// Locks the encoder by putting it in the [`Self::Locked`] state.
329    ///
330    /// Render or compute passes call this on start. At the end of the pass,
331    /// they call [`Self::unlock_encoder`] to put the [`CommandBuffer`] back
332    /// into the [`Self::Recording`] state.
333    fn lock_encoder(&mut self) -> Result<(), EncoderStateError> {
334        match mem::replace(self, Self::Transitioning) {
335            Self::Recording(inner) => {
336                *self = Self::Locked(inner);
337                Ok(())
338            }
339            st @ Self::Finished(_) => {
340                // Attempting to open a pass on a finished encoder raises a
341                // validation error but does not invalidate the encoder. This is
342                // related to https://github.com/gpuweb/gpuweb/issues/5207.
343                *self = st;
344                Err(EncoderStateError::Ended)
345            }
346            Self::Locked(_) => Err(self.invalidate(EncoderStateError::Locked)),
347            st @ Self::Consumed => {
348                *self = st;
349                Err(EncoderStateError::Ended)
350            }
351            st @ Self::Error(_) => {
352                *self = st;
353                Err(EncoderStateError::Invalid)
354            }
355            Self::Transitioning => unreachable!(),
356        }
357    }
358
359    /// Unlocks the encoder and puts it back into the [`Self::Recording`] state.
360    ///
361    /// This function is the unlocking counterpart to [`Self::lock_encoder`]. It
362    /// is only valid to call this function if the encoder is in the
363    /// [`Self::Locked`] state.
364    ///
365    /// If the encoder is in a state other than [`Self::Locked`] and a
366    /// validation error should be raised immediately, returns it in `Err`,
367    /// otherwise, stores the error in the encoder and returns `Ok(())`.
368    fn unlock_encoder(&mut self) -> Result<(), EncoderStateError> {
369        match mem::replace(self, Self::Transitioning) {
370            Self::Locked(inner) => {
371                *self = Self::Recording(inner);
372                Ok(())
373            }
374            st @ Self::Finished(_) => {
375                *self = st;
376                Err(EncoderStateError::Ended)
377            }
378            Self::Recording(_) => {
379                *self = make_error_state(EncoderStateError::Unlocked);
380                Err(EncoderStateError::Unlocked)
381            }
382            st @ Self::Consumed => {
383                *self = st;
384                Err(EncoderStateError::Ended)
385            }
386            st @ Self::Error(_) => {
387                // Encoder is already invalid. The error will be reported by
388                // `CommandEncoder.finish`.
389                *self = st;
390                Ok(())
391            }
392            Self::Transitioning => unreachable!(),
393        }
394    }
395
396    fn finish(&mut self) -> Self {
397        // Replace our state with `Consumed`, and return either the inner
398        // state or an error, to be transferred to the command buffer.
399        match mem::replace(self, Self::Consumed) {
400            Self::Recording(inner) => {
401                // Raw encoding leaves the encoder open in `command_encoder_as_hal_mut`.
402                // Otherwise, nothing should have opened it yet.
403                if inner.encoder.api != EncodingApi::Raw {
404                    assert!(!inner.encoder.is_open);
405                }
406                Self::Finished(inner)
407            }
408            Self::Consumed | Self::Finished(_) => make_error_state(EncoderStateError::Ended),
409            Self::Locked(_) => make_error_state(EncoderStateError::Locked),
410            st @ Self::Error(_) => st,
411            Self::Transitioning => unreachable!(),
412        }
413    }
414
415    /// Invalidate the command encoder due to an error.
416    ///
417    /// The error `err` is stored so that it can be reported when the encoder is
418    /// finished. If tracing is enabled, the traced commands are also stored.
419    ///
420    /// Since we do not track the state of an invalid encoder, it is not
421    /// necessary to unlock an encoder that has been invalidated.
422    fn invalidate<E: Clone + Into<CommandEncoderError>>(&mut self, err: E) -> E {
423        #[cfg(feature = "trace")]
424        let trace_commands = match self {
425            Self::Recording(cmd_buf_data) => Some(
426                mem::take(&mut cmd_buf_data.commands)
427                    .into_iter()
428                    .map(crate::device::trace::IntoTrace::into_trace)
429                    .collect(),
430            ),
431            _ => None,
432        };
433
434        let enc_err = err.clone().into();
435        api_log!("Invalidating command encoder: {enc_err:?}");
436        *self = Self::Error(EncoderErrorState {
437            error: enc_err,
438            #[cfg(feature = "trace")]
439            trace_commands,
440        });
441        err
442    }
443}
444
445/// A guard to enforce error reporting, for a [`CommandBuffer`] in the [`Recording`] state.
446///
447/// An [`RecordingGuard`] holds a mutable reference to a [`CommandEncoderStatus`] that
448/// has been verified to be in the [`Recording`] state. The [`RecordingGuard`] dereferences
449/// mutably to the [`CommandBufferMutable`] that the status holds.
450///
451/// Dropping an [`RecordingGuard`] sets the [`CommandBuffer`]'s state to
452/// [`CommandEncoderStatus::Error`]. If your use of the guard was
453/// successful, call its [`mark_successful`] method to dispose of it.
454///
455/// [`Recording`]: CommandEncoderStatus::Recording
456/// [`mark_successful`]: Self::mark_successful
457pub(crate) struct RecordingGuard<'a> {
458    inner: &'a mut CommandEncoderStatus,
459}
460
461impl<'a> RecordingGuard<'a> {
462    pub(crate) fn mark_successful(self) {
463        mem::forget(self)
464    }
465
466    fn record<
467        F: FnOnce(&mut CommandBufferMutable) -> Result<(), E>,
468        E: Clone + Into<CommandEncoderError>,
469    >(
470        mut self,
471        f: F,
472    ) {
473        match f(&mut self) {
474            Ok(()) => self.mark_successful(),
475            Err(err) => {
476                self.inner.invalidate(err);
477            }
478        }
479    }
480
481    /// Special version of record used by `command_encoder_as_hal_mut`. This
482    /// version takes an infallible recording closure.
483    pub(crate) fn record_as_hal_mut<T, F: FnOnce(Option<&mut CommandBufferMutable>) -> T>(
484        mut self,
485        f: F,
486    ) -> T {
487        let res = f(Some(&mut self));
488        self.mark_successful();
489        res
490    }
491}
492
493impl<'a> Drop for RecordingGuard<'a> {
494    fn drop(&mut self) {
495        if matches!(*self.inner, CommandEncoderStatus::Error(_)) {
496            // Don't overwrite an error that is already present.
497            return;
498        }
499        self.inner.invalidate(EncoderStateError::Invalid);
500    }
501}
502
503impl<'a> ops::Deref for RecordingGuard<'a> {
504    type Target = CommandBufferMutable;
505
506    fn deref(&self) -> &Self::Target {
507        match &*self.inner {
508            CommandEncoderStatus::Recording(command_buffer_mutable) => command_buffer_mutable,
509            _ => unreachable!(),
510        }
511    }
512}
513
514impl<'a> ops::DerefMut for RecordingGuard<'a> {
515    fn deref_mut(&mut self) -> &mut Self::Target {
516        match self.inner {
517            CommandEncoderStatus::Recording(command_buffer_mutable) => command_buffer_mutable,
518            _ => unreachable!(),
519        }
520    }
521}
522
523pub(crate) struct CommandEncoder {
524    pub(crate) device: Arc<Device>,
525
526    pub(crate) label: String,
527
528    /// The mutable state of this command encoder.
529    pub(crate) data: Mutex<CommandEncoderStatus>,
530}
531
532crate::impl_resource_type!(CommandEncoder);
533crate::impl_labeled!(CommandEncoder);
534crate::impl_parent_device!(CommandEncoder);
535crate::impl_storage_item!(CommandEncoder);
536
537#[cfg(send_sync)]
538const _: () = {
539    // SAFETY: Bounds checked below
540    unsafe impl Send for CommandEncoder {}
541    // SAFETY: Bounds checked below
542    unsafe impl Sync for CommandEncoder {}
543
544    fn _command_encoder_fields_are_send_sync(obj: &CommandEncoder) {
545        fn _check_bound<T: Send + Sync>(_: &T) {}
546        let CommandEncoder {
547            device,
548            label,
549            data,
550        } = obj;
551        _check_bound(device);
552        _check_bound(label);
553        _check_bound(data);
554    }
555};
556
557impl Drop for CommandEncoder {
558    fn drop(&mut self) {
559        resource_log!("Drop {}", self.error_ident());
560    }
561}
562
563/// The encoding API being used with a `CommandEncoder`.
564///
565/// Mixing APIs on the same encoder is not allowed.
566#[derive(Copy, Clone, Debug, Eq, PartialEq)]
567pub enum EncodingApi {
568    // The regular wgpu encoding APIs are being used.
569    Wgpu,
570
571    // The raw hal encoding API is being used.
572    Raw,
573
574    // Neither encoding API has been called yet.
575    Undecided,
576
577    // The encoder is used internally by wgpu.
578    InternalUse,
579}
580
581impl EncodingApi {
582    pub(crate) fn set(&mut self, api: EncodingApi) {
583        match *self {
584            EncodingApi::Undecided => {
585                *self = api;
586            }
587            self_api if self_api != api => {
588                panic!("Mixing the wgpu encoding API with the raw encoding API is not permitted");
589            }
590            _ => {}
591        }
592    }
593}
594
595/// A raw [`CommandEncoder`][rce], and the raw [`CommandBuffer`][rcb]s built from it.
596///
597/// Each wgpu-core [`CommandBuffer`] owns an instance of this type, which is
598/// where the commands are actually stored.
599///
600/// This holds a `Vec` of raw [`CommandBuffer`][rcb]s, not just one. We are not
601/// always able to record commands in the order in which they must ultimately be
602/// submitted to the queue, but raw command buffers don't permit inserting new
603/// commands into the middle of a recorded stream. However, hal queue submission
604/// accepts a series of command buffers at once, so we can simply break the
605/// stream up into multiple buffers, and then reorder the buffers. See
606/// [`InnerCommandEncoder::close_and_swap`] for a specific example of this.
607///
608/// [rce]: hal::Api::CommandEncoder
609/// [rcb]: hal::Api::CommandBuffer
610pub(crate) struct InnerCommandEncoder {
611    /// The underlying `wgpu_hal` [`CommandEncoder`].
612    ///
613    /// Successfully executed command buffers' encoders are saved in a
614    /// [`CommandAllocator`] for recycling.
615    ///
616    /// [`CommandEncoder`]: hal::Api::CommandEncoder
617    /// [`CommandAllocator`]: crate::command::CommandAllocator
618    pub(crate) raw: ManuallyDrop<Box<dyn hal::DynCommandEncoder>>,
619
620    /// All the raw command buffers for our owning [`CommandBuffer`], in
621    /// submission order.
622    ///
623    /// These command buffers were all constructed with `raw`. The
624    /// [`wgpu_hal::CommandEncoder`] trait forbids these from outliving `raw`,
625    /// and requires that we provide all of these when we call
626    /// [`raw.reset_all()`][CE::ra], so the encoder and its buffers travel
627    /// together.
628    ///
629    /// [CE::ra]: hal::CommandEncoder::reset_all
630    /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder
631    pub(crate) list: Vec<Box<dyn hal::DynCommandBuffer>>,
632
633    pub(crate) device: Arc<Device>,
634
635    /// True if `raw` is in the "recording" state.
636    ///
637    /// See the documentation for [`wgpu_hal::CommandEncoder`] for
638    /// details on the states `raw` can be in.
639    ///
640    /// [`wgpu_hal::CommandEncoder`]: hal::CommandEncoder
641    pub(crate) is_open: bool,
642
643    /// Tracks which API is being used to encode commands.
644    ///
645    /// Mixing the wgpu encoding API with access to the raw hal encoder via
646    /// `as_hal_mut` is not supported. this field tracks which API is being used
647    /// in order to detect and reject invalid usage.
648    pub(crate) api: EncodingApi,
649
650    pub(crate) label: String,
651}
652
653impl InnerCommandEncoder {
654    /// Finish the current command buffer and insert it just before
655    /// the last element in [`self.list`][l].
656    ///
657    /// On return, the underlying hal encoder is closed.
658    ///
659    /// What is this for?
660    ///
661    /// The `wgpu_hal` contract requires that each render or compute pass's
662    /// commands be preceded by calls to [`transition_buffers`] and
663    /// [`transition_textures`], to put the resources the pass operates on in
664    /// the appropriate state. Unfortunately, we don't know which transitions
665    /// are needed until we're done recording the pass itself. Rather than
666    /// iterating over the pass twice, we note the necessary transitions as we
667    /// record its commands, finish the raw command buffer for the actual pass,
668    /// record a new raw command buffer for the transitions, and jam that buffer
669    /// in just before the pass's. This is the function that jams in the
670    /// transitions' command buffer.
671    ///
672    /// # Panics
673    ///
674    /// - If the encoder is not open.
675    ///
676    /// # Warning
677    ///
678    /// Any [`DeferredQuerySetResolve::insertion_point`] pointing to the
679    /// last element will be invalidated.
680    ///
681    /// [l]: InnerCommandEncoder::list
682    /// [`transition_buffers`]: hal::CommandEncoder::transition_buffers
683    /// [`transition_textures`]: hal::CommandEncoder::transition_textures
684    /// [`DeferredQuerySetResolve::insertion_point`]: query::DeferredQuerySetResolve::insertion_point
685    fn close_and_swap(&mut self) -> Result<(), DeviceError> {
686        self.close_and_insert_at(self.list.len() - 1)
687    }
688
689    /// Finish the current command buffer and insert it at the beginning
690    /// of [`self.list`][l].
691    ///
692    /// On return, the underlying hal encoder is closed.
693    ///
694    /// # Panics
695    ///
696    /// - If the encoder is not open.
697    ///
698    /// # Warning
699    ///
700    /// All existing [`DeferredQuerySetResolve::insertion_point`] values
701    /// will be invalidated.
702    ///
703    /// [l]: InnerCommandEncoder::list
704    /// [`DeferredQuerySetResolve::insertion_point`]: query::DeferredQuerySetResolve::insertion_point
705    pub(crate) fn close_and_push_front(&mut self) -> Result<(), DeviceError> {
706        self.close_and_insert_at(0)
707    }
708
709    /// Finish the current command buffer and insert it at the given index
710    /// in [`self.list`][l].
711    ///
712    /// On return, the underlying hal encoder is closed.
713    ///
714    /// # Panics
715    ///
716    /// - If the encoder is not open.
717    ///
718    /// # Warning
719    ///
720    /// Any [`DeferredQuerySetResolve::insertion_point`] value that is
721    /// >= `index` will be invalidated.
722    ///
723    /// [l]: InnerCommandEncoder::list
724    /// [`DeferredQuerySetResolve::insertion_point`]: query::DeferredQuerySetResolve::insertion_point
725    pub(crate) fn close_and_insert_at(&mut self, index: usize) -> Result<(), DeviceError> {
726        assert!(self.is_open);
727        self.is_open = false;
728
729        let cmd_buf =
730            unsafe { self.raw.end_encoding() }.map_err(|e| self.device.handle_hal_error(e))?;
731        self.list.insert(index, cmd_buf);
732
733        Ok(())
734    }
735
736    /// Finish the current command buffer, and push it onto
737    /// the end of [`self.list`][l].
738    ///
739    /// On return, the underlying hal encoder is closed.
740    ///
741    /// # Panics
742    ///
743    /// - If the encoder is not open.
744    ///
745    /// [l]: InnerCommandEncoder::list
746    pub(crate) fn close(&mut self) -> Result<(), DeviceError> {
747        assert!(self.is_open);
748        self.is_open = false;
749
750        let cmd_buf =
751            unsafe { self.raw.end_encoding() }.map_err(|e| self.device.handle_hal_error(e))?;
752        self.list.push(cmd_buf);
753
754        Ok(())
755    }
756
757    /// Finish the current command buffer, if any, and add it to the
758    /// end of [`self.list`][l].
759    ///
760    /// If we have opened this command encoder, finish its current
761    /// command buffer, and push it onto the end of [`self.list`][l].
762    /// If this command buffer is closed, do nothing.
763    ///
764    /// On return, the underlying hal encoder is closed.
765    ///
766    /// [l]: InnerCommandEncoder::list
767    fn close_if_open(&mut self) -> Result<(), DeviceError> {
768        if self.is_open {
769            self.is_open = false;
770            let cmd_buf =
771                unsafe { self.raw.end_encoding() }.map_err(|e| self.device.handle_hal_error(e))?;
772            self.list.push(cmd_buf);
773        }
774
775        Ok(())
776    }
777
778    /// If the command encoder is not open, begin recording a new command buffer.
779    ///
780    /// If the command encoder was already open, does nothing.
781    ///
782    /// In both cases, returns a reference to the raw encoder.
783    fn open_if_closed(&mut self) -> Result<&mut dyn hal::DynCommandEncoder, DeviceError> {
784        if !self.is_open {
785            let hal_label = hal_label(Some(self.label.as_str()), self.device.instance_flags);
786            unsafe { self.raw.begin_encoding(hal_label) }
787                .map_err(|e| self.device.handle_hal_error(e))?;
788            self.is_open = true;
789        }
790
791        Ok(self.raw.as_mut())
792    }
793
794    /// Begin recording a new command buffer, if we haven't already.
795    ///
796    /// The underlying hal encoder is put in the "recording" state.
797    pub(crate) fn open(&mut self) -> Result<&mut dyn hal::DynCommandEncoder, DeviceError> {
798        if !self.is_open {
799            let hal_label = hal_label(Some(self.label.as_str()), self.device.instance_flags);
800            unsafe { self.raw.begin_encoding(hal_label) }
801                .map_err(|e| self.device.handle_hal_error(e))?;
802            self.is_open = true;
803        }
804
805        Ok(self.raw.as_mut())
806    }
807
808    /// Begin recording a new command buffer for a render or compute pass, with
809    /// its own label.
810    ///
811    /// The underlying hal encoder is put in the "recording" state.
812    ///
813    /// # Panics
814    ///
815    /// - If the encoder is already open.
816    pub(crate) fn open_pass(
817        &mut self,
818        label: Option<&str>,
819    ) -> Result<&mut dyn hal::DynCommandEncoder, DeviceError> {
820        assert!(!self.is_open);
821
822        let hal_label = hal_label(label, self.device.instance_flags);
823        unsafe { self.raw.begin_encoding(hal_label) }
824            .map_err(|e| self.device.handle_hal_error(e))?;
825        self.is_open = true;
826
827        Ok(self.raw.as_mut())
828    }
829}
830
831impl Drop for InnerCommandEncoder {
832    fn drop(&mut self) {
833        if self.is_open {
834            unsafe { self.raw.discard_encoding() };
835        }
836        unsafe {
837            self.raw.reset_all(mem::take(&mut self.list));
838        }
839        // SAFETY: We are in the Drop impl and we don't use self.raw anymore after this point.
840        let raw = unsafe { ManuallyDrop::take(&mut self.raw) };
841        self.device.command_allocator.release_encoder(raw);
842    }
843}
844
845/// Look at the documentation for [`CommandBufferMutable`] for an explanation of
846/// the fields in this struct. This is the "built" counterpart to that type.
847pub(crate) struct BakedCommands {
848    pub(crate) encoder: InnerCommandEncoder,
849    pub(crate) trackers: Tracker,
850    pub(crate) temp_resources: Vec<TempResource>,
851    pub(crate) indirect_draw_validation_resources: crate::indirect_validation::DrawResources,
852    buffer_memory_init_actions: Vec<BufferInitTrackerAction>,
853    texture_memory_actions: CommandBufferTextureMemoryActions,
854    pub(crate) query_set_writes: query::QuerySetWrites,
855    pub(crate) deferred_query_set_resolves: Vec<query::DeferredQuerySetResolve>,
856}
857
858/// The mutable state of a [`CommandBuffer`].
859pub struct CommandBufferMutable {
860    /// The [`wgpu_hal::Api::CommandBuffer`]s we've built so far, and the encoder
861    /// they belong to.
862    ///
863    /// [`wgpu_hal::Api::CommandBuffer`]: hal::Api::CommandBuffer
864    pub(crate) encoder: InnerCommandEncoder,
865
866    /// All the resources that the commands recorded so far have referred to.
867    pub(crate) trackers: Tracker,
868
869    /// The regions of buffers and textures these commands will read and write.
870    ///
871    /// This is used to determine which portions of which
872    /// buffers/textures we actually need to initialize. If we're
873    /// definitely going to write to something before we read from it,
874    /// we don't need to clear its contents.
875    buffer_memory_init_actions: Vec<BufferInitTrackerAction>,
876    texture_memory_actions: CommandBufferTextureMemoryActions,
877
878    as_actions: Vec<AsAction>,
879    temp_resources: Vec<TempResource>,
880
881    indirect_draw_validation_resources: crate::indirect_validation::DrawResources,
882
883    pub(crate) commands: Vec<Command<ArcReferences>>,
884
885    /// If tracing, `command_encoder_finish` replaces the `Arc`s in `commands`
886    /// with integer pointers, and moves them into `trace_commands`.
887    #[cfg(feature = "trace")]
888    pub(crate) trace_commands: Option<Vec<Command<PointerReferences>>>,
889
890    /// Tracks which query slots have been written by commands in this encoder.
891    pub(crate) query_set_writes: query::QuerySetWrites,
892    /// Query set resolves that had to be deferred to submit time.
893    pub(crate) deferred_query_set_resolves: Vec<query::DeferredQuerySetResolve>,
894}
895
896impl CommandBufferMutable {
897    pub(crate) fn into_baked_commands(self) -> BakedCommands {
898        BakedCommands {
899            encoder: self.encoder,
900            trackers: self.trackers,
901            temp_resources: self.temp_resources,
902            indirect_draw_validation_resources: self.indirect_draw_validation_resources,
903            buffer_memory_init_actions: self.buffer_memory_init_actions,
904            texture_memory_actions: self.texture_memory_actions,
905            query_set_writes: self.query_set_writes,
906            deferred_query_set_resolves: self.deferred_query_set_resolves,
907        }
908    }
909}
910
911/// A buffer of commands to be submitted to the GPU for execution.
912///
913/// Once a command buffer is submitted to the queue, its contents are taken
914/// to construct a [`BakedCommands`], whose contents eventually become the
915/// property of the submission queue.
916pub struct CommandBuffer {
917    pub(crate) device: Arc<Device>,
918    /// The `label` from the descriptor used to create the resource.
919    label: String,
920
921    /// The mutable state of this command buffer.
922    pub(crate) data: Mutex<CommandEncoderStatus>,
923}
924
925#[cfg(send_sync)]
926const _: () = {
927    // SAFETY: Bounds checked below
928    unsafe impl Send for CommandBuffer {}
929    // SAFETY: Bounds checked below
930    unsafe impl Sync for CommandBuffer {}
931
932    fn _command_buffer_fields_are_send_sync(obj: &CommandBuffer) {
933        fn _check_bound<T: Send + Sync>(_: &T) {}
934        let CommandBuffer {
935            device,
936            label,
937            data,
938        } = obj;
939        _check_bound(device);
940        _check_bound(label);
941        _check_bound(data);
942    }
943};
944
945impl Drop for CommandBuffer {
946    fn drop(&mut self) {
947        resource_log!("Drop {}", self.error_ident());
948    }
949}
950
951impl CommandEncoder {
952    pub(crate) fn new(
953        encoder: Box<dyn hal::DynCommandEncoder>,
954        device: &Arc<Device>,
955        label: &Label,
956    ) -> Self {
957        CommandEncoder {
958            device: device.clone(),
959            label: label.to_string(),
960            data: Mutex::new(
961                rank::COMMAND_BUFFER_DATA,
962                CommandEncoderStatus::Recording(CommandBufferMutable {
963                    encoder: InnerCommandEncoder {
964                        raw: ManuallyDrop::new(encoder),
965                        list: Vec::new(),
966                        device: device.clone(),
967                        is_open: false,
968                        api: EncodingApi::Undecided,
969                        label: label.to_string(),
970                    },
971                    trackers: Tracker::new(
972                        device.ordered_buffer_usages,
973                        device.ordered_texture_usages,
974                    ),
975                    buffer_memory_init_actions: Default::default(),
976                    texture_memory_actions: Default::default(),
977                    as_actions: Default::default(),
978                    temp_resources: Default::default(),
979                    indirect_draw_validation_resources:
980                        crate::indirect_validation::DrawResources::new(device.clone()),
981                    commands: Vec::new(),
982                    query_set_writes: Default::default(),
983                    deferred_query_set_resolves: Default::default(),
984                    #[cfg(feature = "trace")]
985                    trace_commands: if device.trace.lock().is_some() {
986                        Some(Vec::new())
987                    } else {
988                        None
989                    },
990                }),
991            ),
992        }
993    }
994
995    pub(crate) fn new_invalid(
996        device: &Arc<Device>,
997        label: &Label,
998        err: CommandEncoderError,
999    ) -> Self {
1000        CommandEncoder {
1001            device: device.clone(),
1002            label: label.to_string(),
1003            data: Mutex::new(rank::COMMAND_BUFFER_DATA, make_error_state(err)),
1004        }
1005    }
1006
1007    pub(crate) fn validate_pass_timestamp_writes<E>(
1008        device: &Device,
1009        timestamp_writes: &PassTimestampWrites<Fallible<QuerySet>>,
1010    ) -> Result<ArcPassTimestampWrites, E>
1011    where
1012        E: From<TimestampWritesError>
1013            + From<QueryUseError>
1014            + From<DeviceError>
1015            + From<MissingFeatures>
1016            + From<InvalidResourceError>,
1017    {
1018        let &PassTimestampWrites {
1019            ref query_set,
1020            beginning_of_pass_write_index,
1021            end_of_pass_write_index,
1022        } = timestamp_writes;
1023
1024        device.require_features(wgt::Features::TIMESTAMP_QUERY)?;
1025
1026        let query_set = query_set.clone().get()?;
1027
1028        query_set.same_device(device)?;
1029
1030        for idx in [beginning_of_pass_write_index, end_of_pass_write_index]
1031            .into_iter()
1032            .flatten()
1033        {
1034            query_set.validate_query(SimplifiedQueryType::Timestamp, idx, None)?;
1035        }
1036
1037        if let Some((begin, end)) = beginning_of_pass_write_index.zip(end_of_pass_write_index) {
1038            if begin == end {
1039                return Err(TimestampWritesError::IndicesEqual { idx: begin }.into());
1040            }
1041        }
1042
1043        if beginning_of_pass_write_index
1044            .or(end_of_pass_write_index)
1045            .is_none()
1046        {
1047            return Err(TimestampWritesError::IndicesMissing.into());
1048        }
1049
1050        Ok(ArcPassTimestampWrites {
1051            query_set,
1052            beginning_of_pass_write_index,
1053            end_of_pass_write_index,
1054        })
1055    }
1056
1057    pub(crate) fn insert_barriers_from_tracker(
1058        raw: &mut dyn hal::DynCommandEncoder,
1059        base: &mut Tracker,
1060        head: &Tracker,
1061        snatch_guard: &SnatchGuard,
1062    ) {
1063        profiling::scope!("insert_barriers");
1064
1065        base.buffers.set_from_tracker(&head.buffers);
1066        base.textures.set_from_tracker(&head.textures);
1067
1068        Self::drain_barriers(raw, base, snatch_guard);
1069    }
1070
1071    pub(crate) fn insert_barriers_from_scope(
1072        raw: &mut dyn hal::DynCommandEncoder,
1073        base: &mut Tracker,
1074        head: &UsageScope,
1075        snatch_guard: &SnatchGuard,
1076    ) {
1077        profiling::scope!("insert_barriers");
1078
1079        base.buffers.set_from_usage_scope(&head.buffers);
1080        base.textures.set_from_usage_scope(&head.textures);
1081
1082        Self::drain_barriers(raw, base, snatch_guard);
1083    }
1084
1085    pub(crate) fn drain_barriers(
1086        raw: &mut dyn hal::DynCommandEncoder,
1087        base: &mut Tracker,
1088        snatch_guard: &SnatchGuard,
1089    ) {
1090        profiling::scope!("drain_barriers");
1091
1092        let buffer_barriers = base
1093            .buffers
1094            .drain_transitions(snatch_guard)
1095            .collect::<Vec<_>>();
1096        let (transitions, textures) = base.textures.drain_transitions(snatch_guard);
1097        let texture_barriers = transitions
1098            .into_iter()
1099            .enumerate()
1100            .map(|(i, p)| p.into_hal(textures[i].unwrap().raw()))
1101            .collect::<Vec<_>>();
1102
1103        unsafe {
1104            raw.transition_buffers(&buffer_barriers);
1105            raw.transition_textures(&texture_barriers);
1106        }
1107    }
1108
1109    pub(crate) fn insert_barriers_from_device_tracker(
1110        raw: &mut dyn hal::DynCommandEncoder,
1111        base: &mut DeviceTracker,
1112        head: &Tracker,
1113        snatch_guard: &SnatchGuard,
1114    ) {
1115        profiling::scope!("insert_barriers_from_device_tracker");
1116
1117        let buffer_barriers = base
1118            .buffers
1119            .set_from_tracker_and_drain_transitions(&head.buffers, snatch_guard)
1120            .collect::<Vec<_>>();
1121
1122        let texture_barriers = base
1123            .textures
1124            .set_from_tracker_and_drain_transitions(&head.textures, snatch_guard)
1125            .collect::<Vec<_>>();
1126
1127        unsafe {
1128            raw.transition_buffers(&buffer_barriers);
1129            raw.transition_textures(&texture_barriers);
1130        }
1131    }
1132
1133    fn encode_commands(
1134        device: &Arc<Device>,
1135        cmd_buf_data: &mut CommandBufferMutable,
1136    ) -> Result<(), CommandEncoderError> {
1137        device.check_is_valid()?;
1138        let snatch_guard = device.snatchable_lock.read();
1139        let mut debug_scope_depth = 0;
1140
1141        if cmd_buf_data.encoder.api == EncodingApi::Raw {
1142            // Should have panicked on the first call that switched APIs,
1143            // but lets be sure.
1144            assert!(cmd_buf_data.commands.is_empty());
1145        }
1146
1147        let commands = mem::take(&mut cmd_buf_data.commands);
1148
1149        #[cfg(feature = "trace")]
1150        if device.trace.lock().is_some() {
1151            cmd_buf_data.trace_commands = Some(
1152                commands
1153                    .iter()
1154                    .map(crate::device::trace::IntoTrace::to_trace)
1155                    .collect(),
1156            );
1157        }
1158
1159        for command in commands {
1160            if matches!(
1161                command,
1162                ArcCommand::RunRenderPass { .. }
1163                    | ArcCommand::RunComputePass { .. }
1164                    | ArcCommand::ResolveQuerySet { .. }
1165            ) {
1166                // Compute passes and render passes can accept either an
1167                // open or closed encoder. Resolving query sets needs to
1168                // potentially close and open the encoder. This state
1169                // object holds an `InnerCommandEncoder`. See the
1170                // documentation of [`EncodingState`].
1171                let mut state = EncodingState {
1172                    device,
1173                    raw_encoder: &mut cmd_buf_data.encoder,
1174                    tracker: &mut cmd_buf_data.trackers,
1175                    buffer_memory_init_actions: &mut cmd_buf_data.buffer_memory_init_actions,
1176                    texture_memory_actions: &mut cmd_buf_data.texture_memory_actions,
1177                    as_actions: &mut cmd_buf_data.as_actions,
1178                    temp_resources: &mut cmd_buf_data.temp_resources,
1179                    indirect_draw_validation_resources: &mut cmd_buf_data
1180                        .indirect_draw_validation_resources,
1181                    snatch_guard: &snatch_guard,
1182                    debug_scope_depth: &mut debug_scope_depth,
1183                    query_set_writes: &mut cmd_buf_data.query_set_writes,
1184                    deferred_query_set_resolves: &mut cmd_buf_data.deferred_query_set_resolves,
1185                };
1186
1187                match command {
1188                    ArcCommand::RunRenderPass {
1189                        pass,
1190                        color_attachments,
1191                        depth_stencil_attachment,
1192                        timestamp_writes,
1193                        occlusion_query_set,
1194                        multiview_mask,
1195                    } => {
1196                        api_log!(
1197                            "Begin encoding render pass with '{}' label",
1198                            pass.label.as_deref().unwrap_or("")
1199                        );
1200                        let res = render::encode_render_pass(
1201                            &mut state,
1202                            pass,
1203                            color_attachments,
1204                            depth_stencil_attachment,
1205                            timestamp_writes,
1206                            occlusion_query_set,
1207                            multiview_mask,
1208                        );
1209                        match res.as_ref() {
1210                            Err(err) => {
1211                                api_log!("Finished encoding render pass ({err:?})")
1212                            }
1213                            Ok(_) => {
1214                                api_log!("Finished encoding render pass (success)")
1215                            }
1216                        }
1217                        res?;
1218                    }
1219                    ArcCommand::RunComputePass {
1220                        pass,
1221                        timestamp_writes,
1222                    } => {
1223                        api_log!(
1224                            "Begin encoding compute pass with '{}' label",
1225                            pass.label.as_deref().unwrap_or("")
1226                        );
1227                        let res = compute::encode_compute_pass(&mut state, pass, timestamp_writes);
1228                        match res.as_ref() {
1229                            Err(err) => {
1230                                api_log!("Finished encoding compute pass ({err:?})")
1231                            }
1232                            Ok(_) => {
1233                                api_log!("Finished encoding compute pass (success)")
1234                            }
1235                        }
1236                        res?;
1237                    }
1238                    ArcCommand::ResolveQuerySet {
1239                        query_set,
1240                        start_query,
1241                        query_count,
1242                        destination,
1243                        destination_offset,
1244                    } => {
1245                        query::resolve_query_set(
1246                            &mut state,
1247                            query_set,
1248                            start_query,
1249                            query_count,
1250                            destination,
1251                            destination_offset,
1252                        )?;
1253                    }
1254                    _ => unreachable!(),
1255                }
1256            } else {
1257                // All the other non-pass encoding routines assume the
1258                // encoder is open, so open it if necessary. This state
1259                // object holds an `&mut dyn hal::DynCommandEncoder`. By
1260                // convention, a bare HAL encoder reference in
1261                // [`EncodingState`] must always be an open encoder.
1262                let raw_encoder = cmd_buf_data.encoder.open_if_closed()?;
1263                let mut state = EncodingState {
1264                    device,
1265                    raw_encoder,
1266                    tracker: &mut cmd_buf_data.trackers,
1267                    buffer_memory_init_actions: &mut cmd_buf_data.buffer_memory_init_actions,
1268                    texture_memory_actions: &mut cmd_buf_data.texture_memory_actions,
1269                    as_actions: &mut cmd_buf_data.as_actions,
1270                    temp_resources: &mut cmd_buf_data.temp_resources,
1271                    indirect_draw_validation_resources: &mut cmd_buf_data
1272                        .indirect_draw_validation_resources,
1273                    snatch_guard: &snatch_guard,
1274                    debug_scope_depth: &mut debug_scope_depth,
1275                    query_set_writes: &mut cmd_buf_data.query_set_writes,
1276                    deferred_query_set_resolves: &mut cmd_buf_data.deferred_query_set_resolves,
1277                };
1278                match command {
1279                    ArcCommand::CopyBufferToBuffer {
1280                        src,
1281                        src_offset,
1282                        dst,
1283                        dst_offset,
1284                        size,
1285                    } => {
1286                        transfer::copy_buffer_to_buffer(
1287                            &mut state, &src, src_offset, &dst, dst_offset, size,
1288                        )?;
1289                    }
1290                    ArcCommand::CopyBufferToTexture { src, dst, size } => {
1291                        transfer::copy_buffer_to_texture(&mut state, &src, &dst, &size)?;
1292                    }
1293                    ArcCommand::CopyTextureToBuffer { src, dst, size } => {
1294                        transfer::copy_texture_to_buffer(&mut state, &src, &dst, &size)?;
1295                    }
1296                    ArcCommand::CopyTextureToTexture { src, dst, size } => {
1297                        transfer::copy_texture_to_texture(&mut state, &src, &dst, &size)?;
1298                    }
1299                    ArcCommand::ClearBuffer { dst, offset, size } => {
1300                        clear::clear_buffer(&mut state, dst, offset, size)?;
1301                    }
1302                    ArcCommand::ClearTexture {
1303                        dst,
1304                        subresource_range,
1305                    } => {
1306                        clear::clear_texture_cmd(&mut state, dst, &subresource_range)?;
1307                    }
1308                    ArcCommand::WriteTimestamp {
1309                        query_set,
1310                        query_index,
1311                    } => {
1312                        query::write_timestamp(&mut state, query_set, query_index)?;
1313                    }
1314                    ArcCommand::PushDebugGroup(label) => {
1315                        push_debug_group(&mut state, &label)?;
1316                    }
1317                    ArcCommand::PopDebugGroup => {
1318                        pop_debug_group(&mut state)?;
1319                    }
1320                    ArcCommand::InsertDebugMarker(label) => {
1321                        insert_debug_marker(&mut state, &label)?;
1322                    }
1323                    ArcCommand::BuildAccelerationStructures { blas, tlas } => {
1324                        ray_tracing::build_acceleration_structures(&mut state, blas, tlas)?;
1325                    }
1326                    ArcCommand::TransitionResources {
1327                        buffer_transitions,
1328                        texture_transitions,
1329                    } => {
1330                        transition_resources::transition_resources(
1331                            &mut state,
1332                            buffer_transitions,
1333                            texture_transitions,
1334                        )?;
1335                    }
1336                    ArcCommand::RunComputePass { .. }
1337                    | ArcCommand::RunRenderPass { .. }
1338                    | ArcCommand::ResolveQuerySet { .. } => {
1339                        unreachable!()
1340                    }
1341                }
1342            }
1343        }
1344
1345        if debug_scope_depth > 0 {
1346            Err(CommandEncoderError::DebugGroupError(
1347                DebugGroupError::MissingPop,
1348            ))?;
1349        }
1350
1351        // Close the encoder, unless it was closed already by a render or compute pass.
1352        cmd_buf_data.encoder.close_if_open()?;
1353
1354        // Note: if we want to stop tracking the swapchain texture view,
1355        // this is the place to do it.
1356
1357        Ok(())
1358    }
1359
1360    fn finish(
1361        self: &Arc<Self>,
1362        desc: &wgt::CommandBufferDescriptor<Label>,
1363    ) -> (Arc<CommandBuffer>, Option<CommandEncoderError>) {
1364        let status = self.data.lock().finish();
1365
1366        let res = match status {
1367            CommandEncoderStatus::Finished(mut cmd_buf_data) => {
1368                match Self::encode_commands(&self.device, &mut cmd_buf_data) {
1369                    Ok(()) => Ok(cmd_buf_data),
1370                    Err(error) => Err(EncoderErrorState {
1371                        error,
1372                        #[cfg(feature = "trace")]
1373                        trace_commands: mem::take(&mut cmd_buf_data.trace_commands),
1374                    }),
1375                }
1376            }
1377            CommandEncoderStatus::Error(error_state) => Err(error_state),
1378            _ => unreachable!(),
1379        };
1380
1381        let (data, error) = match res {
1382            Err(EncoderErrorState {
1383                error,
1384                #[cfg(feature = "trace")]
1385                trace_commands,
1386            }) => {
1387                // Normally, commands are added to the trace when submitted, but
1388                // since this command buffer won't be submitted, add it to the
1389                // trace now.
1390                #[cfg(feature = "trace")]
1391                if let Some(trace) = self.device.trace.lock().as_mut() {
1392                    use alloc::string::ToString;
1393
1394                    trace.add(crate::device::trace::Action::FailedCommands {
1395                        commands: trace_commands,
1396                        failed_at_submit: None,
1397                        error: error.to_string(),
1398                    });
1399                }
1400
1401                if error.is_destroyed_error() {
1402                    // Errors related to destroyed resources are not reported until the
1403                    // command buffer is submitted.
1404                    (make_error_state(error), None)
1405                } else {
1406                    (make_error_state(error.clone()), Some(error))
1407                }
1408            }
1409
1410            Ok(data) => (CommandEncoderStatus::Finished(data), None),
1411        };
1412
1413        let cmd_buf = Arc::new(CommandBuffer {
1414            device: self.device.clone(),
1415            label: desc.label.to_string(),
1416            data: Mutex::new(rank::COMMAND_BUFFER_DATA, data),
1417        });
1418
1419        (cmd_buf, error)
1420    }
1421}
1422
1423impl CommandBuffer {
1424    /// Replay commands from a trace.
1425    ///
1426    /// This is exposed for the `player` crate only. It is not a public API.
1427    /// It is not guaranteed to apply all of the validation that the original
1428    /// entrypoints provide.
1429    #[doc(hidden)]
1430    pub fn from_trace(device: &Arc<Device>, commands: Vec<Command<ArcReferences>>) -> Arc<Self> {
1431        let encoder = device.create_command_encoder(&None).unwrap();
1432        let mut cmd_enc_status = encoder.data.lock();
1433        cmd_enc_status.replay(commands);
1434        drop(cmd_enc_status);
1435
1436        let (cmd_buf, error) = encoder.finish(&wgt::CommandBufferDescriptor { label: None });
1437        if let Some(err) = error {
1438            panic!("CommandEncoder::finish failed: {err}");
1439        }
1440
1441        cmd_buf
1442    }
1443
1444    pub fn take_finished(&self) -> Result<CommandBufferMutable, CommandEncoderError> {
1445        use CommandEncoderStatus as St;
1446        match mem::replace(
1447            &mut *self.data.lock(),
1448            make_error_state(EncoderStateError::Submitted),
1449        ) {
1450            St::Finished(command_buffer_mutable) => Ok(command_buffer_mutable),
1451            St::Error(EncoderErrorState {
1452                #[cfg(feature = "trace")]
1453                    trace_commands: _,
1454                error,
1455            }) => Err(error),
1456            St::Recording(_) | St::Locked(_) | St::Consumed | St::Transitioning => unreachable!(),
1457        }
1458    }
1459}
1460
1461crate::impl_resource_type!(CommandBuffer);
1462crate::impl_labeled!(CommandBuffer);
1463crate::impl_parent_device!(CommandBuffer);
1464crate::impl_storage_item!(CommandBuffer);
1465
1466/// A stream of commands for a render pass or compute pass.
1467///
1468/// This also contains side tables referred to by certain commands,
1469/// like dynamic offsets for [`SetBindGroup`] or string data for
1470/// [`InsertDebugMarker`].
1471///
1472/// Render passes use `BasePass<RenderCommand>`, whereas compute
1473/// passes use `BasePass<ComputeCommand>`.
1474///
1475/// [`SetBindGroup`]: RenderCommand::SetBindGroup
1476/// [`InsertDebugMarker`]: RenderCommand::InsertDebugMarker
1477#[doc(hidden)]
1478#[derive(Debug, Clone)]
1479#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
1480pub struct BasePass<C, E> {
1481    pub label: Option<String>,
1482
1483    /// If the pass is invalid, contains the error that caused the invalidation.
1484    ///
1485    /// If the pass is valid, this is `None`.
1486    ///
1487    /// Passes are serialized into traces. but we don't support doing so for
1488    /// passes containing errors. These serde attributes allow `E` to be
1489    /// `Infallible`.
1490    #[cfg_attr(feature = "serde", serde(skip, default = "Option::default"))]
1491    pub error: Option<E>,
1492
1493    /// The stream of commands.
1494    ///
1495    /// The commands are moved out of this vector when the pass is ended (i.e.
1496    /// at the same time that `parent` is taken out of the
1497    /// `ComputePass`/`RenderPass`).
1498    pub commands: Vec<C>,
1499
1500    /// Dynamic offsets consumed by [`SetBindGroup`] commands in `commands`.
1501    ///
1502    /// Each successive `SetBindGroup` consumes the next
1503    /// [`num_dynamic_offsets`] values from this list.
1504    pub dynamic_offsets: Vec<wgt::DynamicOffset>,
1505
1506    /// Strings used by debug instructions.
1507    ///
1508    /// Each successive [`PushDebugGroup`] or [`InsertDebugMarker`]
1509    /// instruction consumes the next `len` bytes from this vector.
1510    pub string_data: Vec<u8>,
1511
1512    /// Data used by `SetImmediate` instructions.
1513    ///
1514    /// See the documentation for [`RenderCommand::SetImmediate`]
1515    /// and [`ComputeCommand::SetImmediate`] for details.
1516    pub immediates_data: Vec<u32>,
1517}
1518
1519impl<C: Clone, E: Clone> BasePass<C, E> {
1520    fn new(label: &Label) -> Self {
1521        Self {
1522            label: label.as_deref().map(str::to_owned),
1523            error: None,
1524            commands: Vec::new(),
1525            dynamic_offsets: Vec::new(),
1526            string_data: Vec::new(),
1527            immediates_data: Vec::new(),
1528        }
1529    }
1530
1531    fn new_invalid(label: &Label, err: E) -> Self {
1532        Self {
1533            label: label.as_deref().map(str::to_owned),
1534            error: Some(err),
1535            commands: Vec::new(),
1536            dynamic_offsets: Vec::new(),
1537            string_data: Vec::new(),
1538            immediates_data: Vec::new(),
1539        }
1540    }
1541
1542    /// Takes the commands from the pass, or returns an error if the pass is
1543    /// invalid.
1544    ///
1545    /// This is called when the pass is ended, at the same time that the
1546    /// `parent` member of the `ComputePass` or `RenderPass` containing the pass
1547    /// is taken.
1548    fn take(&mut self) -> Result<BasePass<C, Infallible>, E> {
1549        match self.error.as_ref() {
1550            Some(err) => Err(err.clone()),
1551            None => Ok(BasePass {
1552                label: self.label.clone(),
1553                error: None,
1554                commands: mem::take(&mut self.commands),
1555                dynamic_offsets: mem::take(&mut self.dynamic_offsets),
1556                string_data: mem::take(&mut self.string_data),
1557                immediates_data: mem::take(&mut self.immediates_data),
1558            }),
1559        }
1560    }
1561}
1562
1563/// Checks the state of a [`compute::ComputePass`] or [`render::RenderPass`] and
1564/// evaluates to a mutable reference to the [`BasePass`], if the pass is open and
1565/// valid.
1566///
1567/// If the pass is ended or not valid, **returns from the invoking function**,
1568/// like the `?` operator.
1569///
1570/// If the pass is ended (i.e. the application is attempting to record a command
1571/// on a finished pass), returns `Err(EncoderStateError::Ended)` from the
1572/// invoking function, for immediate propagation as a validation error.
1573///
1574/// If the pass is open but invalid (i.e. a previous command encountered an
1575/// error), returns `Ok(())` from the invoking function. The pass should already
1576/// have stored the previous error, which will be transferred to the parent
1577/// encoder when the pass is ended, and then raised as a validation error when
1578/// `finish()` is called for the parent).
1579///
1580/// Although in many cases the functionality of `pass_base!` could be achieved
1581/// by combining a helper method on the passes with the `pass_try!` macro,
1582/// taking the mutable reference to the base pass in a macro avoids borrowing
1583/// conflicts when a reference to some other member of the pass struct is
1584/// needed simultaneously with the base pass reference.
1585macro_rules! pass_base {
1586    ($pass:expr, $scope:expr $(,)?) => {
1587        match (&$pass.parent, &$pass.base.error) {
1588            // Pass is ended
1589            (&None, _) => return Err(EncoderStateError::Ended).map_pass_err($scope),
1590            // Pass is invalid
1591            (&Some(_), &Some(_)) => return Ok(()),
1592            // Pass is open and valid
1593            (&Some(_), &None) => &mut $pass.base,
1594        }
1595    };
1596}
1597pub(crate) use pass_base;
1598
1599/// Handles the error case in an expression of type `Result<T, E>`.
1600///
1601/// This macro operates like the `?` operator (or, in early Rust versions, the
1602/// `try!` macro, hence the name `pass_try`). **When there is an error, the
1603/// macro returns from the invoking function.** However, `Ok(())`, and not the
1604/// error itself, is returned. The error is stored in the pass and will later be
1605/// transferred to the parent encoder when the pass ends, and then raised as a
1606/// validation error when `finish()` is called for the parent.
1607///
1608/// `pass_try!` also calls [`MapPassErr::map_pass_err`] to annotate the error
1609/// with the command being encoded at the time it occurred.
1610macro_rules! pass_try {
1611    ($base:expr, $scope:expr, $res:expr $(,)?) => {
1612        match $res.map_pass_err($scope) {
1613            Ok(val) => val,
1614            Err(err) => {
1615                $base.error.get_or_insert(err);
1616                return Ok(());
1617            }
1618        }
1619    };
1620}
1621pub(crate) use pass_try;
1622
1623/// Errors related to the state of a command or pass encoder.
1624///
1625/// The exact behavior of these errors may change based on the resolution of
1626/// <https://github.com/gpuweb/gpuweb/issues/5207>.
1627#[derive(Clone, Debug, Error)]
1628#[non_exhaustive]
1629pub enum EncoderStateError {
1630    /// Used internally by wgpu functions to indicate the encoder already
1631    /// contained an error. This variant should usually not be seen by users of
1632    /// the API, since an effort should be made to provide the caller with a
1633    /// more specific reason for the encoder being invalid.
1634    #[error("Encoder is invalid")]
1635    Invalid,
1636
1637    /// Returned immediately when an attempt is made to encode a command using
1638    /// an encoder that has already finished.
1639    #[error("Encoding must not have ended")]
1640    Ended,
1641
1642    /// Returned by a subsequent call to `encoder.finish()`, if there was an
1643    /// attempt to open a second pass on the encoder while it was locked for
1644    /// a first pass (i.e. the first pass was still open).
1645    ///
1646    /// Note: only command encoders can be locked (not pass encoders).
1647    #[error("Encoder is locked by a previously created render/compute pass. Before recording any new commands, the pass must be ended.")]
1648    Locked,
1649
1650    /// Returned when attempting to end a pass if the parent encoder is not
1651    /// locked. This can only happen if pass begin/end calls are mismatched.
1652    #[error(
1653        "Encoder is not currently locked. A pass can only be ended while the encoder is locked."
1654    )]
1655    Unlocked,
1656
1657    /// The command buffer has already been submitted.
1658    ///
1659    /// Although command encoders and command buffers are distinct WebGPU
1660    /// objects, we use `CommandEncoderStatus` for both.
1661    #[error("This command buffer has already been submitted.")]
1662    Submitted,
1663}
1664
1665impl WebGpuError for EncoderStateError {
1666    fn webgpu_error_type(&self) -> ErrorType {
1667        match self {
1668            EncoderStateError::Invalid
1669            | EncoderStateError::Ended
1670            | EncoderStateError::Locked
1671            | EncoderStateError::Unlocked
1672            | EncoderStateError::Submitted => ErrorType::Validation,
1673        }
1674    }
1675}
1676
1677#[derive(Clone, Debug, Error)]
1678#[non_exhaustive]
1679pub enum CommandEncoderError {
1680    #[error(transparent)]
1681    State(#[from] EncoderStateError),
1682    #[error(transparent)]
1683    Device(#[from] DeviceError),
1684    #[error(transparent)]
1685    InvalidResource(#[from] InvalidResourceError),
1686    #[error(transparent)]
1687    DestroyedResource(#[from] DestroyedResourceError),
1688    #[error(transparent)]
1689    ResourceUsage(#[from] ResourceUsageCompatibilityError),
1690    #[error(transparent)]
1691    DebugGroupError(#[from] DebugGroupError),
1692    #[error(transparent)]
1693    MissingFeatures(#[from] MissingFeatures),
1694    #[error(transparent)]
1695    Transfer(#[from] TransferError),
1696    #[error(transparent)]
1697    Clear(#[from] ClearError),
1698    #[error(transparent)]
1699    Query(#[from] QueryError),
1700    #[error(transparent)]
1701    BuildAccelerationStructure(#[from] BuildAccelerationStructureError),
1702    #[error(transparent)]
1703    TransitionResources(#[from] TransitionResourcesError),
1704    #[error(transparent)]
1705    ComputePass(#[from] ComputePassError),
1706    #[error(transparent)]
1707    RenderPass(#[from] RenderPassError),
1708}
1709
1710impl From<InvalidOrDestroyedResourceError> for CommandEncoderError {
1711    fn from(err: InvalidOrDestroyedResourceError) -> Self {
1712        match err {
1713            InvalidOrDestroyedResourceError::InvalidResource(e) => Self::InvalidResource(e),
1714            InvalidOrDestroyedResourceError::DestroyedResource(e) => Self::DestroyedResource(e),
1715        }
1716    }
1717}
1718
1719impl CommandEncoderError {
1720    fn is_destroyed_error(&self) -> bool {
1721        matches!(
1722            self,
1723            Self::DestroyedResource(_)
1724                | Self::Clear(ClearError::DestroyedResource(_))
1725                | Self::Query(QueryError::DestroyedResource(_))
1726                | Self::ComputePass(ComputePassError {
1727                    inner: ComputePassErrorInner::DestroyedResource(_),
1728                    ..
1729                })
1730                | Self::RenderPass(RenderPassError {
1731                    inner: RenderPassErrorInner::DestroyedResource(_),
1732                    ..
1733                })
1734                | Self::RenderPass(RenderPassError {
1735                    inner: RenderPassErrorInner::RenderCommand(
1736                        RenderCommandError::DestroyedResource(_)
1737                    ),
1738                    ..
1739                })
1740                | Self::RenderPass(RenderPassError {
1741                    inner: RenderPassErrorInner::RenderCommand(RenderCommandError::BindingError(
1742                        BindingError::DestroyedResource(_)
1743                    )),
1744                    ..
1745                })
1746        )
1747    }
1748}
1749
1750impl WebGpuError for CommandEncoderError {
1751    fn webgpu_error_type(&self) -> ErrorType {
1752        match self {
1753            Self::Device(e) => e.webgpu_error_type(),
1754            Self::InvalidResource(e) => e.webgpu_error_type(),
1755            Self::DebugGroupError(e) => e.webgpu_error_type(),
1756            Self::MissingFeatures(e) => e.webgpu_error_type(),
1757            Self::State(e) => e.webgpu_error_type(),
1758            Self::DestroyedResource(e) => e.webgpu_error_type(),
1759            Self::Transfer(e) => e.webgpu_error_type(),
1760            Self::Clear(e) => e.webgpu_error_type(),
1761            Self::Query(e) => e.webgpu_error_type(),
1762            Self::BuildAccelerationStructure(e) => e.webgpu_error_type(),
1763            Self::TransitionResources(e) => e.webgpu_error_type(),
1764            Self::ResourceUsage(e) => e.webgpu_error_type(),
1765            Self::ComputePass(e) => e.webgpu_error_type(),
1766            Self::RenderPass(e) => e.webgpu_error_type(),
1767        }
1768    }
1769}
1770
1771#[derive(Clone, Debug, Error)]
1772#[non_exhaustive]
1773pub enum DebugGroupError {
1774    #[error("Cannot pop debug group, because number of pushed debug groups is zero")]
1775    InvalidPop,
1776    #[error("A debug group was not popped before the encoder was finished")]
1777    MissingPop,
1778}
1779
1780impl WebGpuError for DebugGroupError {
1781    fn webgpu_error_type(&self) -> ErrorType {
1782        match self {
1783            Self::InvalidPop | Self::MissingPop => ErrorType::Validation,
1784        }
1785    }
1786}
1787
1788#[derive(Clone, Debug, Error)]
1789#[non_exhaustive]
1790pub enum TimestampWritesError {
1791    #[error(
1792        "begin and end indices of pass timestamp writes are both set to {idx}, which is not allowed"
1793    )]
1794    IndicesEqual { idx: u32 },
1795    #[error("no begin or end indices were specified for pass timestamp writes, expected at least one to be set")]
1796    IndicesMissing,
1797}
1798
1799impl WebGpuError for TimestampWritesError {
1800    fn webgpu_error_type(&self) -> ErrorType {
1801        match self {
1802            Self::IndicesEqual { .. } | Self::IndicesMissing => ErrorType::Validation,
1803        }
1804    }
1805}
1806
1807impl Global {
1808    fn resolve_buffer_id(
1809        &self,
1810        buffer_id: Id<id::markers::Buffer>,
1811    ) -> Result<Arc<crate::resource::Buffer>, InvalidResourceError> {
1812        self.hub.buffers.get(buffer_id).get()
1813    }
1814
1815    fn resolve_texture_id(
1816        &self,
1817        texture_id: Id<id::markers::Texture>,
1818    ) -> Arc<crate::resource::Texture> {
1819        self.hub.textures.get(texture_id)
1820    }
1821
1822    fn resolve_query_set(
1823        &self,
1824        query_set_id: Id<id::markers::QuerySet>,
1825    ) -> Result<Arc<QuerySet>, InvalidResourceError> {
1826        self.hub.query_sets.get(query_set_id).get()
1827    }
1828
1829    /// Finishes a command encoder, creating a command buffer and returning errors that were
1830    /// deferred until now.
1831    ///
1832    /// The returned `String` is the label of the command encoder, supplied so that `wgpu` can
1833    /// include the label when printing deferred errors without having its own copy of the label.
1834    /// This is a kludge and should be replaced if we think of a better solution to propagating
1835    /// labels.
1836    pub fn command_encoder_finish(
1837        &self,
1838        encoder_id: id::CommandEncoderId,
1839        desc: &wgt::CommandBufferDescriptor<Label>,
1840        id_in: Option<id::CommandBufferId>,
1841    ) -> (id::CommandBufferId, Option<(String, CommandEncoderError)>) {
1842        profiling::scope!("CommandEncoder::finish");
1843
1844        let hub = &self.hub;
1845        let cmd_enc = hub.command_encoders.get(encoder_id);
1846
1847        let (cmd_buf, opt_error) = cmd_enc.finish(desc);
1848        let cmd_buf_id = hub.command_buffers.prepare(id_in).assign(cmd_buf);
1849
1850        (
1851            cmd_buf_id,
1852            opt_error.map(|error| (cmd_enc.label.clone(), error)),
1853        )
1854    }
1855
1856    pub fn command_encoder_push_debug_group(
1857        &self,
1858        encoder_id: id::CommandEncoderId,
1859        label: &str,
1860    ) -> Result<(), EncoderStateError> {
1861        profiling::scope!("CommandEncoder::push_debug_group");
1862        api_log!("CommandEncoder::push_debug_group {label}");
1863
1864        let hub = &self.hub;
1865
1866        let cmd_enc = hub.command_encoders.get(encoder_id);
1867        let mut cmd_buf_data = cmd_enc.data.lock();
1868
1869        cmd_buf_data.push_with(|| -> Result<_, CommandEncoderError> {
1870            Ok(ArcCommand::PushDebugGroup(label.to_owned()))
1871        })
1872    }
1873
1874    pub fn command_encoder_insert_debug_marker(
1875        &self,
1876        encoder_id: id::CommandEncoderId,
1877        label: &str,
1878    ) -> Result<(), EncoderStateError> {
1879        profiling::scope!("CommandEncoder::insert_debug_marker");
1880        api_log!("CommandEncoder::insert_debug_marker {label}");
1881
1882        let hub = &self.hub;
1883
1884        let cmd_enc = hub.command_encoders.get(encoder_id);
1885        let mut cmd_buf_data = cmd_enc.data.lock();
1886
1887        cmd_buf_data.push_with(|| -> Result<_, CommandEncoderError> {
1888            Ok(ArcCommand::InsertDebugMarker(label.to_owned()))
1889        })
1890    }
1891
1892    pub fn command_encoder_pop_debug_group(
1893        &self,
1894        encoder_id: id::CommandEncoderId,
1895    ) -> Result<(), EncoderStateError> {
1896        profiling::scope!("CommandEncoder::pop_debug_marker");
1897        api_log!("CommandEncoder::pop_debug_group");
1898
1899        let hub = &self.hub;
1900
1901        let cmd_enc = hub.command_encoders.get(encoder_id);
1902        let mut cmd_buf_data = cmd_enc.data.lock();
1903
1904        cmd_buf_data
1905            .push_with(|| -> Result<_, CommandEncoderError> { Ok(ArcCommand::PopDebugGroup) })
1906    }
1907}
1908
1909pub(crate) fn push_debug_group(
1910    state: &mut EncodingState,
1911    label: &str,
1912) -> Result<(), CommandEncoderError> {
1913    *state.debug_scope_depth += 1;
1914
1915    if !state
1916        .device
1917        .instance_flags
1918        .contains(wgt::InstanceFlags::DISCARD_HAL_LABELS)
1919    {
1920        unsafe { state.raw_encoder.begin_debug_marker(label) };
1921    }
1922
1923    Ok(())
1924}
1925
1926pub(crate) fn insert_debug_marker(
1927    state: &mut EncodingState,
1928    label: &str,
1929) -> Result<(), CommandEncoderError> {
1930    if !state
1931        .device
1932        .instance_flags
1933        .contains(wgt::InstanceFlags::DISCARD_HAL_LABELS)
1934    {
1935        unsafe { state.raw_encoder.insert_debug_marker(label) };
1936    }
1937
1938    Ok(())
1939}
1940
1941pub(crate) fn pop_debug_group(state: &mut EncodingState) -> Result<(), CommandEncoderError> {
1942    if *state.debug_scope_depth == 0 {
1943        return Err(DebugGroupError::InvalidPop.into());
1944    }
1945    *state.debug_scope_depth -= 1;
1946
1947    if !state
1948        .device
1949        .instance_flags
1950        .contains(wgt::InstanceFlags::DISCARD_HAL_LABELS)
1951    {
1952        unsafe { state.raw_encoder.end_debug_marker() };
1953    }
1954
1955    Ok(())
1956}
1957
1958fn immediates_clear<PushFn>(offset: u32, size_bytes: u32, mut push_fn: PushFn)
1959where
1960    PushFn: FnMut(u32, &[u32]),
1961{
1962    let mut count_words = 0_u32;
1963    let size_words = size_bytes / wgt::IMMEDIATE_DATA_ALIGNMENT;
1964    while count_words < size_words {
1965        let count_bytes = count_words * wgt::IMMEDIATE_DATA_ALIGNMENT;
1966        let size_to_write_words =
1967            (size_words - count_words).min(IMMEDIATES_CLEAR_ARRAY.len() as u32);
1968
1969        push_fn(
1970            offset + count_bytes,
1971            &IMMEDIATES_CLEAR_ARRAY[0..size_to_write_words as usize],
1972        );
1973
1974        count_words += size_to_write_words;
1975    }
1976}
1977
1978#[derive(Debug, Copy, Clone)]
1979struct StateChange<T> {
1980    last_state: Option<T>,
1981}
1982
1983impl<T: Copy + PartialEq> StateChange<T> {
1984    fn new() -> Self {
1985        Self { last_state: None }
1986    }
1987    fn set_and_check_redundant(&mut self, new_state: T) -> bool {
1988        let already_set = self.last_state == Some(new_state);
1989        self.last_state = Some(new_state);
1990        already_set
1991    }
1992    fn reset(&mut self) {
1993        self.last_state = None;
1994    }
1995}
1996
1997impl<T: Copy + PartialEq> Default for StateChange<T> {
1998    fn default() -> Self {
1999        Self::new()
2000    }
2001}
2002
2003#[derive(Debug)]
2004struct BindGroupStateChange {
2005    last_states: [StateChange<Option<id::BindGroupId>>; hal::MAX_BIND_GROUPS],
2006}
2007
2008impl BindGroupStateChange {
2009    fn new() -> Self {
2010        Self {
2011            last_states: [StateChange::new(); hal::MAX_BIND_GROUPS],
2012        }
2013    }
2014
2015    fn set_and_check_redundant(
2016        &mut self,
2017        bind_group_id: Option<id::BindGroupId>,
2018        index: u32,
2019        dynamic_offsets: &mut Vec<u32>,
2020        offsets: &[wgt::DynamicOffset],
2021    ) -> bool {
2022        // For now never deduplicate bind groups with dynamic offsets.
2023        if offsets.is_empty() {
2024            // If this get returns None, that means we're well over the limit,
2025            // so let the call through to get a proper error
2026            if let Some(current_bind_group) = self.last_states.get_mut(index as usize) {
2027                // Bail out if we're binding the same bind group.
2028                if current_bind_group.set_and_check_redundant(bind_group_id) {
2029                    return true;
2030                }
2031            }
2032        } else {
2033            // We intentionally remove the memory of this bind group if we have dynamic offsets,
2034            // such that if you try to bind this bind group later with _no_ dynamic offsets it
2035            // tries to bind it again and gives a proper validation error.
2036            if let Some(current_bind_group) = self.last_states.get_mut(index as usize) {
2037                current_bind_group.reset();
2038            }
2039            dynamic_offsets.extend_from_slice(offsets);
2040        }
2041        false
2042    }
2043    fn reset(&mut self) {
2044        self.last_states = [StateChange::new(); hal::MAX_BIND_GROUPS];
2045    }
2046}
2047
2048impl Default for BindGroupStateChange {
2049    fn default() -> Self {
2050        Self::new()
2051    }
2052}
2053
2054/// Helper to attach [`PassErrorScope`] to errors.
2055trait MapPassErr<T> {
2056    fn map_pass_err(self, scope: PassErrorScope) -> T;
2057}
2058
2059impl<T, E, F> MapPassErr<Result<T, F>> for Result<T, E>
2060where
2061    E: MapPassErr<F>,
2062{
2063    fn map_pass_err(self, scope: PassErrorScope) -> Result<T, F> {
2064        self.map_err(|err| err.map_pass_err(scope))
2065    }
2066}
2067
2068impl MapPassErr<PassStateError> for EncoderStateError {
2069    fn map_pass_err(self, scope: PassErrorScope) -> PassStateError {
2070        PassStateError { scope, inner: self }
2071    }
2072}
2073
2074#[derive(Clone, Copy, Debug)]
2075pub enum DrawKind {
2076    Draw,
2077    DrawIndirect,
2078    MultiDrawIndirect,
2079    MultiDrawIndirectCount,
2080}
2081
2082/// The type of draw command(indexed or not, or mesh shader)
2083#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
2084#[derive(Clone, Copy, Debug, PartialEq, Eq)]
2085pub enum DrawCommandFamily {
2086    Draw,
2087    DrawIndexed,
2088    DrawMeshTasks,
2089}
2090
2091/// A command that can be recorded in a pass or bundle.
2092///
2093/// This is used to provide context for errors during command recording.
2094/// [`MapPassErr`] is used as a helper to attach a `PassErrorScope` to
2095/// an error.
2096///
2097/// The [`PassErrorScope::Bundle`] and [`PassErrorScope::Pass`] variants
2098/// are used when the error occurs during the opening or closing of the
2099/// pass or bundle.
2100#[derive(Clone, Copy, Debug, Error)]
2101pub enum PassErrorScope {
2102    // TODO: Extract out the 2 error variants below so that we can always
2103    // include the ResourceErrorIdent of the pass around all inner errors
2104    #[error("In a bundle parameter")]
2105    Bundle,
2106    #[error("In a pass parameter")]
2107    Pass,
2108    #[error("In a set_bind_group command")]
2109    SetBindGroup,
2110    #[error("In a set_pipeline command")]
2111    SetPipelineRender,
2112    #[error("In a set_pipeline command")]
2113    SetPipelineCompute,
2114    #[error("In a set_immediates command")]
2115    SetImmediate,
2116    #[error("In a set_vertex_buffer command")]
2117    SetVertexBuffer,
2118    #[error("In a set_index_buffer command")]
2119    SetIndexBuffer,
2120    #[error("In a set_blend_constant command")]
2121    SetBlendConstant,
2122    #[error("In a set_stencil_reference command")]
2123    SetStencilReference,
2124    #[error("In a set_viewport command")]
2125    SetViewport,
2126    #[error("In a set_scissor_rect command")]
2127    SetScissorRect,
2128    #[error("In a draw command, kind: {kind:?}")]
2129    Draw {
2130        kind: DrawKind,
2131        family: DrawCommandFamily,
2132    },
2133    #[error("In a write_timestamp command")]
2134    WriteTimestamp,
2135    #[error("In a begin_occlusion_query command")]
2136    BeginOcclusionQuery,
2137    #[error("In a end_occlusion_query command")]
2138    EndOcclusionQuery,
2139    #[error("In a begin_pipeline_statistics_query command")]
2140    BeginPipelineStatisticsQuery,
2141    #[error("In a end_pipeline_statistics_query command")]
2142    EndPipelineStatisticsQuery,
2143    #[error("In a transition_resources command")]
2144    TransitionResources,
2145    #[error("In a execute_bundle command")]
2146    ExecuteBundle,
2147    #[error("In a dispatch command, indirect:{indirect}")]
2148    Dispatch { indirect: bool },
2149    #[error("In a push_debug_group command")]
2150    PushDebugGroup,
2151    #[error("In a pop_debug_group command")]
2152    PopDebugGroup,
2153    #[error("In a insert_debug_marker command")]
2154    InsertDebugMarker,
2155}
2156
2157/// Variant of `EncoderStateError` that includes the pass scope.
2158#[derive(Clone, Debug, Error)]
2159#[error("{scope}")]
2160pub struct PassStateError {
2161    pub scope: PassErrorScope,
2162    #[source]
2163    pub(super) inner: EncoderStateError,
2164}
2165
2166impl WebGpuError for PassStateError {
2167    fn webgpu_error_type(&self) -> ErrorType {
2168        let Self { scope: _, inner } = self;
2169        inner.webgpu_error_type()
2170    }
2171}