wgpu_types/
device.rs

1use core::ops::Range;
2
3use macro_rules_attribute::derive;
4
5use crate::ConstDefault;
6
7#[cfg(any(feature = "serde", test))]
8use serde::{Deserialize, Serialize};
9
10/// Describes a [`Device`](../wgpu/struct.Device.html).
11///
12/// Corresponds to [WebGPU `GPUDeviceDescriptor`](
13/// https://gpuweb.github.io/gpuweb/#gpudevicedescriptor).
14#[derive(Clone, Debug, Default)]
15#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
16pub struct DeviceDescriptor<L> {
17    /// Debug label for the device.
18    pub label: L,
19    /// Specifies the features that are required by the device request.
20    /// The request will fail if the adapter cannot provide these features.
21    ///
22    /// Exactly the specified set of features, and no more or less,
23    /// will be allowed in validation of API calls on the resulting device.
24    pub required_features: crate::Features,
25    /// Specifies the limits that are required by the device request.
26    /// The request will fail if the adapter cannot provide these limits.
27    ///
28    /// Exactly the specified limits, and no better or worse,
29    /// will be allowed in validation of API calls on the resulting device.
30    pub required_limits: crate::Limits,
31    /// Specifies whether `self.required_features` is allowed to contain experimental features.
32    #[cfg_attr(feature = "serde", serde(skip))]
33    pub experimental_features: crate::ExperimentalFeatures,
34    /// Hints for memory allocation strategies.
35    pub memory_hints: MemoryHints,
36    /// Whether API tracing for debugging is enabled,
37    /// and where the trace is written if so.
38    pub trace: Trace,
39}
40
41impl<L> DeviceDescriptor<L> {
42    /// Takes a closure and maps the label of the device descriptor into another.
43    #[must_use]
44    pub fn map_label<'a, K>(&'a self, fun: impl FnOnce(&'a L) -> K) -> DeviceDescriptor<K> {
45        DeviceDescriptor {
46            label: fun(&self.label),
47            required_features: self.required_features,
48            required_limits: self.required_limits.clone(),
49            experimental_features: self.experimental_features,
50            memory_hints: self.memory_hints.clone(),
51            trace: self.trace.clone(),
52        }
53    }
54}
55
56/// Hints to the device about the memory allocation strategy.
57///
58/// Some backends may ignore these hints.
59#[derive(Clone, Debug, Eq, PartialEq, ConstDefault!)]
60#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
61pub enum MemoryHints {
62    /// Favor performance over memory usage (the default value).
63    #[custom(default)]
64    Performance,
65    /// Favor memory usage over performance.
66    MemoryUsage,
67    /// Applications that have control over the content that is rendered
68    /// (typically games) may find an optimal compromise between memory
69    /// usage and performance by specifying the allocation configuration.
70    Manual {
71        /// Defines the range of allowed memory block sizes for sub-allocated
72        /// resources.
73        ///
74        /// The backend may attempt to group multiple resources into fewer
75        /// device memory blocks (sub-allocation) for performance reasons.
76        /// The start of the provided range specifies the initial memory
77        /// block size for sub-allocated resources. After running out of
78        /// space in existing memory blocks, the backend may chose to
79        /// progressively increase the block size of subsequent allocations
80        /// up to a limit specified by the end of the range.
81        ///
82        /// This does not limit resource sizes. If a resource does not fit
83        /// in the specified range, it will typically be placed in a dedicated
84        /// memory block.
85        suballocated_device_memory_block_size: Range<u64>,
86    },
87}
88
89/// Controls API call tracing and specifies where the trace is written.
90#[derive(Clone, Debug, ConstDefault!)]
91#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
92// This enum must be non-exhaustive so that enabling the "trace" feature is not a semver break.
93#[non_exhaustive]
94pub enum Trace {
95    /// Tracing disabled.
96    #[custom(default)]
97    Off,
98
99    /// Write trace to disk.
100    #[cfg(feature = "trace")]
101    // This must be owned rather than `&'a Path`, because if it were that, then the lifetime
102    // parameter would be unused when the "trace" feature is disabled, which is prohibited.
103    Directory(std::path::PathBuf),
104
105    /// Store trace in memory.
106    #[cfg(feature = "trace")]
107    Memory,
108}
wgpu_types/device.rs

wgpu_types/
device.rs
