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}