Skip to main content

wgpu/api/
ray_tracing_pipeline.rs

1use crate::*;
2
3/// Handle to a ray tracing pipeline.
4///
5/// A `RayTracingPipeline` object represents a ray tracing pipeline and its stages.
6/// It can be created with [`Device::create_ray_tracing_pipeline`].
7#[derive(Debug, Clone)]
8pub struct RayTracingPipeline {
9    pub(crate) inner: dispatch::DispatchRayTracingPipeline,
10}
11#[cfg(send_sync)]
12static_assertions::assert_impl_all!(RayTracingPipeline: Send, Sync);
13
14crate::cmp::impl_eq_ord_hash_proxy!(RayTracingPipeline => .inner);
15
16impl RayTracingPipeline {
17    /// Get an object representing the bind group layout at a given index.
18    ///
19    /// If this pipeline was created with a [default layout][RayTracingPipelineDescriptor::layout], then
20    /// bind groups created with the returned `BindGroupLayout` can only be used with this pipeline.
21    ///
22    /// This method will raise a validation error if there is no bind group layout at `index`.
23    pub fn get_bind_group_layout(&self, index: u32) -> BindGroupLayout {
24        let layout = self.inner.get_bind_group_layout(index);
25        BindGroupLayout { inner: layout }
26    }
27
28    #[cfg(custom)]
29    /// Returns custom implementation of RayTracingPipeline (if custom backend and is internally T)
30    pub fn as_custom<T: custom::RayTracingPipelineInterface>(&self) -> Option<&T> {
31        self.inner.as_custom()
32    }
33}
34
35/// Describes a stage in a ray tracing pipeline
36///
37/// For use in [`RayTracingPipelineDescriptor`]
38#[derive(Clone, Debug)]
39pub struct RayTracingStage<'a> {
40    /// The compiled shader module for this stage.
41    pub module: &'a ShaderModule,
42    /// The name of the entry point in the compiled shader to use.
43    ///
44    /// If [`Some`], there must be a shader entry point with this name in `module` of the stage required.
45    /// Otherwise, expect exactly one entry point in `module` of the stage required, which will be
46    /// selected.
47    // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
48    // NOTE: keep phrasing in sync. with `VertexState::entry_point`
49    // NOTE: keep phrasing in sync. with `FragmentState::entry_point`
50    pub entry_point: Option<&'a str>,
51    /// Advanced options for when this pipeline is compiled
52    ///
53    /// This implements `Default`, and for most users can be set to `Default::default()`
54    pub compilation_options: PipelineCompilationOptions<'a>,
55}
56
57/// Describes a group of stages to be called for an intersection in a ray tracing pipeline
58///
59/// For use in [`RayTracingPipelineDescriptor`]
60#[derive(Clone, Debug)]
61pub enum RayTracingIntersectionDescriptor<'a> {
62    /// This group of shaders may only be used when
63    /// a BLAS with triangle geometry is intersected.
64    Triangle {
65        /// Stage to call if, after the entire intersection process is complete, a triangle within an instance bound to this
66        /// descriptor is the closest hit.
67        closest_hit: RayTracingStage<'a>,
68        /// Optional stage to call when a triangle within an instance bound to this descriptor is hit at any point during the
69        /// intersection process.
70        any_hit: Option<RayTracingStage<'a>>,
71    },
72}
73
74/// Describes a ray tracing pipeline.
75///
76/// For use with [`Device::create_ray_tracing_pipeline`].
77#[derive(Clone, Debug)]
78pub struct RayTracingPipelineDescriptor<'a> {
79    /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
80    pub label: Label<'a>,
81    /// The layout of bind groups for this pipeline.
82    ///
83    /// If this is set, then [`Device::create_ray_tracing_pipeline`] will raise a validation error if
84    /// the layout doesn't match what the shader module(s) expect.
85    ///
86    /// Using the same [`PipelineLayout`] for many [`RayTracingPipeline`] or [`RenderPipeline`] or [`ComputePipeline`]
87    /// pipelines guarantees that you don't have to rebind any resources when switching between
88    /// those pipelines.
89    ///
90    /// ## Default pipeline layout
91    ///
92    /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
93    /// The default layout is deduced from the shader modules.
94    ///
95    /// You can use [`RayTracingPipeline::get_bind_group_layout`] to create bind groups for use with the
96    /// default layout. However, these bind groups cannot be used with any other pipelines. This is
97    /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
98    ///
99    /// Keep phrasing in sync. with [`RenderPipelineDescriptor`] and [`ComputePipelineDescriptor`].
100    ///
101    /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
102    pub layout: Option<&'a PipelineLayout>,
103    /// The ray generation stage. The shader stage invoked by command encoder trace rays.
104    pub ray_generation: RayTracingStage<'a>,
105    /// The miss stage. Called if a ray does not hit any object.
106    pub miss: RayTracingStage<'a>,
107    /// The list of intersection descriptors
108    pub intersections: &'a [RayTracingIntersectionDescriptor<'a>],
109    /// The maximum number of nested `traceRay` calls. The ray generation stage is at depth 0,
110    /// so it can call `traceRay` only if this is at least 1. Calling `traceRay` at a depth
111    /// equal to or greater than this value is undefined behavior.
112    pub max_recursion_depth: u32,
113    /// The pipeline cache to use when creating this pipeline.
114    pub cache: Option<&'a PipelineCache>,
115}
116#[cfg(send_sync)]
117static_assertions::assert_impl_all!(RayTracingPipelineDescriptor<'_>: Send, Sync);
118
119#[cfg(wgpu_core)]
120impl RayTracingPipeline {
121    /// Create a new ray tracing pipeline of wgpu from a wgpu-core ray tracing pipeline.
122    ///
123    /// # Arguments
124    ///
125    /// - `core_ray_tracing_pipeline` - wgpu-core ray tracing pipeline.
126    pub fn from_core(
127        core_ray_tracing_pipeline: alloc::sync::Arc<wgc::ray_tracing_pipeline::RayTracingPipeline>,
128    ) -> Self {
129        Self {
130            inner: crate::backend::wgpu_core::CoreRayTracingPipeline::from_core(
131                core_ray_tracing_pipeline,
132            )
133            .into(),
134        }
135    }
136
137    /// Returns the underlying wgpu-core ray tracing pipeline if this `RayTracingPipeline` is on the wgpu-core backend, otherwise `None`.
138    pub fn as_core(
139        &self,
140    ) -> Option<alloc::sync::Arc<wgc::ray_tracing_pipeline::RayTracingPipeline>> {
141        self.inner.as_core_opt().map(|rtp| rtp.as_core())
142    }
143}