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