Skip to main content

sui_render_wgpu/
device.rs

1use crate::WgpuRenderer;
2use crate::gpu::SharedRenderer;
3use crate::gpu::TextAtlasQuadVertex;
4use crate::resources::create_text_atlas_array_bind_group_layout;
5use std::collections::HashMap;
6use sui_core::Error;
7use sui_core::Result;
8use wgpu::util::DeviceExt;
9
10#[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
11pub(crate) struct DevicePreparation {
12    pub window: Option<sui_core::WindowId>,
13    cancelled: std::sync::Arc<std::sync::atomic::AtomicBool>,
14    thread: Option<std::thread::JoinHandle<Result<(SharedRenderer, u64)>>>,
15}
16
17#[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
18impl DevicePreparation {
19    fn finish(mut self) -> Result<(SharedRenderer, u64)> {
20        self.thread
21            .take()
22            .expect("pending device thread")
23            .join()
24            .map_err(|_| Error::new("GPU device preparation thread panicked"))?
25    }
26}
27
28#[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
29impl Drop for DevicePreparation {
30    fn drop(&mut self) {
31        // Closing an unrendered window must not install resources later or block
32        // the UI. In-flight driver calls finish on the worker and release their
33        // owned surface/device; subsequent initialization stages are cancelled.
34        self.cancelled
35            .store(true, std::sync::atomic::Ordering::Release);
36    }
37}
38
39pub(crate) fn optional_renderer_features(adapter: &wgpu::Adapter) -> wgpu::Features {
40    let mut features = wgpu::Features::empty();
41    if adapter
42        .features()
43        .contains(wgpu::Features::DUAL_SOURCE_BLENDING)
44    {
45        features |= wgpu::Features::DUAL_SOURCE_BLENDING;
46    }
47    features
48}
49
50impl SharedRenderer {
51    pub(crate) fn new(adapter: wgpu::Adapter, device: wgpu::Device, queue: wgpu::Queue) -> Self {
52        let image_bind_group_layout =
53            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
54                label: Some("SUI image bind group layout"),
55                entries: &[
56                    wgpu::BindGroupLayoutEntry {
57                        binding: 0,
58                        visibility: wgpu::ShaderStages::FRAGMENT,
59                        ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
60                        count: None,
61                    },
62                    wgpu::BindGroupLayoutEntry {
63                        binding: 1,
64                        visibility: wgpu::ShaderStages::FRAGMENT,
65                        ty: wgpu::BindingType::Texture {
66                            sample_type: wgpu::TextureSampleType::Float { filterable: true },
67                            view_dimension: wgpu::TextureViewDimension::D2,
68                            multisampled: false,
69                        },
70                        count: None,
71                    },
72                ],
73            });
74        let text_atlas_array_bind_group_layout = create_text_atlas_array_bind_group_layout(&device);
75        let image_linear_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
76            label: Some("SUI linear image sampler"),
77            mag_filter: wgpu::FilterMode::Linear,
78            min_filter: wgpu::FilterMode::Linear,
79            mipmap_filter: wgpu::MipmapFilterMode::Linear,
80            ..Default::default()
81        });
82        let image_nearest_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
83            label: Some("SUI nearest image sampler"),
84            mag_filter: wgpu::FilterMode::Nearest,
85            min_filter: wgpu::FilterMode::Nearest,
86            mipmap_filter: wgpu::MipmapFilterMode::Nearest,
87            lod_max_clamp: 0.0,
88            ..Default::default()
89        });
90        let text_atlas_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
91            label: Some("SUI text atlas sampler"),
92            mag_filter: wgpu::FilterMode::Linear,
93            min_filter: wgpu::FilterMode::Linear,
94            mipmap_filter: wgpu::MipmapFilterMode::Nearest,
95            ..Default::default()
96        });
97        let text_quad_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
98            label: Some("SUI text atlas quad"),
99            contents: bytemuck::cast_slice(&TextAtlasQuadVertex::unit_quad()),
100            usage: wgpu::BufferUsages::VERTEX,
101        });
102        let analytic_path_bind_group_layout =
103            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
104                label: Some("SUI analytic path bind group layout"),
105                entries: &[
106                    wgpu::BindGroupLayoutEntry {
107                        binding: 0,
108                        visibility: wgpu::ShaderStages::FRAGMENT,
109                        ty: wgpu::BindingType::Buffer {
110                            ty: wgpu::BufferBindingType::Storage { read_only: true },
111                            has_dynamic_offset: false,
112                            min_binding_size: None,
113                        },
114                        count: None,
115                    },
116                    wgpu::BindGroupLayoutEntry {
117                        binding: 1,
118                        visibility: wgpu::ShaderStages::FRAGMENT,
119                        ty: wgpu::BindingType::Buffer {
120                            ty: wgpu::BufferBindingType::Storage { read_only: true },
121                            has_dynamic_offset: false,
122                            min_binding_size: None,
123                        },
124                        count: None,
125                    },
126                    wgpu::BindGroupLayoutEntry {
127                        binding: 2,
128                        visibility: wgpu::ShaderStages::FRAGMENT,
129                        ty: wgpu::BindingType::Buffer {
130                            ty: wgpu::BufferBindingType::Storage { read_only: true },
131                            has_dynamic_offset: false,
132                            min_binding_size: None,
133                        },
134                        count: None,
135                    },
136                ],
137            });
138        let output_transform_bind_group_layout =
139            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
140                label: Some("SUI output transform bind group layout"),
141                entries: &[
142                    wgpu::BindGroupLayoutEntry {
143                        binding: 0,
144                        visibility: wgpu::ShaderStages::FRAGMENT,
145                        ty: wgpu::BindingType::Texture {
146                            sample_type: wgpu::TextureSampleType::Float { filterable: false },
147                            view_dimension: wgpu::TextureViewDimension::D2,
148                            multisampled: false,
149                        },
150                        count: None,
151                    },
152                    wgpu::BindGroupLayoutEntry {
153                        binding: 1,
154                        visibility: wgpu::ShaderStages::FRAGMENT,
155                        ty: wgpu::BindingType::Buffer {
156                            ty: wgpu::BufferBindingType::Uniform,
157                            has_dynamic_offset: false,
158                            min_binding_size: None,
159                        },
160                        count: None,
161                    },
162                ],
163            });
164
165        let dual_source_blending_enabled = device
166            .features()
167            .contains(wgpu::Features::DUAL_SOURCE_BLENDING);
168
169        Self {
170            collect_pipeline_timings: true,
171            pipeline_create_time_us: 0,
172            pipeline_create_count: 0,
173            adapter,
174            device,
175            queue,
176            pipelines: HashMap::new(),
177            image_bind_group_layout,
178            text_atlas_array_bind_group_layout,
179            analytic_path_bind_group_layout,
180            output_transform_bind_group_layout,
181            image_linear_sampler,
182            image_nearest_sampler,
183            text_atlas_sampler,
184            text_quad_buffer,
185            dual_source_blending_enabled,
186        }
187    }
188}
189impl WgpuRenderer {
190    /// Start offscreen device preparation while the host constructs/layouts its
191    /// first frame. Desktop hosts should use `prepare_window` for surface-aware
192    /// adapter selection. Other targets retain their existing initialization path.
193    pub fn prepare_device(&mut self) {
194        #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
195        self.start_device_preparation(None, None);
196    }
197
198    #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
199    pub(crate) fn start_device_preparation(
200        &mut self,
201        window: Option<sui_core::WindowId>,
202        surface: Option<std::sync::Arc<wgpu::Surface<'static>>>,
203    ) {
204        if self.shared.is_some() || self.device_preparation.is_some() {
205            return;
206        }
207        let instance = self.instance.clone();
208        let cancelled = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
209        let cancellation = cancelled.clone();
210        let task = std::thread::Builder::new()
211            .name("sui-gpu-prepare".into())
212            .spawn(move || {
213                let started = web_time::Instant::now();
214                let shared =
215                    Self::acquire_shared(&instance, surface.as_deref(), Some(&cancellation))?;
216                Ok((shared, started.elapsed().as_micros() as u64))
217            });
218        // A host that cannot spawn another thread can still initialize normally.
219        if let Ok(thread) = task {
220            self.device_preparation = Some(DevicePreparation {
221                window,
222                cancelled,
223                thread: Some(thread),
224            });
225        }
226    }
227
228    pub(crate) fn install_shared(&mut self, mut shared: SharedRenderer) {
229        shared.collect_pipeline_timings = self.runtime_diagnostics_enabled;
230        if let Some(registry) = &self.external_texture_registry {
231            registry.attach(
232                shared.device.clone(),
233                shared.queue.clone(),
234                shared.adapter.get_info(),
235            );
236        }
237        self.shared = Some(shared);
238    }
239
240    pub(crate) fn ensure_shared(
241        &mut self,
242        compatible_surface: Option<&wgpu::Surface<'_>>,
243    ) -> Result<()> {
244        if self.shared.is_some() {
245            return Ok(());
246        }
247
248        #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
249        if let Some(preparation) = self.device_preparation.take() {
250            let started = web_time::Instant::now();
251            let (shared, work_us) = preparation.finish()?;
252            if self.runtime_diagnostics_enabled {
253                self.pending_device_prepare_time_us += work_us;
254                self.pending_device_wait_time_us += started.elapsed().as_micros() as u64;
255            }
256            if compatible_surface.is_none_or(|surface| shared.adapter.is_surface_supported(surface))
257            {
258                self.install_shared(shared);
259                return Ok(());
260            }
261            // An offscreen preparation may be followed by a native window. If
262            // it needs a different adapter, retry with that actual surface.
263        }
264
265        let started = self
266            .runtime_diagnostics_enabled
267            .then(web_time::Instant::now);
268        let shared = Self::acquire_shared(&self.instance, compatible_surface, None)?;
269        self.install_shared(shared);
270        if let Some(started) = started {
271            let elapsed = started.elapsed().as_micros() as u64;
272            self.pending_device_prepare_time_us += elapsed;
273            self.pending_device_wait_time_us += elapsed;
274        }
275        Ok(())
276    }
277
278    fn acquire_shared(
279        instance: &wgpu::Instance,
280        compatible_surface: Option<&wgpu::Surface<'_>>,
281        cancelled: Option<&std::sync::atomic::AtomicBool>,
282    ) -> Result<SharedRenderer> {
283        let check_cancelled = || {
284            if cancelled
285                .is_some_and(|cancelled| cancelled.load(std::sync::atomic::Ordering::Acquire))
286            {
287                Err(Error::new("GPU device preparation cancelled"))
288            } else {
289                Ok(())
290            }
291        };
292        check_cancelled()?;
293        #[cfg(target_os = "windows")]
294        let preferred = Self::preferred_windows_adapter(instance, compatible_surface);
295        #[cfg(not(target_os = "windows"))]
296        let preferred = None;
297        let adapter = match preferred {
298            Some(adapter) => adapter,
299            None => pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
300                power_preference: wgpu::PowerPreference::HighPerformance,
301                force_fallback_adapter: false,
302                compatible_surface,
303                apply_limit_buckets: false,
304            }))
305            .map_err(|error| Error::new(format!("failed to acquire wgpu adapter: {error}")))?,
306        };
307
308        check_cancelled()?;
309        let required_features = optional_renderer_features(&adapter);
310        let (device, queue) = pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
311            label: Some("SUI renderer device"),
312            required_features,
313            required_limits: adapter.limits(),
314            ..Default::default()
315        }))
316        .map_err(|error| Error::new(format!("failed to create wgpu device: {error}")))?;
317
318        check_cancelled()?;
319        Ok(SharedRenderer::new(adapter, device, queue))
320    }
321
322    #[cfg(target_os = "windows")]
323    fn preferred_windows_adapter(
324        instance: &wgpu::Instance,
325        surface: Option<&wgpu::Surface<'_>>,
326    ) -> Option<wgpu::Adapter> {
327        // Prefer the native presentation backend. NVIDIA's Vulkan FIFO path can
328        // spend multiple refresh intervals acquiring images during window moves;
329        // DX12 also supports our native scRGB swapchain configuration directly.
330        // Explicit backend selection and machines without a compatible DX12 GPU
331        // continue through wgpu's normal adapter selection/fallback path.
332        if std::env::var_os("WGPU_BACKEND").is_some() {
333            return None;
334        }
335        pollster::block_on(instance.enumerate_adapters(wgpu::Backends::DX12))
336            .into_iter()
337            .filter(|adapter| surface.is_none_or(|surface| adapter.is_surface_supported(surface)))
338            .filter_map(|adapter| {
339                let info = adapter.get_info();
340                windows_adapter_rank(info.backend, info.device_type).map(|rank| (rank, adapter))
341            })
342            .min_by_key(|(rank, _)| *rank)
343            .map(|(_, adapter)| adapter)
344    }
345
346    #[cfg(target_arch = "wasm32")]
347    pub async fn initialize_async(
348        &mut self,
349        compatible_surface: Option<&wgpu::Surface<'_>>,
350    ) -> Result<()> {
351        if self.shared.is_some() {
352            return Ok(());
353        }
354
355        let adapter = self
356            .instance
357            .request_adapter(&wgpu::RequestAdapterOptions {
358                power_preference: wgpu::PowerPreference::None,
359                force_fallback_adapter: false,
360                compatible_surface,
361                apply_limit_buckets: false,
362            })
363            .await
364            .map_err(|error| Error::new(format!("failed to acquire wgpu adapter: {error}")))?;
365
366        let required_features = optional_renderer_features(&adapter);
367        let (device, queue) = adapter
368            .request_device(&wgpu::DeviceDescriptor {
369                label: Some("SUI renderer device"),
370                required_features,
371                required_limits: adapter.limits(),
372                ..Default::default()
373            })
374            .await
375            .map_err(|error| Error::new(format!("failed to create wgpu device: {error}")))?;
376
377        self.install_shared(SharedRenderer::new(adapter, device, queue));
378
379        Ok(())
380    }
381}
382
383#[cfg(any(target_os = "windows", test))]
384fn windows_adapter_rank(backend: wgpu::Backend, device_type: wgpu::DeviceType) -> Option<u8> {
385    if backend != wgpu::Backend::Dx12 {
386        return None;
387    }
388    match device_type {
389        wgpu::DeviceType::DiscreteGpu => Some(0),
390        wgpu::DeviceType::IntegratedGpu => Some(1),
391        wgpu::DeviceType::VirtualGpu => Some(2),
392        wgpu::DeviceType::Cpu | wgpu::DeviceType::Other => None,
393    }
394}
395
396/// Build the renderer's wgpu instance with the GL backend left out unless the
397/// environment explicitly asks for it (`WGPU_BACKEND=gl`).
398///
399/// Initializing the GL/WGL backend spins up a device thread per instance, and
400/// concurrent initialization — one renderer per test in the headless harness —
401/// deadlocks inside some Windows OpenGL drivers (observed as all test threads
402/// parked on `wgl::create_instance_device` results while the creator threads
403/// sat inside `nvoglv64.dll`; the same churn also produces access-violation
404/// crashes). The primary native backends (Vulkan/Metal/DX12) cover every
405/// platform SUI supports, so GL is opt-in rather than eagerly probed.
406pub(crate) fn default_wgpu_instance() -> wgpu::Instance {
407    let mut descriptor = wgpu::InstanceDescriptor::new_without_display_handle_from_env();
408    if std::env::var_os("WGPU_BACKEND").is_none() {
409        descriptor.backends -= wgpu::Backends::GL;
410    }
411    wgpu::Instance::new(descriptor)
412}
413
414#[cfg(test)]
415mod tests {
416    #[test]
417    #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
418    fn preparation_failure_is_reported_without_installing_a_device() {
419        use std::sync::{Arc, atomic::AtomicBool};
420        let mut renderer = super::WgpuRenderer::new();
421        renderer.device_preparation = Some(super::DevicePreparation {
422            window: None,
423            cancelled: Arc::new(AtomicBool::new(false)),
424            thread: Some(std::thread::spawn(|| {
425                Err(sui_core::Error::new("expected device failure"))
426            })),
427        });
428        let id = renderer
429            .device_preparation
430            .as_ref()
431            .unwrap()
432            .thread
433            .as_ref()
434            .unwrap()
435            .thread()
436            .id();
437        renderer.prepare_device();
438        assert_eq!(
439            renderer
440                .device_preparation
441                .as_ref()
442                .unwrap()
443                .thread
444                .as_ref()
445                .unwrap()
446                .thread()
447                .id(),
448            id
449        );
450        assert!(
451            renderer
452                .ensure_shared(None)
453                .unwrap_err()
454                .to_string()
455                .contains("expected device failure")
456        );
457        assert!(renderer.shared.is_none());
458        assert!(renderer.device_preparation.is_none());
459    }
460
461    #[test]
462    #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
463    fn removing_a_prepared_window_and_dropping_renderer_cancel_pending_work() {
464        use std::sync::{
465            Arc,
466            atomic::{AtomicBool, Ordering},
467            mpsc,
468        };
469        for remove_window in [false, true] {
470            let mut renderer = super::WgpuRenderer::new();
471            let cancelled = Arc::new(AtomicBool::new(false));
472            let observed = cancelled.clone();
473            let (resume, resumed) = mpsc::channel();
474            let (done, completed) = mpsc::channel();
475            let window = sui_core::WindowId::new(8962);
476            renderer.device_preparation = Some(super::DevicePreparation {
477                window: Some(window),
478                cancelled,
479                thread: Some(std::thread::spawn(move || {
480                    resumed.recv().unwrap();
481                    done.send(observed.load(Ordering::Acquire)).unwrap();
482                    Err(sui_core::Error::new("cancelled test preparation"))
483                })),
484            });
485            if remove_window {
486                renderer.remove_window(window);
487            }
488            drop(renderer);
489            resume.send(()).unwrap();
490            assert!(
491                completed
492                    .recv_timeout(std::time::Duration::from_secs(5))
493                    .unwrap()
494            );
495        }
496    }
497
498    #[test]
499    fn windows_preference_selects_hardware_dx12_without_forcing_software_rendering() {
500        use wgpu::{
501            Backend::Dx12,
502            DeviceType::{Cpu, DiscreteGpu, IntegratedGpu},
503        };
504        let discrete = super::windows_adapter_rank(Dx12, DiscreteGpu).unwrap();
505        assert!(super::windows_adapter_rank(Dx12, IntegratedGpu).unwrap() > discrete);
506        assert_eq!(super::windows_adapter_rank(Dx12, Cpu), None);
507        assert_eq!(
508            super::windows_adapter_rank(wgpu::Backend::Vulkan, DiscreteGpu),
509            None
510        );
511    }
512}