wgpu_types/
features.rs

1use crate::VertexFormat;
2#[cfg(feature = "serde")]
3use alloc::fmt;
4use alloc::vec::Vec;
5#[cfg(feature = "serde")]
6use bitflags::parser::{ParseError, ParseHex, WriteHex};
7#[cfg(feature = "serde")]
8use bitflags::Bits;
9use bitflags::Flags;
10#[cfg(feature = "serde")]
11use core::mem::size_of;
12#[cfg(feature = "serde")]
13use serde::{Deserialize, Serialize};
14
15pub use webgpu_impl::*;
16mod webgpu_impl {
17    //! Constant values for [`super::FeaturesWebGPU`], separated so they can be picked up by
18    //! `cbindgen` in `mozilla-central` (where Firefox is developed).
19    #![allow(missing_docs)]
20
21    #[doc(hidden)]
22    pub const WEBGPU_FEATURE_DEPTH_CLIP_CONTROL: u64 = 1 << 0;
23
24    #[doc(hidden)]
25    pub const WEBGPU_FEATURE_DEPTH32FLOAT_STENCIL8: u64 = 1 << 1;
26
27    #[doc(hidden)]
28    pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC: u64 = 1 << 2;
29
30    #[doc(hidden)]
31    pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC_SLICED_3D: u64 = 1 << 3;
32
33    #[doc(hidden)]
34    pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ETC2: u64 = 1 << 4;
35
36    #[doc(hidden)]
37    pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC: u64 = 1 << 5;
38
39    #[doc(hidden)]
40    pub const WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC_SLICED_3D: u64 = 1 << 6;
41
42    #[doc(hidden)]
43    pub const WEBGPU_FEATURE_TIMESTAMP_QUERY: u64 = 1 << 7;
44
45    #[doc(hidden)]
46    pub const WEBGPU_FEATURE_INDIRECT_FIRST_INSTANCE: u64 = 1 << 8;
47
48    #[doc(hidden)]
49    pub const WEBGPU_FEATURE_SHADER_F16: u64 = 1 << 9;
50
51    #[doc(hidden)]
52    pub const WEBGPU_FEATURE_RG11B10UFLOAT_RENDERABLE: u64 = 1 << 10;
53
54    #[doc(hidden)]
55    pub const WEBGPU_FEATURE_BGRA8UNORM_STORAGE: u64 = 1 << 11;
56
57    #[doc(hidden)]
58    pub const WEBGPU_FEATURE_FLOAT32_FILTERABLE: u64 = 1 << 12;
59
60    #[doc(hidden)]
61    pub const WEBGPU_FEATURE_DUAL_SOURCE_BLENDING: u64 = 1 << 13;
62
63    #[doc(hidden)]
64    pub const WEBGPU_FEATURE_CLIP_DISTANCES: u64 = 1 << 14;
65}
66
67macro_rules! bitflags_array_impl {
68    ($impl_name:ident $inner_name:ident $name:ident $op:tt $($struct_names:ident)*) => (
69        impl core::ops::$impl_name for $name {
70            type Output = Self;
71
72            #[inline]
73            fn $inner_name(self, other: Self) -> Self {
74                Self {
75                    $($struct_names: self.$struct_names $op other.$struct_names,)*
76                }
77            }
78        }
79    )
80}
81
82macro_rules! bitflags_array_impl_assign {
83    ($impl_name:ident $inner_name:ident $name:ident $op:tt $($struct_names:ident)*) => (
84        impl core::ops::$impl_name for $name {
85            #[inline]
86            fn $inner_name(&mut self, other: Self) {
87                $(self.$struct_names $op other.$struct_names;)*
88            }
89        }
90    )
91}
92
93macro_rules! bit_array_impl {
94    ($impl_name:ident $inner_name:ident $name:ident $op:tt) => (
95        impl core::ops::$impl_name for $name {
96            type Output = Self;
97
98            #[inline]
99            fn $inner_name(mut self, other: Self) -> Self {
100                for (inner, other) in self.0.iter_mut().zip(other.0.iter()) {
101                    *inner $op *other;
102                }
103                self
104            }
105        }
106    )
107}
108
109macro_rules! bitflags_independent_two_arg {
110    ($(#[$meta:meta])* $func_name:ident $($struct_names:ident)*) => (
111        $(#[$meta])*
112        pub const fn $func_name(self, other:Self) -> Self {
113            Self { $($struct_names: self.$struct_names.$func_name(other.$struct_names),)* }
114        }
115    )
116}
117
118// For the most part this macro should not be modified, most configuration should be possible
119// without changing this macro.
120/// Macro for creating sets of bitflags, we need this because there are almost more flags than bits
121/// in a u64, we can't use a u128 because of FFI, and the number of flags is increasing.
122macro_rules! bitflags_array {
123    (
124        $(#[$outer:meta])*
125        pub struct $name:ident: [$T:ty; $Len:expr];
126
127        $(
128            $(#[$bit_outer:meta])*
129            $vis:vis struct $inner_name:ident $lower_inner_name:ident {
130                $(
131                    $(#[$inner:ident $($args:tt)*])*
132                    const $Flag:tt = $value:expr;
133                )*
134            }
135        )*
136    ) => {
137        $(
138            bitflags::bitflags! {
139                $(#[$bit_outer])*
140                $vis struct $inner_name: $T {
141                    $(
142                        $(#[$inner $($args)*])*
143                        const $Flag = $value;
144                    )*
145                }
146            }
147        )*
148
149        $(#[$outer])*
150        pub struct $name {
151            $(
152                #[allow(missing_docs)]
153                $vis $lower_inner_name: $inner_name,
154            )*
155        }
156
157        /// Bits from `Features` in array form
158        #[derive(Default, Copy, Clone, Debug, PartialEq, Eq)]
159        #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
160        pub struct FeatureBits(pub [$T; $Len]);
161
162        bitflags_array_impl! { BitOr bitor $name | $($lower_inner_name)* }
163        bitflags_array_impl! { BitAnd bitand $name & $($lower_inner_name)* }
164        bitflags_array_impl! { BitXor bitxor $name ^ $($lower_inner_name)* }
165        impl core::ops::Not for $name {
166            type Output = Self;
167
168            #[inline]
169            fn not(self) -> Self {
170                Self {
171                   $($lower_inner_name: !self.$lower_inner_name,)*
172                }
173            }
174        }
175        bitflags_array_impl! { Sub sub $name - $($lower_inner_name)* }
176
177        #[cfg(feature = "serde")]
178        impl Serialize for $name {
179            fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
180            where
181                S: serde::Serializer,
182            {
183                bitflags::serde::serialize(self, serializer)
184            }
185        }
186
187        #[cfg(feature = "serde")]
188        impl<'de> Deserialize<'de> for $name {
189            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
190            where
191                D: serde::Deserializer<'de>,
192            {
193                bitflags::serde::deserialize(deserializer)
194            }
195        }
196
197        impl core::fmt::Display for $name {
198            fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
199                let mut iter = self.iter_names();
200                // simple look ahead
201                let mut next = iter.next();
202                while let Some((name, _)) = next {
203                    f.write_str(name)?;
204                    next = iter.next();
205                    if next.is_some() {
206                        f.write_str(" | ")?;
207                    }
208                }
209                Ok(())
210            }
211        }
212
213        bitflags_array_impl_assign! { BitOrAssign bitor_assign $name |= $($lower_inner_name)* }
214        bitflags_array_impl_assign! { BitAndAssign bitand_assign $name &= $($lower_inner_name)* }
215        bitflags_array_impl_assign! { BitXorAssign bitxor_assign $name ^= $($lower_inner_name)* }
216
217        bit_array_impl! { BitOr bitor FeatureBits |= }
218        bit_array_impl! { BitAnd bitand FeatureBits &= }
219        bit_array_impl! { BitXor bitxor FeatureBits ^= }
220
221        impl core::ops::Not for FeatureBits {
222            type Output = Self;
223
224            #[inline]
225            fn not(self) -> Self {
226                let [$($lower_inner_name,)*] = self.0;
227                Self([$(!$lower_inner_name,)*])
228            }
229        }
230
231        #[cfg(feature = "serde")]
232        impl WriteHex for FeatureBits {
233            fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
234                let [$($lower_inner_name,)*] = self.0;
235                let mut wrote = false;
236                let mut stager = alloc::string::String::with_capacity(size_of::<$T>() * 2);
237                // we don't want to write it if it's just zero as there may be multiple zeros
238                // resulting in something like "00" being written out. We do want to write it if
239                // there has already been something written though.
240                $(if ($lower_inner_name != 0) || wrote {
241                    // First we write to a staging string, then we add any zeros (e.g if #1
242                    // is f and a u8 and #2 is a then the two combined would be f0a which requires
243                    // a 0 inserted)
244                    $lower_inner_name.write_hex(&mut stager)?;
245                    if (stager.len() != size_of::<$T>() * 2) && wrote {
246                        let zeros_to_write = (size_of::<$T>() * 2) - stager.len();
247                        for _ in 0..zeros_to_write {
248                            writer.write_char('0')?
249                        }
250                    }
251                    writer.write_str(&stager)?;
252                    stager.clear();
253                    wrote = true;
254                })*
255                if !wrote {
256                    writer.write_str("0")?;
257                }
258                Ok(())
259            }
260        }
261
262        #[cfg(feature = "serde")]
263        impl ParseHex for FeatureBits {
264            fn parse_hex(input: &str) -> Result<Self, ParseError> {
265
266                let mut unset = Self::EMPTY;
267                let mut end = input.len();
268                if end == 0 {
269                    return Err(ParseError::empty_flag())
270                }
271                // we iterate starting at the least significant places and going up
272                for (idx, _) in [$(stringify!($lower_inner_name),)*].iter().enumerate().rev() {
273                    // A byte is two hex places - u8 (1 byte) = 0x00 (2 hex places).
274                    let checked_start = end.checked_sub(size_of::<$T>() * 2);
275                    let start = checked_start.unwrap_or(0);
276
277                    let cur_input = &input[start..end];
278                    unset.0[idx] = <$T>::from_str_radix(cur_input, 16)
279                        .map_err(|_|ParseError::invalid_hex_flag(cur_input))?;
280
281                    end = start;
282
283                    if let None = checked_start {
284                        break;
285                    }
286                }
287                Ok(unset)
288            }
289        }
290
291        impl bitflags::Bits for FeatureBits {
292            const EMPTY: Self = $name::empty().bits();
293
294            const ALL: Self = $name::all().bits();
295        }
296
297        impl Flags for $name {
298            const FLAGS: &'static [bitflags::Flag<Self>] = $name::FLAGS;
299
300            type Bits = FeatureBits;
301
302            fn bits(&self) -> FeatureBits {
303                FeatureBits([
304                    $(self.$lower_inner_name.bits(),)*
305                ])
306            }
307
308            fn from_bits_retain(bits: FeatureBits) -> Self {
309                let [$($lower_inner_name,)*] = bits.0;
310                Self {
311                    $($lower_inner_name: $inner_name::from_bits_retain($lower_inner_name),)*
312                }
313            }
314
315            fn empty() -> Self {
316                Self::empty()
317            }
318
319            fn all() -> Self {
320                Self::all()
321            }
322        }
323
324        impl $name {
325            pub(crate) const FLAGS: &'static [bitflags::Flag<Self>] = &[
326                $(
327                    $(
328                        bitflags::Flag::new(stringify!($Flag), $name::$Flag),
329                    )*
330                )*
331            ];
332
333            /// Gets the set flags as a container holding an array of bits.
334            pub const fn bits(&self) -> FeatureBits {
335                FeatureBits([
336                    $(self.$lower_inner_name.bits(),)*
337                ])
338            }
339
340            /// Returns self with no flags set.
341            pub const fn empty() -> Self {
342                Self {
343                    $($lower_inner_name: $inner_name::empty(),)*
344                }
345            }
346
347            /// Returns self with all flags set.
348            pub const fn all() -> Self {
349                Self {
350                    $($lower_inner_name: $inner_name::all(),)*
351                }
352            }
353
354            /// Whether all the bits set in `other` are all set in `self`
355            pub const fn contains(self, other:Self) -> bool {
356                // we need an annoying true to catch the last && >:(
357                $(self.$lower_inner_name.contains(other.$lower_inner_name) &&)* true
358            }
359
360            /// Returns whether any bit set in `self` matched any bit set in `other`.
361            pub const fn intersects(self, other:Self) -> bool {
362                $(self.$lower_inner_name.intersects(other.$lower_inner_name) ||)* false
363            }
364
365            /// Returns whether there is no flag set.
366            pub const fn is_empty(self) -> bool {
367                $(self.$lower_inner_name.is_empty() &&)* true
368            }
369
370            /// Returns whether the struct has all flags set.
371            pub const fn is_all(self) -> bool {
372                $(self.$lower_inner_name.is_all() &&)* true
373            }
374
375            bitflags_independent_two_arg! {
376                /// Bitwise or - `self | other`
377                union $($lower_inner_name)*
378            }
379
380            bitflags_independent_two_arg! {
381                /// Bitwise and - `self & other`
382                intersection $($lower_inner_name)*
383            }
384
385            bitflags_independent_two_arg! {
386                /// Bitwise and of the complement of other - `self & !other`
387                difference $($lower_inner_name)*
388            }
389
390            bitflags_independent_two_arg! {
391                /// Bitwise xor - `self ^ other`
392                symmetric_difference $($lower_inner_name)*
393            }
394
395            /// Bitwise not - `!self`
396            pub const fn complement(self) -> Self {
397                Self {
398                    $($lower_inner_name: self.$lower_inner_name.complement(),)*
399                }
400            }
401
402            /// Calls [`Self::insert`] if `set` is true and otherwise calls [`Self::remove`].
403            pub fn set(&mut self, other:Self, set: bool) {
404                $(self.$lower_inner_name.set(other.$lower_inner_name, set);)*
405            }
406
407            /// Inserts specified flag(s) into self
408            pub fn insert(&mut self, other:Self) {
409                $(self.$lower_inner_name.insert(other.$lower_inner_name);)*
410            }
411
412            /// Removes specified flag(s) from self
413            pub fn remove(&mut self, other:Self) {
414                $(self.$lower_inner_name.remove(other.$lower_inner_name);)*
415            }
416
417            /// Toggles specified flag(s) in self
418            pub fn toggle(&mut self, other:Self) {
419                $(self.$lower_inner_name.toggle(other.$lower_inner_name);)*
420            }
421
422            /// Takes in [`FeatureBits`] and returns None if there are invalid bits or otherwise Self with
423            /// those bits set
424            pub const fn from_bits(bits:FeatureBits) -> Option<Self> {
425                let [$($lower_inner_name,)*] = bits.0;
426                // The ? operator does not work in a const context.
427                Some(Self {
428                    $(
429                        $lower_inner_name: match $inner_name::from_bits($lower_inner_name) {
430                            Some(some) => some,
431                            None => return None,
432                        },
433                    )*
434                })
435            }
436
437            /// Takes in [`FeatureBits`] and returns Self with only valid bits (all other bits removed)
438            pub const fn from_bits_truncate(bits:FeatureBits) -> Self {
439                let [$($lower_inner_name,)*] = bits.0;
440                Self { $($lower_inner_name: $inner_name::from_bits_truncate($lower_inner_name),)* }
441            }
442
443            /// Takes in [`FeatureBits`] and returns Self with all bits that were set without removing
444            /// invalid bits
445            pub const fn from_bits_retain(bits:FeatureBits) -> Self {
446                let [$($lower_inner_name,)*] = bits.0;
447                Self { $($lower_inner_name: $inner_name::from_bits_retain($lower_inner_name),)* }
448            }
449
450            /// Takes in a name and returns Self if it matches or none if the name does not match
451            /// the name of any of the flags. Name is capitalisation dependent.
452            pub fn from_name(name: &str) -> Option<Self> {
453                match name {
454                    $(
455                        $(
456                            stringify!($Flag) => Some(Self::$Flag),
457                        )*
458                    )*
459                    _ => None,
460                }
461            }
462
463            /// Combines the features from the internal flags into the entire features struct
464            pub fn from_internal_flags($($lower_inner_name: $inner_name,)*) -> Self {
465                Self {
466                    $($lower_inner_name,)*
467                }
468            }
469
470            /// Returns an iterator over the set flags.
471            pub const fn iter(&self) -> bitflags::iter::Iter<$name> {
472                bitflags::iter::Iter::__private_const_new($name::FLAGS, *self, *self)
473            }
474
475            /// Returns an iterator over the set flags and their names.
476            pub const fn iter_names(&self) -> bitflags::iter::IterNames<$name> {
477                bitflags::iter::IterNames::__private_const_new($name::FLAGS, *self, *self)
478            }
479
480            $(
481                $(
482                    $(#[$inner $($args)*])*
483                    // We need this for structs with only a member.
484                    #[allow(clippy::needless_update)]
485                    pub const $Flag: Self = Self {
486                        $lower_inner_name: $inner_name::from_bits_truncate($value),
487                        ..Self::empty()
488                    };
489                )*
490            )*
491        }
492
493        $(
494            impl From<$inner_name> for Features {
495                // We need this for structs with only a member.
496                #[allow(clippy::needless_update)]
497                fn from($lower_inner_name: $inner_name) -> Self {
498                    Self {
499                        $lower_inner_name,
500                        ..Self::empty()
501                    }
502                }
503            }
504        )*
505    };
506}
507
508impl From<FeatureBits> for Features {
509    fn from(value: FeatureBits) -> Self {
510        Self::from_bits_retain(value)
511    }
512}
513
514impl From<Features> for FeatureBits {
515    fn from(value: Features) -> Self {
516        value.bits()
517    }
518}
519
520bitflags_array! {
521    /// Features that are not guaranteed to be supported.
522    ///
523    /// These are either part of the webgpu standard, or are extension features supported by
524    /// wgpu when targeting native.
525    ///
526    /// If you want to use a feature, you need to first verify that the adapter supports
527    /// the feature. If the adapter does not support the feature, requesting a device with it enabled
528    /// will panic.
529    ///
530    /// Corresponds to [WebGPU `GPUFeatureName`](
531    /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
532    #[repr(C)]
533    #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
534    pub struct Features: [u64; 2];
535
536    /// Features that are not guaranteed to be supported.
537    ///
538    /// Most of these are native-only extension features supported by wgpu only when targeting
539    /// native. A few are intended to align with a proposed WebGPU extension, and one
540    /// (`EXTERNAL_TEXTURE`) controls WebGPU-specified behavior that is not optional in the
541    /// standard, but that we don't want to make a [`crate::DownlevelFlags`] until the
542    /// implementation is more complete. For all features see [`Features`].
543    ///
544    /// If you want to use a feature, you need to first verify that the adapter supports
545    /// the feature. If the adapter does not support the feature, requesting a device with it enabled
546    /// will panic.
547    ///
548    /// Corresponds to [WebGPU `GPUFeatureName`](
549    /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
550    #[repr(transparent)]
551    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
552    #[cfg_attr(feature = "serde", serde(transparent))]
553    #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
554    pub struct FeaturesWGPU features_wgpu {
555        /// Allows shaders to use f32 atomic load, store, add, sub, and exchange.
556        ///
557        /// Supported platforms:
558        /// - Metal (with MSL 3.0+ and Apple7+/Mac2)
559        /// - Vulkan (with [VK_EXT_shader_atomic_float])
560        ///
561        /// This is a native only feature.
562        ///
563        /// [VK_EXT_shader_atomic_float]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_shader_atomic_float.html
564        const SHADER_FLOAT32_ATOMIC = 1 << 0;
565
566        // The features starting with a ? are features that might become part of the spec or
567        // at the very least we can implement as native features; since they should cover all
568        // possible formats and capabilities across backends.
569        //
570        // ? const FORMATS_TIER_1 = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3837)
571        // ? const RW_STORAGE_TEXTURE_TIER_1 = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3838)
572        // ? const NORM16_FILTERABLE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3839)
573        // ? const NORM16_RESOLVE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3839)
574        // ? const FLOAT32_BLENDABLE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3556)
575        // ? const 32BIT_FORMAT_MULTISAMPLE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3844)
576        // ? const 32BIT_FORMAT_RESOLVE = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3844)
577        // ? const TEXTURE_COMPRESSION_ASTC_HDR = 1 << ??; (https://github.com/gpuweb/gpuweb/issues/3856)
578        // TEXTURE_FORMAT_16BIT_NORM & TEXTURE_COMPRESSION_ASTC_HDR will most likely become web features as well
579        // TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES might not be necessary if we have all the texture features implemented
580
581        // Texture Formats:
582
583        /// Enables normalized `16-bit` texture formats.
584        ///
585        /// Supported platforms:
586        /// - Vulkan
587        /// - DX12
588        /// - Metal
589        ///
590        /// This is a native only feature.
591        const TEXTURE_FORMAT_16BIT_NORM = 1 << 1;
592        /// Enables ASTC HDR family of compressed textures.
593        ///
594        /// Compressed textures sacrifice some quality in exchange for significantly reduced
595        /// bandwidth usage.
596        ///
597        /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ASTC formats with the HDR channel type.
598        /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
599        ///
600        /// Supported Platforms:
601        /// - Metal
602        /// - Vulkan
603        /// - OpenGL
604        ///
605        /// This is a native only feature.
606        const TEXTURE_COMPRESSION_ASTC_HDR = 1 << 2;
607        /// Enables device specific texture format features.
608        ///
609        /// See `TextureFormatFeatures` for a listing of the features in question.
610        ///
611        /// By default only texture format properties as defined by the WebGPU specification are allowed.
612        /// Enabling this feature flag extends the features of each format to the ones supported by the current device.
613        /// Note that without this flag, read/write storage access is not allowed at all.
614        ///
615        /// This extension does not enable additional formats.
616        ///
617        /// This is a native only feature.
618        const TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES = 1 << 3;
619
620        // API:
621
622        /// Enables use of Pipeline Statistics Queries. These queries tell the count of various operations
623        /// performed between the start and stop call. Call [`RenderPass::begin_pipeline_statistics_query`] to start
624        /// a query, then call [`RenderPass::end_pipeline_statistics_query`] to stop one.
625        ///
626        /// They must be resolved using [`CommandEncoder::resolve_query_set`] into a buffer.
627        /// The rules on how these resolve into buffers are detailed in the documentation for [`PipelineStatisticsTypes`].
628        ///
629        /// Supported Platforms:
630        /// - Vulkan
631        /// - DX12
632        ///
633        /// This is a native only feature with a [proposal](https://github.com/gpuweb/gpuweb/blob/0008bd30da2366af88180b511a5d0d0c1dffbc36/proposals/pipeline-statistics-query.md) for the web.
634        ///
635        /// [`RenderPass::begin_pipeline_statistics_query`]: https://docs.rs/wgpu/latest/wgpu/struct.RenderPass.html#method.begin_pipeline_statistics_query
636        /// [`RenderPass::end_pipeline_statistics_query`]: https://docs.rs/wgpu/latest/wgpu/struct.RenderPass.html#method.end_pipeline_statistics_query
637        /// [`CommandEncoder::resolve_query_set`]: https://docs.rs/wgpu/latest/wgpu/struct.CommandEncoder.html#method.resolve_query_set
638        /// [`PipelineStatisticsTypes`]: super::PipelineStatisticsTypes
639        const PIPELINE_STATISTICS_QUERY = 1 << 4;
640        /// Allows for timestamp queries directly on command encoders.
641        ///
642        /// Implies [`Features::TIMESTAMP_QUERY`] is supported.
643        ///
644        /// Additionally allows for timestamp writes on command encoders
645        /// using  [`CommandEncoder::write_timestamp`].
646        ///
647        /// Supported platforms:
648        /// - Vulkan
649        /// - DX12
650        /// - Metal
651        ///
652        /// This is a native only feature.
653        ///
654        /// [`CommandEncoder::write_timestamp`]: https://docs.rs/wgpu/latest/wgpu/struct.CommandEncoder.html#method.write_timestamp
655        const TIMESTAMP_QUERY_INSIDE_ENCODERS = 1 << 5;
656        /// Allows for timestamp queries directly on command encoders.
657        ///
658        /// Implies [`Features::TIMESTAMP_QUERY`] & [`Features::TIMESTAMP_QUERY_INSIDE_ENCODERS`] is supported.
659        ///
660        /// Additionally allows for timestamp queries to be used inside render & compute passes using:
661        /// - [`RenderPass::write_timestamp`]
662        /// - [`ComputePass::write_timestamp`]
663        ///
664        /// Supported platforms:
665        /// - Vulkan
666        /// - DX12
667        /// - Metal (AMD & Intel, not Apple GPUs)
668        ///
669        /// This is generally not available on tile-based rasterization GPUs.
670        ///
671        /// 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.
672        ///
673        /// [`RenderPass::write_timestamp`]: https://docs.rs/wgpu/latest/wgpu/struct.RenderPass.html#method.write_timestamp
674        /// [`ComputePass::write_timestamp`]: https://docs.rs/wgpu/latest/wgpu/struct.ComputePass.html#method.write_timestamp
675        const TIMESTAMP_QUERY_INSIDE_PASSES = 1 << 6;
676        /// Webgpu only allows the MAP_READ and MAP_WRITE buffer usage to be matched with
677        /// COPY_DST and COPY_SRC respectively. This removes this requirement.
678        ///
679        /// This is only beneficial on systems that share memory between CPU and GPU. If enabled
680        /// on a system that doesn't, this can severely hinder performance. Only use if you understand
681        /// the consequences.
682        ///
683        /// Supported platforms:
684        /// - Vulkan
685        /// - DX12
686        /// - Metal
687        ///
688        /// This is a native only feature.
689        const MAPPABLE_PRIMARY_BUFFERS = 1 << 7;
690        /// Allows the user to create uniform arrays of textures in shaders:
691        ///
692        /// ex.
693        /// - `var textures: binding_array<texture_2d<f32>, 10>` (WGSL)
694        /// - `uniform texture2D textures[10]` (GLSL)
695        ///
696        /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
697        /// may also create uniform arrays of storage textures.
698        ///
699        /// ex.
700        /// - `var textures: array<texture_storage_2d<r32float, write>, 10>` (WGSL)
701        /// - `uniform image2D textures[10]` (GLSL)
702        ///
703        /// This capability allows them to exist and to be indexed by dynamically uniform
704        /// values.
705        ///
706        /// Supported platforms:
707        /// - DX12
708        /// - Metal (with MSL 2.0+ on macOS 10.13+)
709        /// - Vulkan
710        ///
711        /// This is a native only feature.
712        const TEXTURE_BINDING_ARRAY = 1 << 8;
713        /// Allows the user to create arrays of buffers in shaders:
714        ///
715        /// ex.
716        /// - `var<uniform> buffer_array: array<MyBuffer, 10>` (WGSL)
717        /// - `uniform myBuffer { ... } buffer_array[10]` (GLSL)
718        ///
719        /// This capability allows them to exist and to be indexed by dynamically uniform
720        /// values.
721        ///
722        /// If [`Features::STORAGE_RESOURCE_BINDING_ARRAY`] is supported as well as this, the user
723        /// may also create arrays of storage buffers.
724        ///
725        /// ex.
726        /// - `var<storage> buffer_array: array<MyBuffer, 10>` (WGSL)
727        /// - `buffer myBuffer { ... } buffer_array[10]` (GLSL)
728        ///
729        /// Supported platforms:
730        /// - Vulkan
731        ///
732        /// This is a native only feature.
733        const BUFFER_BINDING_ARRAY = 1 << 9;
734        /// Allows the user to create uniform arrays of storage buffers or textures in shaders,
735        /// if resp. [`Features::BUFFER_BINDING_ARRAY`] or [`Features::TEXTURE_BINDING_ARRAY`]
736        /// is supported.
737        ///
738        /// This capability allows them to exist and to be indexed by dynamically uniform
739        /// values.
740        ///
741        /// Supported platforms:
742        /// - Metal (with MSL 2.2+ on macOS 10.13+)
743        /// - Vulkan
744        ///
745        /// This is a native only feature.
746        const STORAGE_RESOURCE_BINDING_ARRAY = 1 << 10;
747        /// Allows shaders to index sampled texture and storage buffer resource arrays with dynamically non-uniform values:
748        ///
749        /// ex. `texture_array[vertex_data]`
750        ///
751        /// In order to use this capability, the corresponding GLSL extension must be enabled like so:
752        ///
753        /// `#extension GL_EXT_nonuniform_qualifier : require`
754        ///
755        /// and then used either as `nonuniformEXT` qualifier in variable declaration:
756        ///
757        /// ex. `layout(location = 0) nonuniformEXT flat in int vertex_data;`
758        ///
759        /// or as `nonuniformEXT` constructor:
760        ///
761        /// ex. `texture_array[nonuniformEXT(vertex_data)]`
762        ///
763        /// WGSL and HLSL do not need any extension.
764        ///
765        /// Supported platforms:
766        /// - DX12
767        /// - Metal (with MSL 2.0+ on macOS 10.13+)
768        /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s shaderSampledImageArrayNonUniformIndexing & shaderStorageBufferArrayNonUniformIndexing feature)
769        ///
770        /// This is a native only feature.
771        const SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING = 1 << 11;
772        /// Allows shaders to index storage texture resource arrays with dynamically non-uniform values:
773        ///
774        /// ex. `texture_array[vertex_data]`
775        ///
776        /// Supported platforms:
777        /// - DX12
778        /// - Metal (with MSL 2.0+ on macOS 10.13+)
779        /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s shaderStorageTextureArrayNonUniformIndexing feature)
780        ///
781        /// This is a native only feature.
782        const STORAGE_TEXTURE_ARRAY_NON_UNIFORM_INDEXING = 1 << 12;
783        /// Allows the user to create bind groups containing arrays with less bindings than the BindGroupLayout.
784        ///
785        /// Supported platforms:
786        /// - Vulkan
787        /// - DX12
788        ///
789        /// This is a native only feature.
790        const PARTIALLY_BOUND_BINDING_ARRAY = 1 << 13;
791        /// Allows the user to call [`RenderPass::multi_draw_indirect_count`] and [`RenderPass::multi_draw_indexed_indirect_count`].
792        ///
793        /// This allows the use of a buffer containing the actual number of draw calls. This feature being present also implies
794        /// that all calls to [`RenderPass::multi_draw_indirect`] and [`RenderPass::multi_draw_indexed_indirect`] are not being emulated
795        /// with a series of `draw_indirect` calls.
796        ///
797        /// Supported platforms:
798        /// - DX12
799        /// - Vulkan 1.2+ (or VK_KHR_draw_indirect_count)
800        ///
801        /// This is a native only feature.
802        ///
803        /// [`RenderPass::multi_draw_indirect`]: ../wgpu/struct.RenderPass.html#method.multi_draw_indirect
804        /// [`RenderPass::multi_draw_indexed_indirect`]: ../wgpu/struct.RenderPass.html#method.multi_draw_indexed_indirect
805        /// [`RenderPass::multi_draw_indirect_count`]: ../wgpu/struct.RenderPass.html#method.multi_draw_indirect_count
806        /// [`RenderPass::multi_draw_indexed_indirect_count`]: ../wgpu/struct.RenderPass.html#method.multi_draw_indexed_indirect_count
807        const MULTI_DRAW_INDIRECT_COUNT = 1 << 15;
808        /// Allows the use of push constants: small, fast bits of memory that can be updated
809        /// inside a [`RenderPass`].
810        ///
811        /// Allows the user to call [`RenderPass::set_push_constants`], provide a non-empty array
812        /// to [`PipelineLayoutDescriptor`], and provide a non-zero limit to [`Limits::max_push_constant_size`].
813        ///
814        /// A block of push constants can be declared in WGSL with `var<push_constant>`:
815        ///
816        /// ```rust,ignore
817        /// struct PushConstants { example: f32, }
818        /// var<push_constant> c: PushConstants;
819        /// ```
820        ///
821        /// In GLSL, this corresponds to `layout(push_constant) uniform Name {..}`.
822        ///
823        /// Supported platforms:
824        /// - DX12
825        /// - Vulkan
826        /// - Metal
827        /// - OpenGL (emulated with uniforms)
828        ///
829        /// This is a native only feature.
830        ///
831        /// [`RenderPass`]: ../wgpu/struct.RenderPass.html
832        /// [`PipelineLayoutDescriptor`]: ../wgpu/struct.PipelineLayoutDescriptor.html
833        /// [`RenderPass::set_push_constants`]: ../wgpu/struct.RenderPass.html#method.set_push_constants
834        /// [`Limits::max_push_constant_size`]: super::Limits
835        const PUSH_CONSTANTS = 1 << 16;
836        /// Allows the use of [`AddressMode::ClampToBorder`] with a border color
837        /// of [`SamplerBorderColor::Zero`].
838        ///
839        /// Supported platforms:
840        /// - DX12
841        /// - Vulkan
842        /// - Metal
843        /// - OpenGL
844        ///
845        /// This is a native only feature.
846        ///
847        /// [`AddressMode::ClampToBorder`]: super::AddressMode::ClampToBorder
848        /// [`SamplerBorderColor::Zero`]: super::SamplerBorderColor::Zero
849        const ADDRESS_MODE_CLAMP_TO_ZERO = 1 << 17;
850        /// Allows the use of [`AddressMode::ClampToBorder`] with a border color
851        /// other than [`SamplerBorderColor::Zero`].
852        ///
853        /// Supported platforms:
854        /// - DX12
855        /// - Vulkan
856        /// - Metal (macOS 10.12+ only)
857        /// - OpenGL
858        ///
859        /// This is a native only feature.
860        ///
861        /// [`AddressMode::ClampToBorder`]: super::AddressMode::ClampToBorder
862        /// [`SamplerBorderColor::Zero`]: super::SamplerBorderColor::Zero
863        const ADDRESS_MODE_CLAMP_TO_BORDER = 1 << 18;
864        /// Allows the user to set [`PolygonMode::Line`] in [`PrimitiveState::polygon_mode`]
865        ///
866        /// This allows drawing polygons/triangles as lines (wireframe) instead of filled
867        ///
868        /// Supported platforms:
869        /// - DX12
870        /// - Vulkan
871        /// - Metal
872        ///
873        /// This is a native only feature.
874        ///
875        /// [`PrimitiveState::polygon_mode`]: super::PrimitiveState
876        /// [`PolygonMode::Line`]: super::PolygonMode::Line
877        const POLYGON_MODE_LINE = 1 << 19;
878        /// Allows the user to set [`PolygonMode::Point`] in [`PrimitiveState::polygon_mode`]
879        ///
880        /// This allows only drawing the vertices of polygons/triangles instead of filled
881        ///
882        /// Supported platforms:
883        /// - Vulkan
884        ///
885        /// This is a native only feature.
886        ///
887        /// [`PrimitiveState::polygon_mode`]: super::PrimitiveState
888        /// [`PolygonMode::Point`]: super::PolygonMode::Point
889        const POLYGON_MODE_POINT = 1 << 20;
890        /// Allows the user to set a overestimation-conservative-rasterization in [`PrimitiveState::conservative`]
891        ///
892        /// Processing of degenerate triangles/lines is hardware specific.
893        /// Only triangles are supported.
894        ///
895        /// Supported platforms:
896        /// - Vulkan
897        ///
898        /// This is a native only feature.
899        ///
900        /// [`PrimitiveState::conservative`]: super::PrimitiveState::conservative
901        const CONSERVATIVE_RASTERIZATION = 1 << 21;
902        /// Enables bindings of writable storage buffers and textures visible to vertex shaders.
903        ///
904        /// Note: some (tiled-based) platforms do not support vertex shaders with any side-effects.
905        ///
906        /// Supported Platforms:
907        /// - All
908        ///
909        /// This is a native only feature.
910        const VERTEX_WRITABLE_STORAGE = 1 << 22;
911        /// Enables clear to zero for textures.
912        ///
913        /// Supported platforms:
914        /// - All
915        ///
916        /// This is a native only feature.
917        const CLEAR_TEXTURE = 1 << 23;
918        /// Enables multiview render passes and `builtin(view_index)` in vertex shaders.
919        ///
920        /// Supported platforms:
921        /// - Vulkan
922        /// - OpenGL (web only)
923        ///
924        /// This is a native only feature.
925        const MULTIVIEW = 1 << 26;
926        /// Enables using 64-bit types for vertex attributes.
927        ///
928        /// Requires SHADER_FLOAT64.
929        ///
930        /// Supported Platforms: N/A
931        ///
932        /// This is a native only feature.
933        const VERTEX_ATTRIBUTE_64BIT = 1 << 27;
934        /// Enables image atomic fetch add, and, xor, or, min, and max for R32Uint and R32Sint textures.
935        ///
936        /// Supported platforms:
937        /// - Vulkan
938        /// - DX12
939        /// - Metal (with MSL 3.1+)
940        ///
941        /// This is a native only feature.
942        const TEXTURE_ATOMIC = 1 << 28;
943        /// Allows for creation of textures of format [`TextureFormat::NV12`]
944        ///
945        /// Supported platforms:
946        /// - DX12
947        /// - Vulkan
948        ///
949        /// This is a native only feature.
950        ///
951        /// [`TextureFormat::NV12`]: super::TextureFormat::NV12
952        const TEXTURE_FORMAT_NV12 = 1 << 29;
953        /// Allows for creation of textures of format [`TextureFormat::P010`]
954        ///
955        /// Supported platforms:
956        /// - DX12
957        /// - Vulkan
958        ///
959        /// This is a native only feature.
960        ///
961        /// [`TextureFormat::P010`]: super::TextureFormat::P010
962        const TEXTURE_FORMAT_P010 = 1 << 30;
963
964        /// Allows for the creation and usage of `ExternalTexture`s, and bind
965        /// group layouts containing external texture `BindingType`s.
966        ///
967        /// Conceptually this should really be a [`crate::DownlevelFlags`] as
968        /// it corresponds to WebGPU's [`GPUExternalTexture`](
969        /// https://www.w3.org/TR/webgpu/#gpuexternaltexture).
970        /// However, the implementation is currently in-progress, and until it
971        /// is complete we do not want applications to ignore adapters due to
972        /// a missing downlevel flag, when they may not require this feature at
973        /// all.
974        ///
975        /// Supported platforms:
976        /// - DX12
977        /// - Metal
978        const EXTERNAL_TEXTURE = 1 << 31;
979
980        // Shader:
981
982        /// ***THIS IS EXPERIMENTAL:*** Features enabled by this may have
983        /// major bugs in it and are expected to be subject to breaking changes, suggestions
984        /// for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/1040)
985        ///
986        /// Allows for the creation of ray-tracing queries within shaders.
987        ///
988        /// Supported platforms:
989        /// - Vulkan
990        ///
991        /// This is a native-only feature.
992        const EXPERIMENTAL_RAY_QUERY = 1 << 32;
993        /// Enables 64-bit floating point types in SPIR-V shaders.
994        ///
995        /// Note: even when supported by GPU hardware, 64-bit floating point operations are
996        /// frequently between 16 and 64 _times_ slower than equivalent operations on 32-bit floats.
997        ///
998        /// Supported Platforms:
999        /// - Vulkan
1000        ///
1001        /// This is a native only feature.
1002        const SHADER_F64 = 1 << 33;
1003        /// Allows shaders to use i16. Not currently supported in `naga`, only available through `spirv-passthrough`.
1004        ///
1005        /// Supported platforms:
1006        /// - Vulkan
1007        ///
1008        /// This is a native only feature.
1009        const SHADER_I16 = 1 << 34;
1010        /// Enables `builtin(primitive_index)` in fragment shaders.
1011        ///
1012        /// Note: enables geometry processing for pipelines using the builtin.
1013        /// This may come with a significant performance impact on some hardware.
1014        /// Other pipelines are not affected.
1015        ///
1016        /// Supported platforms:
1017        /// - Vulkan
1018        /// - DX12
1019        /// - Metal (some)
1020        /// - OpenGL (some)
1021        ///
1022        /// This is a native only feature.
1023        const SHADER_PRIMITIVE_INDEX = 1 << 35;
1024        /// Allows shaders to use the `early_depth_test` attribute.
1025        ///
1026        /// The attribute is applied to the fragment shader entry point. It can be used in two
1027        /// ways:
1028        ///
1029        ///   1. Force early depth/stencil tests:
1030        ///
1031        ///      - `@early_depth_test(force)` (WGSL)
1032        ///
1033        ///      - `layout(early_fragment_tests) in;` (GLSL)
1034        ///
1035        ///   2. Provide a conservative depth specifier that allows an additional early
1036        ///      depth test under certain conditions:
1037        ///
1038        ///      - `@early_depth_test(greater_equal/less_equal/unchanged)` (WGSL)
1039        ///
1040        ///      - `layout(depth_<greater/less/unchanged>) out float gl_FragDepth;` (GLSL)
1041        ///
1042        /// See [`EarlyDepthTest`] for more details.
1043        ///
1044        /// Supported platforms:
1045        /// - Vulkan
1046        /// - GLES 3.1+
1047        ///
1048        /// This is a native only feature.
1049        ///
1050        /// [`EarlyDepthTest`]: https://docs.rs/naga/latest/naga/ir/enum.EarlyDepthTest.html
1051        const SHADER_EARLY_DEPTH_TEST = 1 << 36;
1052        /// Allows shaders to use i64 and u64.
1053        ///
1054        /// Supported platforms:
1055        /// - Vulkan
1056        /// - DX12 (DXC only)
1057        /// - Metal (with MSL 2.3+)
1058        ///
1059        /// This is a native only feature.
1060        const SHADER_INT64 = 1 << 37;
1061        /// Allows compute and fragment shaders to use the subgroup operation
1062        /// built-ins and perform subgroup operations (except barriers).
1063        ///
1064        /// Supported Platforms:
1065        /// - Vulkan
1066        /// - DX12
1067        /// - Metal
1068        ///
1069        /// This is a native only feature.
1070        const SUBGROUP = 1 << 38;
1071        /// Allows vertex shaders to use the subgroup operation built-ins and
1072        /// perform subgroup operations (except barriers).
1073        ///
1074        /// Supported Platforms:
1075        /// - Vulkan
1076        ///
1077        /// This is a native only feature.
1078        const SUBGROUP_VERTEX = 1 << 39;
1079        /// Allows compute shaders to use the subgroup barrier.
1080        ///
1081        /// Requires [`Features::SUBGROUP`]. Without it, enables nothing.
1082        ///
1083        /// Supported Platforms:
1084        /// - Vulkan
1085        /// - Metal
1086        ///
1087        /// This is a native only feature.
1088        const SUBGROUP_BARRIER = 1 << 40;
1089        /// Allows the use of pipeline cache objects
1090        ///
1091        /// Supported platforms:
1092        /// - Vulkan
1093        ///
1094        /// Unimplemented Platforms:
1095        /// - DX12
1096        /// - Metal
1097        const PIPELINE_CACHE = 1 << 41;
1098        /// Allows shaders to use i64 and u64 atomic min and max.
1099        ///
1100        /// Supported platforms:
1101        /// - Vulkan (with VK_KHR_shader_atomic_int64)
1102        /// - DX12 (with SM 6.6+)
1103        /// - Metal (with MSL 2.4+)
1104        ///
1105        /// This is a native only feature.
1106        const SHADER_INT64_ATOMIC_MIN_MAX = 1 << 42;
1107        /// Allows shaders to use all i64 and u64 atomic operations.
1108        ///
1109        /// Supported platforms:
1110        /// - Vulkan (with VK_KHR_shader_atomic_int64)
1111        /// - DX12 (with SM 6.6+)
1112        ///
1113        /// This is a native only feature.
1114        const SHADER_INT64_ATOMIC_ALL_OPS = 1 << 43;
1115        /// Allows using the [VK_GOOGLE_display_timing] Vulkan extension.
1116        ///
1117        /// This is used for frame pacing to reduce latency, and is generally only available on Android.
1118        ///
1119        /// This feature does not have a `wgpu`-level API, and so users of wgpu wishing
1120        /// to use this functionality must access it using various `as_hal` functions,
1121        /// primarily [`Surface::as_hal()`], to then use.
1122        ///
1123        /// Supported platforms:
1124        /// - Vulkan (with [VK_GOOGLE_display_timing])
1125        ///
1126        /// This is a native only feature.
1127        ///
1128        /// [VK_GOOGLE_display_timing]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_GOOGLE_display_timing.html
1129        /// [`Surface::as_hal()`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html#method.as_hal
1130        const VULKAN_GOOGLE_DISPLAY_TIMING = 1 << 44;
1131
1132        /// Allows using the [VK_KHR_external_memory_win32] Vulkan extension.
1133        ///
1134        /// Supported platforms:
1135        /// - Vulkan (with [VK_KHR_external_memory_win32])
1136        ///
1137        /// This is a native only feature.
1138        ///
1139        /// [VK_KHR_external_memory_win32]: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_KHR_external_memory_win32.html
1140        const VULKAN_EXTERNAL_MEMORY_WIN32 = 1 << 45;
1141
1142        /// Enables R64Uint image atomic min and max.
1143        ///
1144        /// Supported platforms:
1145        /// - Vulkan (with VK_EXT_shader_image_atomic_int64)
1146        /// - DX12 (with SM 6.6+)
1147        /// - Metal (with MSL 3.1+)
1148        ///
1149        /// This is a native only feature.
1150        const TEXTURE_INT64_ATOMIC = 1 << 46;
1151
1152        /// Allows uniform buffers to be bound as binding arrays.
1153        ///
1154        /// This allows:
1155        /// - Shaders to contain `var<uniform> buffer: binding_array<UniformBuffer>;`
1156        /// - The `count` field of `BindGroupLayoutEntry`s with `Uniform` buffers, to be set to `Some`.
1157        ///
1158        /// Supported platforms:
1159        /// - None (<https://github.com/gfx-rs/wgpu/issues/7149>)
1160        ///
1161        /// Potential Platforms:
1162        /// - DX12
1163        /// - Metal
1164        /// - Vulkan 1.2+ (or VK_EXT_descriptor_indexing)'s `shaderUniformBufferArrayNonUniformIndexing` feature)
1165        ///
1166        /// This is a native only feature.
1167        const UNIFORM_BUFFER_BINDING_ARRAYS = 1 << 47;
1168
1169        /// Enables mesh shaders and task shaders in mesh shader pipelines.
1170        ///
1171        /// Supported platforms:
1172        /// - Vulkan (with [VK_EXT_mesh_shader](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_mesh_shader.html))
1173        ///
1174        /// Potential Platforms:
1175        /// - DX12
1176        /// - Metal
1177        ///
1178        /// This is a native only feature.
1179        const EXPERIMENTAL_MESH_SHADER = 1 << 48;
1180
1181        /// ***THIS IS EXPERIMENTAL:*** Features enabled by this may have
1182        /// major bugs in them and are expected to be subject to breaking changes, suggestions
1183        /// for the API exposed by this should be posted on [the ray-tracing issue](https://github.com/gfx-rs/wgpu/issues/6762)
1184        ///
1185        /// Allows for returning of the hit triangle's vertex position when tracing with an
1186        /// acceleration structure marked with [`AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN`].
1187        ///
1188        /// Supported platforms:
1189        /// - Vulkan
1190        ///
1191        /// This is a native only feature
1192        ///
1193        /// [`AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN`]: super::AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN
1194        const EXPERIMENTAL_RAY_HIT_VERTEX_RETURN = 1 << 49;
1195
1196        /// Enables multiview in mesh shader pipelines
1197        ///
1198        /// Supported platforms:
1199        /// - Vulkan (with [VK_EXT_mesh_shader](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_EXT_mesh_shader.html))
1200        ///
1201        /// Potential Platforms:
1202        /// - DX12
1203        /// - Metal
1204        ///
1205        /// This is a native only feature.
1206        const EXPERIMENTAL_MESH_SHADER_MULTIVIEW = 1 << 50;
1207
1208        /// Allows usage of additional vertex formats in [BlasTriangleGeometrySizeDescriptor::vertex_format]
1209        ///
1210        /// Supported platforms
1211        /// - Vulkan
1212        /// - DX12
1213        ///
1214        /// [BlasTriangleGeometrySizeDescriptor::vertex_format]: super::BlasTriangleGeometrySizeDescriptor
1215        const EXTENDED_ACCELERATION_STRUCTURE_VERTEX_FORMATS = 1 << 51;
1216
1217        /// Enables creating shaders from passthrough with reflection info (unsafe)
1218        ///
1219        /// Allows using [`Device::create_shader_module_passthrough`].
1220        /// Shader code isn't parsed or interpreted in any way. It is the user's
1221        /// responsibility to ensure the code and reflection (if passed) are correct.
1222        ///
1223        /// Supported platforms
1224        /// - Vulkan
1225        /// - DX12
1226        /// - Metal
1227        /// - WebGPU
1228        ///
1229        /// Ideally, in the future, all platforms will be supported. For more info, see
1230        /// [this comment](https://github.com/gfx-rs/wgpu/issues/3103#issuecomment-2833058367).
1231        ///
1232        /// [`Device::create_shader_module_passthrough`]: https://docs.rs/wgpu/latest/wgpu/struct.Device.html#method.create_shader_module_passthrough
1233        const EXPERIMENTAL_PASSTHROUGH_SHADERS = 1 << 52;
1234    }
1235
1236    /// Features that are not guaranteed to be supported.
1237    ///
1238    /// These are part of the WebGPU standard. For all features, see [`Features`].
1239    ///
1240    /// If you want to use a feature, you need to first verify that the adapter supports
1241    /// the feature. If the adapter does not support the feature, requesting a device with it enabled
1242    /// will panic.
1243    ///
1244    /// Corresponds to [WebGPU `GPUFeatureName`](
1245    /// https://gpuweb.github.io/gpuweb/#enumdef-gpufeaturename).
1246    #[repr(transparent)]
1247    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
1248    #[cfg_attr(feature = "serde", serde(transparent))]
1249    #[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash)]
1250    pub struct FeaturesWebGPU features_webgpu {
1251        // API:
1252
1253        /// By default, polygon depth is clipped to 0-1 range before/during rasterization.
1254        /// Anything outside of that range is rejected, and respective fragments are not touched.
1255        ///
1256        /// With this extension, we can disabling clipping. That allows
1257        /// shadow map occluders to be rendered into a tighter depth range.
1258        ///
1259        /// Supported platforms:
1260        /// - desktops
1261        /// - some mobile chips
1262        ///
1263        /// This is a web and native feature.
1264        const DEPTH_CLIP_CONTROL = WEBGPU_FEATURE_DEPTH_CLIP_CONTROL;
1265
1266        /// Allows for explicit creation of textures of format [`TextureFormat::Depth32FloatStencil8`]
1267        ///
1268        /// Supported platforms:
1269        /// - Vulkan (mostly)
1270        /// - DX12
1271        /// - Metal
1272        /// - OpenGL
1273        ///
1274        /// This is a web and native feature.
1275        ///
1276        /// [`TextureFormat::Depth32FloatStencil8`]: super::TextureFormat::Depth32FloatStencil8
1277        const DEPTH32FLOAT_STENCIL8 = WEBGPU_FEATURE_DEPTH32FLOAT_STENCIL8;
1278
1279        /// Enables BCn family of compressed textures. All BCn textures use 4x4 pixel blocks
1280        /// with 8 or 16 bytes per block.
1281        ///
1282        /// Compressed textures sacrifice some quality in exchange for significantly reduced
1283        /// bandwidth usage.
1284        ///
1285        /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for BCn formats.
1286        /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1287        ///
1288        /// This feature guarantees availability of sliced-3d textures for BC formats when combined with TEXTURE_COMPRESSION_BC_SLICED_3D.
1289        ///
1290        /// Supported Platforms:
1291        /// - desktops
1292        /// - Mobile (All Apple9 and some Apple7 and Apple8 devices)
1293        ///
1294        /// This is a web and native feature.
1295        const TEXTURE_COMPRESSION_BC = WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC;
1296
1297
1298        /// Allows the 3d dimension for textures with BC compressed formats.
1299        ///
1300        /// This feature must be used in combination with TEXTURE_COMPRESSION_BC to enable 3D textures with BC compression.
1301        /// It does not enable the BC formats by itself.
1302        ///
1303        /// Supported Platforms:
1304        /// - desktops
1305        /// - Mobile (All Apple9 and some Apple7 and Apple8 devices)
1306        ///
1307        /// This is a web and native feature.
1308        const TEXTURE_COMPRESSION_BC_SLICED_3D = WEBGPU_FEATURE_TEXTURE_COMPRESSION_BC_SLICED_3D;
1309
1310        /// Enables ETC family of compressed textures. All ETC textures use 4x4 pixel blocks.
1311        /// ETC2 RGB and RGBA1 are 8 bytes per block. RTC2 RGBA8 and EAC are 16 bytes per block.
1312        ///
1313        /// Compressed textures sacrifice some quality in exchange for significantly reduced
1314        /// bandwidth usage.
1315        ///
1316        /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ETC2 formats.
1317        /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1318        ///
1319        /// Supported Platforms:
1320        /// - Vulkan on Intel
1321        /// - Mobile (some)
1322        ///
1323        /// This is a web and native feature.
1324        const TEXTURE_COMPRESSION_ETC2 = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ETC2;
1325
1326        /// Enables ASTC family of compressed textures. ASTC textures use pixel blocks varying from 4x4 to 12x12.
1327        /// Blocks are always 16 bytes.
1328        ///
1329        /// Compressed textures sacrifice some quality in exchange for significantly reduced
1330        /// bandwidth usage.
1331        ///
1332        /// Support for this feature guarantees availability of [`TextureUsages::COPY_SRC | TextureUsages::COPY_DST | TextureUsages::TEXTURE_BINDING`] for ASTC formats with Unorm/UnormSrgb channel type.
1333        /// [`Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] may enable additional usages.
1334        ///
1335        /// This feature does not guarantee availability of sliced 3d textures for ASTC formats.
1336        /// If available, 3d support can be enabled by TEXTURE_COMPRESSION_ASTC_SLICED_3D feature.
1337        ///
1338        /// Supported Platforms:
1339        /// - Vulkan on Intel
1340        /// - Mobile (some)
1341        ///
1342        /// This is a web and native feature.
1343        const TEXTURE_COMPRESSION_ASTC = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC;
1344
1345
1346        /// Allows the 3d dimension for textures with ASTC compressed formats.
1347        ///
1348        /// This feature must be used in combination with TEXTURE_COMPRESSION_ASTC to enable 3D textures with ASTC compression.
1349        /// It does not enable the ASTC formats by itself.
1350        ///
1351        /// Supported Platforms:
1352        /// - Vulkan (some)
1353        /// - Metal on Apple3+
1354        /// - OpenGL/WebGL (some)
1355        ///
1356        /// Not Supported:
1357        /// - DX12
1358        ///
1359        /// This is a web and native feature.
1360        const TEXTURE_COMPRESSION_ASTC_SLICED_3D = WEBGPU_FEATURE_TEXTURE_COMPRESSION_ASTC_SLICED_3D;
1361
1362        /// Enables use of Timestamp Queries. These queries tell the current gpu timestamp when
1363        /// all work before the query is finished.
1364        ///
1365        /// This feature allows the use of
1366        /// - [`RenderPassDescriptor::timestamp_writes`]
1367        /// - [`ComputePassDescriptor::timestamp_writes`]
1368        /// to write out timestamps.
1369        ///
1370        /// For arbitrary timestamp write commands on encoders refer to [`Features::TIMESTAMP_QUERY_INSIDE_ENCODERS`].
1371        /// For arbitrary timestamp write commands on passes refer to [`Features::TIMESTAMP_QUERY_INSIDE_PASSES`].
1372        ///
1373        /// They must be resolved using [`CommandEncoder::resolve_query_set`] into a buffer,
1374        /// then the result must be multiplied by the timestamp period [`Queue::get_timestamp_period`]
1375        /// to get the timestamp in nanoseconds. Multiple timestamps can then be diffed to get the
1376        /// time for operations between them to finish.
1377        ///
1378        /// Supported Platforms:
1379        /// - Vulkan
1380        /// - DX12
1381        /// - Metal
1382        ///
1383        /// This is a web and native feature.
1384        ///
1385        /// [`RenderPassDescriptor::timestamp_writes`]: https://docs.rs/wgpu/latest/wgpu/struct.RenderPassDescriptor.html#structfield.timestamp_writes
1386        /// [`ComputePassDescriptor::timestamp_writes`]: https://docs.rs/wgpu/latest/wgpu/struct.ComputePassDescriptor.html#structfield.timestamp_writes
1387        /// [`CommandEncoder::resolve_query_set`]: https://docs.rs/wgpu/latest/wgpu/struct.CommandEncoder.html#method.resolve_query_set
1388        /// [`Queue::get_timestamp_period`]: https://docs.rs/wgpu/latest/wgpu/struct.Queue.html#method.get_timestamp_period
1389        const TIMESTAMP_QUERY = WEBGPU_FEATURE_TIMESTAMP_QUERY;
1390
1391        /// Allows non-zero value for the `first_instance` member in indirect draw calls.
1392        ///
1393        /// If this feature is not enabled, and the `first_instance` member is non-zero, the behavior may be:
1394        /// - The draw call is ignored.
1395        /// - The draw call is executed as if the `first_instance` is zero.
1396        /// - The draw call is executed with the correct `first_instance` value.
1397        ///
1398        /// Supported Platforms:
1399        /// - Vulkan (mostly)
1400        /// - DX12
1401        /// - Metal on Apple3+ or Mac1+
1402        /// - OpenGL (Desktop 4.2+ with ARB_shader_draw_parameters only)
1403        ///
1404        /// Not Supported:
1405        /// - OpenGL ES / WebGL
1406        ///
1407        /// This is a web and native feature.
1408        const INDIRECT_FIRST_INSTANCE = WEBGPU_FEATURE_INDIRECT_FIRST_INSTANCE;
1409
1410        /// Allows shaders to use 16-bit floating point types. You may use them uniform buffers,
1411        /// storage buffers, and local variables. You may not use them in push constants.
1412        ///
1413        /// In order to use this in WGSL shaders, you must add `enable f16;` to the top of your shader,
1414        /// before any global items.
1415        ///
1416        /// Supported Platforms:
1417        /// - Vulkan
1418        /// - Metal
1419        /// - DX12
1420        ///
1421        /// This is a web and native feature.
1422        const SHADER_F16 = WEBGPU_FEATURE_SHADER_F16;
1423
1424        /// Allows for usage of textures of format [`TextureFormat::Rg11b10Ufloat`] as a render target
1425        ///
1426        /// Supported platforms:
1427        /// - Vulkan
1428        /// - DX12
1429        /// - Metal
1430        ///
1431        /// This is a web and native feature.
1432        ///
1433        /// [`TextureFormat::Rg11b10Ufloat`]: super::TextureFormat::Rg11b10Ufloat
1434        const RG11B10UFLOAT_RENDERABLE = WEBGPU_FEATURE_RG11B10UFLOAT_RENDERABLE;
1435
1436        /// Allows the [`TextureUsages::STORAGE_BINDING`] usage on textures with format [`TextureFormat::Bgra8Unorm`]
1437        ///
1438        /// Supported Platforms:
1439        /// - Vulkan
1440        /// - DX12
1441        /// - Metal
1442        ///
1443        /// This is a web and native feature.
1444        ///
1445        /// [`TextureFormat::Bgra8Unorm`]: super::TextureFormat::Bgra8Unorm
1446        /// [`TextureUsages::STORAGE_BINDING`]: super::TextureUsages::STORAGE_BINDING
1447        const BGRA8UNORM_STORAGE = WEBGPU_FEATURE_BGRA8UNORM_STORAGE;
1448
1449
1450        /// Allows textures with formats "r32float", "rg32float", and "rgba32float" to be filterable.
1451        ///
1452        /// Supported Platforms:
1453        /// - Vulkan (mainly on Desktop GPUs)
1454        /// - DX12
1455        /// - Metal on macOS or Apple9+ GPUs, optional on iOS/iPadOS with Apple7/8 GPUs
1456        /// - GL with one of `GL_ARB_color_buffer_float`/`GL_EXT_color_buffer_float`/`OES_texture_float_linear`
1457        ///
1458        /// This is a web and native feature.
1459        const FLOAT32_FILTERABLE = WEBGPU_FEATURE_FLOAT32_FILTERABLE;
1460
1461        /// Allows two outputs from a shader to be used for blending.
1462        /// Note that dual-source blending doesn't support multiple render targets.
1463        ///
1464        /// For more info see the OpenGL ES extension GL_EXT_blend_func_extended.
1465        ///
1466        /// Supported platforms:
1467        /// - OpenGL ES (with GL_EXT_blend_func_extended)
1468        /// - Metal (with MSL 1.2+)
1469        /// - Vulkan (with dualSrcBlend)
1470        /// - DX12
1471        ///
1472        /// This is a web and native feature.
1473        const DUAL_SOURCE_BLENDING = WEBGPU_FEATURE_DUAL_SOURCE_BLENDING;
1474
1475        /// Allows the use of `@builtin(clip_distances)` in WGSL.
1476        ///
1477        /// Supported platforms:
1478        /// - Vulkan (mainly on Desktop GPUs)
1479        /// - GL (Desktop or `GL_EXT_clip_cull_distance`)
1480        ///
1481        /// This is a web and native feature.
1482        const CLIP_DISTANCES = WEBGPU_FEATURE_CLIP_DISTANCES;
1483    }
1484}
1485
1486impl Features {
1487    /// Mask of all features which are part of the upstream WebGPU standard.
1488    #[must_use]
1489    pub const fn all_webgpu_mask() -> Self {
1490        Self::from_bits_truncate(FeatureBits([
1491            FeaturesWGPU::empty().bits(),
1492            FeaturesWebGPU::all().bits(),
1493        ]))
1494    }
1495
1496    /// Mask of all features that are only available when targeting native (not web).
1497    #[must_use]
1498    pub const fn all_native_mask() -> Self {
1499        Self::from_bits_truncate(FeatureBits([
1500            FeaturesWGPU::all().bits(),
1501            FeaturesWebGPU::empty().bits(),
1502        ]))
1503    }
1504
1505    /// Mask of all features which are experimental.
1506    #[must_use]
1507    pub const fn all_experimental_mask() -> Self {
1508        Self::from_bits_truncate(FeatureBits([
1509            FeaturesWGPU::EXPERIMENTAL_MESH_SHADER.bits()
1510                | FeaturesWGPU::EXPERIMENTAL_MESH_SHADER_MULTIVIEW.bits()
1511                | FeaturesWGPU::EXPERIMENTAL_RAY_QUERY.bits()
1512                | FeaturesWGPU::EXPERIMENTAL_RAY_HIT_VERTEX_RETURN.bits()
1513                | FeaturesWGPU::EXPERIMENTAL_PASSTHROUGH_SHADERS.bits(),
1514            FeaturesWebGPU::empty().bits(),
1515        ]))
1516    }
1517
1518    /// Vertex formats allowed for creating and building BLASes
1519    #[must_use]
1520    pub fn allowed_vertex_formats_for_blas(&self) -> Vec<VertexFormat> {
1521        let mut formats = Vec::new();
1522        if self.intersects(Self::EXPERIMENTAL_RAY_QUERY) {
1523            formats.push(VertexFormat::Float32x3);
1524        }
1525        if self.contains(Self::EXTENDED_ACCELERATION_STRUCTURE_VERTEX_FORMATS) {
1526            formats.push(VertexFormat::Float32x2);
1527            formats.push(VertexFormat::Float16x2);
1528            formats.push(VertexFormat::Float16x4);
1529            formats.push(VertexFormat::Snorm16x2);
1530            formats.push(VertexFormat::Snorm16x4);
1531        }
1532        formats
1533    }
1534}
1535
1536#[cfg(test)]
1537mod tests {
1538    use crate::{Features, FeaturesWGPU, FeaturesWebGPU};
1539
1540    #[cfg(feature = "serde")]
1541    #[test]
1542    fn check_hex() {
1543        use crate::FeatureBits;
1544
1545        use bitflags::{
1546            parser::{ParseHex as _, WriteHex as _},
1547            Bits as _,
1548        };
1549
1550        let mut hex = alloc::string::String::new();
1551        FeatureBits::ALL.write_hex(&mut hex).unwrap();
1552        assert_eq!(
1553            FeatureBits::parse_hex(hex.as_str()).unwrap(),
1554            FeatureBits::ALL
1555        );
1556
1557        hex.clear();
1558        FeatureBits::EMPTY.write_hex(&mut hex).unwrap();
1559        assert_eq!(
1560            FeatureBits::parse_hex(hex.as_str()).unwrap(),
1561            FeatureBits::EMPTY
1562        );
1563
1564        for feature in Features::FLAGS {
1565            hex.clear();
1566            feature.value().bits().write_hex(&mut hex).unwrap();
1567            assert_eq!(
1568                FeatureBits::parse_hex(hex.as_str()).unwrap(),
1569                feature.value().bits(),
1570                "{hex}"
1571            );
1572        }
1573    }
1574
1575    #[test]
1576    fn check_features_display() {
1577        use alloc::format;
1578
1579        let feature = Features::CLEAR_TEXTURE;
1580        assert_eq!(format!("{feature}"), "CLEAR_TEXTURE");
1581
1582        let feature = Features::CLEAR_TEXTURE | Features::BGRA8UNORM_STORAGE;
1583        assert_eq!(format!("{feature}"), "CLEAR_TEXTURE | BGRA8UNORM_STORAGE");
1584    }
1585
1586    #[test]
1587    fn check_features_bits() {
1588        let bits = Features::all().bits();
1589        assert_eq!(Features::from_bits_retain(bits), Features::all());
1590
1591        let bits = Features::empty().bits();
1592        assert_eq!(Features::from_bits_retain(bits), Features::empty());
1593
1594        for feature in Features::FLAGS {
1595            let bits = feature.value().bits();
1596            assert_eq!(Features::from_bits_retain(bits), *feature.value());
1597        }
1598
1599        let bits = Features::all().bits();
1600        assert_eq!(Features::from_bits_truncate(bits), Features::all());
1601
1602        let bits = Features::empty().bits();
1603        assert_eq!(Features::from_bits_truncate(bits), Features::empty());
1604
1605        for feature in Features::FLAGS {
1606            let bits = feature.value().bits();
1607            assert_eq!(Features::from_bits_truncate(bits), *feature.value());
1608        }
1609
1610        let bits = Features::all().bits();
1611        assert_eq!(Features::from_bits(bits).unwrap(), Features::all());
1612
1613        let bits = Features::empty().bits();
1614        assert_eq!(Features::from_bits(bits).unwrap(), Features::empty());
1615
1616        for feature in Features::FLAGS {
1617            let bits = feature.value().bits();
1618            assert_eq!(Features::from_bits(bits).unwrap(), *feature.value());
1619        }
1620    }
1621
1622    #[test]
1623    fn create_features_from_parts() {
1624        let features: Features = FeaturesWGPU::TEXTURE_ATOMIC.into();
1625        assert_eq!(features, Features::TEXTURE_ATOMIC);
1626
1627        let features: Features = FeaturesWebGPU::TIMESTAMP_QUERY.into();
1628        assert_eq!(features, Features::TIMESTAMP_QUERY);
1629
1630        let features: Features = Features::from(FeaturesWGPU::TEXTURE_ATOMIC)
1631            | Features::from(FeaturesWebGPU::TIMESTAMP_QUERY);
1632        assert_eq!(
1633            features,
1634            Features::TEXTURE_ATOMIC | Features::TIMESTAMP_QUERY
1635        );
1636        assert_eq!(
1637            features,
1638            Features::from_internal_flags(
1639                FeaturesWGPU::TEXTURE_ATOMIC,
1640                FeaturesWebGPU::TIMESTAMP_QUERY
1641            )
1642        );
1643    }
1644
1645    #[test]
1646    fn experimental_features_part_of_experimental_mask() {
1647        for (name, feature) in Features::all().iter_names() {
1648            let prefixed_with_experimental = name.starts_with("EXPERIMENTAL_");
1649            let in_experimental_mask = Features::all_experimental_mask().contains(feature);
1650            assert_eq!(in_experimental_mask, prefixed_with_experimental);
1651        }
1652    }
1653}