wgpu_types/
device.rs

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

wgpu_types/
device.rs
