wgpu/api/render_pipeline.rs
1use core::num::NonZeroU32;
2
3use crate::*;
4
5/// Handle to a rendering (graphics) pipeline.
6///
7/// A `RenderPipeline` object represents a graphics pipeline and its stages, bindings, vertex
8/// buffers and targets. It can be created with [`Device::create_render_pipeline`].
9///
10/// Corresponds to [WebGPU `GPURenderPipeline`](https://gpuweb.github.io/gpuweb/#render-pipeline).
11#[derive(Debug, Clone)]
12pub struct RenderPipeline {
13 pub(crate) inner: dispatch::DispatchRenderPipeline,
14}
15#[cfg(send_sync)]
16static_assertions::assert_impl_all!(RenderPipeline: Send, Sync);
17
18crate::cmp::impl_eq_ord_hash_proxy!(RenderPipeline => .inner);
19
20impl RenderPipeline {
21 /// Get an object representing the bind group layout at a given index.
22 ///
23 /// If this pipeline was created with a [default layout][RenderPipelineDescriptor::layout], then
24 /// bind groups created with the returned `BindGroupLayout` can only be used with this pipeline.
25 ///
26 /// This method will raise a validation error if there is no bind group layout at `index`.
27 pub fn get_bind_group_layout(&self, index: u32) -> BindGroupLayout {
28 let layout = self.inner.get_bind_group_layout(index);
29 BindGroupLayout { inner: layout }
30 }
31
32 #[cfg(custom)]
33 /// Returns custom implementation of RenderPipeline (if custom backend and is internally T)
34 pub fn as_custom<T: custom::RenderPipelineInterface>(&self) -> Option<&T> {
35 self.inner.as_custom()
36 }
37}
38
39/// Specifies an interpretation of the bytes of a vertex buffer as vertex attributes.
40///
41/// Use this in a [`RenderPipelineDescriptor`] to describe the format of the vertex buffers that
42/// are passed to [`RenderPass::set_vertex_buffer()`].
43///
44/// Corresponds to [WebGPU `GPUVertexBufferLayout`](
45/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexbufferlayout).
46///
47/// # Example
48///
49/// The following example defines a `struct` with three fields,
50/// and a [`VertexBufferLayout`] that contains [`VertexAttribute`]s for each field,
51/// using the [`vertex_attr_array!`] macro to compute attribute offsets:
52///
53/// ```
54/// #[repr(C, packed)]
55/// struct Vertex {
56/// foo: [f32; 2],
57/// bar: f32,
58/// baz: [u16; 4],
59/// }
60///
61/// impl Vertex {
62/// /// Layout to use with a buffer whose contents are a `[Vertex]`.
63/// pub const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
64/// array_stride: size_of::<Self>() as wgpu::BufferAddress,
65/// step_mode: wgpu::VertexStepMode::Vertex,
66/// attributes: &wgpu::vertex_attr_array![
67/// 0 => Float32x2,
68/// 1 => Float32,
69/// 2 => Uint16x4,
70/// ],
71/// };
72/// }
73///
74/// # assert_eq!(Vertex::LAYOUT.attributes[2].offset, Vertex::LAYOUT.array_stride - 2 * 4);
75#[derive(Clone, Debug, Hash, Eq, PartialEq)]
76pub struct VertexBufferLayout<'a> {
77 /// The stride, in bytes, between elements of this buffer (between vertices).
78 ///
79 /// This must be a multiple of [`VERTEX_ALIGNMENT`].
80 pub array_stride: BufferAddress,
81 /// How often this vertex buffer is "stepped" forward.
82 pub step_mode: VertexStepMode,
83 /// The list of attributes which comprise a single vertex.
84 pub attributes: &'a [VertexAttribute],
85}
86static_assertions::assert_impl_all!(VertexBufferLayout<'_>: Send, Sync);
87
88/// Describes the vertex processing in a render pipeline.
89///
90/// For use in [`RenderPipelineDescriptor`].
91///
92/// Corresponds to [WebGPU `GPUVertexState`](
93/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexstate).
94#[derive(Clone, Debug)]
95pub struct VertexState<'a> {
96 /// The compiled shader module for this stage.
97 pub module: &'a ShaderModule,
98 /// The name of the entry point in the compiled shader to use.
99 ///
100 /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
101 /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
102 /// selected.
103 // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
104 // NOTE: keep phrasing in sync. with `FragmentState::entry_point`
105 pub entry_point: Option<&'a str>,
106 /// Advanced options for when this pipeline is compiled
107 ///
108 /// This implements `Default`, and for most users can be set to `Default::default()`
109 pub compilation_options: PipelineCompilationOptions<'a>,
110 /// The format of any vertex buffers used with this pipeline via
111 /// [`RenderPass::set_vertex_buffer()`].
112 ///
113 /// The attribute locations and types specified in this layout must match the
114 /// locations and types of the inputs to the `entry_point` function.
115 pub buffers: &'a [VertexBufferLayout<'a>],
116}
117#[cfg(send_sync)]
118static_assertions::assert_impl_all!(VertexState<'_>: Send, Sync);
119
120/// Describes the fragment processing in a render pipeline.
121///
122/// For use in [`RenderPipelineDescriptor`].
123///
124/// Corresponds to [WebGPU `GPUFragmentState`](
125/// https://gpuweb.github.io/gpuweb/#dictdef-gpufragmentstate).
126#[derive(Clone, Debug)]
127pub struct FragmentState<'a> {
128 /// The compiled shader module for this stage.
129 pub module: &'a ShaderModule,
130 /// The name of the entry point in the compiled shader to use.
131 ///
132 /// If [`Some`], there must be a `@fragment` shader entry point with this name in `module`.
133 /// Otherwise, expect exactly one fragment-stage entry point in `module`, which will be
134 /// selected.
135 // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
136 // NOTE: keep phrasing in sync. with `VertexState::entry_point`
137 pub entry_point: Option<&'a str>,
138 /// Advanced options for when this pipeline is compiled
139 ///
140 /// This implements `Default`, and for most users can be set to `Default::default()`
141 pub compilation_options: PipelineCompilationOptions<'a>,
142 /// The color state of the render targets.
143 pub targets: &'a [Option<ColorTargetState>],
144}
145#[cfg(send_sync)]
146static_assertions::assert_impl_all!(FragmentState<'_>: Send, Sync);
147
148/// Describes the task shader stage in a mesh shader pipeline.
149///
150/// For use in [`MeshPipelineDescriptor`]
151#[derive(Clone, Debug)]
152pub struct TaskState<'a> {
153 /// The compiled shader module for this stage.
154 pub module: &'a ShaderModule,
155 /// The name of the entry point in the compiled shader to use.
156 ///
157 /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
158 /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
159 /// selected.
160 pub entry_point: Option<&'a str>,
161 /// Advanced options for when this pipeline is compiled
162 ///
163 /// This implements `Default`, and for most users can be set to `Default::default()`
164 pub compilation_options: PipelineCompilationOptions<'a>,
165}
166#[cfg(send_sync)]
167static_assertions::assert_impl_all!(TaskState<'_>: Send, Sync);
168
169/// Describes the mesh shader stage in a mesh shader pipeline.
170///
171/// For use in [`MeshPipelineDescriptor`]
172#[derive(Clone, Debug)]
173pub struct MeshState<'a> {
174 /// The compiled shader module for this stage.
175 pub module: &'a ShaderModule,
176 /// The name of the entry point in the compiled shader to use.
177 ///
178 /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
179 /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
180 /// selected.
181 pub entry_point: Option<&'a str>,
182 /// Advanced options for when this pipeline is compiled
183 ///
184 /// This implements `Default`, and for most users can be set to `Default::default()`
185 pub compilation_options: PipelineCompilationOptions<'a>,
186}
187#[cfg(send_sync)]
188static_assertions::assert_impl_all!(MeshState<'_>: Send, Sync);
189
190/// Describes a render (graphics) pipeline.
191///
192/// For use with [`Device::create_render_pipeline`].
193///
194/// Corresponds to [WebGPU `GPURenderPipelineDescriptor`](
195/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor).
196#[derive(Clone, Debug)]
197pub struct RenderPipelineDescriptor<'a> {
198 /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
199 pub label: Label<'a>,
200 /// The layout of bind groups for this pipeline.
201 ///
202 /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
203 /// the layout doesn't match what the shader module(s) expect.
204 ///
205 /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
206 /// pipelines guarantees that you don't have to rebind any resources when switching between
207 /// those pipelines.
208 ///
209 /// ## Default pipeline layout
210 ///
211 /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
212 /// The default layout is deduced from the shader modules.
213 ///
214 /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
215 /// default layout. However, these bind groups cannot be used with any other pipelines. This is
216 /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
217 ///
218 /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
219 pub layout: Option<&'a PipelineLayout>,
220 /// The compiled vertex stage, its entry point, and the input buffers layout.
221 pub vertex: VertexState<'a>,
222 /// The properties of the pipeline at the primitive assembly and rasterization level.
223 pub primitive: PrimitiveState,
224 /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
225 pub depth_stencil: Option<DepthStencilState>,
226 /// The multi-sampling properties of the pipeline.
227 pub multisample: MultisampleState,
228 /// The compiled fragment stage, its entry point, and the color targets.
229 pub fragment: Option<FragmentState<'a>>,
230 /// If the pipeline will be used with a multiview render pass, this indicates how many array
231 /// layers the attachments will have.
232 pub multiview: Option<NonZeroU32>,
233 /// The pipeline cache to use when creating this pipeline.
234 pub cache: Option<&'a PipelineCache>,
235}
236#[cfg(send_sync)]
237static_assertions::assert_impl_all!(RenderPipelineDescriptor<'_>: Send, Sync);
238
239/// Describes a mesh shader (graphics) pipeline.
240///
241/// For use with [`Device::create_mesh_pipeline`].
242#[derive(Clone, Debug)]
243pub struct MeshPipelineDescriptor<'a> {
244 /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
245 pub label: Label<'a>,
246 /// The layout of bind groups for this pipeline.
247 ///
248 /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
249 /// the layout doesn't match what the shader module(s) expect.
250 ///
251 /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
252 /// pipelines guarantees that you don't have to rebind any resources when switching between
253 /// those pipelines.
254 ///
255 /// ## Default pipeline layout
256 ///
257 /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
258 /// The default layout is deduced from the shader modules.
259 ///
260 /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
261 /// default layout. However, these bind groups cannot be used with any other pipelines. This is
262 /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
263 ///
264 /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
265 pub layout: Option<&'a PipelineLayout>,
266 /// The compiled task stage, its entry point, and the color targets.
267 pub task: Option<TaskState<'a>>,
268 /// The compiled mesh stage and its entry point
269 pub mesh: MeshState<'a>,
270 /// The properties of the pipeline at the primitive assembly and rasterization level.
271 pub primitive: PrimitiveState,
272 /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
273 pub depth_stencil: Option<DepthStencilState>,
274 /// The multi-sampling properties of the pipeline.
275 pub multisample: MultisampleState,
276 /// The compiled fragment stage, its entry point, and the color targets.
277 pub fragment: Option<FragmentState<'a>>,
278 /// If the pipeline will be used with a multiview render pass, this indicates how many array
279 /// layers the attachments will have.
280 pub multiview: Option<NonZeroU32>,
281 /// The pipeline cache to use when creating this pipeline.
282 pub cache: Option<&'a PipelineCache>,
283}
284#[cfg(send_sync)]
285static_assertions::assert_impl_all!(MeshPipelineDescriptor<'_>: Send, Sync);