lampshade 0.13.0

Fast, composable GPU primitives for Rust applications using wgpu and WGSL.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

use crate::Error;
use wgpu::{AdapterInfo, Backends, Device, Instance, MemoryHints, Queue, RequestAdapterOptions};

pub struct Context {
    pub adapter_info: AdapterInfo,
    pub device: Device,
    pub queue: Queue,
}

impl Context {
    /// Creates a context with the optional GPU features Lampshade can use safely.
    ///
    /// Timestamp queries are not enabled by this convenience constructor on
    /// Apple Metal or integrated NVIDIA Vulkan. Those paths have produced
    /// incomplete timestamps or corrupted repeated compute dispatches.
    /// Profiling methods consequently return [`Error::TimestampQueriesUnsupported`]
    /// for this context instead of reporting misleading durations.
    pub async fn init() -> Result<Self, Error> {
        let descriptor = wgpu::InstanceDescriptor {
            backends: Backends::PRIMARY,
            ..wgpu::InstanceDescriptor::new_without_display_handle()
        }
        .with_env();
        let instance = Instance::new(descriptor);

        let adapter = instance
            .request_adapter(&RequestAdapterOptions {
                power_preference: wgpu::PowerPreference::HighPerformance,
                compatible_surface: None,
                force_fallback_adapter: false,
                apply_limit_buckets: false,
            })
            .await?;
        let adapter_info = adapter.get_info();
        let required_features = context_features(&adapter_info, adapter.features());

        let (device, queue) = adapter
            .request_device(&wgpu::DeviceDescriptor {
                label: Some("Context Device"),
                required_features,
                required_limits: adapter.limits(),
                memory_hints: MemoryHints::Performance,
                ..Default::default()
            })
            .await?;

        Ok(Self {
            adapter_info,
            device,
            queue,
        })
    }
}

fn context_features(
    adapter_info: &wgpu::AdapterInfo,
    supported_features: wgpu::Features,
) -> wgpu::Features {
    let mut optional_features = wgpu::Features::empty();
    if reliable_subgroup_scan(adapter_info) {
        optional_features |= wgpu::Features::SUBGROUP;
    }
    // Apple Metal stage-boundary timestamp queries can leave the final query
    // pair unwritten. Do not expose incomplete profiling through Context.
    let apple_metal = adapter_info.backend == wgpu::Backend::Metal
        && (adapter_info.vendor == 0x106b || adapter_info.name.starts_with("Apple "));
    if !apple_metal && reliable_optional_compute_features(adapter_info) {
        optional_features |= wgpu::Features::TIMESTAMP_QUERY;
    }
    supported_features & optional_features
}

pub(crate) fn reliable_subgroup_scan(adapter_info: &wgpu::AdapterInfo) -> bool {
    reliable_optional_compute_features(adapter_info)
}

fn reliable_optional_compute_features(adapter_info: &wgpu::AdapterInfo) -> bool {
    !(adapter_info.backend == wgpu::Backend::Vulkan
        && adapter_info.vendor == 0x10de
        && adapter_info.device_type == wgpu::DeviceType::IntegratedGpu)
}

#[cfg(test)]
mod tests {
    use super::{context_features, reliable_subgroup_scan};

    fn adapter(name: &str, vendor: u32, backend: wgpu::Backend) -> wgpu::AdapterInfo {
        let mut adapter = wgpu::AdapterInfo::new(wgpu::DeviceType::Other, backend);
        adapter.name = name.to_owned();
        adapter.vendor = vendor;
        adapter
    }

    #[test]
    fn disables_unreliable_apple_metal_timestamps_only() {
        let supported = wgpu::Features::TIMESTAMP_QUERY | wgpu::Features::SUBGROUP;
        let apple_vendor = context_features(
            &adapter("Metal device", 0x106b, wgpu::Backend::Metal),
            supported,
        );
        assert!(!apple_vendor.contains(wgpu::Features::TIMESTAMP_QUERY));
        assert!(apple_vendor.contains(wgpu::Features::SUBGROUP));

        let apple_name =
            context_features(&adapter("Apple M3 Pro", 0, wgpu::Backend::Metal), supported);
        assert!(!apple_name.contains(wgpu::Features::TIMESTAMP_QUERY));

        let intel_metal = context_features(
            &adapter("Intel GPU", 0x8086, wgpu::Backend::Metal),
            supported,
        );
        assert!(intel_metal.contains(wgpu::Features::TIMESTAMP_QUERY));

        let apple_vulkan = context_features(
            &adapter("Apple GPU", 0x106b, wgpu::Backend::Vulkan),
            supported,
        );
        assert!(apple_vulkan.contains(wgpu::Features::TIMESTAMP_QUERY));
    }

    #[test]
    fn disables_subgroups_on_integrated_nvidia_vulkan() {
        let mut orin = adapter("Orin (nvgpu)", 0x10de, wgpu::Backend::Vulkan);
        orin.device_type = wgpu::DeviceType::IntegratedGpu;
        let enabled = context_features(
            &orin,
            wgpu::Features::TIMESTAMP_QUERY | wgpu::Features::SUBGROUP,
        );

        assert!(!reliable_subgroup_scan(&orin));
        assert!(!enabled.contains(wgpu::Features::SUBGROUP));
        assert!(!enabled.contains(wgpu::Features::TIMESTAMP_QUERY));
    }
}