Skip to main content

wgpu_core/
instance.rs

1use alloc::{borrow::ToOwned as _, boxed::Box, string::String, sync::Arc, vec, vec::Vec};
2use core::{fmt, sync::atomic::AtomicBool};
3
4use hashbrown::HashMap;
5use thiserror::Error;
6
7use crate::{
8    api_log, api_log_debug,
9    device::{queue::Queue, resource::Device, DeviceDescriptor, DeviceError},
10    global::Global,
11    id::{markers, AdapterId, DeviceId, QueueId, SurfaceId},
12    limits::{self, check_limits, FailedLimit},
13    lock::{rank, Mutex},
14    present::Presentation,
15    resource::ResourceType,
16    resource_log,
17    timestamp_normalization::TimestampNormalizerInitError,
18    DOWNLEVEL_WARNING_MESSAGE,
19};
20
21use wgt::{Backend, Backends, InstanceFlags, PowerPreference};
22
23pub type RequestAdapterOptions = wgt::RequestAdapterOptions<SurfaceId>;
24
25#[test]
26fn downlevel_default_limits_less_than_default_limits() {
27    let res = check_limits(&wgt::Limits::downlevel_defaults(), &wgt::Limits::default());
28    assert!(
29        res.is_empty(),
30        "Downlevel limits are greater than default limits",
31    )
32}
33
34#[derive(Default)]
35pub struct Instance {
36    _name: String,
37
38    /// List of instances per `wgpu-hal` backend.
39    ///
40    /// The ordering in this list implies prioritization and needs to be preserved.
41    instance_per_backend: Vec<(Backend, Box<dyn hal::DynInstance>)>,
42
43    /// The backends that were requested by the user.
44    requested_backends: Backends,
45
46    /// The backends that we could have attempted to obtain from `wgpu-hal` —
47    /// those for which support is compiled in, currently.
48    ///
49    /// The union of this and `requested_backends` is the set of backends that would be used,
50    /// independent of whether accessing the drivers/hardware for them succeeds.
51    /// To obtain the set of backends actually in use by this instance, check
52    /// `instance_per_backend` instead.
53    supported_backends: Backends,
54
55    pub flags: InstanceFlags,
56
57    /// Non-lifetimed [`raw_window_handle::DisplayHandle`], for keepalive and validation purposes in
58    /// [`Self::create_surface()`].
59    ///
60    /// When used with `winit`, callers are expected to pass its `OwnedDisplayHandle` (created from
61    /// the `EventLoop`) here.
62    display: Option<Box<dyn wgt::WgpuHasDisplayHandle>>,
63}
64
65impl Instance {
66    pub fn new(
67        name: &str,
68        mut instance_desc: wgt::InstanceDescriptor,
69        telemetry: Option<hal::Telemetry>,
70    ) -> Self {
71        let mut this = Self {
72            _name: name.to_owned(),
73            instance_per_backend: Vec::new(),
74            requested_backends: instance_desc.backends,
75            supported_backends: Backends::empty(),
76            flags: instance_desc.flags,
77            // HACK: We must take ownership of the field here, without being able to pass it into
78            // try_add_hal(). Remove it from the mutable descriptor instead, while try_add_hal()
79            // borrows the handle from `this.display` instead.
80            display: instance_desc.display.take(),
81        };
82
83        #[cfg(all(vulkan, not(target_os = "netbsd")))]
84        this.try_add_hal(hal::api::Vulkan, &instance_desc, telemetry);
85        #[cfg(metal)]
86        this.try_add_hal(hal::api::Metal, &instance_desc, telemetry);
87        #[cfg(dx12)]
88        this.try_add_hal(hal::api::Dx12, &instance_desc, telemetry);
89        #[cfg(gles)]
90        this.try_add_hal(hal::api::Gles, &instance_desc, telemetry);
91        #[cfg(feature = "noop")]
92        this.try_add_hal(hal::api::Noop, &instance_desc, telemetry);
93
94        this
95    }
96
97    /// Helper for `Instance::new()`; attempts to add a single `wgpu-hal` backend to this instance.
98    fn try_add_hal<A: hal::Api>(
99        &mut self,
100        _: A,
101        instance_desc: &wgt::InstanceDescriptor,
102        telemetry: Option<hal::Telemetry>,
103    ) {
104        // Whether or not the backend was requested, and whether or not it succeeds,
105        // note that we *could* try it.
106        self.supported_backends |= A::VARIANT.into();
107
108        if !instance_desc.backends.contains(A::VARIANT.into()) {
109            log::trace!("Instance::new: backend {:?} not requested", A::VARIANT);
110            return;
111        }
112
113        // If this was Some, it was moved into self
114        assert!(instance_desc.display.is_none());
115
116        let hal_desc = hal::InstanceDescriptor {
117            name: "wgpu",
118            flags: self.flags,
119            memory_budget_thresholds: instance_desc.memory_budget_thresholds,
120            backend_options: instance_desc.backend_options.clone(),
121            telemetry,
122            // Pass a borrow, the core instance here keeps the owned handle alive already
123            // WARNING: Using self here, not instance_desc!
124            display: self.display.as_ref().map(|hdh| {
125                hdh.display_handle()
126                    .expect("Implementation did not provide a DisplayHandle")
127            }),
128        };
129
130        use hal::Instance as _;
131        // SAFETY: ???
132        match unsafe { A::Instance::init(&hal_desc) } {
133            Ok(instance) => {
134                log::debug!("Instance::new: created {:?} backend", A::VARIANT);
135                self.instance_per_backend
136                    .push((A::VARIANT, Box::new(instance)));
137            }
138            Err(err) => {
139                log::debug!(
140                    "Instance::new: failed to create {:?} backend: {:?}",
141                    A::VARIANT,
142                    err
143                );
144            }
145        }
146    }
147
148    pub(crate) fn from_hal_instance<A: hal::Api>(
149        name: String,
150        hal_instance: <A as hal::Api>::Instance,
151    ) -> Self {
152        Self {
153            _name: name,
154            instance_per_backend: vec![(A::VARIANT, Box::new(hal_instance))],
155            requested_backends: A::VARIANT.into(),
156            supported_backends: A::VARIANT.into(),
157            flags: InstanceFlags::default(),
158            display: None, // TODO: Extract display from HAL instance if available?
159        }
160    }
161
162    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynInstance> {
163        self.instance_per_backend
164            .iter()
165            .find_map(|(instance_backend, instance)| {
166                (*instance_backend == backend).then(|| instance.as_ref())
167            })
168    }
169
170    /// # Safety
171    ///
172    /// - The raw instance handle returned must not be manually destroyed.
173    pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
174        self.raw(A::VARIANT).map(|instance| {
175            instance
176                .as_any()
177                .downcast_ref()
178                // This should be impossible. It would mean that backend instance and enum type are mismatching.
179                .expect("Stored instance is not of the correct type")
180        })
181    }
182
183    /// Creates a new surface targeting the given display/window handles.
184    ///
185    /// Internally attempts to create hal surfaces for all enabled backends.
186    ///
187    /// Fails only if creation for surfaces for all enabled backends fails in which case
188    /// the error for each enabled backend is listed.
189    /// Vice versa, if creation for any backend succeeds, success is returned.
190    /// Surface creation errors are logged to the debug log in any case.
191    ///
192    /// # Safety
193    ///
194    /// - `display_handle` must be a valid object to create a surface upon,
195    ///   falls back to the instance display handle otherwise.
196    /// - `window_handle` must remain valid as long as the returned
197    ///   [`SurfaceId`] is being used.
198    pub unsafe fn create_surface(
199        &self,
200        display_handle: Option<raw_window_handle::RawDisplayHandle>,
201        window_handle: raw_window_handle::RawWindowHandle,
202    ) -> Result<Surface, CreateSurfaceError> {
203        profiling::scope!("Instance::create_surface");
204
205        let instance_display_handle = self.display.as_ref().map(|d| {
206            d.display_handle()
207                .expect("Implementation did not provide a DisplayHandle")
208                .as_raw()
209        });
210        let display_handle = match (instance_display_handle, display_handle) {
211            (Some(a), Some(b)) => {
212                if a != b {
213                    return Err(CreateSurfaceError::MismatchingDisplayHandle);
214                }
215                a
216            }
217            (Some(hnd), None) => hnd,
218            (None, Some(hnd)) => hnd,
219            (None, None) => return Err(CreateSurfaceError::MissingDisplayHandle),
220        };
221
222        let mut errors = HashMap::default();
223        let mut surface_per_backend = HashMap::default();
224
225        for (backend, instance) in &self.instance_per_backend {
226            match unsafe {
227                instance
228                    .as_ref()
229                    .create_surface(display_handle, window_handle)
230            } {
231                Ok(raw) => {
232                    surface_per_backend.insert(*backend, raw);
233                }
234                Err(err) => {
235                    log::debug!(
236                        "Instance::create_surface: failed to create surface for {backend:?}: {err:?}"
237                    );
238                    errors.insert(*backend, err);
239                }
240            }
241        }
242
243        if surface_per_backend.is_empty() {
244            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
245                errors,
246            ))
247        } else {
248            let surface = Surface {
249                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
250                keep_images: AtomicBool::new(false),
251                surface_per_backend,
252            };
253
254            Ok(surface)
255        }
256    }
257
258    /// Creates a new surface from the given drm configuration.
259    ///
260    /// # Safety
261    ///
262    /// - All parameters must point to valid DRM values.
263    ///
264    /// # Platform Support
265    ///
266    /// This function requires the `"drm"` feature. It is only available on
267    /// non-apple Unix-like platforms (Linux, FreeBSD) and currently only works
268    /// with the Vulkan backend.
269    #[cfg(drm)]
270    #[cfg_attr(not(vulkan), expect(unused_variables, unused_mut))]
271    pub unsafe fn create_surface_from_drm(
272        &self,
273        fd: i32,
274        plane: u32,
275        connector_id: u32,
276        width: u32,
277        height: u32,
278        refresh_rate: u32,
279    ) -> Result<Surface, CreateSurfaceError> {
280        profiling::scope!("Instance::create_surface_from_drm");
281
282        let mut errors = HashMap::default();
283        let mut surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>> =
284            HashMap::default();
285
286        #[cfg(vulkan)]
287        {
288            let instance = unsafe { self.as_hal::<hal::api::Vulkan>() }
289                .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Vulkan))?;
290
291            // Safety must be upheld by the caller
292            match unsafe {
293                instance.create_surface_from_drm(
294                    fd,
295                    plane,
296                    connector_id,
297                    width,
298                    height,
299                    refresh_rate,
300                )
301            } {
302                Ok(surface) => {
303                    surface_per_backend.insert(Backend::Vulkan, Box::new(surface));
304                }
305                Err(err) => {
306                    errors.insert(Backend::Vulkan, err);
307                }
308            }
309        }
310
311        if surface_per_backend.is_empty() {
312            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
313                errors,
314            ))
315        } else {
316            let surface = Surface {
317                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
318                keep_images: AtomicBool::new(false),
319                surface_per_backend,
320            };
321
322            Ok(surface)
323        }
324    }
325
326    /// # Safety
327    ///
328    /// `layer` must be a valid pointer.
329    #[cfg(metal)]
330    pub unsafe fn create_surface_metal(
331        &self,
332        layer: *mut core::ffi::c_void,
333    ) -> Result<Surface, CreateSurfaceError> {
334        profiling::scope!("Instance::create_surface_metal");
335
336        let instance = unsafe { self.as_hal::<hal::api::Metal>() }
337            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Metal))?;
338
339        let layer = layer.cast();
340        // SAFETY: We do this cast and deref. (rather than using `metal` to get the
341        // object we want) to avoid direct coupling on the `metal` crate.
342        //
343        // To wit, this pointer…
344        //
345        // - …is properly aligned.
346        // - …is dereferenceable to a `MetalLayerRef` as an invariant of the `metal`
347        //   field.
348        // - …points to an _initialized_ `MetalLayerRef`.
349        // - …is only ever aliased via an immutable reference that lives within this
350        //   lexical scope.
351        let layer = unsafe { &*layer };
352        let raw_surface: Box<dyn hal::DynSurface> =
353            Box::new(instance.create_surface_from_layer(layer));
354
355        let surface = Surface {
356            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
357            keep_images: AtomicBool::new(false),
358            surface_per_backend: core::iter::once((Backend::Metal, raw_surface)).collect(),
359        };
360
361        Ok(surface)
362    }
363
364    #[cfg(dx12)]
365    fn create_surface_dx12(
366        &self,
367        create_surface_func: impl FnOnce(&hal::dx12::Instance) -> hal::dx12::Surface,
368    ) -> Result<Surface, CreateSurfaceError> {
369        let instance = unsafe { self.as_hal::<hal::api::Dx12>() }
370            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Dx12))?;
371        let surface: Box<dyn hal::DynSurface> = Box::new(create_surface_func(instance));
372
373        let surface = Surface {
374            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
375            keep_images: AtomicBool::new(false),
376            surface_per_backend: core::iter::once((Backend::Dx12, surface)).collect(),
377        };
378
379        Ok(surface)
380    }
381
382    #[cfg(dx12)]
383    /// # Safety
384    ///
385    /// The visual must be valid and able to be used to make a swapchain with.
386    pub unsafe fn create_surface_from_visual(
387        &self,
388        visual: *mut core::ffi::c_void,
389    ) -> Result<Surface, CreateSurfaceError> {
390        profiling::scope!("Instance::instance_create_surface_from_visual");
391        self.create_surface_dx12(|inst| unsafe { inst.create_surface_from_visual(visual) })
392    }
393
394    #[cfg(dx12)]
395    /// # Safety
396    ///
397    /// The surface_handle must be valid and able to be used to make a swapchain with.
398    pub unsafe fn create_surface_from_surface_handle(
399        &self,
400        surface_handle: *mut core::ffi::c_void,
401    ) -> Result<Surface, CreateSurfaceError> {
402        profiling::scope!("Instance::instance_create_surface_from_surface_handle");
403        self.create_surface_dx12(|inst| unsafe {
404            inst.create_surface_from_surface_handle(surface_handle)
405        })
406    }
407
408    #[cfg(dx12)]
409    /// # Safety
410    ///
411    /// The swap_chain_panel must be valid and able to be used to make a swapchain with.
412    pub unsafe fn create_surface_from_swap_chain_panel(
413        &self,
414        swap_chain_panel: *mut core::ffi::c_void,
415    ) -> Result<Surface, CreateSurfaceError> {
416        profiling::scope!("Instance::instance_create_surface_from_swap_chain_panel");
417        self.create_surface_dx12(|inst| unsafe {
418            inst.create_surface_from_swap_chain_panel(swap_chain_panel)
419        })
420    }
421
422    fn adapter_allowed(&self, raw: &hal::DynExposedAdapter) -> bool {
423        adapter_allowed(
424            self.flags,
425            &raw.info,
426            &raw.capabilities.limits,
427            &raw.capabilities.downlevel,
428        )
429    }
430
431    pub fn enumerate_adapters(
432        &self,
433        backends: Backends,
434        apply_limit_buckets: bool,
435    ) -> Vec<Adapter> {
436        profiling::scope!("Instance::enumerate_adapters");
437        api_log!("Instance::enumerate_adapters");
438
439        let mut adapters = Vec::new();
440        for (_backend, instance) in self
441            .instance_per_backend
442            .iter()
443            .filter(|(backend, _)| backends.contains(Backends::from(*backend)))
444        {
445            // NOTE: We might be using `profiling` without any features. The empty backend of this
446            // macro emits no code, so unused code linting changes depending on the backend.
447            profiling::scope!("enumerating", &*alloc::format!("{_backend:?}"));
448
449            let hal_adapters = unsafe { instance.enumerate_adapters(None) };
450
451            adapters.extend(
452                hal_adapters
453                    .into_iter()
454                    .map(|mut raw| {
455                        self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
456                        raw
457                    })
458                    .map(|mut raw| {
459                        filter_features_and_limits(
460                            self.flags,
461                            &mut raw.features,
462                            &mut raw.capabilities.limits,
463                        );
464                        raw
465                    })
466                    .filter(|raw| self.adapter_allowed(raw))
467                    .filter_map(|raw| {
468                        if apply_limit_buckets {
469                            limits::apply_limit_buckets(raw)
470                        } else {
471                            Some(raw)
472                        }
473                    })
474                    .map(|raw| {
475                        let adapter = Adapter::new(raw);
476                        api_log_debug!("Adapter {:?}", adapter.raw.info);
477                        adapter
478                    }),
479            );
480        }
481        adapters
482    }
483
484    pub fn request_adapter(
485        &self,
486        desc: &wgt::RequestAdapterOptions<&Surface>,
487        backends: Backends,
488    ) -> Result<Adapter, wgt::RequestAdapterError> {
489        profiling::scope!("Instance::request_adapter");
490        api_log!("Instance::request_adapter");
491
492        let mut adapters = Vec::new();
493        let mut incompatible_surface_backends = Backends::empty();
494        let mut no_fallback_backends = Backends::empty();
495        let mut no_adapter_backends = Backends::empty();
496
497        for &(backend, ref instance) in self
498            .instance_per_backend
499            .iter()
500            .filter(|&&(backend, _)| backends.contains(Backends::from(backend)))
501        {
502            let compatible_hal_surface = desc
503                .compatible_surface
504                .and_then(|surface| surface.raw(backend));
505
506            let mut backend_adapters =
507                unsafe { instance.enumerate_adapters(compatible_hal_surface) };
508            if backend_adapters.is_empty() {
509                log::debug!("enabled backend `{backend:?}` has no adapters");
510                no_adapter_backends |= Backends::from(backend);
511                // by continuing, we avoid setting the further error bits below
512                continue;
513            }
514
515            if desc.force_fallback_adapter {
516                log::debug!("Filtering `{backend:?}` for `force_fallback_adapter`");
517                backend_adapters.retain(|exposed| {
518                    let keep = exposed.info.device_type == wgt::DeviceType::Cpu;
519                    if !keep {
520                        log::debug!("* Eliminating adapter `{}`", exposed.info.name);
521                    }
522                    keep
523                });
524                if backend_adapters.is_empty() {
525                    log::debug!("* Backend `{backend:?}` has no fallback adapters");
526                    no_fallback_backends |= Backends::from(backend);
527                    continue;
528                }
529            }
530
531            if let Some(surface) = desc.compatible_surface {
532                backend_adapters.retain(|exposed| {
533                    let capabilities = surface.get_capabilities_with_raw(exposed);
534                    if let Err(err) = capabilities {
535                        log::debug!(
536                            "Adapter {:?} not compatible with surface: {}",
537                            exposed.info,
538                            err
539                        );
540                        incompatible_surface_backends |= Backends::from(backend);
541                        false
542                    } else {
543                        true
544                    }
545                });
546                if backend_adapters.is_empty() {
547                    incompatible_surface_backends |= Backends::from(backend);
548                    continue;
549                }
550            }
551
552            let backend_adapters = backend_adapters
553                .into_iter()
554                .map(|mut raw| {
555                    self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
556                    raw
557                })
558                .map(|mut raw| {
559                    filter_features_and_limits(
560                        self.flags,
561                        &mut raw.features,
562                        &mut raw.capabilities.limits,
563                    );
564                    raw
565                })
566                .filter(|raw| self.adapter_allowed(raw));
567
568            if desc.apply_limit_buckets {
569                adapters.extend(backend_adapters.filter_map(limits::apply_limit_buckets));
570            } else {
571                adapters.extend(backend_adapters);
572            }
573        }
574
575        match desc.power_preference {
576            PowerPreference::LowPower => {
577                sort(&mut adapters, true);
578            }
579            PowerPreference::HighPerformance => {
580                sort(&mut adapters, false);
581            }
582            PowerPreference::None => {}
583        };
584
585        fn sort(adapters: &mut [hal::DynExposedAdapter], prefer_integrated_gpu: bool) {
586            adapters
587                .sort_by_key(|adapter| get_order(adapter.info.device_type, prefer_integrated_gpu));
588        }
589
590        fn get_order(device_type: wgt::DeviceType, prefer_integrated_gpu: bool) -> u8 {
591            // Since devices of type "Other" might really be "Unknown" and come
592            // from APIs like OpenGL that don't specify device type, Prefer more
593            // Specific types over Other.
594            //
595            // This means that backends which do provide accurate device types
596            // will be preferred if their device type indicates an actual
597            // hardware GPU (integrated or discrete).
598            match device_type {
599                wgt::DeviceType::DiscreteGpu if prefer_integrated_gpu => 2,
600                wgt::DeviceType::IntegratedGpu if prefer_integrated_gpu => 1,
601                wgt::DeviceType::DiscreteGpu => 1,
602                wgt::DeviceType::IntegratedGpu => 2,
603                wgt::DeviceType::Other => 3,
604                wgt::DeviceType::VirtualGpu => 4,
605                wgt::DeviceType::Cpu => 5,
606            }
607        }
608
609        // `request_adapter` can be a bit of a black box.
610        // Shine some light on its decision in debug log.
611        if adapters.is_empty() {
612            log::debug!("Request adapter didn't find compatible adapters.");
613        } else {
614            log::debug!(
615                "Found {} compatible adapters. Sorted by preference:",
616                adapters.len()
617            );
618            for adapter in &adapters {
619                log::debug!("* {:?}", adapter.info);
620            }
621        }
622
623        if let Some(adapter) = adapters.into_iter().next() {
624            api_log_debug!("Request adapter result {:?}", adapter.info);
625            let adapter = Adapter::new(adapter);
626            Ok(adapter)
627        } else {
628            Err(wgt::RequestAdapterError::NotFound {
629                supported_backends: self.supported_backends,
630                requested_backends: self.requested_backends,
631                active_backends: self.active_backends(),
632                no_fallback_backends,
633                no_adapter_backends,
634                incompatible_surface_backends,
635            })
636        }
637    }
638
639    /// This is similar to wgpu-hal's `adjust_raw_limits` but tailored to
640    /// wgpu-core's constraints.
641    fn adjust_limits_for_indirect_validation(&self, limits: &mut wgt::Limits) {
642        // Indirect draw validation can't support u64 offsets,
643        // lower max buffer and binding size to fit in an u32.
644        if self.flags.contains(InstanceFlags::VALIDATION_INDIRECT_CALL) {
645            limits.max_buffer_size = limits.max_buffer_size.min(u32::MAX as u64);
646            limits.max_uniform_buffer_binding_size =
647                limits.max_uniform_buffer_binding_size.min(u32::MAX as u64);
648            limits.max_storage_buffer_binding_size = limits
649                .max_storage_buffer_binding_size
650                .min(u32::MAX as u64 & !(wgt::STORAGE_BINDING_SIZE_ALIGNMENT as u64 - 1));
651        }
652    }
653
654    fn active_backends(&self) -> Backends {
655        self.instance_per_backend
656            .iter()
657            .map(|&(backend, _)| Backends::from(backend))
658            .collect()
659    }
660}
661
662pub struct Surface {
663    pub(crate) presentation: Mutex<Option<Presentation>>,
664    /// Whether an image acquired again holds what it presented, where the
665    /// backend keeps it (Cranpose fork; see `Global::surface_keep_presented_images`).
666    pub(crate) keep_images: AtomicBool,
667    pub surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>>,
668}
669
670impl ResourceType for Surface {
671    const TYPE: &'static str = "Surface";
672}
673impl crate::storage::StorageItem for Surface {
674    type Marker = markers::Surface;
675}
676
677impl Surface {
678    pub fn get_capabilities(
679        &self,
680        adapter: &Adapter,
681    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
682        self.get_capabilities_with_raw(&adapter.raw)
683    }
684
685    pub fn get_capabilities_with_raw(
686        &self,
687        adapter: &hal::DynExposedAdapter,
688    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
689        let backend = adapter.backend();
690        let suf = self
691            .raw(backend)
692            .ok_or(GetSurfaceSupportError::NotSupportedByBackend(backend))?;
693        profiling::scope!("surface_capabilities");
694        let caps = unsafe { adapter.adapter.surface_capabilities(suf) }
695            .ok_or(GetSurfaceSupportError::FailedToRetrieveSurfaceCapabilitiesForAdapter)?;
696        Ok(caps)
697    }
698
699    /// Returns the HDR / luminance characteristics of the display backing this
700    /// surface on `adapter`.
701    ///
702    /// Falls back to [`wgt::DisplayHdrInfo::default`] (all fields `None`) when the
703    /// surface is not on `adapter`'s backend or the backend reports nothing.
704    pub fn display_hdr_info(&self, adapter: &Adapter) -> wgt::DisplayHdrInfo {
705        self.display_hdr_info_with_raw(&adapter.raw)
706    }
707
708    pub fn display_hdr_info_with_raw(
709        &self,
710        adapter: &hal::DynExposedAdapter,
711    ) -> wgt::DisplayHdrInfo {
712        let backend = adapter.backend();
713        let Some(suf) = self.raw(backend) else {
714            return wgt::DisplayHdrInfo::default();
715        };
716        profiling::scope!("surface_display_hdr_info");
717        unsafe { adapter.adapter.surface_display_hdr_info(suf) }.unwrap_or_default()
718    }
719
720    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynSurface> {
721        self.surface_per_backend
722            .get(&backend)
723            .map(|surface| surface.as_ref())
724    }
725}
726
727impl Drop for Surface {
728    fn drop(&mut self) {
729        if let Some(present) = self.presentation.lock().take() {
730            for (&backend, surface) in &self.surface_per_backend {
731                if backend == present.device.backend() {
732                    unsafe { surface.unconfigure(present.device.raw()) };
733                }
734            }
735        }
736    }
737}
738
739pub struct Adapter {
740    pub(crate) raw: hal::DynExposedAdapter,
741}
742
743impl Adapter {
744    pub fn new(raw: hal::DynExposedAdapter) -> Self {
745        Self { raw }
746    }
747
748    /// Returns the backend this adapter is using.
749    pub fn backend(&self) -> Backend {
750        self.raw.backend()
751    }
752
753    pub fn is_surface_supported(&self, surface: &Surface) -> bool {
754        // If get_capabilities returns Err, then the API does not advertise support for the surface.
755        //
756        // This could occur if the user is running their app on Wayland but Vulkan does not support
757        // VK_KHR_wayland_surface.
758        surface.get_capabilities(self).is_ok()
759    }
760
761    pub fn get_info(&self) -> wgt::AdapterInfo {
762        self.raw.info.clone()
763    }
764
765    pub fn features(&self) -> wgt::Features {
766        self.raw.features
767    }
768
769    pub fn limits(&self) -> wgt::Limits {
770        self.raw.capabilities.limits.clone()
771    }
772
773    pub fn downlevel_capabilities(&self) -> wgt::DownlevelCapabilities {
774        self.raw.capabilities.downlevel.clone()
775    }
776
777    pub fn get_presentation_timestamp(&self) -> wgt::PresentationTimestamp {
778        unsafe { self.raw.adapter.get_presentation_timestamp() }
779    }
780
781    pub fn cooperative_matrix_properties(&self) -> Vec<wgt::CooperativeMatrixProperties> {
782        self.raw.capabilities.cooperative_matrix_properties.clone()
783    }
784
785    pub fn get_texture_format_features(
786        &self,
787        format: wgt::TextureFormat,
788    ) -> wgt::TextureFormatFeatures {
789        use hal::TextureFormatCapabilities as Tfc;
790
791        let caps = unsafe { self.raw.adapter.texture_format_capabilities(format) };
792        let mut allowed_usages = wgt::TextureUsages::empty();
793
794        allowed_usages.set(wgt::TextureUsages::COPY_SRC, caps.contains(Tfc::COPY_SRC));
795        allowed_usages.set(wgt::TextureUsages::COPY_DST, caps.contains(Tfc::COPY_DST));
796        allowed_usages.set(
797            wgt::TextureUsages::TEXTURE_BINDING,
798            caps.contains(Tfc::SAMPLED),
799        );
800        allowed_usages.set(
801            wgt::TextureUsages::STORAGE_BINDING,
802            caps.intersects(
803                Tfc::STORAGE_WRITE_ONLY
804                    | Tfc::STORAGE_READ_ONLY
805                    | Tfc::STORAGE_READ_WRITE
806                    | Tfc::STORAGE_ATOMIC,
807            ),
808        );
809        allowed_usages.set(
810            wgt::TextureUsages::RENDER_ATTACHMENT | wgt::TextureUsages::TRANSIENT_ATTACHMENT,
811            caps.intersects(Tfc::COLOR_ATTACHMENT | Tfc::DEPTH_STENCIL_ATTACHMENT),
812        );
813        allowed_usages.set(
814            wgt::TextureUsages::STORAGE_ATOMIC,
815            caps.contains(Tfc::STORAGE_ATOMIC),
816        );
817
818        let mut flags = wgt::TextureFormatFeatureFlags::empty();
819        flags.set(
820            wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY,
821            caps.contains(Tfc::STORAGE_READ_ONLY),
822        );
823        flags.set(
824            wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY,
825            caps.contains(Tfc::STORAGE_WRITE_ONLY),
826        );
827        flags.set(
828            wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
829            caps.contains(Tfc::STORAGE_READ_WRITE),
830        );
831
832        flags.set(
833            wgt::TextureFormatFeatureFlags::STORAGE_ATOMIC,
834            caps.contains(Tfc::STORAGE_ATOMIC),
835        );
836
837        flags.set(
838            wgt::TextureFormatFeatureFlags::FILTERABLE,
839            caps.contains(Tfc::SAMPLED_LINEAR),
840        );
841
842        flags.set(
843            wgt::TextureFormatFeatureFlags::BLENDABLE,
844            caps.contains(Tfc::COLOR_ATTACHMENT_BLEND),
845        );
846
847        flags.set(
848            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X2,
849            caps.contains(Tfc::MULTISAMPLE_X2),
850        );
851        flags.set(
852            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X4,
853            caps.contains(Tfc::MULTISAMPLE_X4),
854        );
855        flags.set(
856            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X8,
857            caps.contains(Tfc::MULTISAMPLE_X8),
858        );
859        flags.set(
860            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X16,
861            caps.contains(Tfc::MULTISAMPLE_X16),
862        );
863
864        flags.set(
865            wgt::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
866            caps.contains(Tfc::MULTISAMPLE_RESOLVE),
867        );
868
869        wgt::TextureFormatFeatures {
870            allowed_usages,
871            flags,
872        }
873    }
874
875    fn create_device_and_queue_from_hal(
876        self: &Arc<Self>,
877        hal_device: hal::DynOpenDevice,
878        desc: &DeviceDescriptor,
879        instance_flags: InstanceFlags,
880    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
881        api_log!("Adapter::create_device");
882
883        let device = Device::new(hal_device.device, self, desc, instance_flags)?;
884        let device = Arc::new(device);
885
886        let queue = Queue::new(device.clone(), hal_device.queue, instance_flags)?;
887        let queue = Arc::new(queue);
888
889        device.set_queue(&queue);
890        device.late_init_resources_with_queue()?;
891
892        Ok((device, queue))
893    }
894
895    pub fn create_device_and_queue(
896        self: &Arc<Self>,
897        desc: &DeviceDescriptor,
898        instance_flags: InstanceFlags,
899    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
900        let mut desc = desc.clone();
901        filter_features_and_limits(
902            instance_flags,
903            &mut desc.required_features,
904            &mut desc.required_limits,
905        );
906
907        // Verify all features were exposed by the adapter
908        if !self.raw.features.contains(desc.required_features) {
909            return Err(RequestDeviceError::UnsupportedFeature(
910                desc.required_features - self.raw.features,
911            ));
912        }
913
914        // Check if experimental features are permitted to be enabled.
915        if desc
916            .required_features
917            .intersects(wgt::Features::all_experimental_mask())
918            && !desc.experimental_features.is_enabled()
919        {
920            return Err(RequestDeviceError::ExperimentalFeaturesNotEnabled(
921                desc.required_features
922                    .intersection(wgt::Features::all_experimental_mask()),
923            ));
924        }
925
926        let caps = &self.raw.capabilities;
927        if Backends::PRIMARY.contains(Backends::from(self.backend()))
928            && !caps.downlevel.is_webgpu_compliant()
929        {
930            let missing_flags = wgt::DownlevelFlags::compliant() - caps.downlevel.flags;
931            log::warn!("Missing downlevel flags: {missing_flags:?}\n{DOWNLEVEL_WARNING_MESSAGE}");
932            log::warn!("{:#?}", caps.downlevel);
933        }
934
935        // Verify feature preconditions
936        if desc
937            .required_features
938            .contains(wgt::Features::MAPPABLE_PRIMARY_BUFFERS)
939            && self.raw.info.device_type == wgt::DeviceType::DiscreteGpu
940        {
941            log::warn!(
942                "Feature MAPPABLE_PRIMARY_BUFFERS enabled on a discrete gpu. \
943                        This is a massive performance footgun and likely not what you wanted"
944            );
945        }
946
947        if let Some(failed) = check_limits(&desc.required_limits, &caps.limits).pop() {
948            return Err(RequestDeviceError::LimitsExceeded(failed));
949        }
950
951        let open = unsafe {
952            self.raw.adapter.open(
953                desc.required_features,
954                &desc.required_limits,
955                &desc.memory_hints,
956            )
957        }
958        .map_err(DeviceError::from_hal)?;
959
960        self.create_device_and_queue_from_hal(open, &desc, instance_flags)
961    }
962}
963
964crate::impl_resource_type!(Adapter);
965crate::impl_storage_item!(Adapter);
966
967#[derive(Clone, Debug, Error)]
968#[non_exhaustive]
969pub enum GetSurfaceSupportError {
970    #[error("Surface is not supported for the specified backend {0}")]
971    NotSupportedByBackend(Backend),
972    #[error("Failed to retrieve surface capabilities for the specified adapter.")]
973    FailedToRetrieveSurfaceCapabilitiesForAdapter,
974}
975
976#[derive(Clone, Debug, Error)]
977/// Error when requesting a device from the adapter
978#[non_exhaustive]
979pub enum RequestDeviceError {
980    #[error(transparent)]
981    Device(#[from] DeviceError),
982    #[error(transparent)]
983    LimitsExceeded(#[from] FailedLimit),
984    #[error("Failed to initialize Timestamp Normalizer")]
985    TimestampNormalizerInitFailed(#[from] TimestampNormalizerInitError),
986    #[error("Unsupported features were requested: {0}")]
987    UnsupportedFeature(wgt::Features),
988    #[error(
989        "Some experimental features, {0}, were requested, but experimental features are not enabled"
990    )]
991    ExperimentalFeaturesNotEnabled(wgt::Features),
992}
993
994#[derive(Clone, Debug, Error)]
995#[non_exhaustive]
996pub enum CreateSurfaceError {
997    #[error("The backend {0} was not enabled on the instance.")]
998    BackendNotEnabled(Backend),
999    #[error("Failed to create surface for any enabled backend: {0:?}")]
1000    FailedToCreateSurfaceForAnyBackend(HashMap<Backend, hal::InstanceError>),
1001    #[error("The display handle used to create this Instance does not match the one used to create a surface on it")]
1002    MismatchingDisplayHandle,
1003    #[error(
1004        "No `DisplayHandle` is available to create this surface with.  When creating a surface with `create_surface()` \
1005        you must specify a display handle in `InstanceDescriptor::display`.  \
1006        Rarely, if you need to create surfaces from different `DisplayHandle`s (ex. different Wayland or X11 connections), \
1007        you must use `create_surface_unsafe()`."
1008    )]
1009    MissingDisplayHandle,
1010}
1011
1012impl Global {
1013    /// Creates a new surface targeting the given display/window handles.
1014    ///
1015    /// Internally attempts to create hal surfaces for all enabled backends.
1016    ///
1017    /// Fails only if creation for surfaces for all enabled backends fails in which case
1018    /// the error for each enabled backend is listed.
1019    /// Vice versa, if creation for any backend succeeds, success is returned.
1020    /// Surface creation errors are logged to the debug log in any case.
1021    ///
1022    /// id_in:
1023    /// - If `Some`, the id to assign to the surface. A new one will be generated otherwise.
1024    ///
1025    /// # Safety
1026    ///
1027    /// - `display_handle` must be a valid object to create a surface upon,
1028    ///   falls back to the instance display handle otherwise.
1029    /// - `window_handle` must remain valid as long as the returned
1030    ///   [`SurfaceId`] is being used.
1031    pub unsafe fn instance_create_surface(
1032        &self,
1033        display_handle: Option<raw_window_handle::RawDisplayHandle>,
1034        window_handle: raw_window_handle::RawWindowHandle,
1035        id_in: Option<SurfaceId>,
1036    ) -> Result<SurfaceId, CreateSurfaceError> {
1037        let surface = unsafe { self.instance.create_surface(display_handle, window_handle) }?;
1038        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1039        Ok(id)
1040    }
1041
1042    /// Creates a new surface from the given drm configuration.
1043    ///
1044    /// # Safety
1045    ///
1046    /// - All parameters must point to valid DRM values.
1047    ///
1048    /// # Platform Support
1049    ///
1050    /// This function requires the `"drm"` feature, and is only available on
1051    /// non-apple Unix-like platforms (Linux, FreeBSD) and currently only works
1052    /// with the Vulkan backend.
1053    #[cfg(drm)]
1054    pub unsafe fn instance_create_surface_from_drm(
1055        &self,
1056        fd: i32,
1057        plane: u32,
1058        connector_id: u32,
1059        width: u32,
1060        height: u32,
1061        refresh_rate: u32,
1062        id_in: Option<SurfaceId>,
1063    ) -> Result<SurfaceId, CreateSurfaceError> {
1064        let surface = unsafe {
1065            self.instance.create_surface_from_drm(
1066                fd,
1067                plane,
1068                connector_id,
1069                width,
1070                height,
1071                refresh_rate,
1072            )
1073        }?;
1074        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1075
1076        Ok(id)
1077    }
1078
1079    /// # Safety
1080    ///
1081    /// `layer` must be a valid pointer.
1082    #[cfg(metal)]
1083    pub unsafe fn instance_create_surface_metal(
1084        &self,
1085        layer: *mut core::ffi::c_void,
1086        id_in: Option<SurfaceId>,
1087    ) -> Result<SurfaceId, CreateSurfaceError> {
1088        let surface = unsafe { self.instance.create_surface_metal(layer) }?;
1089        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1090        Ok(id)
1091    }
1092
1093    #[cfg(dx12)]
1094    /// # Safety
1095    ///
1096    /// The visual must be valid and able to be used to make a swapchain with.
1097    pub unsafe fn instance_create_surface_from_visual(
1098        &self,
1099        visual: *mut core::ffi::c_void,
1100        id_in: Option<SurfaceId>,
1101    ) -> Result<SurfaceId, CreateSurfaceError> {
1102        let surface = unsafe { self.instance.create_surface_from_visual(visual) }?;
1103        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1104        Ok(id)
1105    }
1106
1107    #[cfg(dx12)]
1108    /// # Safety
1109    ///
1110    /// The surface_handle must be valid and able to be used to make a swapchain with.
1111    pub unsafe fn instance_create_surface_from_surface_handle(
1112        &self,
1113        surface_handle: *mut core::ffi::c_void,
1114        id_in: Option<SurfaceId>,
1115    ) -> Result<SurfaceId, CreateSurfaceError> {
1116        let surface = unsafe {
1117            self.instance
1118                .create_surface_from_surface_handle(surface_handle)
1119        }?;
1120        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1121        Ok(id)
1122    }
1123
1124    #[cfg(dx12)]
1125    /// # Safety
1126    ///
1127    /// The swap_chain_panel must be valid and able to be used to make a swapchain with.
1128    pub unsafe fn instance_create_surface_from_swap_chain_panel(
1129        &self,
1130        swap_chain_panel: *mut core::ffi::c_void,
1131        id_in: Option<SurfaceId>,
1132    ) -> Result<SurfaceId, CreateSurfaceError> {
1133        let surface = unsafe {
1134            self.instance
1135                .create_surface_from_swap_chain_panel(swap_chain_panel)
1136        }?;
1137        let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1138        Ok(id)
1139    }
1140
1141    pub fn surface_drop(&self, id: SurfaceId) {
1142        profiling::scope!("Surface::drop");
1143
1144        api_log!("Surface::drop {id:?}");
1145
1146        self.surfaces.remove(id);
1147    }
1148
1149    pub fn enumerate_adapters(
1150        &self,
1151        backends: Backends,
1152        apply_limit_buckets: bool,
1153    ) -> Vec<AdapterId> {
1154        let adapters = self
1155            .instance
1156            .enumerate_adapters(backends, apply_limit_buckets);
1157        adapters
1158            .into_iter()
1159            .map(|adapter| self.hub.adapters.prepare(None).assign(Arc::new(adapter)))
1160            .collect()
1161    }
1162
1163    pub fn request_adapter(
1164        &self,
1165        desc: &RequestAdapterOptions,
1166        backends: Backends,
1167        id_in: Option<AdapterId>,
1168    ) -> Result<AdapterId, wgt::RequestAdapterError> {
1169        let compatible_surface = desc.compatible_surface.map(|id| self.surfaces.get(id));
1170        let desc = wgt::RequestAdapterOptions {
1171            power_preference: desc.power_preference,
1172            force_fallback_adapter: desc.force_fallback_adapter,
1173            compatible_surface: compatible_surface.as_deref(),
1174            apply_limit_buckets: desc.apply_limit_buckets,
1175        };
1176        let adapter = self.instance.request_adapter(&desc, backends)?;
1177        let id = self.hub.adapters.prepare(id_in).assign(Arc::new(adapter));
1178        Ok(id)
1179    }
1180
1181    /// Create an adapter from a HAL adapter.
1182    ///
1183    /// The HAL adapter may be obtained e.g. by calling `enumerate_adapters` on
1184    /// the HAL directly.
1185    ///
1186    /// If [limit bucketing][lt] is desired, [`crate::limits::apply_limit_buckets`]
1187    /// should be called with the HAL adapter before calling this function.
1188    ///
1189    /// # Safety
1190    ///
1191    /// `hal_adapter` must be created from this global internal instance handle.
1192    ///
1193    /// [lt]: crate::limits#Limit-bucketing
1194    pub unsafe fn create_adapter_from_hal(
1195        &self,
1196        hal_adapter: hal::DynExposedAdapter,
1197        input: Option<AdapterId>,
1198    ) -> AdapterId {
1199        profiling::scope!("Instance::create_adapter_from_hal");
1200
1201        let fid = self.hub.adapters.prepare(input);
1202        let id = fid.assign(Arc::new(Adapter::new(hal_adapter)));
1203
1204        resource_log!("Created Adapter {:?}", id);
1205        id
1206    }
1207
1208    pub fn adapter_get_info(&self, adapter_id: AdapterId) -> wgt::AdapterInfo {
1209        let adapter = self.hub.adapters.get(adapter_id);
1210        adapter.get_info()
1211    }
1212
1213    pub fn adapter_get_texture_format_features(
1214        &self,
1215        adapter_id: AdapterId,
1216        format: wgt::TextureFormat,
1217    ) -> wgt::TextureFormatFeatures {
1218        let adapter = self.hub.adapters.get(adapter_id);
1219        adapter.get_texture_format_features(format)
1220    }
1221
1222    pub fn adapter_features(&self, adapter_id: AdapterId) -> wgt::Features {
1223        let adapter = self.hub.adapters.get(adapter_id);
1224        adapter.features()
1225    }
1226
1227    pub fn adapter_limits(&self, adapter_id: AdapterId) -> wgt::Limits {
1228        let adapter = self.hub.adapters.get(adapter_id);
1229        adapter.limits()
1230    }
1231
1232    pub fn adapter_downlevel_capabilities(
1233        &self,
1234        adapter_id: AdapterId,
1235    ) -> wgt::DownlevelCapabilities {
1236        let adapter = self.hub.adapters.get(adapter_id);
1237        adapter.downlevel_capabilities()
1238    }
1239
1240    pub fn adapter_get_presentation_timestamp(
1241        &self,
1242        adapter_id: AdapterId,
1243    ) -> wgt::PresentationTimestamp {
1244        let adapter = self.hub.adapters.get(adapter_id);
1245        adapter.get_presentation_timestamp()
1246    }
1247
1248    pub fn adapter_cooperative_matrix_properties(
1249        &self,
1250        adapter_id: AdapterId,
1251    ) -> Vec<wgt::CooperativeMatrixProperties> {
1252        let adapter = self.hub.adapters.get(adapter_id);
1253        adapter.cooperative_matrix_properties()
1254    }
1255
1256    pub fn adapter_drop(&self, adapter_id: AdapterId) {
1257        profiling::scope!("Adapter::drop");
1258        api_log!("Adapter::drop {adapter_id:?}");
1259
1260        self.hub.adapters.remove(adapter_id);
1261    }
1262}
1263
1264impl Global {
1265    pub fn adapter_request_device(
1266        &self,
1267        adapter_id: AdapterId,
1268        desc: &DeviceDescriptor,
1269        device_id_in: Option<DeviceId>,
1270        queue_id_in: Option<QueueId>,
1271    ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
1272        profiling::scope!("Adapter::request_device");
1273        api_log!("Adapter::request_device");
1274
1275        let device_fid = self.hub.devices.prepare(device_id_in);
1276        let queue_fid = self.hub.queues.prepare(queue_id_in);
1277
1278        let adapter = self.hub.adapters.get(adapter_id);
1279        let (device, queue) = adapter.create_device_and_queue(desc, self.instance.flags)?;
1280
1281        let device_id = device_fid.assign(device);
1282        resource_log!("Created Device {:?}", device_id);
1283
1284        let queue_id = queue_fid.assign(queue);
1285        resource_log!("Created Queue {:?}", queue_id);
1286
1287        Ok((device_id, queue_id))
1288    }
1289
1290    /// # Safety
1291    ///
1292    /// - `hal_device` must be created from `adapter_id` or its internal handle.
1293    /// - `desc` must be a subset of `hal_device` features and limits.
1294    pub unsafe fn create_device_from_hal(
1295        &self,
1296        adapter_id: AdapterId,
1297        hal_device: hal::DynOpenDevice,
1298        desc: &DeviceDescriptor,
1299        device_id_in: Option<DeviceId>,
1300        queue_id_in: Option<QueueId>,
1301    ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
1302        profiling::scope!("Global::create_device_from_hal");
1303
1304        let devices_fid = self.hub.devices.prepare(device_id_in);
1305        let queues_fid = self.hub.queues.prepare(queue_id_in);
1306
1307        let adapter = self.hub.adapters.get(adapter_id);
1308        let (device, queue) =
1309            adapter.create_device_and_queue_from_hal(hal_device, desc, self.instance.flags)?;
1310
1311        let device_id = devices_fid.assign(device);
1312        resource_log!("Created Device {:?}", device_id);
1313
1314        let queue_id = queues_fid.assign(queue);
1315        resource_log!("Created Queue {:?}", queue_id);
1316
1317        Ok((device_id, queue_id))
1318    }
1319}
1320
1321/// This function checks that the adapter obeys WebGPU's adapter capability
1322/// guarantees. Most of the limits are adjusted in wgpu-hal's
1323/// `adjust_raw_limits` fn. So we only check the remaining properties here.
1324/// See <https://gpuweb.github.io/gpuweb/#adapter-capability-guarantees>.
1325fn adapter_allowed(
1326    flags: InstanceFlags,
1327    info: &impl fmt::Debug,
1328    limits: &wgt::Limits,
1329    downlevel: &wgt::DownlevelCapabilities,
1330) -> bool {
1331    // Check "All alignment-class limits must be powers of 2."
1332    //
1333    // Even if the application has not requested strict WebGPU compliance,
1334    // non-power-of-two alignment limits are nonsensical, so don't attempt
1335    // to use such a device.
1336    let min_uniform_buffer_offset_alignment = limits.min_uniform_buffer_offset_alignment;
1337    if !min_uniform_buffer_offset_alignment.is_power_of_two() {
1338        log::error!(
1339            "Adapter {:?} min_uniform_buffer_offset_alignment limit is not a power of 2: {:?}",
1340            info,
1341            min_uniform_buffer_offset_alignment
1342        );
1343        return false;
1344    }
1345    let min_storage_buffer_offset_alignment = limits.min_storage_buffer_offset_alignment;
1346    if !min_storage_buffer_offset_alignment.is_power_of_two() {
1347        log::error!(
1348            "Adapter {:?} min_storage_buffer_offset_alignment limit is not a power of 2: {:?}",
1349            info,
1350            min_storage_buffer_offset_alignment
1351        );
1352        return false;
1353    }
1354
1355    // Following checks are only enabled if `STRICT_WEBGPU_COMPLIANCE` is set.
1356    if !flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1357        return true;
1358    }
1359
1360    // Check "All supported limits must be either the default value or better."
1361    let mut min_limits = wgt::Limits::defaults();
1362    min_limits.zero_native_only();
1363    let failed_limits = check_limits(&min_limits, limits);
1364    if !failed_limits.is_empty() {
1365        log::debug!(
1366            "Adapter {:?} is not WebGPU compliant due to limits: {:?}",
1367            info,
1368            failed_limits
1369        );
1370        return false;
1371    }
1372
1373    if !downlevel.is_webgpu_compliant() {
1374        let missing_flags = wgt::DownlevelFlags::compliant() - downlevel.flags;
1375        log::debug!(
1376            "Adapter {:?} is not WebGPU compliant due to missing downlevel flags: {:?}",
1377            info,
1378            missing_flags
1379        );
1380        return false;
1381    }
1382
1383    true
1384}
1385
1386fn filter_features_and_limits(
1387    flags: InstanceFlags,
1388    features: &mut wgt::Features,
1389    limits: &mut wgt::Limits,
1390) {
1391    if flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1392        *features &= wgt::Features::all_webgpu_mask() | limits::EXEMPT_FEATURES;
1393        limits.zero_native_only();
1394    }
1395}
1396
1397#[cfg(test)]
1398mod tests {
1399    use super::*;
1400
1401    fn compliant_downlevel() -> wgt::DownlevelCapabilities {
1402        wgt::DownlevelCapabilities {
1403            flags: wgt::DownlevelFlags::compliant(),
1404            ..Default::default()
1405        }
1406    }
1407
1408    #[test]
1409    fn non_power_of_two_uniform_alignment_always_rejected() {
1410        let limits = wgt::Limits {
1411            min_uniform_buffer_offset_alignment: 3,
1412            ..wgt::Limits::defaults()
1413        };
1414        assert!(!adapter_allowed(
1415            InstanceFlags::empty(),
1416            &"",
1417            &limits,
1418            &compliant_downlevel()
1419        ));
1420        assert!(!adapter_allowed(
1421            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1422            &"",
1423            &limits,
1424            &compliant_downlevel()
1425        ));
1426    }
1427
1428    #[test]
1429    fn non_power_of_two_storage_alignment_always_rejected() {
1430        let limits = wgt::Limits {
1431            min_storage_buffer_offset_alignment: 96,
1432            ..wgt::Limits::defaults()
1433        };
1434        assert!(!adapter_allowed(
1435            InstanceFlags::empty(),
1436            &"",
1437            &limits,
1438            &compliant_downlevel()
1439        ));
1440        assert!(!adapter_allowed(
1441            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1442            &"",
1443            &limits,
1444            &compliant_downlevel()
1445        ));
1446    }
1447
1448    #[test]
1449    fn low_limits_allowed_without_strict_compliance() {
1450        let limits = wgt::Limits {
1451            max_texture_dimension_1d: 1,
1452            ..wgt::Limits::defaults()
1453        };
1454        assert!(adapter_allowed(
1455            InstanceFlags::empty(),
1456            &"",
1457            &limits,
1458            &wgt::DownlevelCapabilities::default()
1459        ));
1460    }
1461
1462    #[test]
1463    fn low_limits_rejected_with_strict_compliance() {
1464        let limits = wgt::Limits {
1465            max_texture_dimension_1d: 1,
1466            ..wgt::Limits::defaults()
1467        };
1468        assert!(!adapter_allowed(
1469            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1470            &"",
1471            &limits,
1472            &compliant_downlevel()
1473        ));
1474    }
1475
1476    #[test]
1477    fn missing_downlevel_flags_rejected_with_strict_compliance() {
1478        let downlevel = wgt::DownlevelCapabilities {
1479            flags: wgt::DownlevelFlags::empty(),
1480            ..Default::default()
1481        };
1482        assert!(!adapter_allowed(
1483            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1484            &"",
1485            &wgt::Limits::defaults(),
1486            &downlevel
1487        ));
1488    }
1489
1490    #[test]
1491    fn fully_compliant_adapter_always_allowed() {
1492        assert!(adapter_allowed(
1493            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1494            &"",
1495            &wgt::Limits::defaults(),
1496            &compliant_downlevel()
1497        ));
1498    }
1499}