Skip to main content

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}