Skip to main content

wgpu_core/
instance.rs

1use alloc::{borrow::ToOwned as _, boxed::Box, string::String, sync::Arc, vec, vec::Vec};
2use core::{
3    fmt,
4    sync::atomic::{AtomicBool, Ordering},
5};
6
7use hashbrown::HashMap;
8use thiserror::Error;
9
10use crate::{
11    api_log, api_log_debug,
12    device::{
13        queue::Queue, resource::Device, DeviceDescriptor, DeviceError, UserClosures, WaitIdleError,
14    },
15    id::markers,
16    limits::{self, check_limits, FailedLimit},
17    lock::{rank, Mutex, MutexGuard},
18    present::{ConfigureSurfaceError, Presentation},
19    resource::ResourceType,
20    resource_log,
21    timestamp_normalization::TimestampNormalizerInitError,
22    weak_vec::WeakVec,
23    DOWNLEVEL_WARNING_MESSAGE,
24};
25
26use wgt::{Backend, Backends, InstanceFlags, PowerPreference};
27
28#[derive(Debug)]
29pub(crate) struct InstanceDevices(Mutex<WeakVec<Device>>);
30
31impl Default for InstanceDevices {
32    fn default() -> Self {
33        Self::new()
34    }
35}
36
37impl InstanceDevices {
38    pub(crate) fn new() -> Self {
39        Self(Mutex::new(rank::INSTANCE_DEVICES, WeakVec::new()))
40    }
41
42    pub(crate) fn push(&self, device: &Arc<Device>) {
43        self.0.lock().push(Arc::downgrade(device));
44    }
45
46    /// Poll all devices stored in this instance.
47    ///
48    /// If `force_wait` is true, block until all buffer mappings are done.
49    ///
50    /// Return `all_queue_empty` indicating whether there are more queue
51    /// submissions still in flight.
52    fn poll_all_devices(
53        &self,
54        force_wait: bool,
55        closure_list: &mut UserClosures,
56    ) -> Result<bool, WaitIdleError> {
57        let mut all_queue_empty = true;
58        {
59            let device_guard = self.0.lock();
60
61            for device in device_guard.iter().filter_map(|device| device.upgrade()) {
62                let poll_type = if force_wait {
63                    // TODO(#8286): Should expose timeout to poll_all.
64                    wgt::PollType::wait_indefinitely()
65                } else {
66                    wgt::PollType::Poll
67                };
68
69                let (closures, result) = device.poll_and_return_closures(poll_type);
70
71                let is_queue_empty = matches!(result, Ok(wgt::PollStatus::QueueEmpty));
72
73                all_queue_empty &= is_queue_empty;
74
75                closure_list.extend(closures);
76            }
77        }
78
79        Ok(all_queue_empty)
80    }
81}
82
83#[derive(Default)]
84pub struct Instance {
85    _name: String,
86
87    /// List of instances per `wgpu-hal` backend.
88    ///
89    /// The ordering in this list implies prioritization and needs to be preserved.
90    instance_per_backend: Vec<(Backend, Box<dyn hal::DynInstance>)>,
91
92    /// The backends that were requested by the user.
93    requested_backends: Backends,
94
95    /// The backends that we could have attempted to obtain from `wgpu-hal` —
96    /// those for which support is compiled in, currently.
97    ///
98    /// The union of this and `requested_backends` is the set of backends that would be used,
99    /// independent of whether accessing the drivers/hardware for them succeeds.
100    /// To obtain the set of backends actually in use by this instance, check
101    /// `instance_per_backend` instead.
102    supported_backends: Backends,
103
104    pub flags: InstanceFlags,
105
106    /// Non-lifetimed [`raw_window_handle::DisplayHandle`], for keepalive and validation purposes in
107    /// [`Self::create_surface()`].
108    ///
109    /// When used with `winit`, callers are expected to pass its `OwnedDisplayHandle` (created from
110    /// the `EventLoop`) here.
111    display: Option<Box<dyn wgt::WgpuHasDisplayHandle>>,
112
113    /// Keeps track of all devices created from this instance, so that they can be polled.
114    devices: InstanceDevices,
115}
116
117impl Instance {
118    pub fn new(
119        name: &str,
120        instance_desc: wgt::InstanceDescriptor,
121        telemetry: Option<hal::Telemetry>,
122    ) -> Arc<Self> {
123        let mut this = InstanceBuilder::new(name, instance_desc, telemetry);
124
125        #[cfg(all(vulkan, not(target_os = "netbsd")))]
126        this.try_add_hal(hal::api::Vulkan);
127        #[cfg(metal)]
128        this.try_add_hal(hal::api::Metal);
129        #[cfg(dx12)]
130        this.try_add_hal(hal::api::Dx12);
131        #[cfg(gles)]
132        this.try_add_hal(hal::api::Gles);
133        #[cfg(feature = "noop")]
134        this.try_add_hal(hal::api::Noop);
135
136        this.build()
137    }
138
139    pub fn from_hal_instance<A: hal::Api>(
140        name: String,
141        hal_instance: <A as hal::Api>::Instance,
142    ) -> Arc<Self> {
143        Arc::new(Self {
144            _name: name,
145            instance_per_backend: vec![(A::VARIANT, Box::new(hal_instance))],
146            requested_backends: A::VARIANT.into(),
147            supported_backends: A::VARIANT.into(),
148            flags: InstanceFlags::default(),
149            display: None, // TODO: Extract display from HAL instance if available?
150            devices: InstanceDevices::new(),
151        })
152    }
153
154    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynInstance> {
155        self.instance_per_backend
156            .iter()
157            .find_map(|(instance_backend, instance)| {
158                (*instance_backend == backend).then(|| instance.as_ref())
159            })
160    }
161
162    /// # Safety
163    ///
164    /// - The raw instance handle returned must not be manually destroyed.
165    pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
166        self.raw(A::VARIANT).map(|instance| {
167            instance
168                .as_any()
169                .downcast_ref()
170                // This should be impossible. It would mean that backend instance and enum type are mismatching.
171                .expect("Stored instance is not of the correct type")
172        })
173    }
174
175    /// Creates a new surface targeting the given display/window handles.
176    ///
177    /// Internally attempts to create hal surfaces for all enabled backends.
178    ///
179    /// Fails only if creation for surfaces for all enabled backends fails in which case
180    /// the error for each enabled backend is listed.
181    /// Vice versa, if creation for any backend succeeds, success is returned.
182    /// Surface creation errors are logged to the debug log in any case.
183    ///
184    /// # Safety
185    ///
186    /// - `display_handle` must be a valid object to create a surface upon,
187    ///   falls back to the instance display handle otherwise.
188    /// - `window_handle` must remain valid as long as the returned
189    ///   [`Surface`] is being used.
190    pub unsafe fn create_surface(
191        &self,
192        display_handle: Option<raw_window_handle::RawDisplayHandle>,
193        window_handle: raw_window_handle::RawWindowHandle,
194    ) -> Result<Arc<Surface>, CreateSurfaceError> {
195        profiling::scope!("Instance::create_surface");
196
197        let instance_display_handle = self.display.as_ref().map(|d| {
198            d.display_handle()
199                .expect("Implementation did not provide a DisplayHandle")
200                .as_raw()
201        });
202        let display_handle = match (instance_display_handle, display_handle) {
203            (Some(a), Some(b)) => {
204                if a != b {
205                    return Err(CreateSurfaceError::MismatchingDisplayHandle);
206                }
207                a
208            }
209            (Some(hnd), None) => hnd,
210            (None, Some(hnd)) => hnd,
211            (None, None) => return Err(CreateSurfaceError::MissingDisplayHandle),
212        };
213
214        let mut errors = HashMap::default();
215        let mut surface_per_backend = HashMap::default();
216
217        for (backend, instance) in &self.instance_per_backend {
218            match unsafe {
219                instance
220                    .as_ref()
221                    .create_surface(display_handle, window_handle)
222            } {
223                Ok(raw) => {
224                    surface_per_backend.insert(*backend, raw);
225                }
226                Err(err) => {
227                    log::debug!(
228                        "Instance::create_surface: failed to create surface for {backend:?}: {err:?}"
229                    );
230                    errors.insert(*backend, err);
231                }
232            }
233        }
234
235        if surface_per_backend.is_empty() {
236            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
237                errors,
238            ))
239        } else {
240            let surface = Arc::new(Surface {
241                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
242                surface_per_backend,
243            });
244
245            Ok(surface)
246        }
247    }
248
249    /// Creates a new surface from the given drm configuration.
250    ///
251    /// # Safety
252    ///
253    /// - All parameters must point to valid DRM values.
254    ///
255    /// # Platform Support
256    ///
257    /// This function requires the `"drm"` feature. It is only available on
258    /// non-apple Unix-like platforms (Linux, FreeBSD) and currently only works
259    /// with the Vulkan backend.
260    #[cfg(drm)]
261    #[cfg_attr(not(vulkan), expect(unused_variables, unused_mut))]
262    pub unsafe fn create_surface_from_drm(
263        &self,
264        fd: i32,
265        plane: u32,
266        connector_id: u32,
267        width: u32,
268        height: u32,
269        refresh_rate: u32,
270    ) -> Result<Arc<Surface>, CreateSurfaceError> {
271        profiling::scope!("Instance::create_surface_from_drm");
272
273        let mut errors = HashMap::default();
274        let mut surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>> =
275            HashMap::default();
276
277        #[cfg(vulkan)]
278        {
279            let instance = unsafe { self.as_hal::<hal::api::Vulkan>() }
280                .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Vulkan))?;
281
282            // Safety must be upheld by the caller
283            match unsafe {
284                instance.create_surface_from_drm(
285                    fd,
286                    plane,
287                    connector_id,
288                    width,
289                    height,
290                    refresh_rate,
291                )
292            } {
293                Ok(surface) => {
294                    surface_per_backend.insert(Backend::Vulkan, Box::new(surface));
295                }
296                Err(err) => {
297                    errors.insert(Backend::Vulkan, err);
298                }
299            }
300        }
301
302        if surface_per_backend.is_empty() {
303            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
304                errors,
305            ))
306        } else {
307            let surface = Arc::new(Surface {
308                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
309                surface_per_backend,
310            });
311
312            Ok(surface)
313        }
314    }
315
316    /// # Safety
317    ///
318    /// `layer` must be a valid pointer.
319    #[cfg(metal)]
320    pub unsafe fn create_surface_metal(
321        &self,
322        layer: *mut core::ffi::c_void,
323    ) -> Result<Arc<Surface>, CreateSurfaceError> {
324        profiling::scope!("Instance::create_surface_metal");
325
326        let instance = unsafe { self.as_hal::<hal::api::Metal>() }
327            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Metal))?;
328
329        let layer = layer.cast();
330        // SAFETY: We do this cast and deref. (rather than using `metal` to get the
331        // object we want) to avoid direct coupling on the `metal` crate.
332        //
333        // To wit, this pointer…
334        //
335        // - …is properly aligned.
336        // - …is dereferenceable to a `MetalLayerRef` as an invariant of the `metal`
337        //   field.
338        // - …points to an _initialized_ `MetalLayerRef`.
339        // - …is only ever aliased via an immutable reference that lives within this
340        //   lexical scope.
341        let layer = unsafe { &*layer };
342        let raw_surface: Box<dyn hal::DynSurface> =
343            Box::new(instance.create_surface_from_layer(layer));
344
345        let surface = Arc::new(Surface {
346            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
347            surface_per_backend: core::iter::once((Backend::Metal, raw_surface)).collect(),
348        });
349
350        Ok(surface)
351    }
352
353    #[cfg(dx12)]
354    fn create_surface_dx12(
355        &self,
356        create_surface_func: impl FnOnce(&hal::dx12::Instance) -> hal::dx12::Surface,
357    ) -> Result<Arc<Surface>, CreateSurfaceError> {
358        let instance = unsafe { self.as_hal::<hal::api::Dx12>() }
359            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Dx12))?;
360        let surface: Box<dyn hal::DynSurface> = Box::new(create_surface_func(instance));
361
362        let surface = Arc::new(Surface {
363            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
364            surface_per_backend: core::iter::once((Backend::Dx12, surface)).collect(),
365        });
366
367        Ok(surface)
368    }
369
370    #[cfg(dx12)]
371    /// # Safety
372    ///
373    /// The visual must be valid and able to be used to make a swapchain with.
374    pub unsafe fn create_surface_from_visual(
375        &self,
376        visual: *mut core::ffi::c_void,
377    ) -> Result<Arc<Surface>, CreateSurfaceError> {
378        profiling::scope!("Instance::instance_create_surface_from_visual");
379        self.create_surface_dx12(|inst| unsafe { inst.create_surface_from_visual(visual) })
380    }
381
382    #[cfg(dx12)]
383    /// # Safety
384    ///
385    /// The surface_handle must be valid and able to be used to make a swapchain with.
386    pub unsafe fn create_surface_from_surface_handle(
387        &self,
388        surface_handle: *mut core::ffi::c_void,
389    ) -> Result<Arc<Surface>, CreateSurfaceError> {
390        profiling::scope!("Instance::instance_create_surface_from_surface_handle");
391        self.create_surface_dx12(|inst| unsafe {
392            inst.create_surface_from_surface_handle(surface_handle)
393        })
394    }
395
396    #[cfg(dx12)]
397    /// # Safety
398    ///
399    /// The swap_chain_panel must be valid and able to be used to make a swapchain with.
400    pub unsafe fn create_surface_from_swap_chain_panel(
401        &self,
402        swap_chain_panel: *mut core::ffi::c_void,
403    ) -> Result<Arc<Surface>, CreateSurfaceError> {
404        profiling::scope!("Instance::instance_create_surface_from_swap_chain_panel");
405        self.create_surface_dx12(|inst| unsafe {
406            inst.create_surface_from_swap_chain_panel(swap_chain_panel)
407        })
408    }
409
410    fn adapter_allowed(&self, raw: &hal::DynExposedAdapter) -> bool {
411        adapter_allowed(
412            self.flags,
413            &raw.info,
414            &raw.capabilities.limits,
415            raw.features,
416        )
417    }
418
419    pub fn enumerate_adapters(
420        self: &Arc<Self>,
421        backends: Backends,
422        apply_limit_buckets: bool,
423    ) -> Vec<Arc<Adapter>> {
424        profiling::scope!("Instance::enumerate_adapters");
425        api_log!("Instance::enumerate_adapters");
426
427        self.request_adapters(
428            &wgt::RequestAdapterOptions {
429                power_preference: PowerPreference::None,
430                force_fallback_adapter: false,
431                compatible_surface: None,
432                apply_limit_buckets,
433            },
434            backends,
435        )
436        .unwrap_or_default()
437    }
438
439    /// Returns a list of adapters that match the given request options and are compatible with the specified backends.
440    ///
441    /// On success at least one compatible adapter will be returned in the resulting vector.
442    pub fn request_adapters(
443        self: &Arc<Self>,
444        desc: &wgt::RequestAdapterOptions<&Surface>,
445        backends: Backends,
446    ) -> Result<Vec<Arc<Adapter>>, wgt::RequestAdapterError> {
447        let mut adapters = Vec::new();
448        let mut incompatible_surface_backends = Backends::empty();
449        let mut no_fallback_backends = Backends::empty();
450        let mut no_adapter_backends = Backends::empty();
451
452        for &(backend, ref instance) in self
453            .instance_per_backend
454            .iter()
455            .filter(|&&(backend, _)| backends.contains(Backends::from(backend)))
456        {
457            profiling::scope!("enumerating", &*alloc::format!("{backend:?}"));
458
459            let compatible_hal_surface = desc
460                .compatible_surface
461                .and_then(|surface| surface.raw(backend));
462
463            let mut backend_adapters =
464                unsafe { instance.enumerate_adapters(compatible_hal_surface) };
465            if backend_adapters.is_empty() {
466                log::debug!("enabled backend `{backend:?}` has no adapters");
467                no_adapter_backends |= Backends::from(backend);
468                // by continuing, we avoid setting the further error bits below
469                continue;
470            }
471
472            if desc.force_fallback_adapter {
473                log::debug!("Filtering `{backend:?}` for `force_fallback_adapter`");
474                backend_adapters.retain(|exposed| {
475                    let keep = exposed.info.device_type == wgt::DeviceType::Cpu;
476                    if !keep {
477                        log::debug!("* Eliminating adapter `{}`", exposed.info.name);
478                    }
479                    keep
480                });
481                if backend_adapters.is_empty() {
482                    log::debug!("* Backend `{backend:?}` has no fallback adapters");
483                    no_fallback_backends |= Backends::from(backend);
484                    continue;
485                }
486            }
487
488            if let Some(surface) = desc.compatible_surface {
489                backend_adapters.retain(|exposed| {
490                    let capabilities = surface.get_capabilities_with_raw(exposed);
491                    if let Err(err) = capabilities {
492                        log::debug!(
493                            "Adapter {:?} not compatible with surface: {}",
494                            exposed.info,
495                            err
496                        );
497                        incompatible_surface_backends |= Backends::from(backend);
498                        false
499                    } else {
500                        true
501                    }
502                });
503                if backend_adapters.is_empty() {
504                    incompatible_surface_backends |= Backends::from(backend);
505                    continue;
506                }
507            }
508
509            let backend_adapters = backend_adapters
510                .into_iter()
511                .map(|mut raw| {
512                    self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
513                    raw
514                })
515                .map(|mut raw| {
516                    filter_features_and_limits(
517                        self.flags,
518                        &mut raw.features,
519                        &mut raw.capabilities.limits,
520                    );
521                    raw
522                })
523                .filter(|raw| self.adapter_allowed(raw));
524
525            if desc.apply_limit_buckets {
526                adapters.extend(backend_adapters.filter_map(limits::apply_limit_buckets));
527            } else {
528                adapters.extend(backend_adapters);
529            }
530        }
531
532        match desc.power_preference {
533            PowerPreference::LowPower => {
534                sort(&mut adapters, true);
535            }
536            PowerPreference::HighPerformance => {
537                sort(&mut adapters, false);
538            }
539            PowerPreference::None => {}
540        };
541
542        fn sort(adapters: &mut [hal::DynExposedAdapter], prefer_integrated_gpu: bool) {
543            adapters
544                .sort_by_key(|adapter| get_order(adapter.info.device_type, prefer_integrated_gpu));
545        }
546
547        fn get_order(device_type: wgt::DeviceType, prefer_integrated_gpu: bool) -> u8 {
548            // Since devices of type "Other" might really be "Unknown" and come
549            // from APIs like OpenGL that don't specify device type, Prefer more
550            // Specific types over Other.
551            //
552            // This means that backends which do provide accurate device types
553            // will be preferred if their device type indicates an actual
554            // hardware GPU (integrated or discrete).
555            match device_type {
556                wgt::DeviceType::DiscreteGpu if prefer_integrated_gpu => 2,
557                wgt::DeviceType::IntegratedGpu if prefer_integrated_gpu => 1,
558                wgt::DeviceType::DiscreteGpu => 1,
559                wgt::DeviceType::IntegratedGpu => 2,
560                wgt::DeviceType::Other => 3,
561                wgt::DeviceType::VirtualGpu => 4,
562                wgt::DeviceType::Cpu => 5,
563            }
564        }
565
566        // `request_adapter` can be a bit of a black box.
567        // Shine some light on its decision in debug log.
568        if adapters.is_empty() {
569            log::debug!("Request adapter didn't find compatible adapters.");
570            Err(wgt::RequestAdapterError::NotFound {
571                supported_backends: self.supported_backends,
572                requested_backends: self.requested_backends,
573                active_backends: self.active_backends(),
574                no_fallback_backends,
575                no_adapter_backends,
576                incompatible_surface_backends,
577            })
578        } else {
579            log::debug!(
580                "Found {} compatible adapters. Sorted by preference:",
581                adapters.len()
582            );
583            for adapter in &adapters {
584                log::debug!("* {:?}", adapter.info);
585            }
586            Ok(adapters
587                .into_iter()
588                .map(|adapter| Adapter::new(adapter, self.clone()))
589                .collect::<Vec<_>>())
590        }
591    }
592
593    pub fn request_adapter(
594        self: &Arc<Self>,
595        desc: &wgt::RequestAdapterOptions<&Surface>,
596        backends: Backends,
597    ) -> Result<Arc<Adapter>, wgt::RequestAdapterError> {
598        profiling::scope!("Instance::request_adapter");
599        api_log!("Instance::request_adapter");
600
601        let adapter = self
602            .request_adapters(desc, backends)?
603            .into_iter()
604            .next()
605            .expect(
606                "request_adapters should always return at least one compatible adapter on success",
607            );
608        api_log_debug!("Request adapter result {:?}", adapter.get_info());
609        Ok(adapter)
610    }
611
612    /// This is similar to wgpu-hal's `adjust_raw_limits` but tailored to
613    /// wgpu-core's constraints.
614    fn adjust_limits_for_indirect_validation(&self, limits: &mut wgt::Limits) {
615        // Indirect draw validation can't support u64 offsets,
616        // lower max buffer and binding size to fit in an u32.
617        if self.flags.contains(InstanceFlags::VALIDATION_INDIRECT_CALL) {
618            limits.max_buffer_size = limits.max_buffer_size.min(u32::MAX as u64);
619            limits.max_uniform_buffer_binding_size =
620                limits.max_uniform_buffer_binding_size.min(u32::MAX as u64);
621            limits.max_storage_buffer_binding_size = limits
622                .max_storage_buffer_binding_size
623                .min(u32::MAX as u64 & !(wgt::STORAGE_BINDING_SIZE_ALIGNMENT as u64 - 1));
624        }
625    }
626
627    fn active_backends(&self) -> Backends {
628        self.instance_per_backend
629            .iter()
630            .map(|&(backend, _)| Backends::from(backend))
631            .collect()
632    }
633
634    /// Create an adapter from a HAL adapter.
635    ///
636    /// The HAL adapter may be obtained e.g. by calling `enumerate_adapters` on
637    /// the HAL directly.
638    ///
639    /// If [limit bucketing][lt] is desired, [`crate::limits::apply_limit_buckets`]
640    /// should be called with the HAL adapter before calling this function.
641    ///
642    /// # Safety
643    ///
644    /// `hal_adapter` must be created from this global internal instance handle.
645    ///
646    /// [lt]: crate::limits#Limit-bucketing
647    pub unsafe fn create_adapter_from_hal(
648        self: &Arc<Self>,
649        hal_adapter: hal::DynExposedAdapter,
650    ) -> Arc<Adapter> {
651        profiling::scope!("Instance::create_adapter_from_hal");
652
653        let adapter = Adapter::new(hal_adapter, self.clone());
654
655        resource_log!("Created Adapter {:?}", Arc::as_ptr(&adapter));
656        adapter
657    }
658
659    /// Poll all devices on all backends.
660    ///
661    /// This is the implementation of `wgpu::Instance::poll_all`.
662    ///
663    /// Return `all_queue_empty` indicating whether there are more queue
664    /// submissions still in flight.
665    pub fn poll_all_devices(&self, force_wait: bool) -> Result<bool, WaitIdleError> {
666        api_log!("poll_all_devices");
667        let mut closures = UserClosures::default();
668        let all_queue_empty = self.devices.poll_all_devices(force_wait, &mut closures)?;
669
670        closures.fire();
671
672        Ok(all_queue_empty)
673    }
674}
675
676pub struct InstanceBuilder {
677    instance: Instance,
678    instance_desc: wgt::InstanceDescriptor,
679    telemetry: Option<hal::Telemetry>,
680}
681
682impl InstanceBuilder {
683    pub fn new(
684        name: &str,
685        mut desc: wgt::InstanceDescriptor,
686        telemetry: Option<hal::Telemetry>,
687    ) -> Self {
688        Self {
689            instance: Instance {
690                _name: name.to_owned(),
691                instance_per_backend: Vec::new(),
692                requested_backends: desc.backends,
693                supported_backends: Backends::empty(),
694                flags: desc.flags,
695                // HACK: We must take ownership of the field here, without being able to pass it into
696                // try_add_hal(). Remove it from the mutable descriptor instead, while try_add_hal()
697                // borrows the handle from `this.display` instead.
698                display: desc.display.take(),
699                devices: InstanceDevices::new(),
700            },
701            instance_desc: desc,
702            telemetry,
703        }
704    }
705
706    pub fn try_add_hal<A: hal::Api>(&mut self, api: A) {
707        use hal::Instance as _;
708        self.try_add_custom_hal(api, |hal_desc| unsafe { A::Instance::init(hal_desc) });
709    }
710
711    pub fn try_add_custom_hal<A: hal::Api>(
712        &mut self,
713        _: A,
714        f: impl FnOnce(&hal::InstanceDescriptor) -> Result<A::Instance, hal::InstanceError>,
715    ) {
716        if self.instance.supported_backends.contains(A::VARIANT.into()) {
717            return;
718        }
719
720        // Whether or not the backend was requested, and whether or not it succeeds,
721        // note that we *could* try it.
722        self.instance.supported_backends |= A::VARIANT.into();
723
724        if !self.instance_desc.backends.contains(A::VARIANT.into()) {
725            log::trace!("Instance::new: backend {:?} not requested", A::VARIANT);
726            return;
727        }
728
729        // If this was Some, it was moved into self
730        assert!(self.instance_desc.display.is_none());
731
732        let hal_desc = hal::InstanceDescriptor {
733            name: "wgpu",
734            flags: self.instance.flags,
735            memory_budget_thresholds: self.instance_desc.memory_budget_thresholds,
736            backend_options: self.instance_desc.backend_options.clone(),
737            telemetry: self.telemetry,
738            // Pass a borrow, the core instance here keeps the owned handle alive already
739            // WARNING: Using self here, not instance_desc!
740            display: self.instance.display.as_ref().map(|hdh| {
741                hdh.display_handle()
742                    .expect("Implementation did not provide a DisplayHandle")
743            }),
744        };
745
746        match f(&hal_desc) {
747            Ok(instance) => {
748                log::debug!("Instance::new: created {:?} backend", A::VARIANT);
749                self.instance
750                    .instance_per_backend
751                    .push((A::VARIANT, Box::new(instance)));
752            }
753            Err(err) => {
754                log::debug!(
755                    "Instance::new: failed to create {:?} backend: {:?}",
756                    A::VARIANT,
757                    err
758                );
759            }
760        }
761    }
762
763    pub fn build(self) -> Arc<Instance> {
764        Arc::new(self.instance)
765    }
766}
767
768pub struct Surface {
769    pub(crate) presentation: Mutex<Option<Presentation>>,
770    pub surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>>,
771}
772
773impl ResourceType for Surface {
774    const TYPE: &'static str = "Surface";
775}
776impl crate::storage::StorageItem for Surface {
777    type Marker = markers::Surface;
778}
779
780impl Surface {
781    pub fn get_capabilities(
782        &self,
783        adapter: &Adapter,
784    ) -> Result<wgt::SurfaceCapabilities, GetSurfaceSupportError> {
785        profiling::scope!("Surface::get_capabilities");
786        let mut hal_caps = self.get_hal_capabilities(adapter)?;
787
788        hal_caps
789            .formats
790            .sort_by_key(|fc| !fc.format.has_srgb_suffix());
791
792        let usages = crate::conv::map_texture_usage_from_hal(hal_caps.usage);
793
794        // `SurfaceCapabilities::formats` lists only the formats a
795        // color-space-unaware application can configure via
796        // `SurfaceColorSpace::Auto`, i.e. those for which `Auto` resolves to a
797        // concrete color space. (The full `format_capabilities` still reports
798        // every color space, including HDR ones, for explicit opt-in.)
799        Ok(wgt::SurfaceCapabilities {
800            formats: hal_caps
801                .formats
802                .iter()
803                .filter(|fc| {
804                    crate::device::surface_config::resolve_auto_color_space(
805                        fc.format,
806                        fc.color_spaces,
807                    )
808                    .is_some()
809                })
810                .map(|fc| fc.format)
811                .collect(),
812            format_capabilities: hal_caps.formats,
813            present_modes: hal_caps.present_modes,
814            alpha_modes: hal_caps.composite_alpha_modes,
815            usages,
816        })
817    }
818
819    pub fn get_hal_capabilities(
820        &self,
821        adapter: &Adapter,
822    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
823        self.get_capabilities_with_raw(&adapter.raw)
824    }
825
826    pub fn get_capabilities_with_raw(
827        &self,
828        adapter: &hal::DynExposedAdapter,
829    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
830        let backend = adapter.backend();
831        let suf = self
832            .raw(backend)
833            .ok_or(GetSurfaceSupportError::NotSupportedByBackend(backend))?;
834        profiling::scope!("surface_capabilities");
835        let caps = unsafe { adapter.adapter.surface_capabilities(suf) }
836            .ok_or(GetSurfaceSupportError::FailedToRetrieveSurfaceCapabilitiesForAdapter)?;
837        Ok(caps)
838    }
839
840    /// Returns the HDR / luminance characteristics of the display backing this
841    /// surface on `adapter`.
842    ///
843    /// Falls back to [`wgt::DisplayHdrInfo::default`] (all fields `None`) when the
844    /// surface is not on `adapter`'s backend or the backend reports nothing.
845    pub fn display_hdr_info(&self, adapter: &Adapter) -> wgt::DisplayHdrInfo {
846        profiling::scope!("Surface::display_hdr_info");
847        self.display_hdr_info_with_raw(&adapter.raw)
848    }
849
850    pub fn display_hdr_info_with_raw(
851        &self,
852        adapter: &hal::DynExposedAdapter,
853    ) -> wgt::DisplayHdrInfo {
854        let backend = adapter.backend();
855        let Some(suf) = self.raw(backend) else {
856            return wgt::DisplayHdrInfo::default();
857        };
858        profiling::scope!("surface_display_hdr_info");
859        unsafe { adapter.adapter.surface_display_hdr_info(suf) }.unwrap_or_default()
860    }
861
862    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynSurface> {
863        self.surface_per_backend
864            .get(&backend)
865            .map(|surface| surface.as_ref())
866    }
867
868    /// Takes the current configuration, destroys its acquired texture and waits
869    /// for all work on its device to finish.
870    ///
871    /// Returns the device the surface was configured for. The raw surface is
872    /// still configured, so the caller must unconfigure it next.
873    fn take_presentation<'a>(
874        &self,
875        presentation: &mut MutexGuard<'a, Option<Presentation>>,
876    ) -> (Option<Arc<Device>>, UserClosures) {
877        let mut result = UserClosures::default();
878        let mut device = None;
879        if let Some(mut present) = presentation.take() {
880            if let Some(texture) = present.acquired_texture.take() {
881                texture.destroy();
882            }
883
884            let user_callbacks;
885            {
886                // Wait for all work that uses the surface texture to finish
887                let snatch_guard = present.device.snatchable_lock.read();
888
889                let result;
890                (user_callbacks, result) = present
891                    .device
892                    .maintain(wgt::PollType::wait_indefinitely(), snatch_guard);
893                match result {
894                    Ok(_) => {}
895                    Err(WaitIdleError::Device(_)) => {
896                        // we can ignore device lost errors here, since we are just cleaning up
897                    }
898                    Err(WaitIdleError::Timeout) if cfg!(target_family = "wasm") => {
899                        // On wasm, you cannot actually successfully wait for the surface.
900                        // However WebGL does not actually require you do this, so ignoring
901                        // the failure is totally fine. See https://github.com/gfx-rs/wgpu/issues/7363
902                    }
903                    Err(WaitIdleError::Timeout) => {
904                        unreachable!("wait_indefinitely() should never timeout")
905                    }
906                    Err(WaitIdleError::WrongSubmissionIndex(_, _)) => {
907                        unreachable!("no submission index was provided")
908                    }
909                }
910            }
911            result.extend(user_callbacks);
912            device = Some(present.device);
913        }
914        (device, result)
915    }
916
917    /// Unconfigures the raw surface from `device`.
918    ///
919    /// # Safety
920    ///
921    /// `device` must have been returned by [`Self::take_presentation`], and the
922    /// surface must not have been configured since.
923    unsafe fn unconfigure_raw(&self, device: &Device) {
924        if let Some(surface) = self.raw(device.backend()) {
925            let _command_indices = device.command_indices.write();
926            unsafe { surface.unconfigure(device.raw()) };
927        }
928    }
929
930    fn unconfigure_inner<'a>(
931        &self,
932        presentation: &mut MutexGuard<'a, Option<Presentation>>,
933    ) -> UserClosures {
934        let (device, user_callbacks) = self.take_presentation(presentation);
935        if let Some(device) = device {
936            unsafe { self.unconfigure_raw(&device) };
937        }
938        user_callbacks
939    }
940
941    pub fn unconfigure(self: &Arc<Self>) {
942        profiling::scope!("Surface::unconfigure");
943        let user_callbacks;
944        {
945            let mut presentation = self.presentation.lock();
946            user_callbacks = self.unconfigure_inner(&mut presentation);
947        }
948        user_callbacks.fire();
949    }
950
951    pub fn configure(
952        self: &Arc<Self>,
953        device: &Arc<Device>,
954        config: &wgt::SurfaceConfiguration<Vec<wgt::TextureFormat>>,
955    ) -> Result<(), ConfigureSurfaceError> {
956        use ConfigureSurfaceError as E;
957        profiling::scope!("Surface::configure");
958
959        #[cfg(feature = "trace")]
960        if let Some(ref mut trace) = *device.trace.lock() {
961            use crate::device::trace::{Action, IntoTrace};
962
963            trace.add(Action::ConfigureSurface(self.to_trace(), config.clone()));
964        }
965
966        log::debug!("configuring surface with {config:?}");
967
968        let caps = self
969            .get_hal_capabilities(&device.adapter)
970            .map_err(|_| E::UnsupportedQueueFamily)?;
971
972        let mut hal_view_formats = Vec::new();
973        for format in config.view_formats.iter() {
974            if *format == config.format {
975                continue;
976            }
977            if !caps.formats.iter().any(|fc| fc.format == config.format) {
978                return Err(E::UnsupportedFormat {
979                    requested: config.format,
980                    available: caps.texture_formats().collect(),
981                });
982            }
983            if config.format.remove_srgb_suffix() != format.remove_srgb_suffix() {
984                return Err(E::InvalidViewFormat(*format, config.format));
985            }
986            hal_view_formats.push(*format);
987        }
988
989        if !hal_view_formats.is_empty() {
990            device.require_downlevel_flags(wgt::DownlevelFlags::SURFACE_VIEW_FORMATS)?;
991        }
992
993        let maximum_frame_latency = config.desired_maximum_frame_latency.clamp(
994            *caps.maximum_frame_latency.start(),
995            *caps.maximum_frame_latency.end(),
996        );
997        let mut hal_config = hal::SurfaceConfiguration {
998            maximum_frame_latency,
999            present_mode: config.present_mode,
1000            composite_alpha_mode: config.alpha_mode,
1001            format: config.format,
1002            color_space: config.color_space,
1003            extent: wgt::Extent3d {
1004                width: config.width,
1005                height: config.height,
1006                depth_or_array_layers: 1,
1007            },
1008            usage: crate::conv::map_texture_usage(
1009                config.usage,
1010                hal::FormatAspects::COLOR,
1011                wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY
1012                    | wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY
1013                    | wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
1014            ),
1015            view_formats: hal_view_formats,
1016        };
1017
1018        crate::device::surface_config::validate_surface_configuration(
1019            &mut hal_config,
1020            &caps,
1021            device.limits.max_texture_dimension_2d,
1022        )?;
1023
1024        device.check_is_valid()?;
1025
1026        let user_callbacks;
1027        let result = {
1028            // we keep presentation locked for the entire duration of the configure call,
1029            // so that no change can happen in the middle of it.
1030            let mut presentation = self.presentation.lock();
1031
1032            let previous_device;
1033            (previous_device, user_callbacks) = self.take_presentation(&mut presentation);
1034
1035            let surface_raw = self.raw(device.backend()).unwrap();
1036            // `command_indices` serializes these calls with other queue
1037            // operations. For the same device, hold it across both calls.
1038            let result = {
1039                let same_device = match previous_device {
1040                    Some(previous_device) if Arc::ptr_eq(&previous_device, device) => true,
1041                    Some(previous_device) => {
1042                        unsafe { self.unconfigure_raw(&previous_device) };
1043                        false
1044                    }
1045                    None => false,
1046                };
1047                let _command_indices = device.command_indices.write();
1048                if same_device {
1049                    unsafe { surface_raw.unconfigure(device.raw()) };
1050                }
1051                unsafe { surface_raw.configure(device.raw(), &hal_config) }
1052            };
1053            match result {
1054                Ok(()) => {
1055                    *presentation = Some(Presentation {
1056                        device: Arc::clone(device),
1057                        config: config.clone(),
1058                        acquired_texture: None,
1059                    });
1060                    Ok(())
1061                }
1062                Err(error) => Err(match error {
1063                    hal::SurfaceError::Outdated
1064                    | hal::SurfaceError::Lost
1065                    | hal::SurfaceError::Occluded
1066                    | hal::SurfaceError::Timeout => E::InvalidSurface,
1067                    hal::SurfaceError::Device(error) => E::Device(device.handle_hal_error(error)),
1068                    hal::SurfaceError::Other(message) => {
1069                        log::error!("surface configuration failed: {message}");
1070                        E::InvalidSurface
1071                    }
1072                }),
1073            }
1074        };
1075        user_callbacks.fire();
1076
1077        result
1078    }
1079}
1080
1081impl Drop for Surface {
1082    #[allow(trivial_casts)]
1083    fn drop(&mut self) {
1084        profiling::scope!("Surface::drop");
1085
1086        api_log!("Surface::drop {:?}", self as *const _);
1087        let user_closures;
1088        {
1089            let mut presentation = self.presentation.lock();
1090            user_closures = self.unconfigure_inner(&mut presentation);
1091        }
1092        user_closures.fire();
1093    }
1094}
1095
1096pub struct Adapter {
1097    pub(crate) raw: hal::DynExposedAdapter,
1098    pub(crate) instance: Arc<Instance>,
1099    consumed: AtomicBool,
1100}
1101
1102impl Adapter {
1103    pub(crate) fn new(raw: hal::DynExposedAdapter, instance: Arc<Instance>) -> Arc<Self> {
1104        Arc::new(Self {
1105            raw,
1106            instance,
1107            consumed: AtomicBool::new(false),
1108        })
1109    }
1110
1111    /// Returns the backend this adapter is using.
1112    pub fn backend(&self) -> Backend {
1113        self.raw.backend()
1114    }
1115
1116    pub fn is_surface_supported(&self, surface: &Surface) -> bool {
1117        // If get_capabilities returns Err, then the API does not advertise support for the surface.
1118        //
1119        // This could occur if the user is running their app on Wayland but Vulkan does not support
1120        // VK_KHR_wayland_surface.
1121        surface.get_hal_capabilities(self).is_ok()
1122    }
1123
1124    pub fn get_info(&self) -> wgt::AdapterInfo {
1125        self.raw.info.clone()
1126    }
1127
1128    pub fn features(&self) -> wgt::Features {
1129        self.raw.features
1130    }
1131
1132    pub fn limits(&self) -> wgt::Limits {
1133        self.raw.capabilities.limits.clone()
1134    }
1135
1136    pub fn downlevel_capabilities(&self) -> wgt::DownlevelCapabilities {
1137        self.raw.capabilities.downlevel.clone()
1138    }
1139
1140    pub fn get_presentation_timestamp(&self) -> wgt::PresentationTimestamp {
1141        unsafe { self.raw.adapter.get_presentation_timestamp() }
1142    }
1143
1144    pub fn cooperative_matrix_properties(&self) -> Vec<wgt::CooperativeMatrixProperties> {
1145        self.raw.capabilities.cooperative_matrix_properties.clone()
1146    }
1147
1148    pub fn ray_tracing_invocation_reorder_mode(&self) -> wgt::RayTracingInvocationReorderMode {
1149        self.raw.capabilities.ray_tracing_invocation_reorder_mode
1150    }
1151
1152    pub fn get_texture_format_features(
1153        &self,
1154        format: wgt::TextureFormat,
1155    ) -> wgt::TextureFormatFeatures {
1156        use hal::TextureFormatCapabilities as Tfc;
1157
1158        let mut caps = unsafe { self.raw.adapter.texture_format_capabilities(format) };
1159
1160        // Storage bindings of multi-planar textures are not supported.
1161        if format.is_multi_planar_format() {
1162            caps -= Tfc::STORAGE_READ_ONLY
1163                | Tfc::STORAGE_WRITE_ONLY
1164                | Tfc::STORAGE_READ_WRITE
1165                | Tfc::STORAGE_ATOMIC;
1166        }
1167
1168        let mut allowed_usages = wgt::TextureUsages::empty();
1169
1170        allowed_usages.set(wgt::TextureUsages::COPY_SRC, caps.contains(Tfc::COPY_SRC));
1171        allowed_usages.set(wgt::TextureUsages::COPY_DST, caps.contains(Tfc::COPY_DST));
1172        allowed_usages.set(
1173            wgt::TextureUsages::TEXTURE_BINDING,
1174            caps.contains(Tfc::SAMPLED),
1175        );
1176        allowed_usages.set(
1177            wgt::TextureUsages::STORAGE_BINDING,
1178            caps.intersects(
1179                Tfc::STORAGE_WRITE_ONLY
1180                    | Tfc::STORAGE_READ_ONLY
1181                    | Tfc::STORAGE_READ_WRITE
1182                    | Tfc::STORAGE_ATOMIC,
1183            ),
1184        );
1185        allowed_usages.set(
1186            wgt::TextureUsages::RENDER_ATTACHMENT | wgt::TextureUsages::TRANSIENT_ATTACHMENT,
1187            caps.intersects(Tfc::COLOR_ATTACHMENT | Tfc::DEPTH_STENCIL_ATTACHMENT),
1188        );
1189        allowed_usages.set(
1190            wgt::TextureUsages::STORAGE_ATOMIC,
1191            caps.contains(Tfc::STORAGE_ATOMIC),
1192        );
1193
1194        let mut flags = wgt::TextureFormatFeatureFlags::empty();
1195        flags.set(
1196            wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY,
1197            caps.contains(Tfc::STORAGE_READ_ONLY),
1198        );
1199        flags.set(
1200            wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY,
1201            caps.contains(Tfc::STORAGE_WRITE_ONLY),
1202        );
1203        flags.set(
1204            wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
1205            caps.contains(Tfc::STORAGE_READ_WRITE),
1206        );
1207
1208        flags.set(
1209            wgt::TextureFormatFeatureFlags::STORAGE_ATOMIC,
1210            caps.contains(Tfc::STORAGE_ATOMIC),
1211        );
1212
1213        flags.set(
1214            wgt::TextureFormatFeatureFlags::FILTERABLE,
1215            caps.contains(Tfc::SAMPLED_LINEAR),
1216        );
1217
1218        flags.set(
1219            wgt::TextureFormatFeatureFlags::BLENDABLE,
1220            caps.contains(Tfc::COLOR_ATTACHMENT_BLEND),
1221        );
1222
1223        flags.set(
1224            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X2,
1225            caps.contains(Tfc::MULTISAMPLE_X2),
1226        );
1227        flags.set(
1228            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X4,
1229            caps.contains(Tfc::MULTISAMPLE_X4),
1230        );
1231        flags.set(
1232            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X8,
1233            caps.contains(Tfc::MULTISAMPLE_X8),
1234        );
1235        flags.set(
1236            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X16,
1237            caps.contains(Tfc::MULTISAMPLE_X16),
1238        );
1239
1240        flags.set(
1241            wgt::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
1242            caps.contains(Tfc::MULTISAMPLE_RESOLVE),
1243        );
1244
1245        wgt::TextureFormatFeatures {
1246            allowed_usages,
1247            flags,
1248        }
1249    }
1250
1251    /// # Safety
1252    ///
1253    /// - `hal_device` must be created from this adapter.
1254    /// - `desc` must be a subset of `hal_device` features and limits.
1255    pub unsafe fn create_device_and_queue_from_hal(
1256        self: &Arc<Self>,
1257        hal_device: hal::DynOpenDevice,
1258        desc: &DeviceDescriptor,
1259    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
1260        profiling::scope!("Adapter::create_device_and_queue_from_hal");
1261        api_log!("Adapter::create_device_and_queue_from_hal");
1262
1263        if self
1264            .instance
1265            .flags
1266            .contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE)
1267            && self.consumed.load(Ordering::SeqCst)
1268        {
1269            return Err(RequestDeviceError::AdapterConsumed);
1270        }
1271
1272        let default_queue_desc = desc.default_queue.clone();
1273
1274        let device = Device::new(hal_device.device, self, desc, self.instance.flags)?;
1275        let device = Arc::new(device);
1276
1277        let queue = Queue::new(
1278            device.clone(),
1279            hal_device.queue,
1280            default_queue_desc,
1281            self.instance.flags,
1282        )?;
1283        let queue = Arc::new(queue);
1284
1285        device.set_queue(&queue);
1286        device.late_init_resources_with_queue()?;
1287
1288        resource_log!("Created Device {:?}", Arc::as_ptr(&device));
1289        resource_log!("Created Queue {:?}", Arc::as_ptr(&queue));
1290
1291        self.instance.devices.push(&device);
1292
1293        self.consumed.store(true, Ordering::SeqCst);
1294
1295        Ok((device, queue))
1296    }
1297
1298    /// Validate a device descriptor.
1299    ///
1300    /// This validates the provided device descriptor as if it were passed to
1301    /// [`Self::request_device`]. If [`InstanceFlags::STRICT_WEBGPU_COMPLIANCE`] is active,
1302    /// the requested extensions in the descriptor will be filtered to remove `wgpu`
1303    /// extensions, except for those that are included in [`limits::EXEMPT_FEATURES`].
1304    ///
1305    /// This may be useful when it is necessary to obtain the device itself from a raw hal
1306    /// API, but the rest of the `request_device` validation is still desired.
1307    pub fn validate_device_descriptor(
1308        &self,
1309        desc: &mut DeviceDescriptor,
1310    ) -> Result<(), RequestDeviceError> {
1311        filter_features_and_limits(
1312            self.instance.flags,
1313            &mut desc.required_features,
1314            &mut desc.required_limits,
1315        );
1316
1317        // Verify all features were exposed by the adapter
1318        if !self.raw.features.contains(desc.required_features) {
1319            return Err(RequestDeviceError::UnsupportedFeature(
1320                desc.required_features - self.raw.features,
1321            ));
1322        }
1323
1324        // Check if experimental features are permitted to be enabled.
1325        if desc
1326            .required_features
1327            .intersects(wgt::Features::all_experimental_mask())
1328            && !desc.experimental_features.is_enabled()
1329        {
1330            return Err(RequestDeviceError::ExperimentalFeaturesNotEnabled(
1331                desc.required_features
1332                    .intersection(wgt::Features::all_experimental_mask()),
1333            ));
1334        }
1335
1336        let caps = &self.raw.capabilities;
1337        if Backends::PRIMARY.contains(Backends::from(self.backend()))
1338            && !caps.downlevel.is_webgpu_compliant()
1339        {
1340            let missing_flags = wgt::DownlevelFlags::compliant() - caps.downlevel.flags;
1341            log::warn!("Missing downlevel flags: {missing_flags:?}\n{DOWNLEVEL_WARNING_MESSAGE}");
1342            log::warn!("{:#?}", caps.downlevel);
1343        }
1344
1345        // Verify feature preconditions
1346        if desc
1347            .required_features
1348            .contains(wgt::Features::MAPPABLE_PRIMARY_BUFFERS)
1349            && self.raw.info.device_type == wgt::DeviceType::DiscreteGpu
1350        {
1351            log::warn!(
1352                "Feature MAPPABLE_PRIMARY_BUFFERS enabled on a discrete gpu. \
1353                        This is a massive performance footgun and likely not what you wanted"
1354            );
1355        }
1356
1357        if let Some(failed) = check_limits(&desc.required_limits, &caps.limits).pop() {
1358            return Err(RequestDeviceError::LimitsExceeded(failed));
1359        }
1360
1361        normalize_max_resource_per_shader_stage_limits(&mut desc.required_limits);
1362
1363        Ok(())
1364    }
1365
1366    pub fn request_device(
1367        self: &Arc<Self>,
1368        desc: &DeviceDescriptor,
1369    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
1370        profiling::scope!("Adapter::request_device");
1371        api_log!("Adapter::request_device");
1372
1373        let mut desc = desc.clone();
1374        self.validate_device_descriptor(&mut desc)?;
1375
1376        let open = unsafe {
1377            self.raw.adapter.open(
1378                desc.required_features,
1379                &desc.required_limits,
1380                &desc.memory_hints,
1381            )
1382        }
1383        .map_err(DeviceError::from_hal)?;
1384
1385        unsafe { self.create_device_and_queue_from_hal(open, &desc) }
1386    }
1387}
1388
1389impl Drop for Adapter {
1390    #[allow(trivial_casts)]
1391    fn drop(&mut self) {
1392        profiling::scope!("Adapter::drop");
1393        api_log!("Adapter::drop {:?}", self as *const _);
1394    }
1395}
1396
1397crate::impl_resource_type!(Adapter);
1398crate::impl_storage_item!(Adapter);
1399
1400#[derive(Clone, Debug, Error)]
1401#[non_exhaustive]
1402pub enum GetSurfaceSupportError {
1403    #[error("Surface is not supported for the specified backend {0}")]
1404    NotSupportedByBackend(Backend),
1405    #[error("Failed to retrieve surface capabilities for the specified adapter.")]
1406    FailedToRetrieveSurfaceCapabilitiesForAdapter,
1407}
1408
1409#[derive(Clone, Debug, Error)]
1410/// Error when requesting a device from the adapter
1411#[non_exhaustive]
1412pub enum RequestDeviceError {
1413    #[error(transparent)]
1414    Device(#[from] DeviceError),
1415    #[error(transparent)]
1416    LimitsExceeded(#[from] FailedLimit),
1417    #[error("Failed to initialize Timestamp Normalizer")]
1418    TimestampNormalizerInitFailed(#[from] TimestampNormalizerInitError),
1419    #[error("Unsupported features were requested: {0}")]
1420    UnsupportedFeature(wgt::Features),
1421    #[error(
1422        "Some experimental features, {0}, were requested, but experimental features are not enabled"
1423    )]
1424    ExperimentalFeaturesNotEnabled(wgt::Features),
1425    #[error("The adapter has already been consumed.")]
1426    AdapterConsumed,
1427}
1428
1429#[derive(Clone, Debug, Error)]
1430#[non_exhaustive]
1431pub enum CreateSurfaceError {
1432    #[error("The backend {0} was not enabled on the instance.")]
1433    BackendNotEnabled(Backend),
1434    #[error("Failed to create surface for any enabled backend: {0:?}")]
1435    FailedToCreateSurfaceForAnyBackend(HashMap<Backend, hal::InstanceError>),
1436    #[error("The display handle used to create this Instance does not match the one used to create a surface on it")]
1437    MismatchingDisplayHandle,
1438    #[error(
1439        "No `DisplayHandle` is available to create this surface with.  When creating a surface with `create_surface()` \
1440        you must specify a display handle in `InstanceDescriptor::display`.  \
1441        Rarely, if you need to create surfaces from different `DisplayHandle`s (ex. different Wayland or X11 connections), \
1442        you must use `create_surface_unsafe()`."
1443    )]
1444    MissingDisplayHandle,
1445}
1446
1447/// This function checks that the adapter obeys WebGPU's adapter capability
1448/// guarantees. Most of the limits are adjusted in wgpu-hal's
1449/// `adjust_raw_limits` fn. So we only check the remaining properties here.
1450/// See <https://gpuweb.github.io/gpuweb/#adapter-capability-guarantees>.
1451fn adapter_allowed(
1452    flags: InstanceFlags,
1453    info: &impl fmt::Debug,
1454    limits: &wgt::Limits,
1455    features: wgt::Features,
1456) -> bool {
1457    // Check "All alignment-class limits must be powers of 2."
1458    //
1459    // Even if the application has not requested strict WebGPU compliance,
1460    // non-power-of-two alignment limits are nonsensical, so don't attempt
1461    // to use such a device.
1462    let min_uniform_buffer_offset_alignment = limits.min_uniform_buffer_offset_alignment;
1463    if !min_uniform_buffer_offset_alignment.is_power_of_two() {
1464        log::error!(
1465            "Adapter {:?} min_uniform_buffer_offset_alignment limit is not a power of 2: {:?}",
1466            info,
1467            min_uniform_buffer_offset_alignment
1468        );
1469        return false;
1470    }
1471    let min_storage_buffer_offset_alignment = limits.min_storage_buffer_offset_alignment;
1472    if !min_storage_buffer_offset_alignment.is_power_of_two() {
1473        log::error!(
1474            "Adapter {:?} min_storage_buffer_offset_alignment limit is not a power of 2: {:?}",
1475            info,
1476            min_storage_buffer_offset_alignment
1477        );
1478        return false;
1479    }
1480
1481    // Following checks are only enabled if `STRICT_WEBGPU_COMPLIANCE` is set.
1482    if !flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1483        return true;
1484    }
1485
1486    if !features.contains(wgt::Features::CORE_FEATURES_AND_LIMITS) {
1487        log::debug!(
1488            "Adapter {:?} is not WebGPU compliant because it does not support \
1489            CORE_FEATURES_AND_LIMITS",
1490            info
1491        );
1492        return false;
1493    }
1494
1495    true
1496}
1497
1498fn filter_features_and_limits(
1499    flags: InstanceFlags,
1500    features: &mut wgt::Features,
1501    limits: &mut wgt::Limits,
1502) {
1503    if flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1504        *features &= wgt::Features::all_webgpu_mask() | limits::EXEMPT_FEATURES;
1505        limits.zero_native_only();
1506    }
1507}
1508
1509fn normalize_max_resource_per_shader_stage_limits(limits: &mut wgt::Limits) {
1510    // The next steps are from <https://www.w3.org/TR/webgpu/#a-new-device>.
1511
1512    // > 7. Set `limits.maxStorageBuffersPerShaderStage` to
1513    // >    `max(limits.maxStorageBuffersPerShaderStage, limits.maxStorageBuffersInVertexStage,
1514    // >    limits.maxStorageBuffersInFragmentStage)`.
1515
1516    limits.max_storage_buffers_per_shader_stage = [
1517        limits.max_storage_buffers_per_shader_stage,
1518        limits.max_storage_buffers_in_vertex_stage,
1519        limits.max_storage_buffers_in_fragment_stage,
1520    ]
1521    .into_iter()
1522    .max()
1523    .unwrap();
1524
1525    // > 8. Set `limits.maxStorageTexturesPerShaderStage` to
1526    // >    `max(limits.maxStorageTexturesPerShaderStage, limits.maxStorageTexturesInVertexStage,
1527    // >    limits.maxStorageTexturesInFragmentStage)`.
1528
1529    limits.max_storage_textures_per_shader_stage = [
1530        limits.max_storage_textures_per_shader_stage,
1531        limits.max_storage_textures_in_vertex_stage,
1532        limits.max_storage_textures_in_fragment_stage,
1533    ]
1534    .into_iter()
1535    .max()
1536    .unwrap();
1537
1538    // > 9. If features contains "core-features-and-limits":
1539    //
1540    // NOTE: We don't implement compat (yet?), so we do this unconditionally. See also:
1541    // <https://github.com/gfx-rs/wgpu/issues/8124>
1542
1543    // >   1. Set `limits.maxStorageBuffersInVertexStage` and
1544    // >      `limits.maxStorageBuffersInFragmentStage` to
1545    // >      `limits.maxStorageBuffersPerShaderStage`.
1546    limits.max_storage_buffers_in_vertex_stage = limits.max_storage_buffers_per_shader_stage;
1547    limits.max_storage_buffers_in_fragment_stage = limits.max_storage_buffers_per_shader_stage;
1548
1549    // >   2. Set `limits.maxStorageTexturesInVertexStage` and
1550    // >      `limits.maxStorageTexturesInFragmentStage` to
1551    // >      `limits.maxStorageTexturesPerShaderStage`.
1552    limits.max_storage_textures_in_vertex_stage = limits.max_storage_textures_per_shader_stage;
1553    limits.max_storage_textures_in_fragment_stage = limits.max_storage_textures_per_shader_stage;
1554}
1555
1556#[cfg(test)]
1557mod tests {
1558    use super::*;
1559
1560    #[test]
1561    fn non_power_of_two_uniform_alignment_always_rejected() {
1562        let limits = wgt::Limits {
1563            min_uniform_buffer_offset_alignment: 3,
1564            ..wgt::Limits::defaults()
1565        };
1566        assert!(!adapter_allowed(
1567            InstanceFlags::empty(),
1568            &"",
1569            &limits,
1570            wgt::Features::CORE_FEATURES_AND_LIMITS
1571        ));
1572        assert!(!adapter_allowed(
1573            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1574            &"",
1575            &limits,
1576            wgt::Features::CORE_FEATURES_AND_LIMITS
1577        ));
1578    }
1579
1580    #[test]
1581    fn non_power_of_two_storage_alignment_always_rejected() {
1582        let limits = wgt::Limits {
1583            min_storage_buffer_offset_alignment: 96,
1584            ..wgt::Limits::defaults()
1585        };
1586        assert!(!adapter_allowed(
1587            InstanceFlags::empty(),
1588            &"",
1589            &limits,
1590            wgt::Features::CORE_FEATURES_AND_LIMITS
1591        ));
1592        assert!(!adapter_allowed(
1593            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1594            &"",
1595            &limits,
1596            wgt::Features::CORE_FEATURES_AND_LIMITS
1597        ));
1598    }
1599
1600    #[test]
1601    fn low_limits_allowed_without_strict_compliance() {
1602        let limits = wgt::Limits {
1603            max_texture_dimension_1d: 1,
1604            ..wgt::Limits::defaults()
1605        };
1606        assert!(adapter_allowed(
1607            InstanceFlags::empty(),
1608            &"",
1609            &limits,
1610            wgt::Features::empty()
1611        ));
1612    }
1613
1614    #[test]
1615    fn low_limits_rejected_with_strict_compliance() {
1616        let limits = wgt::Limits {
1617            max_texture_dimension_1d: 1,
1618            ..wgt::Limits::defaults()
1619        };
1620        assert!(!adapter_allowed(
1621            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1622            &"",
1623            &limits,
1624            wgt::Features::empty()
1625        ));
1626    }
1627
1628    #[test]
1629    fn missing_core_features_and_limits_rejected_with_strict_compliance() {
1630        assert!(!adapter_allowed(
1631            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1632            &"",
1633            &wgt::Limits::defaults(),
1634            wgt::Features::empty()
1635        ));
1636    }
1637
1638    #[test]
1639    fn fully_compliant_adapter_always_allowed() {
1640        assert!(adapter_allowed(
1641            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1642            &"",
1643            &wgt::Limits::defaults(),
1644            wgt::Features::CORE_FEATURES_AND_LIMITS
1645        ));
1646    }
1647
1648    mod storage_resource_limits {
1649        use super::*;
1650
1651        #[track_caller]
1652        fn assert_normalized_eq(non_normalized: &wgt::Limits, expected: &wgt::Limits) {
1653            let mut normalized = non_normalized.clone();
1654            normalize_max_resource_per_shader_stage_limits(&mut normalized);
1655            assert_eq!(&normalized, expected);
1656        }
1657
1658        #[test]
1659        fn normalization_is_idempotent() {
1660            let original = wgt::Limits {
1661                max_storage_buffers_in_vertex_stage: 16,
1662                max_storage_textures_in_vertex_stage: 9,
1663                ..wgt::Limits::defaults()
1664            };
1665
1666            let mut first_normalization = original.clone();
1667            normalize_max_resource_per_shader_stage_limits(&mut first_normalization);
1668            assert_ne!(original, first_normalization);
1669
1670            let mut second_normalization = first_normalization.clone();
1671            normalize_max_resource_per_shader_stage_limits(&mut second_normalization);
1672            assert_eq!(first_normalization, second_normalization);
1673        }
1674
1675        #[test]
1676        fn limits_presets_already_normalized() {
1677            [
1678                wgt::Limits::defaults(),
1679                wgt::Limits::downlevel_defaults(),
1680                wgt::Limits::downlevel_webgl2_defaults(),
1681                wgt::Limits::unlimited(),
1682            ]
1683            .iter()
1684            .for_each(|l| assert_normalized_eq(l, l))
1685        }
1686
1687        #[test]
1688        fn in_stage_raises_per_shader_stage() {
1689            assert_normalized_eq(
1690                &wgt::Limits {
1691                    max_storage_buffers_per_shader_stage: 8,
1692                    max_storage_buffers_in_vertex_stage: 16,
1693                    max_storage_buffers_in_fragment_stage: 16,
1694                    ..wgt::Limits::defaults()
1695                },
1696                &wgt::Limits {
1697                    max_storage_buffers_per_shader_stage: 16,
1698                    max_storage_buffers_in_vertex_stage: 16,
1699                    max_storage_buffers_in_fragment_stage: 16,
1700                    ..wgt::Limits::defaults()
1701                },
1702            );
1703
1704            assert_normalized_eq(
1705                &wgt::Limits {
1706                    max_storage_textures_per_shader_stage: 8,
1707                    max_storage_textures_in_vertex_stage: 9,
1708                    max_storage_textures_in_fragment_stage: 9,
1709                    ..wgt::Limits::defaults()
1710                },
1711                &wgt::Limits {
1712                    max_storage_textures_per_shader_stage: 9,
1713                    max_storage_textures_in_vertex_stage: 9,
1714                    max_storage_textures_in_fragment_stage: 9,
1715                    ..wgt::Limits::defaults()
1716                },
1717            );
1718        }
1719
1720        #[test]
1721        fn per_shader_stage_raises_in_stage() {
1722            assert_normalized_eq(
1723                &wgt::Limits {
1724                    max_storage_buffers_per_shader_stage: 16,
1725                    max_storage_buffers_in_vertex_stage: 4,
1726                    max_storage_buffers_in_fragment_stage: 4,
1727                    max_storage_textures_per_shader_stage: 8,
1728                    max_storage_textures_in_vertex_stage: 4,
1729                    max_storage_textures_in_fragment_stage: 4,
1730                    ..wgt::Limits::defaults()
1731                },
1732                &wgt::Limits {
1733                    max_storage_buffers_per_shader_stage: 16,
1734                    max_storage_buffers_in_vertex_stage: 16,
1735                    max_storage_buffers_in_fragment_stage: 16,
1736                    max_storage_textures_per_shader_stage: 8,
1737                    max_storage_textures_in_vertex_stage: 8,
1738                    max_storage_textures_in_fragment_stage: 8,
1739                    ..wgt::Limits::defaults()
1740                },
1741            );
1742        }
1743
1744        #[test]
1745        fn lowering_per_shader_stage_noop() {
1746            assert_normalized_eq(
1747                &wgt::Limits {
1748                    max_storage_buffers_per_shader_stage: 1,
1749                    max_storage_textures_per_shader_stage: 1,
1750                    ..wgt::Limits::defaults()
1751                },
1752                &wgt::Limits::defaults(),
1753            );
1754        }
1755    }
1756
1757    #[test]
1758    fn downlevel_default_limits_less_than_default_limits() {
1759        let res = check_limits(&wgt::Limits::downlevel_defaults(), &wgt::Limits::default());
1760        assert!(
1761            res.is_empty(),
1762            "Downlevel limits are greater than default limits",
1763        )
1764    }
1765}