Skip to main content

sui_render_wgpu/
device.rs

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