wgpu_types/features.rs
1//! # Features
2//!
3//! Types identifying optional features of WebGPU and wgpu. Availability varies
4//! by hardware and can be checked when requesting an adapter and device.
5//!
6//! The `wgpu` Rust API always uses the `Features` bit flag type to represent a
7//! set of features. However, the WebGPU-defined JavaScript API uses
8//! `kebab-case` feature name strings, so some utilities are provided for
9//! working with those names. See [`Features::as_str`] and [`Features::from_str`].
10//!
11//! The [`bitflags`] crate names flags by stringifying the
12//! `SCREAMING_SNAKE_CASE` identifier. These names are returned by
13//! [`Features::iter_names`] and parsed by [`Features::from_name`].
14//! [`bitflags`] does not currently support customized flag naming.
15//! See <https://github.com/bitflags/bitflags/issues/470>.
16
17use crate::{link_to_wgpu_docs, link_to_wgpu_item, VertexFormat};
18use alloc::vec::Vec;
19use bitflags::Flags;
20#[cfg(feature = "serde")]
21use core::mem::size_of;
22use core::str::FromStr;
23#[cfg(feature = "serde")]
24use serde::{Deserialize, Serialize};
25
26pub use webgpu_impl::*;
27mod webgpu_impl {
28 //! Constant values for [`super::FeaturesWebGPU`], separated so they can be picked up by
29 //! `cbindgen` in `mozilla-central` (where Firefox is developed).
30 //!
31 //! Bitmask feature encoding is not defined by the WebGPU specification, and the values
32 //! are subject to change.
33 #![allow(missing_docs, reason = "these constants are internal encoding details")]
34
35 #[doc(hidden)]
36 pub const WEBGPU_FEATURE_CORE_FEATURES_AND_LIMITS: u64 = 1 << 0;
37
38 #[doc(hidden)]
39 pub const WEBGPU_FEATURE_DEPTH_CLIP_CONTROL: u64 = 1 << 1;
40
41 #[doc(hidden)]
42 pub const WEBGPU_FEATURE_DEPTH32FLOAT_STENCIL8: u64 = 1 << 2;
43
44 #[doc(hidden)]
45 pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC: u64 = 1 << 3;
46
47 #[doc(hidden)]
48 pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC_SLICED_3D: u64 = 1 << 4;
49
50 #[doc(hidden)]
51 pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ETC2: u64 = 1 << 5;
52
53 #[doc(hidden)]
54 pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC: u64 = 1 << 6;
55
56 #[doc(hidden)]
57 pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC_SLICED_3D: u64 = 1 << 7;
58
59 #[doc(hidden)]
60 pub const WEBGPU_FEATURE_TIMESTAMP_QUERY: u64 = 1 << 8;
61
62 #[doc(hidden)]
63 pub const WEBGPU_FEATURE_INDIRECT_FIRST_INSTANCE: u64 = 1 << 9;
64
65 #[doc(hidden)]
66 pub const WEBGPU_FEATURE_SHADER_F16: u64 = 1 << 10;
67
68 #[doc(hidden)]
69 pub const WEBGPU_FEATURE_RG11B10UFLOAT_RENDERABLE: u64 = 1 << 11;
70
71 #[doc(hidden)]
72 pub const WEBGPU_FEATURE_BGRA8UNORM_STORAGE: u64 = 1 << 12;
73
74 #[doc(hidden)]
75 pub const WEBGPU_FEATURE_FLOAT32_FILTERABLE: u64 = 1 << 13;
76
77 #[doc(hidden)]
78 pub const WEBGPU_FEATURE_FLOAT32_BLENDABLE: u64 = 1 << 14;
79
80 #[doc(hidden)]
81 pub const WEBGPU_FEATURE_DUAL_SOURCE_BLENDING: u64 = 1 << 15;
82
83 #[doc(hidden)]
84 pub const WEBGPU_FEATURE_CLIP_DISTANCES: u64 = 1 << 16;
85
86 #[doc(hidden)]
87 pub const WEBGPU_FEATURE_IMMEDIATES: u64 = 1 << 17;
88
89 #[doc(hidden)]
90 pub const WEBGPU_FEATURE_PRIMITIVE_INDEX: u64 = 1 << 18;
91
92 #[doc(hidden)]
93 pub const WEBGPU_FEATURE_TEXTURE_COMPONENT_SWIZZLE: u64 = 1 << 19;
94}
95
96/// Prefer `From<(FeaturesWGPU, FeaturesWebGPU)>` instead, which protects against swapping
97/// the two feature sets.
98impl From<FeatureBits> for Features {
99 fn from(value: FeatureBits) -> Self {
100 Self::from_bits_retain(value)
101 }
102}
103
104impl From<(FeaturesWGPU, FeaturesWebGPU)> for Features {
105 fn from(value: (FeaturesWGPU, FeaturesWebGPU)) -> Self {
106 let (wgpu, webgpu) = value;
107 Self::from_parts(wgpu, webgpu)
108 }
109}
110
111impl From<Features> for FeatureBits {
112 fn from(value: Features) -> Self {
113 value.bits()
114 }
115}
116
117/// Maps a feature's `#[web(...)]` attribute to whether the feature is allowed on the web
118/// backend, rejecting a missing or unrecognized value.
119macro_rules! web_attr_allows {
120 ($flag:tt; allow) => {
121 true
122 };
123 ($flag:tt; ignore) => {
124 false
125 };
126 ($flag:tt; $other:tt) => {
127 compile_error!(concat!(
128 "`#[web(",
129 stringify!($other),
130 ")]` on `",
131 stringify!($flag),
132 "`: the value must be `allow` or `ignore`",
133 ))
134 };
135 ($flag:tt;) => {
136 compile_error!(concat!(
137 "WebGPU feature `",
138 stringify!($flag),
139 "` needs a `#[web(allow)]` or `#[web(ignore)]` attribute",
140 ))
141 };
142}
143
144/// Generate the `Features::ALLOWED_ON_WEB_BACKEND` constant.
145///
146/// Each [`FeaturesWebGPU`] feature must have the `web` attribute, specifying
147/// whether or not to expose it on the web backend (typically yes, unless
148/// there are known deficiencies in the bindings that prevent using the
149/// feature). Standards-track native-only features can be added as special
150/// cases.
151macro_rules! features_web {
152 (FeaturesWebGPU; $($flag:tt [$($web:tt)?])*) => {
153 impl Features {
154 /// The features that the web backend will allow through from an underlying
155 /// browser WebGPU implementation.
156 ///
157 /// This may include bits in [`FeaturesWGPU`] for standards-track features
158 /// that have not yet been migrated to [`FeaturesWebGPU`].
159 pub const ALLOWED_ON_WEB_BACKEND: Self = Self::from_parts(
160 FeaturesWGPU::SUBGROUP,
161 FeaturesWebGPU::from_bits_retain(
162 0 $(| if web_attr_allows!($flag; $($web)?) {
163 FeaturesWebGPU::$flag.bits()
164 } else {
165 0
166 })*
167 ),
168 );
169 }
170 };
171 ($inner_name:tt; $($flag:tt [$($web:tt)?])*) => {
172 $($(
173 compile_error!(concat!(
174 "`#[web(", stringify!($web), ")]` on `", stringify!($flag),
175 "`: only `FeaturesWebGPU` features have a `web` attribute, and `",
176 stringify!($flag), "` is a `", stringify!($inner_name), "` feature",
177 ));
178 )?)*
179 };
180}
181
182/// Defines the feature bitflags, using [`bitflags_array`](crate::bitflags_array) for storage.
183///
184/// On top of what `bitflags_array!` accepts, each flag carries feature-specific attributes,
185/// written after its doc comments. These are consumed here rather than passed on to
186/// `bitflags_array!`. Adding another one means adding a matcher for it, in a fixed position
187/// relative to the existing ones, and generating whatever it should produce.
188///
189/// `#[name("kebab-case-name", "alias", ...)]` gives the names that the WebGPU API uses for
190/// the feature: the name from the spec, for features in [`FeaturesWebGPU`], and otherwise a
191/// `wgpu-` prefixed name. It is required on every feature.
192///
193/// `#[web(allow)]` or `#[web(ignore)]` controls whether `wgpu`'s WebGPU backend will
194/// offer the feature when the underlying WebGPU implementation does. Typically should be
195/// `allow`, but `ignore` may be appropriate in cases where missing logic in the WebGPU
196/// backend means the feature will not work via `wgpu` even though it is supported by the
197/// underlying backend, or where there is concern about interactions or confusion with
198/// `wgpu` native features having subtly different API or behavior.
199macro_rules! features {
200 (
201 $(#[$outer:meta])*
202 pub struct ($name:ident, $name_bits:ident): [$T:ty; $Len:expr];
203
204 $(
205 $(#[$bit_outer:meta])*
206 $vis:vis struct $inner_name:ident $lower_inner_name:ident {
207 $(
208 $(#[doc $($args:tt)*])*
209 #[name($str_name:literal $(, $alias:literal)*)]
210 $(#[web($web:tt)])?
211 const $Flag:tt = $value:expr;
212 )*
213 }
214 )*
215 ) => {
216 crate::bitflags_array! {
217 $(#[$outer])*
218 pub struct ($name, $name_bits): [$T; $Len];
219
220 $(
221 $(#[$bit_outer])*
222 $vis struct $inner_name $lower_inner_name {
223 $(
224 $(#[doc $($args)*])*
225 const $Flag = $value;
226 )*
227 }
228 )*
229 }
230
231 $( features_web! { $inner_name; $($Flag [$($web)?])* } )*
232
233 // Parses kebab-case feature names (i.e. the names given in the spec, for features
234 // in FeaturesWebGPU, and otherwise the `wgpu-` prefixed names).
235 impl FromStr for $name {
236 type Err = ();
237
238 fn from_str(s: &str) -> Result<Self, Self::Err> {
239 Ok(match s {
240 $($($str_name $(| $alias)* => Self::$Flag,)*)*
241 _ => return Err(()),
242 })
243 }
244 }
245
246 impl $name {
247 #[doc = concat!("If the argument is a single [`", stringify!($name), "`] flag,")]
248 /// returns the corresponding `kebab-case` flag name, otherwise `None`.
249 #[must_use]
250 pub fn as_str(&self) -> Option<&'static str> {
251 Some(match *self {
252 $($(Self::$Flag => $str_name,)*)*
253 _ => return None,
254 })
255 }
256 }
257 };
258}
259
260features! {
261 /// Features that are not guaranteed to be supported.
262 ///
263 /// These are either part of the webgpu standard, or are extension features supported by
264 /// wgpu when targeting native.
265 ///
266 /// If you want to use a feature, you need to first verify that the adapter supports
267 /// the feature. If the adapter does not support the feature, requesting a device with it enabled
268 /// will panic.
269 ///
270 /// Corresponds to [WebGPU `GPUFeatureName`](
271 /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
272 #[repr(C)]
273 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
274 pub struct (Features, FeatureBits): [u64; 2];
275
276 /// Features that are not guaranteed to be supported.
277 ///
278 /// Most of these are native-only extension features supported by wgpu only when targeting
279 /// native. A few are intended to align with a proposed WebGPU extension, and one
280 /// (`EXTERNAL_TEXTURE`) controls WebGPU-specified behavior that is not optional in the
281 /// standard, but that we don't want to make a [`crate::DownlevelFlags`] until the
282 /// implementation is more complete. For all features see [`Features`].
283 ///
284 /// If you want to use a feature, you need to first verify that the adapter supports
285 /// the feature. If the adapter does not support the feature, requesting a device with it enabled
286 /// will panic.
287 ///
288 /// Corresponds to [WebGPU `GPUFeatureName`](
289 /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
290 #[repr(transparent)]
291 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
292 #[cfg_attr(feature = "serde", serde(transparent))]
293 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
294 pub struct FeaturesWGPU features_wgpu {
295 /// Allows shaders to use f32 atomic load, store, add, sub, and exchange.
296 ///
297 /// Supported platforms:
298 /// - Metal (with MSL 3.0+ and Apple7+/Mac2)
299 /// - Vulkan (with [VK_EXT_shader_atomic_float])
300 ///
301 /// This is a native only feature.
302 ///
303 /// [VK_EXT_shader_atomic_float]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_shader_atomic_float.html
304 #[name("wgpu-shader-float32-atomic")]
305 const SHADER_FLOAT32_ATOMIC = 1 << 0;
306
307 // The features starting with a ? are features that might become part of the spec or
308 // at the very least we can implement as native features; since they should cover all
309 // possible formats and capabilities across backends.
310 //
311 // ? const FORMATS_TIER_1 = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3837)
312 // ? const RW_STORAGE_TEXTURE_TIER_1 = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3838)
313 // ? const NORM16_FILTERABLE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3839)
314 // ? const NORM16_RESOLVE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3839)
315 // ? const 32BIT_FORMAT_MULTISAMPLE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3844)
316 // ? const 32BIT_FORMAT_RESOLVE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3844)
317 // TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES might not be necessary if we have all the texture features implemented
318
319 // Texture Formats:
320
321 /// Enables normalized `16-bit` texture formats.
322 ///
323 /// Supported platforms:
324 /// - Vulkan
325 /// - DX12
326 /// - Metal
327 /// - OpenGL (desktop GL 3.3+ for UNORM; GLES / WebGL2 needs
328 /// `EXT_texture_norm16`. SNORM color-attachment usage
329 /// additionally requires `EXT_render_snorm` on both paths.)
330 ///
331 /// This is a native only feature.
332 #[name("wgpu-texture-format-16-bit-norm", "texture-format-16-bit-norm")]
333 const TEXTURE_FORMAT_16BIT_NORM = 1 << 1;
334 /// Enables ASTC HDR family of compressed textures.
335 ///
336 /// Compressed textures sacrifice some quality in exchange for significantly reduced
337 /// bandwidth usage.
338 ///
339 /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ASTC formats with the HDR channel type.
340 /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
341 ///
342 /// Supported Platforms:
343 /// - Metal
344 /// - Vulkan
345 /// - OpenGL
346 ///
347 /// This is a native only feature.
348 #[name("wgpu-texture-compression-astc-hdr", "texture-compression-astc-hdr")]
349 const TEXTURE_COMPRESSION_ASTC_HDR = 1 << 2;
350 /// Enables device specific texture format features.
351 ///
352 /// See `TextureFormatFeatures` for a listing of the features in question.
353 ///
354 /// By default only texture format properties as defined by the WebGPU specification are allowed.
355 /// Enabling this feature flag extends the features of each format to the ones supported by the current device.
356 /// Note that without this flag, read/write storage access is not allowed at all.
357 ///
358 /// This extension does not enable additional formats.
359 ///
360 /// This is a native only feature.
361 #[name("wgpu-texture-adapter-specific-format-features", "texture-adapter-specific-format-features")]
362 const TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES = 1 << 3;
363
364 // API:
365
366 /// Enables use of Pipeline Statistics Queries. These queries tell the count of various operations
367 /// performed between the start and stop call. Call [`RenderPass::begin_pipeline_statistics_query`] to start
368 /// a query, then call [`RenderPass::end_pipeline_statistics_query`] to stop one.
369 ///
370 /// They must be resolved using [`CommandEncoder::resolve_query_set`] into a buffer.
371 /// The rules on how these resolve into buffers are detailed in the documentation for [`PipelineStatisticsTypes`].
372 ///
373 /// Supported Platforms:
374 /// - Vulkan
375 /// - DX12
376 ///
377 /// This is a native only feature with a [proposal](https://github.com/gpuweb/gpuweb/blob/0008bd30da2366af88180b511a5d0d0c1dffbc36/proposals/pipeline-statistics-query.md) for the web.
378 ///
379 #[doc = link_to_wgpu_docs!(["`RenderPass::begin_pipeline_statistics_query`"]: "struct.RenderPass.html#method.begin_pipeline_statistics_query")]
380 #[doc = link_to_wgpu_docs!(["`RenderPass::end_pipeline_statistics_query`"]: "struct.RenderPass.html#method.end_pipeline_statistics_query")]
381 #[doc = link_to_wgpu_docs!(["`CommandEncoder::resolve_query_set`"]: "struct.CommandEncoder.html#method.resolve_query_set")]
382 /// [`PipelineStatisticsTypes`]: super::PipelineStatisticsTypes
383 #[name("wgpu-pipeline-statistics-query", "pipeline-statistics-query")]
384 const PIPELINE_STATISTICS_QUERY = 1 << 4;
385 /// Allows for timestamp queries directly on command encoders.
386 ///
387 /// Adapters that support this feature also support
388 /// [`Features::TIMESTAMP_QUERY`]. Both features must be requested
389 /// explicitly to use timestamp queries on command encoders.
390 ///
391 /// Additionally allows for timestamp writes on command encoders
392 /// using [`CommandEncoder::write_timestamp`].
393 ///
394 /// Supported platforms:
395 /// - Vulkan
396 /// - DX12
397 /// - Metal (AMD & Intel, not Apple GPUs)
398 /// - OpenGL (with GL_ARB_timer_query)
399 ///
400 /// This is a native only feature.
401 ///
402 #[doc = link_to_wgpu_docs!(["`CommandEncoder::write_timestamp`"]: "struct.CommandEncoder.html#method.write_timestamp")]
403 #[name("wgpu-timestamp-query-inside-encoders")]
404 const TIMESTAMP_QUERY_INSIDE_ENCODERS = 1 << 5;
405 /// Allows for timestamp queries directly inside render and compute passes.
406 ///
407 /// Adapters that support this feature also support
408 /// [`Features::TIMESTAMP_QUERY`] and [`Features::TIMESTAMP_QUERY_INSIDE_ENCODERS`].
409 /// This feature must be requested with [`Features::TIMESTAMP_QUERY`] to use timestamp
410 /// queries inside passes. Additionally, [`Features::TIMESTAMP_QUERY_INSIDE_ENCODERS`]
411 /// must be requested to use timestamp queries on command encoders.
412 ///
413 /// Additionally allows for timestamp queries to be used inside render & compute passes using:
414 /// - [`RenderPass::write_timestamp`]
415 /// - [`ComputePass::write_timestamp`]
416 ///
417 /// Supported platforms:
418 /// - Vulkan
419 /// - DX12
420 /// - Metal (AMD & Intel, not Apple GPUs)
421 /// - OpenGL (with GL_ARB_timer_query)
422 ///
423 /// This is generally not available on tile-based rasterization GPUs.
424 ///
425 /// This is a native only feature with a [proposal](https://github.com/gpuweb/gpuweb/blob/0008bd30da2366af88180b511a5d0d0c1dffbc36/proposals/timestamp-query-inside-passes.md) for the web.
426 ///
427 #[doc = link_to_wgpu_docs!(["`RenderPass::write_timestamp`"]: "struct.RenderPass.html#method.write_timestamp")]
428 #[doc = link_to_wgpu_docs!(["`ComputePass::write_timestamp`"]: "struct.ComputePass.html#method.write_timestamp")]
429 #[name("wgpu-timestamp-query-inside-passes", "timestamp-query-inside-passes")]
430 const TIMESTAMP_QUERY_INSIDE_PASSES = 1 << 6;
431 /// Webgpu only allows the MAP_READ and MAP_WRITE buffer usage to be matched with
432 /// COPY_DST and COPY_SRC respectively. This removes this requirement.
433 ///
434 /// This is only beneficial on systems that share memory between CPU and GPU. If enabled
435 /// on a system that doesn't, this can severely hinder performance. Only use if you understand
436 /// the consequences.
437 ///
438 /// Supported platforms:
439 /// - Vulkan
440 /// - DX12
441 /// - Metal
442 ///
443 /// This is a native only feature.
444 #[name("wgpu-mappable-primary-buffers", "mappable-primary-buffers")]
445 const MAPPABLE_PRIMARY_BUFFERS = 1 << 7;
446 /// Allows the user to create uniform arrays of textures in shaders:
447 ///
448 /// ex.
449 /// - `var textures: binding_array<texture_2d<f32>, 10>` (WGSL)
450 /// - `uniform texture2D textures[10]` (GLSL)
451 ///
452 /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
453 /// may also create uniform arrays of storage textures.
454 ///
455 /// ex.
456 /// - `var textures: array<texture_storage_2d<r32float, write>, 10>` (WGSL)
457 /// - `uniform image2D textures[10]` (GLSL)
458 ///
459 /// This capability allows them to exist and to be indexed by dynamically uniform
460 /// values.
461 ///
462 /// Supported platforms:
463 /// - DX12
464 /// - Metal (with MSL 2.0+ on macOS 10.13+)
465 /// - Vulkan
466 ///
467 /// This is a native only feature.
468 #[name("wgpu-texture-binding-array", "texture-binding-array")]
469 const TEXTURE_BINDING_ARRAY = 1 << 8;
470 /// Allows the user to create arrays of buffers in shaders:
471 ///
472 /// ex.
473 /// - `var<uniform> buffer_array: array<MyBuffer, 10>` (WGSL)
474 /// - `uniform myBuffer { ... } buffer_array[10]` (GLSL)
475 ///
476 /// This capability allows them to exist and to be indexed by dynamically uniform
477 /// values.
478 ///
479 /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
480 /// may also create arrays of storage buffers.
481 ///
482 /// ex.
483 /// - `var<storage> buffer_array: array<MyBuffer, 10>` (WGSL)
484 /// - `buffer myBuffer { ... } buffer_array[10]` (GLSL)
485 ///
486 /// Supported platforms:
487 /// - Vulkan
488 ///
489 /// This is a native only feature.
490 #[name("wgpu-buffer-binding-array", "buffer-binding-array")]
491 const BUFFER_BINDING_ARRAY = 1 << 9;
492 /// Allows the user to create uniform arrays of storage buffers or textures in shaders,
493 /// if resp. [`Features::BUFFER_BINDING_ARRAY`] or [`Features::TEXTURE_BINDING_ARRAY`]
494 /// is supported.
495 ///
496 /// This capability allows them to exist and to be indexed by dynamically uniform
497 /// values.
498 ///
499 /// Supported platforms:
500 /// - Metal (with MSL 2.2+ on macOS 10.13+)
501 /// - Vulkan
502 ///
503 /// This is a native only feature.
504 #[name("wgpu-storage-resource-binding-array", "storage-resource-binding-array")]
505 const STORAGE_RESOURCE_BINDING_ARRAY = 1 << 10;
506 /// Allows shaders to index sampled texture and storage buffer resource arrays with dynamically non-uniform values:
507 ///
508 /// ex. `texture_array[vertex_data]`
509 ///
510 /// In order to use this capability, the corresponding GLSL extension must be enabled like so:
511 ///
512 /// `#extension GL_EXT_nonuniform_qualifier : require`
513 ///
514 /// and then used either as `nonuniformEXT` qualifier in variable declaration:
515 ///
516 /// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
517 ///
518 /// or as `nonuniformEXT` constructor:
519 ///
520 /// ex. `texture_array[nonuniformEXT(vertex_data)]`
521 ///
522 /// WGSL and HLSL do not need any extension.
523 ///
524 /// Supported platforms:
525 /// - DX12
526 /// - Metal (with MSL 2.0+ on macOS 10.13+)
527 /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s shaderSampledImageArrayNonUniformIndexing & shaderStorageBufferArrayNonUniformIndexing feature)
528 ///
529 /// This is a native only feature.
530 #[name("wgpu-sampled-texture-and-storage-buffer-array-non-uniform-indexing", "sampled-texture-and-storage-buffer-array-non-uniform-indexing")]
531 const SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING = 1 << 11;
532 /// Allows shaders to index storage texture resource arrays with dynamically non-uniform values:
533 ///
534 /// ex. `texture_array[vertex_data]`
535 ///
536 /// Supported platforms:
537 /// - DX12
538 /// - Metal (with MSL 2.0+ on macOS 10.13+)
539 /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s shaderStorageTextureArrayNonUniformIndexing feature)
540 ///
541 /// This is a native only feature.
542 #[name("wgpu-storage-texture-array-non-uniform-indexing", "storage-texture-array-non-uniform-indexing")]
543 const STORAGE_TEXTURE_ARRAY_NON_UNIFORM_INDEXING = 1 << 12;
544 /// Allows the user to create bind groups containing arrays with less bindings than the BindGroupLayout.
545 ///
546 /// Supported platforms:
547 /// - Vulkan
548 /// - DX12
549 ///
550 /// This is a native only feature.
551 #[name("wgpu-partially-bound-binding-array", "partially-bound-binding-array")]
552 const PARTIALLY_BOUND_BINDING_ARRAY = 1 << 13;
553
554 /// Allows the user to print debug messages from shaders using `debugPrintf()`.
555 ///
556 /// Each WGSL module using `debugPrintf` must opt in with `enable wgpu_debug_printf;`.
557 /// See the [`debugPrintf` extension specification][debug_printf]
558 /// for the syntax, how to receive the output, and per-backend requirements.
559 ///
560 /// Supported platforms:
561 /// - Metal (3.2+, lowered to shader logging)
562 /// - Vulkan (lowered to SPIR-V `NonSemantic.DebugPrintf`; output requires the
563 /// validation layer's debug-printf path, enabled with
564 /// [`InstanceFlags::VALIDATION`](crate::InstanceFlags::VALIDATION) and
565 /// [`InstanceFlags::DEBUG_PRINTF`](crate::InstanceFlags::DEBUG_PRINTF))
566 ///
567 /// This is a native only feature.
568 ///
569 #[doc = link_to_wgpu_docs!(["debug_printf"]: "documentation/extensions/debug_printf/index.html")]
570 #[name("wgpu-debug-printf")]
571 const DEBUG_PRINTF = 1 << 14;
572
573 /// Allows the user to call [`RenderPass::multi_draw_indirect_count`] and [`RenderPass::multi_draw_indexed_indirect_count`].
574 ///
575 /// This allows the use of a buffer containing the actual number of draw calls. This feature being present also implies
576 /// that all calls to [`RenderPass::multi_draw_indirect`] and [`RenderPass::multi_draw_indexed_indirect`] are not being emulated
577 /// with a series of `draw_indirect` calls.
578 ///
579 /// Supported platforms:
580 /// - DX12
581 /// - Vulkan 1.2+ (or VK_KHR_draw_indirect_count)
582 ///
583 /// This is a native only feature.
584 ///
585 #[doc = link_to_wgpu_docs!(["`RenderPass::multi_draw_indirect`"]: "struct.RenderPass.html#method.multi_draw_indirect")]
586 #[doc = link_to_wgpu_docs!(["`RenderPass::multi_draw_indexed_indirect`"]: "struct.RenderPass.html#method.multi_draw_indexed_indirect")]
587 #[doc = link_to_wgpu_docs!(["`RenderPass::multi_draw_indirect_count`"]: "struct.RenderPass.html#method.multi_draw_indirect_count")]
588 #[doc = link_to_wgpu_docs!(["`RenderPass::multi_draw_indexed_indirect_count`"]: "struct.RenderPass.html#method.multi_draw_indexed_indirect_count")]
589 #[name("wgpu-multi-draw-indirect-count", "multi-draw-indirect-count")]
590 const MULTI_DRAW_INDIRECT_COUNT = 1 << 15;
591
592 // Bit 16 is available.
593
594 /// Allows the use of [`AddressMode::ClampToBorder`] with a border color
595 /// of [`SamplerBorderColor::Zero`].
596 ///
597 /// Supported platforms:
598 /// - DX12
599 /// - Vulkan
600 /// - Metal
601 /// - OpenGL
602 ///
603 /// This is a native only feature.
604 ///
605 /// [`AddressMode::ClampToBorder`]: super::AddressMode::ClampToBorder
606 /// [`SamplerBorderColor::Zero`]: super::SamplerBorderColor::Zero
607 #[name("wgpu-address-mode-clamp-to-zero", "address-mode-clamp-to-zero")]
608 const ADDRESS_MODE_CLAMP_TO_ZERO = 1 << 17;
609 /// Allows the use of [`AddressMode::ClampToBorder`] with a border color
610 /// other than [`SamplerBorderColor::Zero`].
611 ///
612 /// Supported platforms:
613 /// - DX12
614 /// - Vulkan
615 /// - Metal (macOS 10.12+ only)
616 /// - OpenGL
617 ///
618 /// This is a native only feature.
619 ///
620 /// [`AddressMode::ClampToBorder`]: super::AddressMode::ClampToBorder
621 /// [`SamplerBorderColor::Zero`]: super::SamplerBorderColor::Zero
622 #[name("wgpu-address-mode-clamp-to-border", "address-mode-clamp-to-border")]
623 const ADDRESS_MODE_CLAMP_TO_BORDER = 1 << 18;
624 /// Allows the user to set [`PolygonMode::Line`] in [`PrimitiveState::polygon_mode`]
625 ///
626 /// This allows drawing polygons/triangles as lines (wireframe) instead of filled
627 ///
628 /// Supported platforms:
629 /// - DX12
630 /// - Vulkan
631 /// - Metal
632 /// - OpenGL (not GLES)
633 ///
634 /// This is a native only feature.
635 ///
636 /// [`PrimitiveState::polygon_mode`]: super::PrimitiveState
637 /// [`PolygonMode::Line`]: super::PolygonMode::Line
638 #[name("wgpu-polygon-mode-line", "polygon-mode-line")]
639 const POLYGON_MODE_LINE = 1 << 19;
640 /// Allows the user to set [`PolygonMode::Point`] in [`PrimitiveState::polygon_mode`]
641 ///
642 /// This allows only drawing the vertices of polygons/triangles instead of filled
643 ///
644 /// Supported platforms:
645 /// - Vulkan
646 /// - OpenGL (not GLES)
647 ///
648 /// This is a native only feature.
649 ///
650 /// [`PrimitiveState::polygon_mode`]: super::PrimitiveState
651 /// [`PolygonMode::Point`]: super::PolygonMode::Point
652 #[name("wgpu-polygon-mode-point", "polygon-mode-point")]
653 const POLYGON_MODE_POINT = 1 << 20;
654 /// Allows the user to set a overestimation-conservative-rasterization in [`PrimitiveState::conservative`]
655 ///
656 /// Processing of degenerate triangles/lines is hardware specific.
657 /// Only triangles are supported.
658 ///
659 /// Supported platforms:
660 /// - Vulkan
661 ///
662 /// This is a native only feature.
663 ///
664 /// [`PrimitiveState::conservative`]: super::PrimitiveState::conservative
665 #[name("wgpu-conservative-rasterization", "conservative-rasterization")]
666 const CONSERVATIVE_RASTERIZATION = 1 << 21;
667 /// Enables bindings of writable storage buffers and textures visible to vertex shaders.
668 ///
669 /// Note: some (tiled-based) platforms do not support vertex shaders with any side-effects.
670 ///
671 /// Supported Platforms:
672 /// - All
673 ///
674 /// This is a native only feature.
675 #[name("wgpu-vertex-writable-storage", "vertex-writable-storage")]
676 const VERTEX_WRITABLE_STORAGE = 1 << 22;
677 /// Enables clear to zero for textures.
678 ///
679 /// Supported platforms:
680 /// - All
681 ///
682 /// This is a native only feature.
683 #[name("wgpu-clear-texture", "clear-texture")]
684 const CLEAR_TEXTURE = 1 << 23;
685
686 /// Allows for constructing ray tracing pipelines.
687 #[name("wgpu-ray-tracing-pipelines")]
688 const EXPERIMENTAL_RAY_TRACING_PIPELINES = 1 << 24;
689
690 /// ***THIS IS EXPERIMENTAL:*** Features enabled by this may have
691 /// major bugs in it and are expected to be subject to breaking changes, suggestions
692 /// for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/1040)
693 ///
694 /// Allows ray tracing pipeline shaders to use the `hit_object` type, the `hitObject*`
695 /// built-in functions, and `reorderThread`. Reordering lets the hardware group
696 /// invocations by the shader they are about to run, which improves coherence.
697 ///
698 /// Requires [`Features::EXPERIMENTAL_RAY_TRACING_PIPELINES`], and
699 /// `enable wgpu_ray_tracing_invocation_reorder;` in WGSL shaders.
700 ///
701 /// `reorderThread` may have no effect. If
702 /// [`Adapter::ray_tracing_invocation_reorder_mode`] returns
703 /// [`RayTracingInvocationReorderMode::Reorder`], the implementation reports that it is
704 /// likely to reorder invocations.
705 ///
706 /// Supported platforms:
707 /// - Vulkan (with [VK_EXT_ray_tracing_invocation_reorder](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_ray_tracing_invocation_reorder.html))
708 ///
709 /// This is a native only feature.
710 ///
711 #[doc = link_to_wgpu_docs!(["`Adapter::ray_tracing_invocation_reorder_mode`"]: "struct.Adapter.html#method.ray_tracing_invocation_reorder_mode")]
712 /// [`RayTracingInvocationReorderMode::Reorder`]: crate::RayTracingInvocationReorderMode::Reorder
713 #[name("wgpu-ray-tracing-invocation-reorder")]
714 const EXPERIMENTAL_RAY_TRACING_INVOCATION_REORDER = 1 << 25;
715
716 /// Enables multiview render passes and `builtin(view_index)` in vertex/mesh shaders.
717 ///
718 /// Supported platforms:
719 /// - Vulkan
720 /// - Metal
721 /// - DX12
722 /// - OpenGL (web only)
723 ///
724 /// This is a native only feature.
725 #[name("wgpu-multiview", "multiview")]
726 const MULTIVIEW = 1 << 26;
727 /// Enables using 64-bit types for vertex attributes.
728 ///
729 /// Requires SHADER_FLOAT64.
730 ///
731 /// Supported Platforms: N/A
732 ///
733 /// This is a native only feature.
734 #[name("wgpu-vertex-attribute-64-bit", "vertex-attribute-64-bit")]
735 const VERTEX_ATTRIBUTE_64BIT = 1 << 27;
736 /// Enables image atomic fetch add, and, xor, or, min, and max for R32Uint and R32Sint textures.
737 ///
738 /// Supported platforms:
739 /// - Vulkan
740 /// - DX12
741 /// - Metal (with MSL 3.1+)
742 ///
743 /// This is a native only feature.
744 #[name("wgpu-texture-atomic")]
745 const TEXTURE_ATOMIC = 1 << 28;
746 /// Allows for creation of textures of format [`TextureFormat::NV12`]
747 ///
748 /// Supported platforms:
749 /// - DX12
750 /// - Vulkan
751 /// - Metal (simulated)
752 ///
753 /// This is a native only feature.
754 ///
755 /// [`TextureFormat::NV12`]: super::TextureFormat::NV12
756 #[name("wgpu-texture-format-nv12")]
757 const TEXTURE_FORMAT_NV12 = 1 << 29;
758 /// Allows for creation of textures of format [`TextureFormat::P010`]
759 ///
760 /// Supported platforms:
761 /// - DX12
762 /// - Vulkan
763 /// - Metal
764 ///
765 /// This is a native only feature.
766 ///
767 /// [`TextureFormat::P010`]: super::TextureFormat::P010
768 #[name("wgpu-texture-format-p010")]
769 const TEXTURE_FORMAT_P010 = 1 << 30;
770
771 /// Allows for the creation and usage of `ExternalTexture`s, and bind
772 /// group layouts containing external texture `BindingType`s.
773 ///
774 /// Conceptually this should really be a [`crate::DownlevelFlags`] as
775 /// it corresponds to WebGPU's [`GPUExternalTexture`](
776 /// https://www.w3.org/TR/webgpu/#gpuexternaltexture).
777 /// However, the implementation is currently in-progress, and until it
778 /// is complete we do not want applications to ignore adapters due to
779 /// a missing downlevel flag, when they may not require this feature at
780 /// all.
781 ///
782 /// Supported platforms:
783 /// - DX12
784 /// - Metal
785 #[name("wgpu-external-texture", "external-texture")]
786 const EXTERNAL_TEXTURE = 1 << 31;
787
788 // Shader:
789
790 /// ***THIS IS EXPERIMENTAL:*** Features enabled by this may have
791 /// major bugs in it and are expected to be subject to breaking changes, suggestions
792 /// for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/1040)
793 ///
794 /// Allows for the creation of ray-tracing queries within shaders.
795 ///
796 /// Supported platforms:
797 /// - Vulkan
798 ///
799 /// This is a native-only feature.
800 #[name("wgpu-ray-query")]
801 const EXPERIMENTAL_RAY_QUERY = 1 << 32;
802 /// Enables 64-bit floating point types in SPIR-V shaders.
803 ///
804 /// Note: even when supported by GPU hardware, 64-bit floating point operations are
805 /// frequently between 16 and 64 _times_ slower than equivalent operations on 32-bit floats.
806 ///
807 /// Supported Platforms:
808 /// - Vulkan
809 ///
810 /// This is a native only feature.
811 #[name("wgpu-shader-f64", "shader-f64")]
812 const SHADER_F64 = 1 << 33;
813 /// Allows shaders to use `i16` and `u16` 16-bit integer types.
814 ///
815 /// Requires `enable wgpu_int16;` in WGSL shaders.
816 ///
817 /// Supported platforms:
818 /// - Vulkan (with `shaderInt16` and `VK_KHR_16bit_storage`)
819 /// - Metal (always available)
820 /// - DX12 (with `Native16BitShaderOpsSupported`, SM 6.2+)
821 ///
822 /// This is a native only feature.
823 #[name("wgpu-shader-i16", "shader-i16")]
824 const SHADER_I16 = 1 << 34;
825
826 // Bit 35 is available.
827
828 /// Allows shaders to use the `early_depth_test` attribute.
829 ///
830 /// The attribute is applied to the fragment shader entry point. It can be used in two
831 /// ways:
832 ///
833 /// 1. Force early depth/stencil tests:
834 ///
835 /// - `@early_depth_test(force)` (WGSL)
836 ///
837 /// - `layout(early_fragment_tests) in;` (GLSL)
838 ///
839 /// - `[[early_fragment_tests]]` (MSL 1.2+)
840 ///
841 /// - `[earlydepthstencil]` (HLSL)
842 ///
843 /// 2. Provide a conservative depth specifier that allows an additional early
844 /// depth test under certain conditions:
845 ///
846 /// - `@early_depth_test(greater_equal/less_equal/unchanged)` (WGSL)
847 ///
848 /// - `layout(depth_<greater/less/unchanged>) out float gl_FragDepth;` (GLSL)
849 ///
850 /// - `[[depth(greater/less)]]` (MSL, any version)
851 ///
852 /// - `SV_Depth<GreaterEqual/LessEqual>` (HLSL), for pipelines that are not
853 /// multisampled. Multisampled pipelines use an unrestricted `SV_Depth` instead.
854 ///
855 /// See [`EarlyDepthTest`] for more details.
856 ///
857 /// Supported platforms:
858 /// - Vulkan
859 /// - Metal (with MSL 1.2+)
860 /// - DX12
861 /// - GLES 3.1+
862 ///
863 /// This is a native only feature.
864 ///
865 /// [`EarlyDepthTest`]: https://docs.rs/naga/latest/naga/ir/enum.EarlyDepthTest.html
866 #[name("wgpu-shader-early-depth-test", "shader-early-depth-test")]
867 const SHADER_EARLY_DEPTH_TEST = 1 << 36;
868 /// Allows shaders to use i64 and u64.
869 ///
870 /// Supported platforms:
871 /// - Vulkan
872 /// - DX12 (DXC only)
873 /// - Metal (with MSL 2.3+)
874 ///
875 /// This is a native only feature.
876 #[name("wgpu-shader-int64")]
877 const SHADER_INT64 = 1 << 37;
878 /// Allows compute and fragment shaders to use the subgroup operation
879 /// built-ins and perform subgroup operations (except barriers).
880 ///
881 /// Supported Platforms:
882 /// - Vulkan
883 /// - DX12
884 /// - Metal
885 /// - WebGPU
886 ///
887 /// The `subgroups` feature has been added to WebGPU, but there may be
888 /// differences between the standard and the `wgpu` implementation,
889 /// so it has not yet been moved to [`FeaturesWebGPU`].
890 /// See <https://github.com/gfx-rs/wgpu/issues/5555>.
891 ///
892 /// Because it is expected to move to the WebGPU feature set in the
893 /// not-too-distant future, the name omits the `wgpu-` prefix.
894 #[name("subgroups")]
895 const SUBGROUP = 1 << 38;
896 /// Allows vertex shaders to use the subgroup operation built-ins and
897 /// perform subgroup operations (except barriers).
898 ///
899 /// Supported Platforms:
900 /// - Vulkan
901 ///
902 /// This is a native only feature.
903 #[name("wgpu-subgroup-vertex")]
904 const SUBGROUP_VERTEX = 1 << 39;
905 /// Allows compute shaders to use the subgroup barrier.
906 ///
907 /// Requires [`Features::SUBGROUP`]. Without it, enables nothing.
908 ///
909 /// Supported Platforms:
910 /// - Vulkan
911 /// - Metal
912 ///
913 /// This is a native only feature.
914 #[name("wgpu-subgroup-barrier")]
915 const SUBGROUP_BARRIER = 1 << 40;
916 /// Allows the use of pipeline cache objects
917 ///
918 /// Supported platforms:
919 /// - Vulkan
920 ///
921 /// Unimplemented Platforms:
922 /// - DX12
923 /// - Metal
924 #[name("wgpu-pipeline-cache")]
925 const PIPELINE_CACHE = 1 << 41;
926 /// Allows shaders to use i64 and u64 atomic min and max.
927 ///
928 /// Supported platforms:
929 /// - Vulkan (with VK_KHR_shader_atomic_int64)
930 /// - DX12 (with SM 6.6+)
931 /// - Metal (with MSL 2.4+)
932 ///
933 /// This is a native only feature.
934 #[name("wgpu-shader-int64-atomic-min-max")]
935 const SHADER_INT64_ATOMIC_MIN_MAX = 1 << 42;
936 /// Allows shaders to use all i64 and u64 atomic operations.
937 ///
938 /// Supported platforms:
939 /// - Vulkan (with VK_KHR_shader_atomic_int64)
940 /// - DX12 (with SM 6.6+)
941 ///
942 /// This is a native only feature.
943 #[name("wgpu-shader-int64-atomic-all-ops")]
944 const SHADER_INT64_ATOMIC_ALL_OPS = 1 << 43;
945
946 // Bit 44 is available.
947
948 // Bit 45 is available.
949
950 /// Enables R64Uint image atomic min and max.
951 ///
952 /// Supported platforms:
953 /// - Vulkan (with VK_EXT_shader_image_atomic_int64)
954 /// - DX12 (with SM 6.6+)
955 /// - Metal (with MSL 3.1+; Apple8 on macOS or Apple9+)
956 ///
957 /// This is a native only feature.
958 #[name("wgpu-texture-int64-atomic")]
959 const TEXTURE_INT64_ATOMIC = 1 << 46;
960
961 /// Allows uniform buffers to be bound as binding arrays.
962 ///
963 /// This allows:
964 /// - Shaders to contain `var<uniform> buffer: binding_array<UniformBuffer>;`
965 /// - The `count` field of `BindGroupLayoutEntry`s with `Uniform` buffers, to be set to `Some`.
966 ///
967 /// Supported platforms:
968 /// - None (<https://github.com/gfx-rs/wgpu/issues/7149>)
969 ///
970 /// Potential Platforms:
971 /// - DX12
972 /// - Metal
973 /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s `shaderUniformBufferArrayNonUniformIndexing` feature)
974 ///
975 /// This is a native only feature.
976 #[name("wgpu-uniform-buffer-binding-arrays", "uniform-buffer-binding-arrays")]
977 const UNIFORM_BUFFER_BINDING_ARRAYS = 1 << 47;
978
979 /// Enables mesh shaders and task shaders in mesh shader pipelines. This extension does NOT imply support for
980 /// compiling mesh shaders at runtime.
981 ///
982 /// Supported platforms:
983 /// - Vulkan (with [VK_EXT_mesh_shader](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_mesh_shader.html))
984 /// - DX12
985 /// - Metal
986 ///
987 /// Naga is only supported on vulkan. On other platforms you will have to use passthrough shaders.
988 ///
989 /// It is recommended to use [`Device::create_shader_module_trusted`] with [`ShaderRuntimeChecks::unchecked()`]
990 /// to avoid workgroup memory zero initialization, which can be expensive due to zero initialization being
991 /// single-threaded currently.
992 ///
993 /// Some Mesa drivers including LLVMPIPE but not RADV fail to run the naga generated code.
994 /// [This may be our bug and will be investigated.](https://github.com/gfx-rs/wgpu/issues/8727)
995 /// However, due to the nature of the failure, the fact that it is unique, and the random changes
996 /// that make it go away, this is believed to be a Mesa bug. See
997 /// [this Mesa issue.](https://gitlab.freedesktop.org/mesa/mesa/-/issues/14376)
998 ///
999 /// This is a native only feature.
1000 ///
1001 /// [`Device::create_shader_module_trusted`]: https://docs.rs/wgpu/latest/wgpu/struct.Device.html#method.create_shader_module_trusted
1002 /// [`ShaderRuntimeChecks::unchecked()`]: crate::ShaderRuntimeChecks::unchecked
1003 #[name("wgpu-mesh-shader")]
1004 const EXPERIMENTAL_MESH_SHADER = 1 << 48;
1005
1006 /// ***THIS IS EXPERIMENTAL:*** Features enabled by this may have
1007 /// major bugs in them and are expected to be subject to breaking changes, suggestions
1008 /// for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/6762)
1009 ///
1010 /// Allows for returning of the hit triangle's vertex position when tracing with an
1011 /// acceleration structure marked with [`AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN`].
1012 ///
1013 /// Supported platforms:
1014 /// - Vulkan
1015 ///
1016 /// This is a native only feature
1017 ///
1018 /// [`AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN`]: super::AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN
1019 #[name("wgpu-ray-hit-vertex-return")]
1020 const EXPERIMENTAL_RAY_HIT_VERTEX_RETURN = 1 << 49;
1021
1022 /// Enables multiview in mesh shader pipelines
1023 ///
1024 /// Supported platforms:
1025 /// - Vulkan (with [VK_EXT_mesh_shader](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_mesh_shader.html))
1026 ///
1027 /// Potential Platforms:
1028 /// - DX12
1029 /// - Metal
1030 ///
1031 /// This is a native only feature.
1032 #[name("wgpu-mesh-shader-multiview")]
1033 const EXPERIMENTAL_MESH_SHADER_MULTIVIEW = 1 << 50;
1034
1035 /// Allows usage of additional vertex formats in [BlasTriangleGeometrySizeDescriptor::vertex_format]
1036 ///
1037 /// Supported platforms
1038 /// - Vulkan
1039 /// - DX12
1040 ///
1041 /// [BlasTriangleGeometrySizeDescriptor::vertex_format]: super::BlasTriangleGeometrySizeDescriptor
1042 #[name("wgpu-extended-acceleration-structure-vertex-formats")]
1043 const EXTENDED_ACCELERATION_STRUCTURE_VERTEX_FORMATS = 1 << 51;
1044
1045 /// Enables creating shaders from passthrough with reflection info (unsafe)
1046 ///
1047 /// Allows using [`Device::create_shader_module_passthrough`].
1048 /// Shader code isn't parsed or interpreted in any way. It is the user's
1049 /// responsibility to ensure the code and reflection (if passed) are correct.
1050 ///
1051 /// Supported platforms
1052 /// - Vulkan
1053 /// - DX12
1054 /// - Metal
1055 /// - WebGPU
1056 ///
1057 /// Ideally, in the future, all platforms will be supported. For more info, see
1058 /// [this comment](https://github.com/gfx-rs/wgpu/issues/3103#issuecomment-2833058367).
1059 ///
1060 #[doc = link_to_wgpu_docs!(["`Device::create_shader_module_passthrough`"]: "struct.Device.html#method.create_shader_module_passthrough")]
1061 #[name("wgpu-passthrough-shaders", "passthrough-shaders")]
1062 const PASSTHROUGH_SHADERS = 1 << 52;
1063
1064 /// Enables shader barycentric coordinates.
1065 ///
1066 /// Supported platforms:
1067 /// - Vulkan (with VK_KHR_fragment_shader_barycentric)
1068 /// - DX12 (with SM 6.1+)
1069 /// - Metal (with MSL 2.2+)
1070 ///
1071 /// This is a native only feature.
1072 #[name("wgpu-shader-barycentrics")]
1073 const SHADER_BARYCENTRICS = 1 << 53;
1074
1075 /// Enables using multiview where not all texture array layers are rendered to in a single render pass/render pipeline. Making
1076 /// use of this feature also requires enabling `Features::MULTIVIEW`.
1077 ///
1078 /// Supported platforms
1079 /// - Vulkan
1080 /// - DX12
1081 ///
1082 ///
1083 /// While metal supports this in theory, the behavior of `view_index` differs from vulkan and dx12 so the feature isn't exposed.
1084 #[name("wgpu-selective-multiview")]
1085 const SELECTIVE_MULTIVIEW = 1 << 54;
1086
1087 /// Enables the use of point-primitive outputs from mesh shaders. Making use of this feature also requires enabling
1088 /// `Features::EXPERIMENTAL_MESH_SHADER`.
1089 ///
1090 /// Supported platforms
1091 /// - Vulkan
1092 /// - Metal
1093 ///
1094 /// This is a native only feature.
1095 #[name("wgpu-mesh-shader-points")]
1096 const EXPERIMENTAL_MESH_SHADER_POINTS = 1 << 55;
1097
1098 /// Enables creating texture arrays that are also multisampled.
1099 ///
1100 /// Without this feature, you cannot create a texture that has both a `sample_count` higher
1101 /// than 1, and a `depth_or_array_layers` higher than 1.
1102 ///
1103 /// Supported platforms:
1104 /// - Vulkan (except VK_KHR_portability_subset if multisampleArrayImage is not available)
1105 /// - Metal (with macos 10.14+, ios 14.0+, tvos 16.0+, visionos 1.0+)
1106 #[name("wgpu-multisample-array")]
1107 const MULTISAMPLE_ARRAY = 1 << 56;
1108
1109 /// Enables cooperative matrix operations (also known as tensor cores on NVIDIA GPUs
1110 /// or simdgroup matrix operations on Apple GPUs).
1111 ///
1112 /// Cooperative matrices allow a workgroup to collectively load, store, and perform
1113 /// matrix multiply-accumulate operations on small tiles of data, enabling
1114 /// hardware-accelerated matrix math.
1115 ///
1116 /// **Current limitations:** The implementation currently only supports 8x8 f32 matrices.
1117 /// On Vulkan, support is determined by querying `vkGetPhysicalDeviceCooperativeMatrixPropertiesKHR`
1118 /// for configurations matching 8x8x8 f32. Most Vulkan implementations (NVIDIA, AMD) primarily
1119 /// support f16 inputs at larger sizes (e.g., 16x16), so Vulkan support may be limited.
1120 ///
1121 /// Supported platforms:
1122 /// - Metal (with MSL 2.3+ and Apple7+/Mac2+, using simdgroup matrix operations)
1123 /// - Vulkan (with [VK_KHR_cooperative_matrix](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_cooperative_matrix.html), if 8x8 f32 is supported)
1124 ///
1125 /// This is a native only feature.
1126 #[name("wgpu-cooperative-matrix")]
1127 const EXPERIMENTAL_COOPERATIVE_MATRIX = 1 << 57;
1128
1129 /// Enables shader per-vertex attributes.
1130 ///
1131 /// Supported platforms:
1132 /// - Vulkan (with VK_KHR_fragment_shader_barycentric)
1133 ///
1134 /// This is a native only feature.
1135 #[name("wgpu-shader-per-vertex")]
1136 const SHADER_PER_VERTEX = 1 << 58;
1137
1138 /// Enables shader `draw_index` builtin.
1139 ///
1140 /// Supported platforms:
1141 /// - GLES
1142 /// - Vulkan
1143 ///
1144 /// Potential platforms:
1145 /// - DX12
1146 /// - Metal
1147 ///
1148 /// This is a native only feature.
1149 #[name("wgpu-shader-draw-index")]
1150 const SHADER_DRAW_INDEX = 1 << 59;
1151 /// Allows the user to create arrays of acceleration structures in shaders:
1152 ///
1153 /// ex.
1154 /// - `var tlas: binding_array<acceleration_structure, 10>` (WGSL)
1155 ///
1156 /// This capability allows them to exist and to be indexed by dynamically uniform values.
1157 ///
1158 /// Supported platforms:
1159 /// - DX12
1160 /// - Vulkan
1161 ///
1162 /// This is a native only feature.
1163 #[name("wgpu-acceleration-structure-binding-array")]
1164 const ACCELERATION_STRUCTURE_BINDING_ARRAY = 1 << 60;
1165
1166 /// Enables the `@coherent` memory decoration on storage buffer variables.
1167 ///
1168 /// Backend mapping:
1169 /// - Vulkan
1170 /// - DX12
1171 /// - Metal (3.2+)
1172 /// - GLES (ES 3.1+ / GL 4.3+)
1173 ///
1174 /// This is a native only feature.
1175 #[name("wgpu-memory-decoration-coherent")]
1176 const MEMORY_DECORATION_COHERENT = 1 << 61;
1177
1178 /// Enables the `@volatile` memory decoration on storage buffer variables.
1179 ///
1180 /// Backend mapping:
1181 /// - Vulkan
1182 /// - GLES (ES 3.1+ / GL 4.3+)
1183 ///
1184 /// This is a native only feature.
1185 #[name("wgpu-memory-decoration-volatile")]
1186 const MEMORY_DECORATION_VOLATILE = 1 << 62;
1187
1188 /// Allows [`TexelCopyBufferLayout::bytes_per_row`] in `copy_buffer_to_texture` and
1189 /// `copy_texture_to_buffer` to be any multiple of the texel block copy size, instead of a
1190 /// multiple of [`COPY_BYTES_PER_ROW_ALIGNMENT`] (256).
1191 ///
1192 /// Supported platforms:
1193 /// - Vulkan
1194 /// - Metal
1195 /// - GLES
1196 /// - DX12 (with `UnrestrictedBufferTextureCopyPitchSupported`)
1197 ///
1198 /// This is a native only feature.
1199 ///
1200 /// [`TexelCopyBufferLayout::bytes_per_row`]: crate::TexelCopyBufferLayout::bytes_per_row
1201 /// [`COPY_BYTES_PER_ROW_ALIGNMENT`]: crate::COPY_BYTES_PER_ROW_ALIGNMENT
1202 #[name("wgpu-unrestricted-bytes-per-row")]
1203 const UNRESTRICTED_BYTES_PER_ROW = 1 << 63;
1204
1205 // Search for "is available" to check for free bits earlier in the list.
1206 }
1207
1208 /// Features that are not guaranteed to be supported.
1209 ///
1210 /// These are part of the WebGPU standard. For all features, see [`Features`].
1211 ///
1212 /// If you want to use a feature, you need to first verify that the adapter supports
1213 /// the feature. If the adapter does not support the feature, requesting a device with it enabled
1214 /// will panic.
1215 ///
1216 /// Corresponds to [WebGPU `GPUFeatureName`](
1217 /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
1218 #[repr(transparent)]
1219 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
1220 #[cfg_attr(feature = "serde", serde(transparent))]
1221 #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
1222 pub struct FeaturesWebGPU features_webgpu {
1223 // API:
1224
1225 /// Core features and limits that are guaranteed to be supported by all WebGPU specification-compliant adapters.
1226 /// This feature is always enabled on adapters for which [`crate::DownlevelCapabilities::is_webgpu_compliant`] returns `true`.
1227 ///
1228 /// This is a web and native feature.
1229 #[name("core-features-and-limits")]
1230 #[web(allow)]
1231 const CORE_FEATURES_AND_LIMITS = WEBGPU_FEATURE_CORE_FEATURES_AND_LIMITS;
1232
1233 /// By default, polygon depth is clipped to 0-1 range before/during rasterization.
1234 /// Anything outside of that range is rejected, and respective fragments are not touched.
1235 ///
1236 /// With this extension, we can disabling clipping. That allows
1237 /// shadow map occluders to be rendered into a tighter depth range.
1238 ///
1239 /// Supported platforms:
1240 /// - desktops
1241 /// - some mobile chips
1242 /// - WebGPU
1243 ///
1244 /// This is a web and native feature.
1245 #[name("depth-clip-control")]
1246 #[web(allow)]
1247 const DEPTH_CLIP_CONTROL = WEBGPU_FEATURE_DEPTH_CLIP_CONTROL;
1248
1249 /// Allows for explicit creation of textures of format [`TextureFormat::Depth32FloatStencil8`]
1250 ///
1251 /// Supported platforms:
1252 /// - Vulkan (mostly)
1253 /// - DX12
1254 /// - Metal
1255 /// - OpenGL
1256 /// - WebGPU
1257 ///
1258 /// This is a web and native feature.
1259 ///
1260 /// [`TextureFormat::Depth32FloatStencil8`]: super::TextureFormat::Depth32FloatStencil8
1261 #[name("depth32float-stencil8")]
1262 #[web(allow)]
1263 const DEPTH32FLOAT_STENCIL8 = WEBGPU_FEATURE_DEPTH32FLOAT_STENCIL8;
1264
1265 /// Enables BCn family of compressed textures. All BCn textures use 4x4 pixel blocks
1266 /// with 8 or 16 bytes per block.
1267 ///
1268 /// Compressed textures sacrifice some quality in exchange for significantly reduced
1269 /// bandwidth usage.
1270 ///
1271 /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for BCn formats.
1272 /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1273 ///
1274 /// This feature guarantees availability of sliced-3d textures for BC formats when combined with TEXTURE_COMPRESSION_BC_SLICED_3D.
1275 ///
1276 /// Supported Platforms:
1277 /// - desktops
1278 /// - Mobile (All Apple9 and some Apple7 and Apple8 devices)
1279 /// - WebGPU
1280 ///
1281 /// This is a web and native feature.
1282 #[name("texture-compression-bc")]
1283 #[web(allow)]
1284 const TEXTURE_COMPRESSION_BC = WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC;
1285
1286
1287 /// Allows the 3d dimension for textures with BC compressed formats.
1288 ///
1289 /// This feature must be used in combination with TEXTURE_COMPRESSION_BC to enable 3D textures with BC compression.
1290 /// It does not enable the BC formats by itself.
1291 ///
1292 /// Supported Platforms:
1293 /// - desktops
1294 /// - Mobile (All Apple9 and some Apple7 and Apple8 devices)
1295 /// - WebGPU
1296 ///
1297 /// This is a web and native feature.
1298 #[name("texture-compression-bc-sliced-3d")]
1299 #[web(allow)]
1300 const TEXTURE_COMPRESSION_BC_SLICED_3D = WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC_SLICED_3D;
1301
1302 /// Enables ETC family of compressed textures. All ETC textures use 4x4 pixel blocks.
1303 /// ETC2 RGB and RGBA1 are 8 bytes per block. RTC2 RGBA8 and EAC are 16 bytes per block.
1304 ///
1305 /// Compressed textures sacrifice some quality in exchange for significantly reduced
1306 /// bandwidth usage.
1307 ///
1308 /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ETC2 formats.
1309 /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1310 ///
1311 /// Supported Platforms:
1312 /// - Vulkan on Intel
1313 /// - Mobile (some)
1314 /// - WebGPU
1315 ///
1316 /// This is a web and native feature.
1317 #[name("texture-compression-etc2")]
1318 #[web(allow)]
1319 const TEXTURE_COMPRESSION_ETC2 = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ETC2;
1320
1321 /// Enables ASTC family of compressed textures. ASTC textures use pixel blocks varying from 4x4 to 12x12.
1322 /// Blocks are always 16 bytes.
1323 ///
1324 /// Compressed textures sacrifice some quality in exchange for significantly reduced
1325 /// bandwidth usage.
1326 ///
1327 /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ASTC formats with Unorm/UnormSrgb channel type.
1328 /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1329 ///
1330 /// This feature does not guarantee availability of sliced 3d textures for ASTC formats.
1331 /// If available, 3d support can be enabled by TEXTURE_COMPRESSION_ASTC_SLICED_3D feature.
1332 ///
1333 /// Supported Platforms:
1334 /// - Vulkan on Intel
1335 /// - Mobile (some)
1336 /// - WebGPU
1337 ///
1338 /// This is a web and native feature.
1339 #[name("texture-compression-astc")]
1340 #[web(allow)]
1341 const TEXTURE_COMPRESSION_ASTC = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC;
1342
1343
1344 /// Allows the 3d dimension for textures with ASTC compressed formats.
1345 ///
1346 /// This feature must be used in combination with TEXTURE_COMPRESSION_ASTC to enable 3D textures with ASTC compression.
1347 /// It does not enable the ASTC formats by itself.
1348 ///
1349 /// Supported Platforms:
1350 /// - Vulkan (some)
1351 /// - Metal on Apple3+
1352 /// - OpenGL/WebGL (some)
1353 /// - WebGPU
1354 ///
1355 /// Not Supported:
1356 /// - DX12
1357 ///
1358 /// This is a web and native feature.
1359 #[name("texture-compression-astc-sliced-3d")]
1360 #[web(allow)]
1361 const TEXTURE_COMPRESSION_ASTC_SLICED_3D = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC_SLICED_3D;
1362
1363 /// Enables use of Timestamp Queries. These queries tell the current gpu timestamp when
1364 /// all work before the query is finished.
1365 ///
1366 /// This feature allows the use of
1367 /// - [`RenderPassDescriptor::timestamp_writes`]
1368 /// - [`ComputePassDescriptor::timestamp_writes`]
1369 /// to write out timestamps.
1370 ///
1371 /// For arbitrary timestamp write commands on encoders refer to [`Features::TIMESTAMP_QUERY_INSIDE_ENCODERS`].
1372 /// For arbitrary timestamp write commands on passes refer to [`Features::TIMESTAMP_QUERY_INSIDE_PASSES`].
1373 ///
1374 /// They must be resolved using [`CommandEncoder::resolve_query_set`] into a buffer,
1375 /// then the result must be multiplied by the timestamp period [`Queue::get_timestamp_period`]
1376 /// to get the timestamp in nanoseconds. Multiple timestamps can then be diffed to get the
1377 /// time for operations between them to finish.
1378 ///
1379 /// Supported Platforms:
1380 /// - Vulkan
1381 /// - DX12
1382 /// - Metal
1383 /// - OpenGL (with GL_ARB_timer_query)
1384 /// - WebGPU
1385 ///
1386 /// This is a web and native feature.
1387 ///
1388 #[doc = link_to_wgpu_docs!(["`RenderPassDescriptor::timestamp_writes`"]: "struct.RenderPassDescriptor.html#structfield.timestamp_writes")]
1389 #[doc = link_to_wgpu_docs!(["`ComputePassDescriptor::timestamp_writes`"]: "struct.ComputePassDescriptor.html#structfield.timestamp_writes")]
1390 #[doc = link_to_wgpu_docs!(["`CommandEncoder::resolve_query_set`"]: "struct.CommandEncoder.html#method.resolve_query_set")]
1391 #[doc = link_to_wgpu_docs!(["`Queue::get_timestamp_period`"]: "struct.Queue.html#method.get_timestamp_period")]
1392 #[name("timestamp-query")]
1393 #[web(allow)]
1394 const TIMESTAMP_QUERY = WEBGPU_FEATURE_TIMESTAMP_QUERY;
1395
1396 /// Allows non-zero value for the `first_instance` member in indirect draw calls.
1397 ///
1398 /// If this feature is not enabled, and the `first_instance` member is non-zero, the behavior may be:
1399 /// - The draw call is ignored.
1400 /// - The draw call is executed as if the `first_instance` is zero.
1401 /// - The draw call is executed with the correct `first_instance` value.
1402 ///
1403 /// Supported Platforms:
1404 /// - Vulkan (mostly)
1405 /// - DX12
1406 /// - Metal on Apple3+ or Mac1+
1407 /// - OpenGL (Desktop 4.2+ with ARB_shader_draw_parameters only)
1408 /// - WebGPU
1409 ///
1410 /// Not Supported:
1411 /// - OpenGL ES / WebGL
1412 ///
1413 /// This is a web and native feature.
1414 #[name("indirect-first-instance")]
1415 #[web(allow)]
1416 const INDIRECT_FIRST_INSTANCE = WEBGPU_FEATURE_INDIRECT_FIRST_INSTANCE;
1417
1418 /// Allows shaders to use 16-bit floating point types. You may use them uniform buffers,
1419 /// storage buffers, and local variables. You may not use them in immediates.
1420 ///
1421 /// In order to use this in WGSL shaders, you must add `enable f16;` to the top of your shader,
1422 /// before any global items.
1423 ///
1424 /// Supported Platforms:
1425 /// - Vulkan
1426 /// - Metal
1427 /// - DX12
1428 /// - WebGPU
1429 ///
1430 /// This is a web and native feature.
1431 #[name("shader-f16")]
1432 #[web(allow)]
1433 const SHADER_F16 = WEBGPU_FEATURE_SHADER_F16;
1434
1435 /// Allows for usage of textures of format [`TextureFormat::Rg11b10Ufloat`] as a render target
1436 ///
1437 /// Supported platforms:
1438 /// - Vulkan
1439 /// - DX12
1440 /// - Metal
1441 /// - WebGPU
1442 ///
1443 /// This is a web and native feature.
1444 ///
1445 /// [`TextureFormat::Rg11b10Ufloat`]: super::TextureFormat::Rg11b10Ufloat
1446 #[name("rg11b10ufloat-renderable")]
1447 #[web(allow)]
1448 const RG11B10UFLOAT_RENDERABLE = WEBGPU_FEATURE_RG11B10UFLOAT_RENDERABLE;
1449
1450 /// Allows the [`TextureUsages::STORAGE_BINDING`] usage on textures with format [`TextureFormat::Bgra8Unorm`]
1451 ///
1452 /// Supported Platforms:
1453 /// - Vulkan
1454 /// - DX12
1455 /// - Metal
1456 /// - WebGPU
1457 ///
1458 /// This is a web and native feature.
1459 ///
1460 /// [`TextureFormat::Bgra8Unorm`]: super::TextureFormat::Bgra8Unorm
1461 /// [`TextureUsages::STORAGE_BINDING`]: super::TextureUsages::STORAGE_BINDING
1462 #[name("bgra8unorm-storage")]
1463 #[web(allow)]
1464 const BGRA8UNORM_STORAGE = WEBGPU_FEATURE_BGRA8UNORM_STORAGE;
1465
1466
1467 /// Allows textures with formats "r32float", "rg32float", and "rgba32float" to be filterable.
1468 ///
1469 /// Supported Platforms:
1470 /// - Vulkan (mainly on Desktop GPUs)
1471 /// - DX12
1472 /// - Metal on macOS or Apple9+ GPUs, optional on iOS/iPadOS with Apple7/8 GPUs
1473 /// - GL with one of `GL_ARB_color_buffer_float`/`GL_EXT_color_buffer_float`/`OES_texture_float_linear`
1474 /// - WebGPU
1475 ///
1476 /// This is a web and native feature.
1477 #[name("float32-filterable")]
1478 #[web(allow)]
1479 const FLOAT32_FILTERABLE = WEBGPU_FEATURE_FLOAT32_FILTERABLE;
1480
1481 /// Allows textures with formats "r32float", "rg32float", and "rgba32float" to be blendable.
1482 ///
1483 /// Supported Platforms:
1484 /// - Vulkan
1485 /// - WebGPU
1486 #[name("float32-blendable")]
1487 #[web(allow)]
1488 const FLOAT32_BLENDABLE = WEBGPU_FEATURE_FLOAT32_BLENDABLE;
1489
1490 /// Allows two outputs from a shader to be used for blending.
1491 /// Note that dual-source blending doesn't support multiple render targets.
1492 ///
1493 /// For more info see the OpenGL ES extension GL_EXT_blend_func_extended.
1494 ///
1495 /// Supported platforms:
1496 /// - OpenGL ES (with GL_EXT_blend_func_extended)
1497 /// - Metal (with MSL 1.2+)
1498 /// - Vulkan (with dualSrcBlend)
1499 /// - DX12
1500 /// - WebGPU
1501 ///
1502 /// This is a web and native feature.
1503 #[name("dual-source-blending")]
1504 #[web(allow)]
1505 const DUAL_SOURCE_BLENDING = WEBGPU_FEATURE_DUAL_SOURCE_BLENDING;
1506
1507 /// Allows the use of `@builtin(clip_distances)` in WGSL.
1508 ///
1509 /// Supported platforms:
1510 /// - Vulkan (mainly on Desktop GPUs)
1511 /// - Metal
1512 /// - GL (Desktop or `GL_EXT_clip_cull_distance`)
1513 /// - WebGPU
1514 ///
1515 /// This is a web and native feature.
1516 #[name("clip-distances")]
1517 #[web(allow)]
1518 const CLIP_DISTANCES = WEBGPU_FEATURE_CLIP_DISTANCES;
1519
1520 /// Allows the use of immediate data: small, fast bits of memory that can be updated
1521 /// inside a [`RenderPass`].
1522 ///
1523 /// Allows the user to call [`RenderPass::set_immediates`], provide a non-zero immediate data size
1524 /// to [`PipelineLayoutDescriptor`], and provide a non-zero limit to [`Limits::max_immediate_size`].
1525 ///
1526 /// A block of immediate data can be declared in WGSL with `var<immediate>`:
1527 ///
1528 /// ```rust,ignore
1529 /// struct Immediates { example: f32, }
1530 /// var<immediate> c: Immediates;
1531 /// ```
1532 ///
1533 /// In GLSL, this corresponds to `layout(immediates) uniform Name {..}`.
1534 ///
1535 /// Supported platforms:
1536 /// - DX12
1537 /// - Vulkan
1538 /// - Metal
1539 /// - OpenGL (emulated with uniforms)
1540 /// - WebGPU
1541 ///
1542 /// WebGPU support is currently a proposal and will be available in browsers in the future.
1543 ///
1544 /// This is a web and native feature.
1545 ///
1546 #[doc = link_to_wgpu_item!(struct RenderPass)]
1547 #[doc = link_to_wgpu_item!(struct PipelineLayoutDescriptor)]
1548 #[doc = link_to_wgpu_docs!(["`RenderPass::set_immediates`"]: "struct.RenderPass.html#method.set_immediates")]
1549 /// [`Limits::max_immediate_size`]: super::Limits
1550 #[name("immediates")]
1551 #[web(allow)]
1552 const IMMEDIATES = WEBGPU_FEATURE_IMMEDIATES;
1553
1554 /// Enables `builtin(primitive_index)` in fragment shaders.
1555 ///
1556 /// Note: enables geometry processing for pipelines using the builtin.
1557 /// This may come with a significant performance impact on some hardware.
1558 /// Other pipelines are not affected.
1559 ///
1560 /// Supported platforms:
1561 /// - Vulkan (with geometryShader)
1562 /// - DX12
1563 /// - Metal (some)
1564 /// - OpenGL (some)
1565 ///
1566 /// This is a web and native feature. `primitive-index` is its
1567 /// WebGPU-defined name, and `shader-primitive-index` is accepted to
1568 /// remain compatible with previous wgpu behavior.
1569 #[name("primitive-index", "shader-primitive-index")]
1570 #[web(allow)]
1571 const PRIMITIVE_INDEX = WEBGPU_FEATURE_PRIMITIVE_INDEX;
1572
1573 /// Allows `TextureView`s to rearrange or replace the color components
1574 /// from texture's red/green/blue/alpha channels when used as a `TEXTURE_BINDING`.
1575 ///
1576 /// Supported platforms:
1577 /// - Vulkan
1578 /// - DX12
1579 /// - Metal on Apple2+ or Mac2+
1580 ///
1581 /// Not yet implemented:
1582 /// - OpenGL
1583 ///
1584 /// This is a web and native feature.
1585 #[name("texture-component-swizzle")]
1586 #[web(allow)]
1587 const TEXTURE_COMPONENT_SWIZZLE = WEBGPU_FEATURE_TEXTURE_COMPONENT_SWIZZLE;
1588 }
1589}
1590
1591impl Features {
1592 /// Construct a [`Features`] from separate [`FeaturesWGPU`] and [`FeaturesWebGPU`].
1593 ///
1594 /// This `const` constructor is also available as a `From` impl.
1595 pub const fn from_parts(wgpu: FeaturesWGPU, webgpu: FeaturesWebGPU) -> Self {
1596 Self::from_bits_retain(FeatureBits([wgpu.bits(), webgpu.bits()]))
1597 }
1598
1599 /// Mask of all features which are part of the upstream WebGPU standard.
1600 #[must_use]
1601 pub const fn all_webgpu_mask() -> Self {
1602 Self::from_parts(FeaturesWGPU::empty(), FeaturesWebGPU::all())
1603 }
1604
1605 /// Mask of all features that are only available when targeting native (not web).
1606 #[must_use]
1607 pub const fn all_native_mask() -> Self {
1608 Self::from_parts(FeaturesWGPU::all(), FeaturesWebGPU::empty())
1609 }
1610
1611 /// Mask of all features which are experimental.
1612 #[must_use]
1613 pub const fn all_experimental_mask() -> Self {
1614 Self::from_parts(
1615 FeaturesWGPU::from_bits_truncate(
1616 FeaturesWGPU::EXPERIMENTAL_MESH_SHADER.bits()
1617 | FeaturesWGPU::EXPERIMENTAL_MESH_SHADER_MULTIVIEW.bits()
1618 | FeaturesWGPU::EXPERIMENTAL_MESH_SHADER_POINTS.bits()
1619 | FeaturesWGPU::EXPERIMENTAL_RAY_QUERY.bits()
1620 | FeaturesWGPU::EXPERIMENTAL_RAY_HIT_VERTEX_RETURN.bits()
1621 | FeaturesWGPU::EXPERIMENTAL_COOPERATIVE_MATRIX.bits()
1622 | FeaturesWGPU::EXPERIMENTAL_RAY_TRACING_PIPELINES.bits()
1623 | FeaturesWGPU::EXPERIMENTAL_RAY_TRACING_INVOCATION_REORDER.bits(),
1624 ),
1625 FeaturesWebGPU::empty(),
1626 )
1627 }
1628
1629 /// Vertex formats allowed for creating and building BLASes
1630 #[must_use]
1631 pub fn allowed_vertex_formats_for_blas(&self) -> Vec<VertexFormat> {
1632 let mut formats = Vec::new();
1633 if self.intersects(Self::EXPERIMENTAL_RAY_QUERY | Self::EXPERIMENTAL_RAY_TRACING_PIPELINES)
1634 {
1635 formats.push(VertexFormat::Float32x3);
1636 }
1637 if self.contains(Self::EXTENDED_ACCELERATION_STRUCTURE_VERTEX_FORMATS) {
1638 formats.push(VertexFormat::Float32x2);
1639 formats.push(VertexFormat::Float16x2);
1640 formats.push(VertexFormat::Float16x4);
1641 formats.push(VertexFormat::Snorm16x2);
1642 formats.push(VertexFormat::Snorm16x4);
1643 }
1644 formats
1645 }
1646}
1647
1648#[cfg(test)]
1649mod tests {
1650 use crate::{Features, FeaturesWGPU, FeaturesWebGPU};
1651 use bitflags::{Flag, Flags};
1652
1653 #[cfg(feature = "serde")]
1654 #[test]
1655 fn check_hex() {
1656 use crate::FeatureBits;
1657
1658 use bitflags::{
1659 parser::{ParseHex as _, WriteHex as _},
1660 Bits as _,
1661 };
1662
1663 let mut hex = alloc::string::String::new();
1664 FeatureBits::ALL.write_hex(&mut hex).unwrap();
1665 assert_eq!(
1666 FeatureBits::parse_hex(hex.as_str()).unwrap(),
1667 FeatureBits::ALL
1668 );
1669
1670 hex.clear();
1671 FeatureBits::EMPTY.write_hex(&mut hex).unwrap();
1672 assert_eq!(
1673 FeatureBits::parse_hex(hex.as_str()).unwrap(),
1674 FeatureBits::EMPTY
1675 );
1676
1677 for feature in Features::FLAGS {
1678 hex.clear();
1679 feature.value().bits().write_hex(&mut hex).unwrap();
1680 assert_eq!(
1681 FeatureBits::parse_hex(hex.as_str()).unwrap(),
1682 feature.value().bits(),
1683 "{hex}"
1684 );
1685 }
1686 }
1687
1688 #[test]
1689 fn allowed_on_web_backend() {
1690 // Every WebGPU feature is currently allowed on the web backend,
1691 // as well as `subgroups`.
1692 assert_eq!(
1693 Features::ALLOWED_ON_WEB_BACKEND,
1694 Features::from_parts(FeaturesWGPU::SUBGROUP, FeaturesWebGPU::all()),
1695 );
1696 }
1697
1698 #[test]
1699 fn check_features_display() {
1700 use alloc::format;
1701
1702 let feature = Features::CLEAR_TEXTURE;
1703 assert_eq!(format!("{feature}"), "CLEAR_TEXTURE");
1704
1705 let feature = Features::CLEAR_TEXTURE | Features::BGRA8UNORM_STORAGE;
1706 assert_eq!(format!("{feature}"), "CLEAR_TEXTURE | BGRA8UNORM_STORAGE");
1707 }
1708
1709 #[test]
1710 fn check_features_bits() {
1711 let bits = Features::all().bits();
1712 assert_eq!(Features::from_bits_retain(bits), Features::all());
1713
1714 let bits = Features::empty().bits();
1715 assert_eq!(Features::from_bits_retain(bits), Features::empty());
1716
1717 for feature in Features::FLAGS {
1718 let bits = feature.value().bits();
1719 assert_eq!(Features::from_bits_retain(bits), *feature.value());
1720 }
1721
1722 let bits = FeaturesWebGPU::all().bits();
1723 assert_eq!(
1724 FeaturesWebGPU::from_bits_truncate(bits),
1725 FeaturesWebGPU::all()
1726 );
1727
1728 let bits = FeaturesWebGPU::empty().bits();
1729 assert_eq!(
1730 FeaturesWebGPU::from_bits_truncate(bits),
1731 FeaturesWebGPU::empty()
1732 );
1733
1734 for feature in FeaturesWebGPU::FLAGS {
1735 let bits = feature.value().bits();
1736 assert_eq!(FeaturesWebGPU::from_bits_truncate(bits), *feature.value());
1737 }
1738
1739 let bits = FeaturesWGPU::all().bits();
1740 assert_eq!(FeaturesWGPU::from_bits(bits).unwrap(), FeaturesWGPU::all());
1741
1742 let bits = FeaturesWGPU::empty().bits();
1743 assert_eq!(
1744 FeaturesWGPU::from_bits(bits).unwrap(),
1745 FeaturesWGPU::empty()
1746 );
1747
1748 for feature in FeaturesWGPU::FLAGS {
1749 let bits = feature.value().bits();
1750 assert_eq!(FeaturesWGPU::from_bits(bits).unwrap(), *feature.value());
1751 }
1752 }
1753
1754 #[test]
1755 fn features_names() {
1756 for feature in Features::FLAGS.iter().map(Flag::value).copied() {
1757 let Some(name) = feature.as_str() else {
1758 panic!("`.as_str()` for {feature:?} returned `None`");
1759 };
1760 assert_eq!(name.parse(), Ok(feature));
1761
1762 // Native-only features that are accepted without `wgpu-` prefix for backwards compatibility
1763 let prefix_backcompat_features = [
1764 Features::TEXTURE_FORMAT_16BIT_NORM,
1765 Features::TEXTURE_COMPRESSION_ASTC_HDR,
1766 Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES,
1767 Features::PIPELINE_STATISTICS_QUERY,
1768 Features::TIMESTAMP_QUERY_INSIDE_PASSES,
1769 Features::MAPPABLE_PRIMARY_BUFFERS,
1770 Features::TEXTURE_BINDING_ARRAY,
1771 Features::BUFFER_BINDING_ARRAY,
1772 Features::STORAGE_RESOURCE_BINDING_ARRAY,
1773 Features::SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING,
1774 Features::STORAGE_TEXTURE_ARRAY_NON_UNIFORM_INDEXING,
1775 Features::UNIFORM_BUFFER_BINDING_ARRAYS,
1776 Features::PARTIALLY_BOUND_BINDING_ARRAY,
1777 Features::MULTI_DRAW_INDIRECT_COUNT,
1778 Features::ADDRESS_MODE_CLAMP_TO_ZERO,
1779 Features::ADDRESS_MODE_CLAMP_TO_BORDER,
1780 Features::POLYGON_MODE_LINE,
1781 Features::POLYGON_MODE_POINT,
1782 Features::CONSERVATIVE_RASTERIZATION,
1783 Features::VERTEX_WRITABLE_STORAGE,
1784 Features::CLEAR_TEXTURE,
1785 Features::MULTIVIEW,
1786 Features::VERTEX_ATTRIBUTE_64BIT,
1787 Features::EXTERNAL_TEXTURE,
1788 Features::SHADER_F64,
1789 Features::SHADER_I16,
1790 Features::SHADER_EARLY_DEPTH_TEST,
1791 Features::PASSTHROUGH_SHADERS,
1792 ];
1793
1794 if feature == Features::SUBGROUP {
1795 // Standard-track feature that does not have `wgpu-` prefix
1796 assert_eq!(name.parse(), Ok(feature));
1797 } else if feature & Features::all_native_mask() != Features::empty() {
1798 let stripped_name = name.strip_prefix("wgpu-").unwrap_or_else(|| {
1799 panic!("Native feature `{name}` should have `wgpu-` prefix")
1800 });
1801 let expected = if prefix_backcompat_features.contains(&feature) {
1802 Ok(feature)
1803 } else {
1804 Err(())
1805 };
1806 assert_eq!(stripped_name.parse(), expected);
1807 }
1808
1809 // Special backcompat case
1810 if feature == Features::PRIMITIVE_INDEX {
1811 assert_eq!("shader-primitive-index".parse(), Ok(feature));
1812 }
1813 }
1814 }
1815
1816 #[test]
1817 fn create_features_from_parts() {
1818 let features: Features = FeaturesWGPU::TEXTURE_ATOMIC.into();
1819 assert_eq!(features, Features::TEXTURE_ATOMIC);
1820
1821 let features: Features = FeaturesWebGPU::TIMESTAMP_QUERY.into();
1822 assert_eq!(features, Features::TIMESTAMP_QUERY);
1823
1824 let features: Features = Features::from(FeaturesWGPU::TEXTURE_ATOMIC)
1825 | Features::from(FeaturesWebGPU::TIMESTAMP_QUERY);
1826 assert_eq!(
1827 features,
1828 Features::TEXTURE_ATOMIC | Features::TIMESTAMP_QUERY
1829 );
1830 assert_eq!(
1831 features,
1832 Features::from_internal_flags(
1833 FeaturesWGPU::TEXTURE_ATOMIC,
1834 FeaturesWebGPU::TIMESTAMP_QUERY
1835 )
1836 );
1837 }
1838
1839 #[test]
1840 fn experimental_features_part_of_experimental_mask() {
1841 for (name, feature) in Features::all().iter_names() {
1842 let prefixed_with_experimental = name.starts_with("EXPERIMENTAL_");
1843 let in_experimental_mask = Features::all_experimental_mask().contains(feature);
1844 assert_eq!(in_experimental_mask, prefixed_with_experimental);
1845 }
1846 }
1847}