sim_engine/renderer/diagnostics.rs
1//! Borrowed, allocation-free context for correlating host and renderer measurements.
2
3use super::{RendererSurfacePresentMode, WgpuRenderer};
4
5/// Adapter and presentation context captured from the active renderer.
6///
7/// This view does not allocate, query the GPU, or wait for completion. A host
8/// should record it with performance reports instead of guessing the selected
9/// adapter from the machine's hardware. Borrowing prevents resize or device
10/// replacement while the view is in use; obtain a new view after either event.
11/// The strings describe driver-reported identity, not an independent hardware
12/// attestation. An empty PCI address means instance identity is unavailable.
13#[derive(Debug, Clone, Copy, PartialEq)]
14pub struct RendererDiagnostics<'renderer> {
15 adapter_name: &'renderer str,
16 backend: &'static str,
17 vendor_id: u32,
18 device_id: u32,
19 pci_bus_id: &'renderer str,
20 driver: &'renderer str,
21 driver_info: &'renderer str,
22 scale_factor: f64,
23 physical_size: [u32; 2],
24 surface_format: wgpu::TextureFormat,
25 sample_count: u32,
26 present_mode: RendererSurfacePresentMode,
27}
28
29impl RendererDiagnostics<'_> {
30 /// Human-readable name of the adapter actually selected by the renderer.
31 pub fn adapter_name(&self) -> &str {
32 self.adapter_name
33 }
34
35 /// Stable lowercase graphics API name, such as `vulkan`.
36 pub const fn backend(&self) -> &'static str {
37 self.backend
38 }
39
40 /// Driver-reported PCI vendor ID; together with device ID identifies a model.
41 pub const fn vendor_id(&self) -> u32 {
42 self.vendor_id
43 }
44
45 /// Driver-reported device model ID, not a physical-instance identifier.
46 pub const fn device_id(&self) -> u32 {
47 self.device_id
48 }
49
50 /// PCI address of the selected physical GPU, or empty when unavailable.
51 pub fn pci_bus_id(&self) -> &str {
52 self.pci_bus_id
53 }
54
55 /// Driver name reported by the active adapter.
56 pub fn driver(&self) -> &str {
57 self.driver
58 }
59
60 /// Driver version or implementation details reported by the adapter.
61 pub fn driver_info(&self) -> &str {
62 self.driver_info
63 }
64
65 /// Physical surface pixels per logical screen pixel at capture time.
66 pub const fn scale_factor(&self) -> f64 {
67 self.scale_factor
68 }
69
70 /// Configured surface width and height in physical pixels.
71 pub const fn physical_size(&self) -> [u32; 2] {
72 self.physical_size
73 }
74
75 /// Actual presentation texture format, not an assumed offscreen format.
76 pub const fn surface_format(&self) -> wgpu::TextureFormat {
77 self.surface_format
78 }
79
80 /// Raster sample count selected for the actual presentation format.
81 pub const fn sample_count(&self) -> u32 {
82 self.sample_count
83 }
84
85 /// Actual presentation mode after capability-dependent fallback.
86 pub const fn present_mode(&self) -> RendererSurfacePresentMode {
87 self.present_mode
88 }
89}
90
91impl WgpuRenderer {
92 /// Returns allocation-free adapter, driver, DPI, and presentation metadata.
93 ///
94 /// Record this alongside CPU preparation/upload timings and separately
95 /// correlated asynchronous GPU timestamp samples. Metadata does not turn
96 /// surface acquisition or a CPU interval into a GPU execution measurement.
97 pub fn diagnostics(&self) -> RendererDiagnostics<'_> {
98 RendererDiagnostics {
99 adapter_name: self.adapter_name(),
100 backend: self.adapter_backend(),
101 vendor_id: self.adapter_vendor_id(),
102 device_id: self.adapter_device_id(),
103 pci_bus_id: self.adapter_pci_bus_id(),
104 driver: self.adapter_driver(),
105 driver_info: self.adapter_driver_info(),
106 scale_factor: self.scale_factor,
107 physical_size: [self.config.width, self.config.height],
108 surface_format: self.config.format,
109 sample_count: self.sample_count,
110 present_mode: self.surface_present_mode,
111 }
112 }
113}