wgpu/api/
bind_group.rs

1use crate::*;
2
3/// Handle to a binding group.
4///
5/// A `BindGroup` represents the set of resources bound to the bindings described by a
6/// [`BindGroupLayout`]. It can be created with [`Device::create_bind_group`]. A `BindGroup` can
7/// be bound to a particular [`RenderPass`] with [`RenderPass::set_bind_group`], or to a
8/// [`ComputePass`] with [`ComputePass::set_bind_group`].
9///
10/// Corresponds to [WebGPU `GPUBindGroup`](https://gpuweb.github.io/gpuweb/#gpubindgroup).
11#[derive(Debug, Clone)]
12pub struct BindGroup {
13    pub(crate) inner: dispatch::DispatchBindGroup,
14}
15#[cfg(send_sync)]
16static_assertions::assert_impl_all!(BindGroup: Send, Sync);
17
18crate::cmp::impl_eq_ord_hash_proxy!(BindGroup => .inner);
19
20impl BindGroup {
21    #[cfg(custom)]
22    /// Returns custom implementation of BindGroup (if custom backend and is internally T)
23    pub fn as_custom<T: custom::BindGroupInterface>(&self) -> Option<&T> {
24        self.inner.as_custom()
25    }
26}
27
28/// Resource to be bound by a [`BindGroup`] for use with a pipeline.
29///
30/// The pipeline’s [`BindGroupLayout`] must contain a matching [`BindingType`].
31///
32/// Corresponds to [WebGPU `GPUBindingResource`](
33/// https://gpuweb.github.io/gpuweb/#typedefdef-gpubindingresource).
34#[non_exhaustive]
35#[derive(Clone, Debug)]
36pub enum BindingResource<'a> {
37    /// Binding is backed by a buffer.
38    ///
39    /// Corresponds to [`wgt::BufferBindingType::Uniform`] and [`wgt::BufferBindingType::Storage`]
40    /// with [`BindGroupLayoutEntry::count`] set to None.
41    Buffer(BufferBinding<'a>),
42    /// Binding is backed by an array of buffers.
43    ///
44    /// [`Features::BUFFER_BINDING_ARRAY`] must be supported to use this feature.
45    ///
46    /// Corresponds to [`wgt::BufferBindingType::Uniform`] and [`wgt::BufferBindingType::Storage`]
47    /// with [`BindGroupLayoutEntry::count`] set to Some.
48    BufferArray(&'a [BufferBinding<'a>]),
49    /// Binding is a sampler.
50    ///
51    /// Corresponds to [`wgt::BindingType::Sampler`] with [`BindGroupLayoutEntry::count`] set to None.
52    Sampler(&'a Sampler),
53    /// Binding is backed by an array of samplers.
54    ///
55    /// [`Features::TEXTURE_BINDING_ARRAY`] must be supported to use this feature.
56    ///
57    /// Corresponds to [`wgt::BindingType::Sampler`] with [`BindGroupLayoutEntry::count`] set
58    /// to Some.
59    SamplerArray(&'a [&'a Sampler]),
60    /// Binding is backed by a texture.
61    ///
62    /// Corresponds to [`wgt::BindingType::Texture`] and [`wgt::BindingType::StorageTexture`] with
63    /// [`BindGroupLayoutEntry::count`] set to None.
64    TextureView(&'a TextureView),
65    /// Binding is backed by an array of textures.
66    ///
67    /// [`Features::TEXTURE_BINDING_ARRAY`] must be supported to use this feature.
68    ///
69    /// Corresponds to [`wgt::BindingType::Texture`] and [`wgt::BindingType::StorageTexture`] with
70    /// [`BindGroupLayoutEntry::count`] set to Some.
71    TextureViewArray(&'a [&'a TextureView]),
72    /// Binding is backed by a top level acceleration structure
73    ///
74    /// Corresponds to [`wgt::BindingType::AccelerationStructure`] with [`BindGroupLayoutEntry::count`] set to None.
75    ///
76    /// # Validation
77    /// When using (e.g. with `set_bind_group`) a bind group that has been created with one or more of this binding
78    /// resource certain checks take place.
79    /// - TLAS must have been built, if not a validation error is generated
80    /// - All BLASes that were built into the TLAS must be built before the TLAS, if this was not satisfied and TLAS was
81    ///   built using `build_acceleration_structures` a validation error is generated otherwise this is a part of the
82    ///   safety section of `build_acceleration_structures_unsafe_tlas` and so undefined behavior occurs.
83    AccelerationStructure(&'a Tlas),
84    /// Binding is backed by an array of top level acceleration structures.
85    ///
86    /// Corresponds to [`wgt::BindingType::AccelerationStructure`] with [`BindGroupLayoutEntry::count`] set to Some.
87    ///
88    /// # Validation
89    /// The same validation rules apply as for [`BindingResource::AccelerationStructure`], for each element.
90    ///
91    /// Note: backend support may vary; this is primarily intended for native backends.
92    AccelerationStructureArray(&'a [&'a Tlas]),
93    /// Binding is backed by an external texture.
94    ///
95    /// [`Features::EXTERNAL_TEXTURE`] must be supported to use this feature.
96    ///
97    /// Corresponds to [`wgt::BindingType::ExternalTexture`].
98    ExternalTexture(&'a ExternalTexture),
99}
100#[cfg(send_sync)]
101static_assertions::assert_impl_all!(BindingResource<'_>: Send, Sync);
102
103/// Describes the segment of a buffer to bind.
104///
105/// Corresponds to [WebGPU `GPUBufferBinding`](
106/// https://gpuweb.github.io/gpuweb/#dictdef-gpubufferbinding).
107#[derive(Clone, Debug)]
108pub struct BufferBinding<'a> {
109    /// The buffer to bind.
110    pub buffer: &'a Buffer,
111
112    /// Base offset of the buffer, in bytes.
113    ///
114    /// If the [`has_dynamic_offset`] field of this buffer's layout entry is
115    /// `true`, the offset here will be added to the dynamic offset passed to
116    /// [`RenderPass::set_bind_group`] or [`ComputePass::set_bind_group`].
117    ///
118    /// If the buffer was created with [`BufferUsages::UNIFORM`], then this
119    /// offset must be a multiple of
120    /// [`Limits::min_uniform_buffer_offset_alignment`].
121    ///
122    /// If the buffer was created with [`BufferUsages::STORAGE`], then this
123    /// offset must be a multiple of
124    /// [`Limits::min_storage_buffer_offset_alignment`].
125    ///
126    /// [`has_dynamic_offset`]: BindingType::Buffer::has_dynamic_offset
127    pub offset: BufferAddress,
128
129    /// Size of the binding in bytes, or `None` for using the rest of the buffer.
130    pub size: Option<BufferSize>,
131}
132#[cfg(send_sync)]
133static_assertions::assert_impl_all!(BufferBinding<'_>: Send, Sync);
134
135/// An element of a [`BindGroupDescriptor`], consisting of a bindable resource
136/// and the slot to bind it to.
137///
138/// Corresponds to [WebGPU `GPUBindGroupEntry`](
139/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgroupentry).
140#[derive(Clone, Debug)]
141pub struct BindGroupEntry<'a> {
142    /// Slot for which binding provides resource. Corresponds to an entry of the same
143    /// binding index in the [`BindGroupLayoutDescriptor`].
144    pub binding: u32,
145    /// Resource to attach to the binding
146    pub resource: BindingResource<'a>,
147}
148#[cfg(send_sync)]
149static_assertions::assert_impl_all!(BindGroupEntry<'_>: Send, Sync);
150
151/// Describes a group of bindings and the resources to be bound.
152///
153/// For use with [`Device::create_bind_group`].
154///
155/// Corresponds to [WebGPU `GPUBindGroupDescriptor`](
156/// https://gpuweb.github.io/gpuweb/#dictdef-gpubindgroupdescriptor).
157#[derive(Clone, Debug)]
158pub struct BindGroupDescriptor<'a> {
159    /// Debug label of the bind group. This will show up in graphics debuggers for easy identification.
160    pub label: Label<'a>,
161    /// The [`BindGroupLayout`] that corresponds to this bind group.
162    pub layout: &'a BindGroupLayout,
163    /// The resources to bind to this bind group.
164    pub entries: &'a [BindGroupEntry<'a>],
165}
166#[cfg(send_sync)]
167static_assertions::assert_impl_all!(BindGroupDescriptor<'_>: Send, Sync);
wgpu/api/bind_group.rs

wgpu/api/
bind_group.rs
