Skip to main content

wgpu_types/
counters.rs

1use alloc::{string::String, vec::Vec};
2#[cfg(feature = "counters")]
3use core::sync::atomic::{AtomicIsize, Ordering};
4use core::{fmt, ops::Range};
5
6/// An internal counter for debugging purposes
7///
8/// Internally represented as an atomic isize if the `counters` feature is enabled,
9/// or compiles to nothing otherwise.
10pub struct InternalCounter {
11    #[cfg(feature = "counters")]
12    value: AtomicIsize,
13}
14
15impl InternalCounter {
16    /// Creates a counter with value 0.
17    #[inline]
18    #[must_use]
19    pub const fn new() -> Self {
20        InternalCounter {
21            #[cfg(feature = "counters")]
22            value: AtomicIsize::new(0),
23        }
24    }
25
26    /// Get the counter's value.
27    #[cfg(feature = "counters")]
28    #[inline]
29    pub fn read(&self) -> isize {
30        self.value.load(Ordering::Relaxed)
31    }
32
33    /// Get the counter's value.
34    ///
35    /// Always returns 0 if the `counters` feature is not enabled.
36    #[cfg(not(feature = "counters"))]
37    #[inline]
38    #[must_use]
39    pub fn read(&self) -> isize {
40        0
41    }
42
43    /// Get and reset the counter's value.
44    ///
45    /// Always returns 0 if the `counters` feature is not enabled.
46    #[cfg(feature = "counters")]
47    #[inline]
48    pub fn take(&self) -> isize {
49        self.value.swap(0, Ordering::Relaxed)
50    }
51
52    /// Get and reset the counter's value.
53    ///
54    /// Always returns 0 if the `counters` feature is not enabled.
55    #[cfg(not(feature = "counters"))]
56    #[inline]
57    #[must_use]
58    pub fn take(&self) -> isize {
59        0
60    }
61
62    /// Increment the counter by the provided amount.
63    #[inline]
64    pub fn add(&self, _val: isize) {
65        #[cfg(feature = "counters")]
66        self.value.fetch_add(_val, Ordering::Relaxed);
67    }
68
69    /// Decrement the counter by the provided amount.
70    #[inline]
71    pub fn sub(&self, _val: isize) {
72        #[cfg(feature = "counters")]
73        self.value.fetch_add(-_val, Ordering::Relaxed);
74    }
75
76    /// Sets the counter to the provided value.
77    #[inline]
78    pub fn set(&self, _val: isize) {
79        #[cfg(feature = "counters")]
80        self.value.store(_val, Ordering::Relaxed);
81    }
82}
83
84impl Clone for InternalCounter {
85    fn clone(&self) -> Self {
86        InternalCounter {
87            #[cfg(feature = "counters")]
88            value: AtomicIsize::new(self.read()),
89        }
90    }
91}
92
93impl Default for InternalCounter {
94    fn default() -> Self {
95        Self::new()
96    }
97}
98
99impl fmt::Debug for InternalCounter {
100    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
101        self.read().fmt(f)
102    }
103}
104
105/// `wgpu-hal`'s part of [`InternalCounters`].
106#[expect(missing_docs, reason = "fields are named after the objects they count")]
107#[derive(Clone, Debug, Default)]
108pub struct HalCounters {
109    // API objects
110    pub buffers: InternalCounter,
111    pub textures: InternalCounter,
112    pub texture_views: InternalCounter,
113    pub bind_groups: InternalCounter,
114    pub bind_group_layouts: InternalCounter,
115    pub render_pipelines: InternalCounter,
116    pub compute_pipelines: InternalCounter,
117    pub ray_tracing_pipelines: InternalCounter,
118    pub pipeline_layouts: InternalCounter,
119    pub samplers: InternalCounter,
120    pub command_encoders: InternalCounter,
121    pub shader_modules: InternalCounter,
122    pub query_sets: InternalCounter,
123    pub fences: InternalCounter,
124
125    // Resources
126    /// Amount of allocated gpu memory attributed to buffers, in bytes.
127    pub buffer_memory: InternalCounter,
128    /// Amount of allocated gpu memory attributed to textures, in bytes.
129    pub texture_memory: InternalCounter,
130    /// Amount of allocated gpu memory attributed to acceleration structures, in bytes.
131    pub acceleration_structure_memory: InternalCounter,
132    /// Amount of gpu memory held in indirect command buffers that the backend
133    /// creates to run multi-draws on the GPU, in bytes. Only the Metal backend
134    /// creates them.
135    pub indirect_command_buffer_memory: InternalCounter,
136    /// Number of gpu memory allocations.
137    pub memory_allocations: InternalCounter,
138}
139
140/// `wgpu-core`'s part of [`InternalCounters`].
141#[derive(Clone, Debug, Default)]
142pub struct CoreCounters {
143    // TODO    #[cfg(features=)]
144}
145
146/// All internal counters, exposed for debugging purposes.
147///
148/// Obtain this from
149/// [`Device::get_internal_counters()`](../wgpu/struct.Device.html#method.get_internal_counters).
150#[derive(Clone, Debug, Default)]
151pub struct InternalCounters {
152    /// `wgpu-core` counters.
153    pub core: CoreCounters,
154    /// `wgpu-hal` counters.
155    pub hal: HalCounters,
156}
157
158/// Describes an allocation in the [`AllocatorReport`].
159#[derive(Clone)]
160pub struct AllocationReport {
161    /// The name provided to the `allocate()` function.
162    pub name: String,
163    /// The offset in bytes of the allocation in its memory block.
164    pub offset: u64,
165    /// The size in bytes of the allocation.
166    pub size: u64,
167}
168
169/// Describes a memory block in the [`AllocatorReport`].
170#[derive(Clone, Debug)]
171pub struct MemoryBlockReport {
172    /// The size in bytes of this memory block.
173    pub size: u64,
174    /// The range of allocations in [`AllocatorReport::allocations`] that are associated
175    /// to this memory block.
176    pub allocations: Range<usize>,
177}
178
179/// A report that can be generated for informational purposes using `Allocator::generate_report()`.
180#[derive(Clone)]
181pub struct AllocatorReport {
182    /// All live allocations, sub-allocated from memory blocks.
183    pub allocations: Vec<AllocationReport>,
184    /// All memory blocks.
185    pub blocks: Vec<MemoryBlockReport>,
186    /// Sum of the memory used by all allocations, in bytes.
187    pub total_allocated_bytes: u64,
188    /// Sum of the memory reserved by all memory blocks including unallocated regions, in bytes.
189    // XXX: Rename to total_capacity_bytes following the rename at https://github.com/Traverse-Research/gpu-allocator/pull/266?
190    pub total_reserved_bytes: u64,
191}
192
193impl fmt::Debug for AllocationReport {
194    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
195        let name = if !self.name.is_empty() {
196            self.name.as_str()
197        } else {
198            "--"
199        };
200        write!(f, "{name:?}: {}", FmtBytes(self.size))
201    }
202}
203
204impl fmt::Debug for AllocatorReport {
205    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
206        let mut allocations = self.allocations.clone();
207        allocations.sort_by_key(|alloc| core::cmp::Reverse(alloc.size));
208
209        let max_num_allocations_to_print = f.precision().unwrap_or(usize::MAX);
210        allocations.truncate(max_num_allocations_to_print);
211
212        f.debug_struct("AllocatorReport")
213            .field(
214                "summary",
215                &core::format_args!(
216                    "{} / {}",
217                    FmtBytes(self.total_allocated_bytes),
218                    FmtBytes(self.total_reserved_bytes)
219                ),
220            )
221            .field("blocks", &self.blocks.len())
222            .field("allocations", &self.allocations.len())
223            .field("largest", &allocations.as_slice())
224            .finish()
225    }
226}
227
228struct FmtBytes(u64);
229
230impl fmt::Display for FmtBytes {
231    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
232        const SUFFIX: [&str; 5] = ["B", "KB", "MB", "GB", "TB"];
233        let mut idx = 0;
234        let mut amount = self.0 as f64;
235        loop {
236            if amount < 1024.0 || idx == SUFFIX.len() - 1 {
237                return write!(f, "{:.2} {}", amount, SUFFIX[idx]);
238            }
239
240            amount /= 1024.0;
241            idx += 1;
242        }
243    }
244}