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

wgpu_types/
device.rs
