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}