wgpu/macros/
mod.rs

1//! Convenience macros
2
3#[cfg(doc)]
4use crate::{VertexAttribute, VertexBufferLayout, VertexFormat};
5
6/// Macro to produce an array of [`VertexAttribute`].
7///
8/// The input is a sequence of pairs of shader locations (expression of type [`u32`]) and
9/// variant names of [`VertexFormat`].
10///
11/// The return value has type `[VertexAttribute; N]`, where `N` is the number of inputs.
12///
13/// Offsets are calculated automatically,
14/// using the assumption that there is no padding or other data between attributes.
15///
16/// # Example
17///
18/// ```
19/// // Suppose that this is our vertex format:
20/// #[repr(C, packed)]
21/// struct Vertex {
22///     foo: [f32; 2],
23///     bar: f32,
24///     baz: [u16; 4],
25/// }
26///
27/// // Then these attributes match it:
28/// let attrs = wgpu::vertex_attr_array![
29///     0 => Float32x2,
30///     1 => Float32,
31///     2 => Uint16x4,
32/// ];
33///
34/// // Here's the full data structure the macro produced:
35/// use wgpu::{VertexAttribute as A, VertexFormat as F};
36/// assert_eq!(attrs, [
37///     A { format: F::Float32x2, offset:  0, shader_location: 0, },
38///     A { format: F::Float32,   offset:  8, shader_location: 1, },
39///     A { format: F::Uint16x4,  offset: 12, shader_location: 2, },
40/// ]);
41/// ```
42///
43/// See [`VertexBufferLayout`] for an example building on this one.
44#[macro_export]
45macro_rules! vertex_attr_array {
46    ($($location:expr => $format:ident),* $(,)?) => {
47        $crate::_vertex_attr_array_helper!([] ; 0; $($location => $format ,)*)
48    };
49}
50
51#[doc(hidden)]
52#[macro_export]
53macro_rules! _vertex_attr_array_helper {
54    ([$($t:expr,)*] ; $off:expr ;) => { [$($t,)*] };
55    ([$($t:expr,)*] ; $off:expr ; $location:expr => $format:ident, $($ll:expr => $ii:ident ,)*) => {
56        $crate::_vertex_attr_array_helper!(
57            [$($t,)*
58            $crate::VertexAttribute {
59                format: $crate::VertexFormat :: $format,
60                offset: $off,
61                shader_location: $location,
62            },];
63            $off + $crate::VertexFormat :: $format.size();
64            $($ll => $ii ,)*
65        )
66    };
67}
68
69#[test]
70fn test_vertex_attr_array() {
71    let attrs = vertex_attr_array![0 => Float32x2, 3 => Uint16x4];
72    // VertexAttribute does not support PartialEq, so we cannot test directly
73    assert_eq!(attrs.len(), 2);
74    assert_eq!(attrs[0].offset, 0);
75    assert_eq!(attrs[0].shader_location, 0);
76    assert_eq!(attrs[1].offset, size_of::<(f32, f32)>() as u64);
77    assert_eq!(attrs[1].shader_location, 3);
78}
79
80#[macro_export]
81#[doc(hidden)]
82macro_rules! include_spirv_source {
83    ($($token:tt)*) => {
84        {
85            // FIXME(MSRV): when bumping to 1.89, use [u8; _] here
86            const SPIRV_SOURCE: [
87                u8;
88                $crate::__macro_helpers::include_bytes!($($token)*).len()
89            ] = *$crate::__macro_helpers::include_bytes!($($token)*);
90            const SPIRV_LEN: usize = SPIRV_SOURCE.len() / 4;
91            const SPIRV_WORDS: [u32; SPIRV_LEN] = $crate::util::make_spirv_const(SPIRV_SOURCE);
92            &SPIRV_WORDS
93        }
94    }
95}
96
97#[test]
98fn make_spirv_le_pass() {
99    static SPIRV: &[u32] = include_spirv_source!("le-aligned.spv");
100    assert_eq!(SPIRV, &[0x07230203, 0x11223344]);
101}
102
103#[test]
104fn make_spirv_be_pass() {
105    static SPIRV: &[u32] = include_spirv_source!("be-aligned.spv");
106    assert_eq!(SPIRV, &[0x07230203, 0x11223344]);
107}
108
109/// Macro to load a SPIR-V module statically.
110///
111/// It ensures the word alignment as well as the magic number.
112///
113/// Return type: [`crate::ShaderModuleDescriptor`]
114#[macro_export]
115#[cfg(feature = "spirv")]
116macro_rules! include_spirv {
117    ($($token:tt)*) => {
118        {
119            //log::info!("including '{}'", $($token)*);
120            $crate::ShaderModuleDescriptor {
121                label: Some($($token)*),
122                source: $crate::ShaderSource::SpirV(
123                    $crate::__macro_helpers::Cow::Borrowed($crate::include_spirv_source!($($token)*))
124                ),
125            }
126        }
127    };
128}
129
130#[cfg(all(feature = "spirv", test))]
131#[expect(dead_code)]
132static SPIRV: crate::ShaderModuleDescriptor<'_> = include_spirv!("le-aligned.spv");
133
134/// Macro to load raw SPIR-V data statically, for use with [`Features::EXPERIMENTAL_PASSTHROUGH_SHADERS`].
135///
136/// It ensures the word alignment as well as the magic number.
137///
138/// [`Features::EXPERIMENTAL_PASSTHROUGH_SHADERS`]: crate::Features::EXPERIMENTAL_PASSTHROUGH_SHADERS
139#[macro_export]
140macro_rules! include_spirv_raw {
141    ($($token:tt)*) => {
142        {
143            //log::info!("including '{}'", $($token)*);
144            $crate::ShaderModuleDescriptorPassthrough {
145                label: $crate::__macro_helpers::Some($($token)*),
146                spirv: Some($crate::__macro_helpers::Cow::Borrowed($crate::include_spirv_source!($($token)*))),
147                entry_point: $crate::__macro_helpers::String::new(),
148                // This is unused for SPIR-V
149                num_workgroups: (0, 0, 0),
150                runtime_checks: $crate::ShaderRuntimeChecks::unchecked(),
151                dxil: None,
152                msl: None,
153                hlsl: None,
154                glsl: None,
155                wgsl: None,
156            }
157        }
158    };
159}
160
161#[cfg(test)]
162#[expect(dead_code)]
163static SPIRV_RAW: crate::ShaderModuleDescriptorPassthrough<'_> =
164    include_spirv_raw!("le-aligned.spv");
165
166/// Load WGSL source code from a file at compile time.
167///
168/// The loaded path is relative to the path of the file containing the macro call, in the same way
169/// as [`include_str!`] operates.
170///
171/// ```ignore
172/// fn main() {
173///     let module: ShaderModuleDescriptor = include_wgsl!("shader.wgsl");
174/// }
175/// ```
176#[macro_export]
177macro_rules! include_wgsl {
178    ($($token:tt)*) => {
179        {
180            //log::info!("including '{}'", $($token)*);
181            $crate::ShaderModuleDescriptor {
182                label: $crate::__macro_helpers::Some($($token)*),
183                source: $crate::ShaderSource::Wgsl($crate::__macro_helpers::Cow::Borrowed($crate::__macro_helpers::include_str!($($token)*))),
184            }
185        }
186    };
187}
188
189// Macros which help us generate the documentation of which hal types correspond to which backend.
190//
191// Because all backends are not compiled into the program, we cannot link to them in all situations,
192// we need to only link to the types if the backend is compiled in. These are used in #[doc] attributes
193// so cannot have more than one line, so cannot use internal cfgs.
194
195/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
196#[macro_export]
197#[doc(hidden)]
198#[cfg(dx12)]
199macro_rules! hal_type_dx12 {
200    ($ty: literal) => {
201        concat!("- [`hal::api::Dx12`] uses [`hal::dx12::", $ty, "`]")
202    };
203}
204/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
205#[macro_export]
206#[doc(hidden)]
207#[cfg(not(dx12))]
208macro_rules! hal_type_dx12 {
209    ($ty: literal) => {
210        concat!("- `hal::api::Dx12` uses `hal::dx12::", $ty, "`")
211    };
212}
213
214/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
215#[macro_export]
216#[doc(hidden)]
217#[cfg(metal)]
218macro_rules! hal_type_metal {
219    ($ty: literal) => {
220        concat!("- [`hal::api::Metal`] uses [`hal::metal::", $ty, "`]")
221    };
222}
223/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
224#[macro_export]
225#[doc(hidden)]
226#[cfg(not(metal))]
227macro_rules! hal_type_metal {
228    ($ty: literal) => {
229        concat!("- `hal::api::Metal` uses `hal::metal::", $ty, "`")
230    };
231}
232
233/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
234#[macro_export]
235#[doc(hidden)]
236#[cfg(vulkan)]
237macro_rules! hal_type_vulkan {
238    ($ty: literal) => {
239        concat!("- [`hal::api::Vulkan`] uses [`hal::vulkan::", $ty, "`]")
240    };
241}
242/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
243#[macro_export]
244#[doc(hidden)]
245#[cfg(not(vulkan))]
246macro_rules! hal_type_vulkan {
247    ($ty: literal) => {
248        concat!("- `hal::api::Vulkan` uses `hal::vulkan::", $ty, "`")
249    };
250}
251
252/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
253#[macro_export]
254#[doc(hidden)]
255#[cfg(gles)]
256macro_rules! hal_type_gles {
257    ($ty: literal) => {
258        concat!("- [`hal::api::Gles`] uses [`hal::gles::", $ty, "`]")
259    };
260}
261/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
262#[macro_export]
263#[doc(hidden)]
264#[cfg(not(gles))]
265macro_rules! hal_type_gles {
266    ($ty: literal) => {
267        concat!("- `hal::api::Gles` uses `hal::gles::", $ty, "`")
268    };
269}
270
271#[doc(hidden)]
272pub mod helpers {
273    pub use alloc::{borrow::Cow, string::String};
274    pub use core::{include_bytes, include_str};
275    pub use Some;
276}
wgpu/macros/mod.rs

wgpu/macros/
mod.rs
