wgpu_types/
tokens.rs

1use macro_rules_attribute::derive;
2
3use crate::{link_to_wgpu_item, ConstDefault};
4
5/// Token of the user agreeing to access experimental features.
6#[derive(Debug, ConstDefault!, Copy, Clone, Eq, PartialEq)]
7pub struct ExperimentalFeatures {
8    enabled: bool,
9}
10
11impl ExperimentalFeatures {
12    /// Uses of [`Features`] prefixed with "EXPERIMENTAL" are disallowed.
13    ///
14    #[doc = link_to_wgpu_item!(struct Features)]
15    pub const fn disabled() -> Self {
16        Self { enabled: false }
17    }
18
19    /// Uses of [`Features`] prefixed with "EXPERIMENTAL" may result
20    /// in undefined behavior when used incorrectly. The exact bounds
21    /// of these issues varies by the feature. These instances are
22    /// inherently bugs in our implementation that we will eventually fix.
23    ///
24    /// By giving access to still work-in-progress APIs, users can get
25    /// access to newer technology sooner, and we can work with users
26    /// to fix bugs quicker.
27    ///
28    /// Look inside our repo at the [`api-specs`] for more information
29    /// on various experimental apis.
30    ///
31    /// # Safety
32    ///
33    /// - You acknowledge that there may be UB-containing bugs in these
34    ///   apis and those may be hit by calling otherwise safe code.
35    /// - You agree to report any such bugs to us, if you find them.
36    ///
37    #[doc = link_to_wgpu_item!(struct Features)]
38    /// [`api-specs`]: https://github.com/gfx-rs/wgpu/tree/trunk/docs/api-specs
39    pub const unsafe fn enabled() -> Self {
40        Self { enabled: true }
41    }
42
43    /// Returns true if the user has agreed to access experimental features.
44    pub const fn is_enabled(&self) -> bool {
45        self.enabled
46    }
47}
48
49/// Token of the user agreeing to use [`LoadOp::DontCare`](crate::LoadOp::DontCare).
50//
51// Maintenance note: This type MUST NOT implement Default, Deserialize, or anything else which
52// allows safely constructing it. This differs from `ExperimentalFeatures` because it doesn't have
53// an "enabled" flag, because its role is to prevent its container (an enum variant) from being
54// constructed at all. We could change that if necessary (e.g. perhaps for the wgpu trace/player),
55// but if we did, we would have to give `LoadOp::DontCare` a specific fallback behavior when the
56// token is disabled/invalid.
57#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
58pub struct LoadOpDontCare {
59    // Private to prevent construction outside of the unsafe
60    // enabled() function.
61    _private: (),
62}
63
64impl LoadOpDontCare {
65    /// Using [`LoadOp::DontCare`](crate::LoadOp::DontCare) will result
66    /// in the render target having undefined contents at the start of the render pass.
67    /// This may lead to undefined behavior if you read from the any of the
68    /// render target pixels without first writing to them.
69    ///
70    /// Blending also becomes undefined behavior if the source
71    /// pixels are undefined.
72    ///
73    /// All pixels in the render target must be written to before
74    /// any blending or a [`StoreOp::Store`](crate::StoreOp::Store) occurs.
75    ///
76    /// # Safety
77    ///
78    /// - You acknowledge that using `LoadOp::DontCare` may lead to undefined behavior
79    ///   if the above conditions are not met.
80    pub const unsafe fn enabled() -> Self {
81        Self { _private: () }
82    }
83}
84
85static_assertions::assert_not_impl_any!(LoadOpDontCare: Default);
86#[cfg(feature = "serde")]
87static_assertions::assert_not_impl_any!(LoadOpDontCare: serde::Deserialize<'static>);
wgpu_types/tokens.rs

wgpu_types/
tokens.rs
