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_STRIDE_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 a render (graphics) pipeline.
149///
150/// For use with [`Device::create_render_pipeline`].
151///
152/// Corresponds to [WebGPU `GPURenderPipelineDescriptor`](
153/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor).
154#[derive(Clone, Debug)]
155pub struct RenderPipelineDescriptor<'a> {
156    /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
157    pub label: Label<'a>,
158    /// The layout of bind groups for this pipeline.
159    ///
160    /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
161    /// the layout doesn't match what the shader module(s) expect.
162    ///
163    /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
164    /// pipelines guarantees that you don't have to rebind any resources when switching between
165    /// those pipelines.
166    ///
167    /// ## Default pipeline layout
168    ///
169    /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
170    /// The default layout is deduced from the shader modules.
171    ///
172    /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
173    /// default layout. However, these bind groups cannot be used with any other pipelines. This is
174    /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
175    ///
176    /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
177    pub layout: Option<&'a PipelineLayout>,
178    /// The compiled vertex stage, its entry point, and the input buffers layout.
179    pub vertex: VertexState<'a>,
180    /// The properties of the pipeline at the primitive assembly and rasterization level.
181    pub primitive: PrimitiveState,
182    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
183    pub depth_stencil: Option<DepthStencilState>,
184    /// The multi-sampling properties of the pipeline.
185    pub multisample: MultisampleState,
186    /// The compiled fragment stage, its entry point, and the color targets.
187    pub fragment: Option<FragmentState<'a>>,
188    /// If the pipeline will be used with a multiview render pass, this indicates how many array
189    /// layers the attachments will have.
190    pub multiview: Option<NonZeroU32>,
191    /// The pipeline cache to use when creating this pipeline.
192    pub cache: Option<&'a PipelineCache>,
193}
194#[cfg(send_sync)]
195static_assertions::assert_impl_all!(RenderPipelineDescriptor<'_>: Send, Sync);
wgpu/api/render_pipeline.rs

wgpu/api/
render_pipeline.rs
