wgpu/macros.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 to load a SPIR-V module statically.
81///
82/// It ensures the word alignment as well as the magic number.
83///
84/// Return type: [`crate::ShaderModuleDescriptor`]
85#[macro_export]
86#[cfg(feature = "spirv")]
87macro_rules! include_spirv {
88 ($($token:tt)*) => {
89 {
90 //log::info!("including '{}'", $($token)*);
91 $crate::ShaderModuleDescriptor {
92 label: Some($($token)*),
93 source: $crate::util::make_spirv(include_bytes!($($token)*)),
94 }
95 }
96 };
97}
98
99/// Macro to load raw SPIR-V data statically, for use with [`Features::SPIRV_SHADER_PASSTHROUGH`].
100///
101/// It ensures the word alignment as well as the magic number.
102///
103/// [`Features::SPIRV_SHADER_PASSTHROUGH`]: crate::Features::SPIRV_SHADER_PASSTHROUGH
104#[macro_export]
105macro_rules! include_spirv_raw {
106 ($($token:tt)*) => {
107 {
108 //log::info!("including '{}'", $($token)*);
109 $crate::ShaderModuleDescriptorPassthrough::SpirV(
110 $crate::ShaderModuleDescriptorSpirV {
111 label: $crate::__macro_helpers::Some($($token)*),
112 source: $crate::util::make_spirv_raw($crate::__macro_helpers::include_bytes!($($token)*)),
113 }
114 )
115 }
116 };
117}
118
119/// Load WGSL source code from a file at compile time.
120///
121/// The loaded path is relative to the path of the file containing the macro call, in the same way
122/// as [`include_str!`] operates.
123///
124/// ```ignore
125/// fn main() {
126/// let module: ShaderModuleDescriptor = include_wgsl!("shader.wgsl");
127/// }
128/// ```
129#[macro_export]
130macro_rules! include_wgsl {
131 ($($token:tt)*) => {
132 {
133 //log::info!("including '{}'", $($token)*);
134 $crate::ShaderModuleDescriptor {
135 label: $crate::__macro_helpers::Some($($token)*),
136 source: $crate::ShaderSource::Wgsl($crate::__macro_helpers::Cow::Borrowed($crate::__macro_helpers::include_str!($($token)*))),
137 }
138 }
139 };
140}
141
142// Macros which help us generate the documentation of which hal types correspond to which backend.
143//
144// Because all backends are not compiled into the program, we cannot link to them in all situations,
145// we need to only link to the types if the backend is compiled in. These are used in #[doc] attributes
146// so cannot have more than one line, so cannot use internal cfgs.
147
148/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
149#[macro_export]
150#[doc(hidden)]
151#[cfg(dx12)]
152macro_rules! hal_type_dx12 {
153 ($ty: literal) => {
154 concat!("- [`hal::api::Dx12`] uses [`hal::dx12::", $ty, "`]")
155 };
156}
157/// Helper macro to generate the documentation for dx12 hal methods, referencing the hal type.
158#[macro_export]
159#[doc(hidden)]
160#[cfg(not(dx12))]
161macro_rules! hal_type_dx12 {
162 ($ty: literal) => {
163 concat!("- `hal::api::Dx12` uses `hal::dx12::", $ty, "`")
164 };
165}
166
167/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
168#[macro_export]
169#[doc(hidden)]
170#[cfg(metal)]
171macro_rules! hal_type_metal {
172 ($ty: literal) => {
173 concat!("- [`hal::api::Metal`] uses [`hal::metal::", $ty, "`]")
174 };
175}
176/// Helper macro to generate the documentation for metal hal methods, referencing the hal type.
177#[macro_export]
178#[doc(hidden)]
179#[cfg(not(metal))]
180macro_rules! hal_type_metal {
181 ($ty: literal) => {
182 concat!("- `hal::api::Metal` uses `hal::metal::", $ty, "`")
183 };
184}
185
186/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
187#[macro_export]
188#[doc(hidden)]
189#[cfg(vulkan)]
190macro_rules! hal_type_vulkan {
191 ($ty: literal) => {
192 concat!("- [`hal::api::Vulkan`] uses [`hal::vulkan::", $ty, "`]")
193 };
194}
195/// Helper macro to generate the documentation for vulkan hal methods, referencing the hal type.
196#[macro_export]
197#[doc(hidden)]
198#[cfg(not(vulkan))]
199macro_rules! hal_type_vulkan {
200 ($ty: literal) => {
201 concat!("- `hal::api::Vulkan` uses `hal::vulkan::", $ty, "`")
202 };
203}
204
205/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
206#[macro_export]
207#[doc(hidden)]
208#[cfg(gles)]
209macro_rules! hal_type_gles {
210 ($ty: literal) => {
211 concat!("- [`hal::api::Gles`] uses [`hal::gles::", $ty, "`]")
212 };
213}
214/// Helper macro to generate the documentation for gles hal methods, referencing the hal type.
215#[macro_export]
216#[doc(hidden)]
217#[cfg(not(gles))]
218macro_rules! hal_type_gles {
219 ($ty: literal) => {
220 concat!("- `hal::api::Gles` uses `hal::gles::", $ty, "`")
221 };
222}
223
224#[doc(hidden)]
225pub mod helpers {
226 pub use alloc::borrow::Cow;
227 pub use core::{include_bytes, include_str};
228 pub use Some;
229}