Skip to main content

wgpu_core/command/
ray_tracing_pass.rs

1use core::{convert::Infallible, fmt};
2
3use alloc::{borrow::Cow, boxed::Box, sync::Arc, vec::Vec};
4
5use thiserror::Error;
6use wgt::{
7    error::{ErrorType, WebGpuError},
8    BufferAddress, DynamicOffset,
9};
10
11use crate::{
12    api_log,
13    binding_model::{BindError, BindGroup, ImmediateUploadError, LateMinBufferBindingSizeMismatch},
14    command::{
15        bind::{Binder, BinderError},
16        memory_init::{fixup_discarded_surfaces, SurfacesInDiscardState},
17        pass::{self, flush_bindings_helper, ImmediateState},
18        pass_base, pass_try,
19        ray_tracing_pass_commands::ArcRayTracingCommand,
20        ArcCommand, BasePass, BindGroupStateChange, CommandEncoder, CommandEncoderError,
21        DebugGroupError, EncoderStateError, EncodingState, InnerCommandEncoder, MapPassErr,
22        PassErrorScope, PassStateError, StateChange,
23    },
24    device::{Device, DeviceError, MissingDownlevelFlags, MissingFeatures},
25    hal_label, id, impl_resource_type,
26    ray_tracing::AsAction,
27    ray_tracing_pipeline::RayTracingPipeline,
28    resource::{
29        DestroyedResourceError, InvalidOrDestroyedResourceError, InvalidResourceError, Labeled,
30        MissingBufferUsageError, ParentDevice,
31    },
32    track::{ResourceUsageCompatibilityError, Tracker},
33    Label,
34};
35
36pub type RayTracingBasePass = BasePass<ArcRayTracingCommand, RayTracingPassError>;
37
38/// Very similar to [`super::compute::ComputePass`]
39pub struct RayTracingPass {
40    /// All pass data & records is stored here.
41    base: RayTracingBasePass,
42
43    /// Parent command encoder that this pass records commands into.
44    ///
45    /// Implications are the same as [`super::compute::ComputePass::parent`]
46    parent: Option<Arc<CommandEncoder>>,
47
48    device: Arc<Device>,
49
50    current_bind_groups: BindGroupStateChange,
51    current_pipeline: StateChange<Arc<RayTracingPipeline>>,
52}
53
54impl_resource_type!(RayTracingPass);
55
56impl crate::storage::StorageItem for RayTracingPass {
57    type Marker = id::markers::RayTracingPassEncoder;
58}
59
60impl fmt::Debug for RayTracingPass {
61    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62        match self.parent {
63            Some(ref cmd_enc) => {
64                write!(f, "RayTracingPass {{ parent: {} }}", cmd_enc.error_ident())
65            }
66            None => write!(f, "RayTracingPass {{ parent: None }}"),
67        }
68    }
69}
70
71impl RayTracingPass {
72    /// If the parent command encoder is invalid, the returned pass will be invalid.
73    fn new(
74        parent: Arc<CommandEncoder>,
75        desc: RayTracingPassDescriptor,
76    ) -> Result<Self, MissingFeatures> {
77        parent
78            .device
79            .require_features(wgt::Features::EXPERIMENTAL_RAY_TRACING_PIPELINES)?;
80
81        let RayTracingPassDescriptor { label } = desc;
82
83        Ok(Self {
84            base: BasePass::new(&label),
85            device: parent.device.clone(),
86            parent: Some(parent),
87
88            current_bind_groups: BindGroupStateChange::new(),
89            current_pipeline: StateChange::new(),
90        })
91    }
92
93    fn new_invalid(parent: Arc<CommandEncoder>, label: &Label, err: RayTracingPassError) -> Self {
94        Self {
95            base: BasePass::new_invalid(label, err),
96            device: parent.device.clone(),
97            parent: Some(parent),
98            current_bind_groups: BindGroupStateChange::new(),
99            current_pipeline: StateChange::new(),
100        }
101    }
102
103    #[inline]
104    pub fn label(&self) -> Option<&str> {
105        self.base.label.as_deref()
106    }
107
108    pub fn set_bind_group(
109        &mut self,
110        index: u32,
111        bind_group: Option<Arc<BindGroup>>,
112        offsets: &[DynamicOffset],
113    ) {
114        if let Err(err) = self.set_bind_group_inner(index, bind_group, offsets) {
115            self.device
116                .handle_error(err, self.label(), "RayTracingPass::set_bind_group");
117        }
118    }
119
120    pub fn set_bind_group_inner(
121        &mut self,
122        index: u32,
123        bind_group: Option<Arc<BindGroup>>,
124        offsets: &[DynamicOffset],
125    ) -> Result<(), PassStateError> {
126        let scope = PassErrorScope::SetBindGroup;
127
128        // This statement will return an error if the pass is ended. It's
129        // important the error check comes before the early-out for
130        // `set_and_check_redundant`.
131        let base = pass_base!(self, scope);
132
133        if self.current_bind_groups.set_and_check_redundant(
134            &bind_group,
135            index,
136            &mut base.dynamic_offsets,
137            offsets,
138        ) {
139            return Ok(());
140        }
141
142        let bind_group = if let Some(bind_group) = bind_group {
143            pass_try!(base, scope, bind_group.check_is_valid());
144            Some(bind_group)
145        } else {
146            None
147        };
148
149        base.commands.push(ArcRayTracingCommand::SetBindGroup {
150            index,
151            num_dynamic_offsets: offsets.len(),
152            bind_group,
153        });
154
155        Ok(())
156    }
157
158    pub fn set_immediates_inner(&mut self, offset: u32, data: &[u8]) -> Result<(), PassStateError> {
159        let scope = PassErrorScope::SetImmediate;
160        let base = pass_base!(self, scope);
161
162        pass_try!(
163            base,
164            scope,
165            pass::validate_immediates_alignment(offset, data.len())
166        );
167
168        base.commands.push(ArcRayTracingCommand::SetImmediate {
169            offset,
170            data: data
171                .chunks_exact(size_of::<u32>())
172                .map(|ck| u32::from_le_bytes(ck.try_into().unwrap()))
173                .collect(),
174        });
175
176        Ok(())
177    }
178    pub fn set_immediates(&mut self, offset: u32, data: &[u8]) {
179        if let Err(err) = self.set_immediates_inner(offset, data) {
180            self.device
181                .handle_error(err, self.label(), "RayTracingPass::set_immediates");
182        }
183    }
184}
185
186#[derive(Clone, Debug, Default)]
187pub struct RayTracingPassDescriptor<'a> {
188    pub label: Label<'a>,
189}
190
191#[derive(Clone, Debug, Error)]
192#[non_exhaustive]
193pub enum TraceRayError {
194    #[error("Ray tracing pipeline must be set")]
195    MissingPipeline(pass::MissingPipeline),
196    #[error(transparent)]
197    IncompatibleBindGroup(#[from] Box<BinderError>),
198    #[error("Trace ray size ({current:?}) must be less or equal to {limit:?}")]
199    InvalidDimensionSize { current: [u32; 3], limit: [u32; 3] },
200    #[error("The total count of rays invocations ({current:?}) must be less or equal to {limit}")]
201    TooManyTotal { current: u32, limit: u32 },
202    #[error(transparent)]
203    BindingSizeTooSmall(#[from] LateMinBufferBindingSizeMismatch),
204    #[error("Not all immediate data required by the pipeline has been set via set_immediates (missing byte ranges: {missing})")]
205    MissingImmediateData {
206        missing: naga::valid::ImmediateSlots,
207    },
208}
209
210impl WebGpuError for TraceRayError {
211    fn webgpu_error_type(&self) -> ErrorType {
212        ErrorType::Validation
213    }
214}
215
216/// Error encountered when performing a ray tracing pass.
217#[derive(Clone, Debug, Error)]
218pub enum RayTracingPassErrorInner {
219    #[error(transparent)]
220    Device(#[from] DeviceError),
221    #[error(transparent)]
222    EncoderState(#[from] EncoderStateError),
223    #[error("Parent encoder is invalid")]
224    InvalidParentEncoder,
225    #[error(transparent)]
226    DebugGroupError(#[from] DebugGroupError),
227    #[error(transparent)]
228    BindGroupIndexOutOfRange(#[from] pass::BindGroupIndexOutOfRange),
229    #[error(transparent)]
230    DestroyedResource(#[from] DestroyedResourceError),
231    #[error("Indirect buffer offset {0:?} is not a multiple of 4")]
232    UnalignedIndirectBufferOffset(BufferAddress),
233    #[error("Indirect buffer uses bytes {offset}..{end_offset} which overruns indirect buffer of size {buffer_size}")]
234    IndirectBufferOverrun {
235        offset: u64,
236        end_offset: u64,
237        buffer_size: u64,
238    },
239    #[error(transparent)]
240    ResourceUsageCompatibility(#[from] ResourceUsageCompatibilityError),
241    #[error(transparent)]
242    MissingBufferUsage(#[from] MissingBufferUsageError),
243    #[error(transparent)]
244    TraceRay(#[from] TraceRayError),
245    #[error(transparent)]
246    Bind(#[from] BindError),
247    #[error(transparent)]
248    ImmediateData(#[from] ImmediateUploadError),
249    #[error("Immediate data offset must be aligned to 4 bytes")]
250    ImmediateOffsetAlignment,
251    #[error("Immediate data size must be aligned to 4 bytes")]
252    ImmediateDataizeAlignment,
253    #[error("Ran out of immediate data space. Don't set 4gb of immediates per RayTracingPass.")]
254    ImmediateOutOfMemory,
255    #[error(transparent)]
256    MissingFeatures(#[from] MissingFeatures),
257    #[error(transparent)]
258    MissingDownlevelFlags(#[from] MissingDownlevelFlags),
259    #[error("The ray tracing pass has already been ended and no further commands can be recorded")]
260    PassEnded,
261    #[error(transparent)]
262    InvalidResource(#[from] InvalidResourceError),
263}
264
265impl From<InvalidOrDestroyedResourceError> for RayTracingPassErrorInner {
266    fn from(error: InvalidOrDestroyedResourceError) -> Self {
267        match error {
268            InvalidOrDestroyedResourceError::InvalidResource(e) => Self::InvalidResource(e),
269            InvalidOrDestroyedResourceError::DestroyedResource(e) => Self::DestroyedResource(e),
270        }
271    }
272}
273
274/// Error encountered when performing a ray tracing pass, stored for later reporting
275/// when encoding ends.
276#[derive(Clone, Debug, Error)]
277#[error("{scope}")]
278pub struct RayTracingPassError {
279    pub scope: PassErrorScope,
280    #[source]
281    pub(super) inner: Box<RayTracingPassErrorInner>,
282}
283
284impl From<pass::MissingPipeline> for RayTracingPassErrorInner {
285    fn from(value: pass::MissingPipeline) -> Self {
286        Self::TraceRay(TraceRayError::MissingPipeline(value))
287    }
288}
289
290impl<E> MapPassErr<RayTracingPassError> for E
291where
292    E: Into<RayTracingPassErrorInner>,
293{
294    fn map_pass_err(self, scope: PassErrorScope) -> RayTracingPassError {
295        RayTracingPassError {
296            scope,
297            inner: Box::new(self.into()),
298        }
299    }
300}
301
302impl WebGpuError for RayTracingPassError {
303    fn webgpu_error_type(&self) -> ErrorType {
304        match self.inner.as_ref() {
305            RayTracingPassErrorInner::Device(e) => e.webgpu_error_type(),
306            RayTracingPassErrorInner::EncoderState(e) => e.webgpu_error_type(),
307            RayTracingPassErrorInner::DebugGroupError(e) => e.webgpu_error_type(),
308            RayTracingPassErrorInner::DestroyedResource(e) => e.webgpu_error_type(),
309            RayTracingPassErrorInner::ResourceUsageCompatibility(e) => e.webgpu_error_type(),
310            RayTracingPassErrorInner::MissingBufferUsage(e) => e.webgpu_error_type(),
311            RayTracingPassErrorInner::TraceRay(e) => e.webgpu_error_type(),
312            RayTracingPassErrorInner::Bind(e) => e.webgpu_error_type(),
313            RayTracingPassErrorInner::ImmediateData(e) => e.webgpu_error_type(),
314            RayTracingPassErrorInner::MissingFeatures(e) => e.webgpu_error_type(),
315            RayTracingPassErrorInner::MissingDownlevelFlags(e) => e.webgpu_error_type(),
316            RayTracingPassErrorInner::InvalidResource(e) => e.webgpu_error_type(),
317
318            RayTracingPassErrorInner::InvalidParentEncoder
319            | RayTracingPassErrorInner::BindGroupIndexOutOfRange { .. }
320            | RayTracingPassErrorInner::UnalignedIndirectBufferOffset(_)
321            | RayTracingPassErrorInner::IndirectBufferOverrun { .. }
322            | RayTracingPassErrorInner::ImmediateOffsetAlignment
323            | RayTracingPassErrorInner::ImmediateDataizeAlignment
324            | RayTracingPassErrorInner::ImmediateOutOfMemory
325            | RayTracingPassErrorInner::PassEnded => ErrorType::Validation,
326        }
327    }
328}
329
330struct State<'scope, 'snatch_guard, 'cmd_enc> {
331    pipeline: Option<Arc<RayTracingPipeline>>,
332
333    pass: pass::PassState<'scope, 'snatch_guard, 'cmd_enc>,
334
335    intermediate_trackers: Tracker,
336}
337
338impl<'scope, 'snatch_guard, 'cmd_enc> State<'scope, 'snatch_guard, 'cmd_enc> {
339    fn is_ready(&self) -> Result<(), TraceRayError> {
340        if let Some(pipeline) = self.pipeline.as_ref() {
341            self.pass.binder.check_compatibility(pipeline.as_ref())?;
342            self.pass.binder.check_late_buffer_bindings()?;
343            if !self
344                .pass
345                .immediate_state
346                .immediate_slots_set
347                .contains(pipeline.immediate_slots_required)
348            {
349                return Err(TraceRayError::MissingImmediateData {
350                    missing: pipeline
351                        .immediate_slots_required
352                        .difference(self.pass.immediate_state.immediate_slots_set),
353                });
354            }
355            Ok(())
356        } else {
357            Err(TraceRayError::MissingPipeline(pass::MissingPipeline))
358        }
359    }
360
361    fn flush_immediates(&mut self) {
362        let pipeline = self.pipeline.as_ref().unwrap();
363        let layout = pipeline.layout().unwrap();
364        self.pass
365            .immediate_state
366            .flush_immediates(layout, self.pass.base.raw_encoder);
367    }
368
369    /// Flush binding state in preparation for a trace rays call.
370    ///
371    /// This behaves almost the same as a compute pass' equivalent
372    /// function, but also adds a `AsAction::TraceTlas` as trace ray
373    /// calls need a bit more validation.
374    ///
375    /// This differs from a render pass, which the equivalent method
376    /// on compute pass' state discuss more.
377    fn flush_bindings(&mut self) -> Result<(), RayTracingPassErrorInner> {
378        for bind_group in self.pass.binder.list_active() {
379            unsafe { self.pass.scope.merge_bind_group(&bind_group.used)? };
380        }
381        // For ray tracing passes, usage scopes are associated with each trace
382        // ray (in the same way as compute passes) and not with the pass as a
383        // whole. However, because the cost of creating and dropping
384        // `UsageScope`s is significant (even with the pool), we add and then
385        // remove usage from a single usage scope.
386
387        let intersection_types = self.pipeline.as_ref().unwrap().intersection_types()?;
388
389        for bind_group in self.pass.binder.list_active() {
390            self.intermediate_trackers
391                .set_and_remove_from_usage_scope_sparse(&mut self.pass.scope, &bind_group.used);
392
393            for tlas in bind_group.used.acceleration_structures.into_iter() {
394                self.pass.base.as_actions.push(AsAction::TraceTlas(
395                    tlas.clone(),
396                    intersection_types.clone(),
397                ));
398            }
399        }
400
401        flush_bindings_helper(&mut self.pass)?;
402
403        CommandEncoder::drain_barriers(
404            self.pass.base.raw_encoder,
405            &mut self.intermediate_trackers,
406            self.pass.base.snatch_guard,
407        );
408        Ok(())
409    }
410}
411
412// Ray tracing pass commands
413
414impl RayTracingPass {
415    pub fn set_pipeline(&mut self, pipeline: Arc<RayTracingPipeline>) {
416        if let Err(err) = self.set_pipeline_inner(pipeline) {
417            self.device
418                .handle_error(err, self.label(), "RayTracingPass::set_pipeline");
419        }
420    }
421    pub fn set_pipeline_inner(
422        &mut self,
423        pipeline: Arc<RayTracingPipeline>,
424    ) -> Result<(), PassStateError> {
425        let scope = PassErrorScope::SetPipelineRayTracing;
426
427        let redundant = self.current_pipeline.set_and_check_redundant(&pipeline);
428
429        // This statement will return an error if the pass is ended.
430        // Its important the error check comes before the early-out for `redundant`.
431        let base = pass_base!(self, scope);
432
433        if redundant {
434            return Ok(());
435        }
436
437        pass_try!(base, scope, pipeline.check_valid());
438
439        base.commands
440            .push(ArcRayTracingCommand::SetPipeline(pipeline));
441
442        Ok(())
443    }
444    pub fn end_inner(&mut self) -> Result<(), EncoderStateError> {
445        profiling::scope!(
446            "CommandEncoder::run_ray_tracing_pass {}",
447            self.base.label.as_deref().unwrap_or("")
448        );
449
450        let cmd_enc = self.parent.take().ok_or(EncoderStateError::Ended)?;
451        let mut cmd_buf_data = cmd_enc.data.lock();
452
453        cmd_buf_data.unlock_encoder()?;
454
455        let base = self.base.take();
456
457        if let Err(RayTracingPassError { inner, scope: _ }) = &base {
458            if let RayTracingPassErrorInner::EncoderState(
459                err @ (EncoderStateError::Locked | EncoderStateError::Ended),
460            ) = inner.as_ref()
461            {
462                // Most encoding errors are detected and raised within `finish()`.
463                //
464                // However, we raise a validation error here if the pass was opened
465                // within another pass, or on a finished encoder. The latter is
466                // particularly important, because in that case reporting errors via
467                // `CommandEncoder::finish` is not possible.
468                return Err(err.clone());
469            }
470        }
471
472        cmd_buf_data.push_with(|| -> Result<_, RayTracingPassError> {
473            Ok(ArcCommand::RunRayTracingPass { pass: base? })
474        })
475    }
476
477    pub fn end(&mut self) {
478        if let Err(err) = self.end_inner() {
479            self.device
480                .handle_error(err, self.label(), "RayTracingPass::end");
481        }
482    }
483
484    pub fn push_debug_group_inner(
485        &mut self,
486        label: &str,
487        color: u32,
488    ) -> Result<(), PassStateError> {
489        let base = pass_base!(self, PassErrorScope::PushDebugGroup);
490
491        let bytes = label.as_bytes();
492        base.string_data.extend_from_slice(bytes);
493
494        base.commands.push(ArcRayTracingCommand::PushDebugGroup {
495            color,
496            len: bytes.len(),
497        });
498
499        Ok(())
500    }
501
502    pub fn push_debug_group(&mut self, label: &str, color: u32) {
503        if let Err(err) = self.push_debug_group_inner(label, color) {
504            self.device
505                .handle_error(err, self.label(), "RayTracingPass::push_debug_group");
506        }
507    }
508
509    pub fn pop_debug_group_inner(&mut self) -> Result<(), PassStateError> {
510        let base = pass_base!(self, PassErrorScope::PopDebugGroup);
511
512        base.commands.push(ArcRayTracingCommand::PopDebugGroup);
513
514        Ok(())
515    }
516
517    pub fn pop_debug_group(&mut self) {
518        if let Err(err) = self.pop_debug_group_inner() {
519            self.device
520                .handle_error(err, self.label(), "RayTracingPass::pop_debug_group");
521        }
522    }
523
524    pub fn insert_debug_marker_inner(
525        &mut self,
526        label: &str,
527        color: u32,
528    ) -> Result<(), PassStateError> {
529        let base = pass_base!(self, PassErrorScope::InsertDebugMarker);
530
531        let bytes = label.as_bytes();
532        base.string_data.extend_from_slice(bytes);
533
534        base.commands.push(ArcRayTracingCommand::InsertDebugMarker {
535            color,
536            len: bytes.len(),
537        });
538
539        Ok(())
540    }
541
542    pub fn insert_debug_marker(&mut self, label: &str, color: u32) {
543        if let Err(err) = self.insert_debug_marker_inner(label, color) {
544            self.device
545                .handle_error(err, self.label(), "RayTracingPass::insert_debug_marker");
546        }
547    }
548
549    pub fn trace_rays_inner(
550        &mut self,
551        count_x: u32,
552        count_y: u32,
553        count_z: u32,
554    ) -> Result<(), PassStateError> {
555        let scope = PassErrorScope::TraceRays;
556
557        pass_base!(self, scope)
558            .commands
559            .push(ArcRayTracingCommand::TraceRays([count_x, count_y, count_z]));
560
561        Ok(())
562    }
563
564    pub fn trace_rays(&mut self, count_x: u32, count_y: u32, count_z: u32) {
565        if let Err(err) = self.trace_rays_inner(count_x, count_y, count_z) {
566            self.device
567                .handle_error(err, self.label(), "RayTracingPass::trace_rays");
568        }
569    }
570}
571
572impl CommandEncoder {
573    pub fn begin_ray_tracing_pass_inner(
574        self: &Arc<Self>,
575        desc: &RayTracingPassDescriptor<'_>,
576    ) -> (RayTracingPass, Option<CommandEncoderError>) {
577        use EncoderStateError as SErr;
578
579        let label = desc.label.as_deref().map(Cow::Borrowed);
580
581        let scope = PassErrorScope::Pass;
582
583        let mut cmd_buf_data = self.data.lock();
584
585        match cmd_buf_data.lock_encoder() {
586            Ok(()) => {
587                drop(cmd_buf_data);
588                if let Err(err) = self.device.check_is_valid() {
589                    return (
590                        RayTracingPass::new_invalid(self.clone(), &label, err.map_pass_err(scope)),
591                        None,
592                    );
593                }
594
595                let pass = match RayTracingPass::new(
596                    self.clone(),
597                    RayTracingPassDescriptor {
598                        label: label.clone(),
599                    },
600                ) {
601                    Ok(pass) => pass,
602                    Err(err) => {
603                        return (
604                            RayTracingPass::new_invalid(
605                                self.clone(),
606                                &label,
607                                err.map_pass_err(scope),
608                            ),
609                            None,
610                        );
611                    }
612                };
613
614                (pass, None)
615            }
616            Err(err @ SErr::Locked) => {
617                // Attempting to open a new pass while the encoder is locked
618                // invalidates the encoder, but does not generate a validation
619                // error.
620                cmd_buf_data.invalidate(err.clone());
621                drop(cmd_buf_data);
622                (
623                    RayTracingPass::new_invalid(self.clone(), &label, err.map_pass_err(scope)),
624                    None,
625                )
626            }
627            Err(err @ (SErr::Ended | SErr::Submitted)) => {
628                // Attempting to open a new pass after the encode has ended
629                // generates an immediate validation error.
630                drop(cmd_buf_data);
631                (
632                    RayTracingPass::new_invalid(
633                        self.clone(),
634                        &label,
635                        err.clone().map_pass_err(scope),
636                    ),
637                    Some(err.into()),
638                )
639            }
640            Err(err @ SErr::Invalid) => {
641                // Passes can be opened even on an invalid encoder. Such passes
642                // are even valid, but since there's no visible side-effect of
643                // the pass being valid and there's no point in storing recorded
644                // commands that will ultimately be discarded, we open an
645                // invalid pass to save that work.
646                drop(cmd_buf_data);
647                (
648                    RayTracingPass::new_invalid(self.clone(), &label, err.map_pass_err(scope)),
649                    None,
650                )
651            }
652            Err(SErr::Unlocked) => {
653                unreachable!("lock_encoder cannot fail due to the encoder being unlocked")
654            }
655        }
656    }
657
658    pub fn begin_ray_tracing_pass(
659        self: &Arc<Self>,
660        desc: &RayTracingPassDescriptor<'_>,
661    ) -> RayTracingPass {
662        let (pass, err) = self.begin_ray_tracing_pass_inner(desc);
663        if let Some(err) = err {
664            self.device
665                .handle_error(err, pass.label(), "CommandEncoder::begin_ray_tracing_pass");
666        }
667        pass
668    }
669}
670
671pub(super) fn encode_ray_tracing_pass(
672    parent_state: &mut EncodingState<InnerCommandEncoder>,
673    mut base: BasePass<ArcRayTracingCommand, Infallible>,
674) -> Result<(), RayTracingPassError> {
675    let pass_scope = PassErrorScope::Pass;
676
677    let device = parent_state.device;
678
679    // We automatically keep extending command buffers over time, and because
680    // we want to insert a command buffer _before_ what we're about to record,
681    // we need to make sure to close the previous one.
682    parent_state
683        .raw_encoder
684        .close_if_open()
685        .map_pass_err(pass_scope)?;
686    let raw_encoder = parent_state
687        .raw_encoder
688        .open_pass(base.label.as_deref())
689        .map_pass_err(pass_scope)?;
690
691    let mut debug_scope_depth = 0;
692
693    let mut state = State {
694        pipeline: None,
695
696        pass: pass::PassState {
697            base: EncodingState {
698                device,
699                raw_encoder,
700                tracker: parent_state.tracker,
701                buffer_memory_init_actions: parent_state.buffer_memory_init_actions,
702                texture_memory_actions: parent_state.texture_memory_actions,
703                as_actions: parent_state.as_actions,
704                temp_resources: parent_state.temp_resources,
705                indirect_draw_validation_resources: parent_state.indirect_draw_validation_resources,
706                snatch_guard: parent_state.snatch_guard,
707                debug_scope_depth: &mut debug_scope_depth,
708                query_set_writes: parent_state.query_set_writes,
709                deferred_query_set_resolves: parent_state.deferred_query_set_resolves,
710            },
711            binder: Binder::new(),
712            temp_offsets: Vec::new(),
713            dynamic_offset_count: 0,
714            pending_discard_init_fixups: SurfacesInDiscardState::new(),
715            scope: device.new_usage_scope(),
716            string_offset: 0,
717
718            immediate_state: ImmediateState::default(),
719        },
720
721        intermediate_trackers: Tracker::new(
722            device.ordered_buffer_usages,
723            device.ordered_texture_usages,
724        ),
725    };
726
727    let indices = &device.tracker_indices;
728    state
729        .pass
730        .base
731        .tracker
732        .buffers
733        .set_size(indices.buffers.size());
734    state
735        .pass
736        .base
737        .tracker
738        .textures
739        .set_size(indices.textures.size());
740
741    let hal_desc = hal::RayTracingPassDescriptor {
742        label: hal_label(base.label.as_deref(), device.instance_flags),
743    };
744
745    unsafe {
746        state
747            .pass
748            .base
749            .raw_encoder
750            .begin_ray_tracing_pass(&hal_desc);
751    }
752
753    for command in base.commands.drain(..) {
754        match command {
755            ArcRayTracingCommand::SetBindGroup {
756                index,
757                num_dynamic_offsets,
758                bind_group,
759            } => {
760                let scope = PassErrorScope::SetBindGroup;
761                pass::set_bind_group::<RayTracingPassErrorInner>(
762                    &mut state.pass,
763                    device,
764                    &base.dynamic_offsets,
765                    index,
766                    num_dynamic_offsets,
767                    bind_group,
768                    false,
769                )
770                .map_pass_err(scope)?;
771            }
772            ArcRayTracingCommand::SetPipeline(pipeline) => {
773                let scope = PassErrorScope::SetPipelineRayTracing;
774                set_pipeline(&mut state, device, pipeline).map_pass_err(scope)?;
775            }
776            ArcRayTracingCommand::SetImmediate { offset, data } => {
777                let scope = PassErrorScope::SetImmediate;
778                state
779                    .pass
780                    .immediate_state
781                    .set_immediates::<RayTracingPassErrorInner>(
782                        &state.pass.base.device.limits,
783                        offset,
784                        &data,
785                    )
786                    .map_pass_err(scope)?;
787            }
788            ArcRayTracingCommand::PushDebugGroup { color: _, len } => {
789                pass::push_debug_group(&mut state.pass, &base.string_data, len);
790            }
791            ArcRayTracingCommand::PopDebugGroup => {
792                let scope = PassErrorScope::PopDebugGroup;
793                pass::pop_debug_group::<RayTracingPassErrorInner>(&mut state.pass)
794                    .map_pass_err(scope)?;
795            }
796            ArcRayTracingCommand::InsertDebugMarker { color: _, len } => {
797                pass::insert_debug_marker(&mut state.pass, &base.string_data, len);
798            }
799            ArcRayTracingCommand::TraceRays(groups) => {
800                let scope = PassErrorScope::TraceRays;
801                trace_rays(&mut state, groups, device).map_pass_err(scope)?;
802            }
803        }
804    }
805
806    if *state.pass.base.debug_scope_depth > 0 {
807        Err(
808            RayTracingPassErrorInner::DebugGroupError(DebugGroupError::MissingPop)
809                .map_pass_err(pass_scope),
810        )?;
811    }
812
813    unsafe {
814        state.pass.base.raw_encoder.end_ray_tracing_pass();
815    }
816
817    let State {
818        pass: pass::PassState {
819            pending_discard_init_fixups,
820            ..
821        },
822        intermediate_trackers,
823        ..
824    } = state;
825
826    // Stop the current command encoder.
827    parent_state.raw_encoder.close().map_pass_err(pass_scope)?;
828
829    // Create a new command encoder, which we will insert _before_ the body of the ray tracing pass.
830    //
831    // Use that buffer to insert barriers and clear discarded images.
832    let transit = parent_state
833        .raw_encoder
834        .open_pass(hal_label(
835            Some("(wgpu internal) Pre Pass"),
836            device.instance_flags,
837        ))
838        .map_pass_err(pass_scope)?;
839    // If the ray tracing pass reads any surfaces that were discarded by a previous
840    // render pass in the same command buffer, initialize them.
841    fixup_discarded_surfaces(
842        pending_discard_init_fixups.into_iter(),
843        transit,
844        &mut parent_state.tracker.textures,
845        device,
846        parent_state.snatch_guard,
847    );
848    CommandEncoder::insert_barriers_from_tracker(
849        transit,
850        parent_state.tracker,
851        &intermediate_trackers,
852        parent_state.snatch_guard,
853    );
854    // Close the command encoder, and swap it with the previous.
855    parent_state
856        .raw_encoder
857        .close_and_swap()
858        .map_pass_err(pass_scope)?;
859
860    Ok(())
861}
862
863fn set_pipeline(
864    state: &mut State,
865    device: &Arc<Device>,
866    pipeline: Arc<RayTracingPipeline>,
867) -> Result<(), RayTracingPassErrorInner> {
868    pipeline.same_device(device)?;
869
870    state.pipeline = Some(pipeline.clone());
871
872    let pipeline = state
873        .pass
874        .base
875        .tracker
876        .ray_tracing_pipelines
877        .insert_single(pipeline)
878        .clone();
879
880    unsafe {
881        state
882            .pass
883            .base
884            .raw_encoder
885            .set_ray_tracing_pipeline(pipeline.raw()?);
886    }
887
888    // Rebind resources
889    let pipeline_layout = pipeline.layout()?;
890    pass::change_pipeline_layout::<RayTracingPassErrorInner>(
891        &mut state.pass,
892        pipeline_layout,
893        &pipeline.late_sized_buffer_groups,
894    )
895}
896
897fn trace_rays(
898    state: &mut State,
899    dims: [u32; 3],
900    device: &Device,
901) -> Result<(), RayTracingPassErrorInner> {
902    api_log!("RayTracingPass::trace_rays {dims:?}");
903
904    state.is_ready()?;
905
906    state.flush_bindings()?;
907    state.flush_immediates();
908
909    let limits = &state.pass.base.device.limits;
910
911    // `saturating_mul` is fine here as it is the limit, so a lower limit if it would overflow is just a
912    // slightly greater restriction.
913    let dim_size_limit = [
914        limits
915            .max_compute_workgroup_size_x
916            .saturating_mul(limits.max_compute_workgroups_per_dimension),
917        limits
918            .max_compute_workgroup_size_y
919            .saturating_mul(limits.max_compute_workgroups_per_dimension),
920        limits
921            .max_compute_workgroup_size_z
922            .saturating_mul(limits.max_compute_workgroups_per_dimension),
923    ];
924
925    if dims[0] > dim_size_limit[0] {
926        return Err(RayTracingPassErrorInner::TraceRay(
927            TraceRayError::InvalidDimensionSize {
928                current: dims,
929                limit: dim_size_limit,
930            },
931        ));
932    }
933
934    if dims[1] > dim_size_limit[1] {
935        return Err(RayTracingPassErrorInner::TraceRay(
936            TraceRayError::InvalidDimensionSize {
937                current: dims,
938                limit: dim_size_limit,
939            },
940        ));
941    }
942
943    if dims[2] > dim_size_limit[2] {
944        return Err(RayTracingPassErrorInner::TraceRay(
945            TraceRayError::InvalidDimensionSize {
946                current: dims,
947                limit: dim_size_limit,
948            },
949        ));
950    }
951
952    let tot_rays = dims[0]
953        .checked_mul(dims[1])
954        .and_then(|tmp| tmp.checked_mul(dims[2]));
955
956    if tot_rays.is_none_or(|tot_rays| tot_rays > limits.max_ray_dispatch_count) {
957        return Err(RayTracingPassErrorInner::TraceRay(
958            TraceRayError::TooManyTotal {
959                current: tot_rays.unwrap_or(u32::MAX),
960                limit: limits.max_ray_dispatch_count,
961            },
962        ));
963    }
964
965    let current_pipeline = state.pipeline.as_ref().unwrap();
966    let shader_binding_data = current_pipeline.shader_binding_data()?;
967
968    unsafe {
969        state.pass.base.raw_encoder.trace_rays(
970            dims,
971            hal::PipelineGroupData {
972                buffer: shader_binding_data.raw.as_ref(),
973                offset: 0,
974                stride: device.alignments.ray_tracing_pipeline_group_data_size as _,
975                count: 1,
976            },
977            hal::PipelineGroupData {
978                buffer: shader_binding_data.raw.as_ref(),
979                offset: shader_binding_data.miss_offset,
980                stride: device.alignments.ray_tracing_pipeline_group_data_size as _,
981                count: 1,
982            },
983            hal::PipelineGroupData {
984                buffer: shader_binding_data.raw.as_ref(),
985                offset: shader_binding_data.intersection_offset,
986                stride: device.alignments.ray_tracing_pipeline_group_data_size as _,
987                count: shader_binding_data.num_intersection_groups as _,
988            },
989        );
990    }
991    Ok(())
992}