Skip to main content

alpha2_gpu/
capabilities.rs

1/// The capability class exposed to renderer code.
2#[derive(Copy, Clone, Debug, Eq, PartialEq)]
3#[non_exhaustive]
4pub enum CapabilityTier {
5    /// Full WebGPU-capable adapter.
6    TierA,
7    /// Conservative downlevel adapter.
8    TierB,
9}
10
11/// Internal compositing texture format.
12#[derive(Copy, Clone, Debug, Eq, PartialEq)]
13#[non_exhaustive]
14pub enum IntermediateFormat {
15    /// Half-float RGBA storage (the format does not specify a transfer curve).
16    Rgba16Float,
17    /// Normalized RGBA fallback.
18    Rgba8Unorm,
19}
20
21/// Adapter facts relevant to rendering decisions.
22#[derive(Clone, Debug)]
23#[non_exhaustive]
24pub struct Capabilities {
25    /// Compatibility classification.
26    pub tier: CapabilityTier,
27    /// Chosen intermediate format.
28    pub intermediate_format: IntermediateFormat,
29    /// Platform adapter name.
30    pub adapter_name: String,
31    /// Maximum 2D texture dimension.
32    pub max_texture_dimension_2d: u32,
33    /// Whether render-pass GPU timestamp queries were enabled on the device.
34    pub timestamp_queries: bool,
35    /// Backend selected by wgpu.
36    pub backend: String,
37    /// Adapter driver name.
38    pub driver: String,
39    /// Adapter driver detail/version when exposed by the platform.
40    pub driver_info: String,
41    /// Whether the adapter rasterizes on the CPU (lavapipe, llvmpipe, `SwiftShader`, WARP),
42    /// where shaders pay full cost per pixel regardless of skipped branches.
43    pub software_rasterizer: bool,
44    /// The DX12 shader compiler (`FXC`, `DXC <path>`, ...); empty on other backends.
45    pub shader_compiler: String,
46}
47
48impl Capabilities {
49    /// Creates an explicit capability snapshot for policy simulation and tests.
50    #[must_use]
51    #[allow(clippy::too_many_arguments)]
52    pub fn new(
53        tier: CapabilityTier,
54        intermediate_format: IntermediateFormat,
55        adapter_name: impl Into<String>,
56        max_texture_dimension_2d: u32,
57        timestamp_queries: bool,
58        backend: impl Into<String>,
59        driver: impl Into<String>,
60        driver_info: impl Into<String>,
61        shader_compiler: impl Into<String>,
62    ) -> Self {
63        Self {
64            tier,
65            intermediate_format,
66            adapter_name: adapter_name.into(),
67            max_texture_dimension_2d,
68            timestamp_queries,
69            backend: backend.into(),
70            driver: driver.into(),
71            driver_info: driver_info.into(),
72            software_rasterizer: false,
73            shader_compiler: shader_compiler.into(),
74        }
75    }
76
77    /// One line naming the device: `<adapter> (<backend>, driver <driver> <driver_info>,
78    /// <compiler>)`, empty parts left out.
79    #[must_use]
80    pub fn summary(&self) -> String {
81        let driver = [self.driver.as_str(), self.driver_info.as_str()]
82            .into_iter()
83            .filter(|part| !part.is_empty())
84            .collect::<Vec<_>>()
85            .join(" ");
86        let mut parts = vec![self.backend.clone()];
87        if !driver.is_empty() {
88            parts.push(format!("driver {driver}"));
89        }
90        if !self.shader_compiler.is_empty() {
91            parts.push(self.shader_compiler.clone());
92        }
93        format!("{} ({})", self.adapter_name, parts.join(", "))
94    }
95
96    /// Device facts reflect what the device was opened with; format facts come from the adapter.
97    pub(crate) fn from_device(adapter: &wgpu::Adapter, device: &wgpu::Device) -> Self {
98        let info = adapter.get_info();
99        let shader_compiler = if info.backend == wgpu::Backend::Dx12 {
100            crate::dx12_shader_compiler().to_string()
101        } else {
102            String::new()
103        };
104        let half_float = adapter.get_texture_format_features(wgpu::TextureFormat::Rgba16Float);
105        let software_rasterizer = software_adapter(&info);
106        Self {
107            tier: tier_for(&adapter.get_downlevel_capabilities()),
108            intermediate_format: intermediate_format_for(half_float),
109            adapter_name: info.name,
110            max_texture_dimension_2d: device.limits().max_texture_dimension_2d,
111            timestamp_queries: device.features().contains(wgpu::Features::TIMESTAMP_QUERY),
112            backend: format!("{:?}", info.backend),
113            driver: info.driver,
114            driver_info: info.driver_info,
115            software_rasterizer,
116            shader_compiler,
117        }
118    }
119}
120
121/// Software rasterizer names: wgpu-hal's GL list plus WARP, which browsers reach through ANGLE
122/// as "Microsoft Basic Render Driver" and wgpu-hal does not flag.
123const SOFTWARE_RENDERER_NAMES: [&str; 4] = [
124    "mesa offscreen",
125    "swiftshader",
126    "llvmpipe",
127    "microsoft basic render",
128];
129
130/// Whether `info` is a software adapter: `DeviceType::Cpu` or a name matched by
131/// [`software_renderer_name`].
132#[must_use]
133pub fn software_adapter(info: &wgpu::AdapterInfo) -> bool {
134    info.device_type == wgpu::DeviceType::Cpu || software_renderer_name(&info.name)
135}
136
137/// Whether a renderer or adapter name (including a browser's unmasked WebGL renderer string)
138/// is a software rasterizer's, ignoring case.
139#[must_use]
140pub fn software_renderer_name(name: &str) -> bool {
141    let name = name.to_ascii_lowercase();
142    SOFTWARE_RENDERER_NAMES
143        .iter()
144        .any(|software| name.contains(software))
145}
146
147/// Half float when `Rgba16Float` can be rendered to, blended, filtered and copied, otherwise
148/// 8-bit, since vector layers blend into the intermediate. The tier is irrelevant: tier B GL
149/// adapters with blendable half-float color buffers still get half float.
150fn intermediate_format_for(half_float: wgpu::TextureFormatFeatures) -> IntermediateFormat {
151    let required = wgpu::TextureUsages::RENDER_ATTACHMENT
152        | wgpu::TextureUsages::TEXTURE_BINDING
153        | wgpu::TextureUsages::COPY_SRC;
154    if half_float.allowed_usages.contains(required)
155        && half_float.flags.contains(
156            wgpu::TextureFormatFeatureFlags::FILTERABLE
157                | wgpu::TextureFormatFeatureFlags::BLENDABLE,
158        )
159    {
160        IntermediateFormat::Rgba16Float
161    } else {
162        IntermediateFormat::Rgba8Unorm
163    }
164}
165
166/// Tier A for full WebGPU, tier B for downlevel adapters.
167fn tier_for(downlevel: &wgpu::DownlevelCapabilities) -> CapabilityTier {
168    if downlevel.is_webgpu_compliant() {
169        CapabilityTier::TierA
170    } else {
171        CapabilityTier::TierB
172    }
173}
174
175#[cfg(test)]
176mod tests {
177    use super::*;
178    use wgpu::{TextureFormatFeatureFlags as Flags, TextureUsages as Usages};
179
180    fn half_float(allowed_usages: Usages, flags: Flags) -> wgpu::TextureFormatFeatures {
181        wgpu::TextureFormatFeatures {
182            allowed_usages,
183            flags,
184        }
185    }
186
187    #[test]
188    fn half_float_is_the_intermediate_only_where_it_renders_blends_filters_and_copies() {
189        let required = Usages::RENDER_ATTACHMENT | Usages::TEXTURE_BINDING | Usages::COPY_SRC;
190        let flags = Flags::FILTERABLE | Flags::BLENDABLE;
191        assert_eq!(
192            intermediate_format_for(half_float(required | Usages::COPY_DST, flags)),
193            IntermediateFormat::Rgba16Float
194        );
195        for missing in [
196            Usages::RENDER_ATTACHMENT,
197            Usages::TEXTURE_BINDING,
198            Usages::COPY_SRC,
199        ] {
200            assert_eq!(
201                intermediate_format_for(half_float(required - missing, flags)),
202                IntermediateFormat::Rgba8Unorm,
203                "without {missing:?}"
204            );
205        }
206        for missing in [Flags::FILTERABLE, Flags::BLENDABLE] {
207            assert_eq!(
208                intermediate_format_for(half_float(required, flags - missing)),
209                IntermediateFormat::Rgba8Unorm,
210                "without {missing:?}"
211            );
212        }
213        // No half float at all, as a WebGL2 context without a float colour buffer.
214        assert_eq!(
215            intermediate_format_for(half_float(Usages::empty(), Flags::empty())),
216            IntermediateFormat::Rgba8Unorm
217        );
218    }
219
220    #[test]
221    fn software_adapters_are_named_by_type_or_renderer() {
222        let info = |name: &str, device_type| wgpu::AdapterInfo {
223            name: name.to_owned(),
224            vendor: 0,
225            device: 0,
226            device_type,
227            device_pci_bus_id: String::new(),
228            driver: String::new(),
229            driver_info: String::new(),
230            backend: wgpu::Backend::Gl,
231            subgroup_min_size: 0,
232            subgroup_max_size: 0,
233            transient_saves_memory: None,
234            limit_bucket: None,
235        };
236        assert!(software_adapter(&info("", wgpu::DeviceType::Cpu)));
237        assert!(software_adapter(&info(
238            "ANGLE (Microsoft, Microsoft Basic Render Driver (0x0000008C) Direct3D11 vs_5_0 \
239             ps_5_0, D3D11)",
240            wgpu::DeviceType::Other
241        )));
242        assert!(software_adapter(&info(
243            "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), \
244             SwiftShader driver)",
245            wgpu::DeviceType::Other
246        )));
247        assert!(!software_adapter(&info(
248            "ANGLE (AMD, AMD Radeon Graphics (0x0000164E) Direct3D11 vs_5_0 ps_5_0, D3D11)",
249            wgpu::DeviceType::Other
250        )));
251        assert!(!software_adapter(&info(
252            "Intel(R) UHD Graphics",
253            wgpu::DeviceType::IntegratedGpu
254        )));
255    }
256
257    #[test]
258    fn the_tier_follows_webgpu_compliance_alone() {
259        assert_eq!(
260            tier_for(&wgpu::DownlevelCapabilities::default()),
261            CapabilityTier::TierA
262        );
263        let mut downlevel = wgpu::DownlevelCapabilities::default();
264        downlevel
265            .flags
266            .remove(wgpu::DownlevelFlags::COMPUTE_SHADERS);
267        assert_eq!(tier_for(&downlevel), CapabilityTier::TierB);
268        let shader_model = wgpu::DownlevelCapabilities {
269            shader_model: wgpu::ShaderModel::Sm4,
270            ..Default::default()
271        };
272        assert_eq!(tier_for(&shader_model), CapabilityTier::TierB);
273    }
274}