wgpu_types/
tokens.rs

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

wgpu_types/
tokens.rs
