molgfx_gpu/descriptors/
binding.rs

1//! Bind-group layouts and bind groups.
2//!
3//! Bind groups are numbered by update frequency, a fixed convention every
4//! layout declaration documents: group 0 per-frame (camera, lights, time),
5//! group 1 per-pass, group 2 per-representation, group 3 per-material. This
6//! ordering minimizes rebinds.
7
8use crate::device::Device;
9
10bitflags::bitflags! {
11    /// Which stages see a binding.
12    #[derive(Clone, Copy, PartialEq, Eq, Debug)]
13    pub struct ShaderStages: u32 {
14        /// Vertex stage.
15        const VERTEX = 1;
16        /// Fragment stage.
17        const FRAGMENT = 1 << 1;
18        /// Compute stage.
19        const COMPUTE = 1 << 2;
20    }
21}
22
23/// What kind of resource a binding slot holds.
24#[derive(Clone, Copy, PartialEq, Eq, Debug)]
25pub enum BindingType {
26    /// A uniform buffer.
27    Uniform,
28    /// A storage buffer.
29    Storage {
30        /// Whether shaders only read it.
31        read_only: bool,
32    },
33    /// A sampled 2-D texture.
34    Texture {
35        /// Whether the texel type is filterable float (versus unsigned
36        /// integer, e.g. the entity-id channel).
37        filterable: bool,
38    },
39    /// A sampled 3-D floating-point texture.
40    Texture3dFloat {
41        /// Whether hardware linear filtering is required.
42        filterable: bool,
43    },
44    /// A sampled 3-D unsigned-integer texture.
45    Texture3dUint,
46    /// A write-only 3-D storage texture used by compute-generated fields.
47    StorageTexture3dWrite {
48        /// Portable storage format shared by the layout and texture.
49        format: crate::TextureFormat,
50    },
51    /// A depth texture sampled for comparison or raw reads.
52    DepthTexture,
53    /// A sampler.
54    Sampler {
55        /// Whether it is a comparison sampler.
56        comparison: bool,
57    },
58}
59
60/// One slot in a bind-group layout: index, visibility, kind. Every binding
61/// index is declared here with a name; shaders never invent one.
62#[derive(Clone, Copy, Debug)]
63pub struct BindGroupLayoutEntry {
64    /// Binding index within the group.
65    pub binding: u32,
66    /// Stages that access it.
67    pub visibility: ShaderStages,
68    /// The resource kind.
69    pub ty: BindingType,
70}
71
72/// Everything needed to create a bind-group layout.
73#[derive(Clone, Copy, Debug)]
74pub struct BindGroupLayoutDesc<'a> {
75    /// Debug label; by convention states the group's update frequency.
76    pub label: &'static str,
77    /// The slots, in binding order.
78    pub entries: &'a [BindGroupLayoutEntry],
79}
80
81/// A live resource bound into a slot.
82#[derive(Debug)]
83pub enum BindGroupEntry<'a, D: Device> {
84    /// A whole buffer.
85    Buffer {
86        /// Binding index.
87        binding: u32,
88        /// The buffer.
89        buffer: &'a D::Buffer,
90    },
91    /// A contiguous slice of a buffer.
92    ///
93    /// Binding a range rather than a whole buffer is what lets one packed
94    /// table be drawn as several groups: each group's shader sees its slice
95    /// starting at instance zero, so no draw needs a first-instance offset —
96    /// a capability the portable baseline does not guarantee.
97    BufferRange {
98        /// Binding index.
99        binding: u32,
100        /// The buffer holding every group.
101        buffer: &'a D::Buffer,
102        /// Byte offset of this group; a multiple of the device's storage
103        /// binding alignment.
104        offset: u64,
105        /// Length of this group in bytes.
106        size: u64,
107    },
108    /// A texture view.
109    Texture {
110        /// Binding index.
111        binding: u32,
112        /// The view.
113        view: &'a D::TextureView,
114    },
115    /// A sampler.
116    Sampler {
117        /// Binding index.
118        binding: u32,
119        /// The sampler.
120        sampler: &'a D::Sampler,
121    },
122}
123
124/// Everything needed to create a bind group over a layout.
125#[derive(Debug)]
126pub struct BindGroupDesc<'a, D: Device> {
127    /// Debug label.
128    pub label: &'static str,
129    /// The layout this group instantiates.
130    pub layout: &'a D::BindGroupLayout,
131    /// The bound resources.
132    pub entries: &'a [BindGroupEntry<'a, D>],
133}
134
135/// One TLAS resource bound into a ray-query bind group.
136#[derive(Clone, Copy, Debug)]
137pub struct AccelerationStructureBinding<'a, D: Device> {
138    /// Binding index within the group.
139    pub binding: u32,
140    /// Top-level acceleration structure.
141    pub tlas: &'a D::Tlas,
142}
143
144/// One acceleration-structure slot in a ray-query bind-group layout.
145#[derive(Clone, Copy, Debug)]
146pub struct AccelerationStructureLayoutEntry {
147    /// Binding index within the group.
148    pub binding: u32,
149    /// Shader stages that may issue ray queries.
150    pub visibility: ShaderStages,
151}
152
153/// Layout containing regular slots and acceleration-structure slots.
154#[derive(Debug)]
155pub struct RayQueryBindGroupLayoutDesc<'a> {
156    /// Diagnostic label.
157    pub label: &'static str,
158    /// Buffer, texture and sampler slots.
159    pub entries: &'a [BindGroupLayoutEntry],
160    /// TLAS slots.
161    pub acceleration_structures: &'a [AccelerationStructureLayoutEntry],
162}
163
164/// Bind group containing regular resources and TLAS resources.
165#[derive(Debug)]
166pub struct RayQueryBindGroupDesc<'a, D: Device> {
167    /// Diagnostic label.
168    pub label: &'static str,
169    /// Layout containing matching acceleration-structure entries.
170    pub layout: &'a D::BindGroupLayout,
171    /// Buffer, texture and sampler resources.
172    pub entries: &'a [BindGroupEntry<'a, D>],
173    /// TLAS resources.
174    pub acceleration_structures: &'a [AccelerationStructureBinding<'a, D>],
175}
molgfx_gpu/descriptors/binding.rs

molgfx_gpu/descriptors/
binding.rs
