instance.rs

use alloc::{borrow::ToOwned as _, boxed::Box, string::String, sync::Arc, vec, vec::Vec};
use core::fmt;

use hashbrown::HashMap;
use thiserror::Error;

use crate::{
    api_log, api_log_debug,
    device::{
        queue::Queue, resource::Device, DeviceDescriptor, DeviceError, UserClosures, WaitIdleError,
    },
    global::Global,
    id::{markers, AdapterId, DeviceId, QueueId, SurfaceId},
    limits::{self, check_limits, FailedLimit},
    lock::{rank, Mutex},
    present::{ConfigureSurfaceError, Presentation},
    resource::ResourceType,
    resource_log,
    timestamp_normalization::TimestampNormalizerInitError,
    weak_vec::WeakVec,
    DOWNLEVEL_WARNING_MESSAGE,
};

use wgt::{Backend, Backends, InstanceFlags, PowerPreference};

pub type RequestAdapterOptions = wgt::RequestAdapterOptions<SurfaceId>;

#[test]
fn downlevel_default_limits_less_than_default_limits() {
    let res = check_limits(&wgt::Limits::downlevel_defaults(), &wgt::Limits::default());
    assert!(
        res.is_empty(),
        "Downlevel limits are greater than default limits",
    )
}

#[derive(Debug, Clone)]
pub(crate) struct InstanceDevices(Arc<Mutex<WeakVec<Device>>>);

impl Default for InstanceDevices {
    fn default() -> Self {
        Self::new()
    }
}

impl InstanceDevices {
    pub(crate) fn new() -> Self {
        Self(Arc::new(Mutex::new(rank::HUB_OTHER, WeakVec::new())))
    }

    pub(crate) fn push(&self, device: &Arc<Device>) {
        self.0.lock().push(Arc::downgrade(device));
    }

    /// Poll all devices stored in this instance.
    ///
    /// If `force_wait` is true, block until all buffer mappings are done.
    ///
    /// Return `all_queue_empty` indicating whether there are more queue
    /// submissions still in flight.
    fn poll_all_devices(
        &self,
        force_wait: bool,
        closure_list: &mut UserClosures,
    ) -> Result<bool, WaitIdleError> {
        let mut all_queue_empty = true;
        {
            let device_guard = self.0.lock();

            for device in device_guard.iter().filter_map(|device| device.upgrade()) {
                let poll_type = if force_wait {
                    // TODO(#8286): Should expose timeout to poll_all.
                    wgt::PollType::wait_indefinitely()
                } else {
                    wgt::PollType::Poll
                };

                let (closures, result) = device.poll_and_return_closures(poll_type);

                let is_queue_empty = matches!(result, Ok(wgt::PollStatus::QueueEmpty));

                all_queue_empty &= is_queue_empty;

                closure_list.extend(closures);
            }
        }

        Ok(all_queue_empty)
    }
}

#[derive(Default)]
pub struct Instance {
    _name: String,

    /// List of instances per `wgpu-hal` backend.
    ///
    /// The ordering in this list implies prioritization and needs to be preserved.
    instance_per_backend: Vec<(Backend, Box<dyn hal::DynInstance>)>,

    /// The backends that were requested by the user.
    requested_backends: Backends,

    /// The backends that we could have attempted to obtain from `wgpu-hal` —
    /// those for which support is compiled in, currently.
    ///
    /// The union of this and `requested_backends` is the set of backends that would be used,
    /// independent of whether accessing the drivers/hardware for them succeeds.
    /// To obtain the set of backends actually in use by this instance, check
    /// `instance_per_backend` instead.
    supported_backends: Backends,

    pub flags: InstanceFlags,

    /// Non-lifetimed [`raw_window_handle::DisplayHandle`], for keepalive and validation purposes in
    /// [`Self::create_surface()`].
    ///
    /// When used with `winit`, callers are expected to pass its `OwnedDisplayHandle` (created from
    /// the `EventLoop`) here.
    display: Option<Box<dyn wgt::WgpuHasDisplayHandle>>,

    /// Keeps track of all devices created from this instance, so that they can be polled.
    devices: InstanceDevices,
}

impl Instance {
    pub fn new(
        name: &str,
        mut instance_desc: wgt::InstanceDescriptor,
        telemetry: Option<hal::Telemetry>,
    ) -> Self {
        let mut this = Self {
            _name: name.to_owned(),
            instance_per_backend: Vec::new(),
            requested_backends: instance_desc.backends,
            supported_backends: Backends::empty(),
            flags: instance_desc.flags,
            // HACK: We must take ownership of the field here, without being able to pass it into
            // try_add_hal(). Remove it from the mutable descriptor instead, while try_add_hal()
            // borrows the handle from `this.display` instead.
            display: instance_desc.display.take(),
            devices: InstanceDevices::new(),
        };

        #[cfg(all(vulkan, not(target_os = "netbsd")))]
        this.try_add_hal(hal::api::Vulkan, &instance_desc, telemetry);
        #[cfg(metal)]
        this.try_add_hal(hal::api::Metal, &instance_desc, telemetry);
        #[cfg(dx12)]
        this.try_add_hal(hal::api::Dx12, &instance_desc, telemetry);
        #[cfg(gles)]
        this.try_add_hal(hal::api::Gles, &instance_desc, telemetry);
        #[cfg(feature = "noop")]
        this.try_add_hal(hal::api::Noop, &instance_desc, telemetry);

        this
    }

    /// Helper for `Instance::new()`; attempts to add a single `wgpu-hal` backend to this instance.
    fn try_add_hal<A: hal::Api>(
        &mut self,
        _: A,
        instance_desc: &wgt::InstanceDescriptor,
        telemetry: Option<hal::Telemetry>,
    ) {
        // Whether or not the backend was requested, and whether or not it succeeds,
        // note that we *could* try it.
        self.supported_backends |= A::VARIANT.into();

        if !instance_desc.backends.contains(A::VARIANT.into()) {
            log::trace!("Instance::new: backend {:?} not requested", A::VARIANT);
            return;
        }

        // If this was Some, it was moved into self
        assert!(instance_desc.display.is_none());

        let hal_desc = hal::InstanceDescriptor {
            name: "wgpu",
            flags: self.flags,
            memory_budget_thresholds: instance_desc.memory_budget_thresholds,
            backend_options: instance_desc.backend_options.clone(),
            telemetry,
            // Pass a borrow, the core instance here keeps the owned handle alive already
            // WARNING: Using self here, not instance_desc!
            display: self.display.as_ref().map(|hdh| {
                hdh.display_handle()
                    .expect("Implementation did not provide a DisplayHandle")
            }),
        };

        use hal::Instance as _;
        // SAFETY: ???
        match unsafe { A::Instance::init(&hal_desc) } {
            Ok(instance) => {
                log::debug!("Instance::new: created {:?} backend", A::VARIANT);
                self.instance_per_backend
                    .push((A::VARIANT, Box::new(instance)));
            }
            Err(err) => {
                log::debug!(
                    "Instance::new: failed to create {:?} backend: {:?}",
                    A::VARIANT,
                    err
                );
            }
        }
    }

    pub(crate) fn from_hal_instance<A: hal::Api>(
        name: String,
        hal_instance: <A as hal::Api>::Instance,
    ) -> Self {
        Self {
            _name: name,
            instance_per_backend: vec![(A::VARIANT, Box::new(hal_instance))],
            requested_backends: A::VARIANT.into(),
            supported_backends: A::VARIANT.into(),
            flags: InstanceFlags::default(),
            display: None, // TODO: Extract display from HAL instance if available?
            devices: InstanceDevices::new(),
        }
    }

    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynInstance> {
        self.instance_per_backend
            .iter()
            .find_map(|(instance_backend, instance)| {
                (*instance_backend == backend).then(|| instance.as_ref())
            })
    }

    /// # Safety
    ///
    /// - The raw instance handle returned must not be manually destroyed.
    pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
        self.raw(A::VARIANT).map(|instance| {
            instance
                .as_any()
                .downcast_ref()
                // This should be impossible. It would mean that backend instance and enum type are mismatching.
                .expect("Stored instance is not of the correct type")
        })
    }

    /// Creates a new surface targeting the given display/window handles.
    ///
    /// Internally attempts to create hal surfaces for all enabled backends.
    ///
    /// Fails only if creation for surfaces for all enabled backends fails in which case
    /// the error for each enabled backend is listed.
    /// Vice versa, if creation for any backend succeeds, success is returned.
    /// Surface creation errors are logged to the debug log in any case.
    ///
    /// # Safety
    ///
    /// - `display_handle` must be a valid object to create a surface upon,
    ///   falls back to the instance display handle otherwise.
    /// - `window_handle` must remain valid as long as the returned
    ///   [`SurfaceId`] is being used.
    pub unsafe fn create_surface(
        &self,
        display_handle: Option<raw_window_handle::RawDisplayHandle>,
        window_handle: raw_window_handle::RawWindowHandle,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::create_surface");

        let instance_display_handle = self.display.as_ref().map(|d| {
            d.display_handle()
                .expect("Implementation did not provide a DisplayHandle")
                .as_raw()
        });
        let display_handle = match (instance_display_handle, display_handle) {
            (Some(a), Some(b)) => {
                if a != b {
                    return Err(CreateSurfaceError::MismatchingDisplayHandle);
                }
                a
            }
            (Some(hnd), None) => hnd,
            (None, Some(hnd)) => hnd,
            (None, None) => return Err(CreateSurfaceError::MissingDisplayHandle),
        };

        let mut errors = HashMap::default();
        let mut surface_per_backend = HashMap::default();

        for (backend, instance) in &self.instance_per_backend {
            match unsafe {
                instance
                    .as_ref()
                    .create_surface(display_handle, window_handle)
            } {
                Ok(raw) => {
                    surface_per_backend.insert(*backend, raw);
                }
                Err(err) => {
                    log::debug!(
                        "Instance::create_surface: failed to create surface for {backend:?}: {err:?}"
                    );
                    errors.insert(*backend, err);
                }
            }
        }

        if surface_per_backend.is_empty() {
            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
                errors,
            ))
        } else {
            let surface = Arc::new(Surface {
                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
                surface_per_backend,
            });

            Ok(surface)
        }
    }

    /// Creates a new surface from the given drm configuration.
    ///
    /// # Safety
    ///
    /// - All parameters must point to valid DRM values.
    ///
    /// # Platform Support
    ///
    /// This function requires the `"drm"` feature. It is only available on
    /// non-apple Unix-like platforms (Linux, FreeBSD) and currently only works
    /// with the Vulkan backend.
    #[cfg(drm)]
    #[cfg_attr(not(vulkan), expect(unused_variables, unused_mut))]
    pub unsafe fn create_surface_from_drm(
        &self,
        fd: i32,
        plane: u32,
        connector_id: u32,
        width: u32,
        height: u32,
        refresh_rate: u32,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::create_surface_from_drm");

        let mut errors = HashMap::default();
        let mut surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>> =
            HashMap::default();

        #[cfg(vulkan)]
        {
            let instance = unsafe { self.as_hal::<hal::api::Vulkan>() }
                .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Vulkan))?;

            // Safety must be upheld by the caller
            match unsafe {
                instance.create_surface_from_drm(
                    fd,
                    plane,
                    connector_id,
                    width,
                    height,
                    refresh_rate,
                )
            } {
                Ok(surface) => {
                    surface_per_backend.insert(Backend::Vulkan, Box::new(surface));
                }
                Err(err) => {
                    errors.insert(Backend::Vulkan, err);
                }
            }
        }

        if surface_per_backend.is_empty() {
            Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
                errors,
            ))
        } else {
            let surface = Arc::new(Surface {
                presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
                surface_per_backend,
            });

            Ok(surface)
        }
    }

    /// # Safety
    ///
    /// `layer` must be a valid pointer.
    #[cfg(metal)]
    pub unsafe fn create_surface_metal(
        &self,
        layer: *mut core::ffi::c_void,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::create_surface_metal");

        let instance = unsafe { self.as_hal::<hal::api::Metal>() }
            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Metal))?;

        let layer = layer.cast();
        // SAFETY: We do this cast and deref. (rather than using `metal` to get the
        // object we want) to avoid direct coupling on the `metal` crate.
        //
        // To wit, this pointer…
        //
        // - …is properly aligned.
        // - …is dereferenceable to a `MetalLayerRef` as an invariant of the `metal`
        //   field.
        // - …points to an _initialized_ `MetalLayerRef`.
        // - …is only ever aliased via an immutable reference that lives within this
        //   lexical scope.
        let layer = unsafe { &*layer };
        let raw_surface: Box<dyn hal::DynSurface> =
            Box::new(instance.create_surface_from_layer(layer));

        let surface = Arc::new(Surface {
            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
            surface_per_backend: core::iter::once((Backend::Metal, raw_surface)).collect(),
        });

        Ok(surface)
    }

    #[cfg(dx12)]
    fn create_surface_dx12(
        &self,
        create_surface_func: impl FnOnce(&hal::dx12::Instance) -> hal::dx12::Surface,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        let instance = unsafe { self.as_hal::<hal::api::Dx12>() }
            .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Dx12))?;
        let surface: Box<dyn hal::DynSurface> = Box::new(create_surface_func(instance));

        let surface = Arc::new(Surface {
            presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
            surface_per_backend: core::iter::once((Backend::Dx12, surface)).collect(),
        });

        Ok(surface)
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The visual must be valid and able to be used to make a swapchain with.
    pub unsafe fn create_surface_from_visual(
        &self,
        visual: *mut core::ffi::c_void,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::instance_create_surface_from_visual");
        self.create_surface_dx12(|inst| unsafe { inst.create_surface_from_visual(visual) })
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The surface_handle must be valid and able to be used to make a swapchain with.
    pub unsafe fn create_surface_from_surface_handle(
        &self,
        surface_handle: *mut core::ffi::c_void,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::instance_create_surface_from_surface_handle");
        self.create_surface_dx12(|inst| unsafe {
            inst.create_surface_from_surface_handle(surface_handle)
        })
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The swap_chain_panel must be valid and able to be used to make a swapchain with.
    pub unsafe fn create_surface_from_swap_chain_panel(
        &self,
        swap_chain_panel: *mut core::ffi::c_void,
    ) -> Result<Arc<Surface>, CreateSurfaceError> {
        profiling::scope!("Instance::instance_create_surface_from_swap_chain_panel");
        self.create_surface_dx12(|inst| unsafe {
            inst.create_surface_from_swap_chain_panel(swap_chain_panel)
        })
    }

    fn adapter_allowed(&self, raw: &hal::DynExposedAdapter) -> bool {
        adapter_allowed(
            self.flags,
            &raw.info,
            &raw.capabilities.limits,
            &raw.capabilities.downlevel,
        )
    }

    pub fn enumerate_adapters(
        &self,
        backends: Backends,
        apply_limit_buckets: bool,
    ) -> Vec<Arc<Adapter>> {
        profiling::scope!("Instance::enumerate_adapters");
        api_log!("Instance::enumerate_adapters");

        let mut adapters = Vec::new();
        for (_backend, instance) in self
            .instance_per_backend
            .iter()
            .filter(|(backend, _)| backends.contains(Backends::from(*backend)))
        {
            // NOTE: We might be using `profiling` without any features. The empty backend of this
            // macro emits no code, so unused code linting changes depending on the backend.
            profiling::scope!("enumerating", &*alloc::format!("{_backend:?}"));

            let hal_adapters = unsafe { instance.enumerate_adapters(None) };

            adapters.extend(
                hal_adapters
                    .into_iter()
                    .map(|mut raw| {
                        self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
                        raw
                    })
                    .map(|mut raw| {
                        filter_features_and_limits(
                            self.flags,
                            &mut raw.features,
                            &mut raw.capabilities.limits,
                        );
                        raw
                    })
                    .filter(|raw| self.adapter_allowed(raw))
                    .filter_map(|raw| {
                        if apply_limit_buckets {
                            limits::apply_limit_buckets(raw)
                        } else {
                            Some(raw)
                        }
                    })
                    .map(|raw| {
                        let adapter = Adapter::new(raw, self.devices.clone(), self.flags);
                        api_log_debug!("Adapter {:?}", adapter.raw.info);
                        adapter
                    }),
            );
        }
        adapters
    }

    pub fn request_adapter(
        &self,
        desc: &wgt::RequestAdapterOptions<&Surface>,
        backends: Backends,
    ) -> Result<Arc<Adapter>, wgt::RequestAdapterError> {
        profiling::scope!("Instance::request_adapter");
        api_log!("Instance::request_adapter");

        let mut adapters = Vec::new();
        let mut incompatible_surface_backends = Backends::empty();
        let mut no_fallback_backends = Backends::empty();
        let mut no_adapter_backends = Backends::empty();

        for &(backend, ref instance) in self
            .instance_per_backend
            .iter()
            .filter(|&&(backend, _)| backends.contains(Backends::from(backend)))
        {
            let compatible_hal_surface = desc
                .compatible_surface
                .and_then(|surface| surface.raw(backend));

            let mut backend_adapters =
                unsafe { instance.enumerate_adapters(compatible_hal_surface) };
            if backend_adapters.is_empty() {
                log::debug!("enabled backend `{backend:?}` has no adapters");
                no_adapter_backends |= Backends::from(backend);
                // by continuing, we avoid setting the further error bits below
                continue;
            }

            if desc.force_fallback_adapter {
                log::debug!("Filtering `{backend:?}` for `force_fallback_adapter`");
                backend_adapters.retain(|exposed| {
                    let keep = exposed.info.device_type == wgt::DeviceType::Cpu;
                    if !keep {
                        log::debug!("* Eliminating adapter `{}`", exposed.info.name);
                    }
                    keep
                });
                if backend_adapters.is_empty() {
                    log::debug!("* Backend `{backend:?}` has no fallback adapters");
                    no_fallback_backends |= Backends::from(backend);
                    continue;
                }
            }

            if let Some(surface) = desc.compatible_surface {
                backend_adapters.retain(|exposed| {
                    let capabilities = surface.get_capabilities_with_raw(exposed);
                    if let Err(err) = capabilities {
                        log::debug!(
                            "Adapter {:?} not compatible with surface: {}",
                            exposed.info,
                            err
                        );
                        incompatible_surface_backends |= Backends::from(backend);
                        false
                    } else {
                        true
                    }
                });
                if backend_adapters.is_empty() {
                    incompatible_surface_backends |= Backends::from(backend);
                    continue;
                }
            }

            let backend_adapters = backend_adapters
                .into_iter()
                .map(|mut raw| {
                    self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
                    raw
                })
                .map(|mut raw| {
                    filter_features_and_limits(
                        self.flags,
                        &mut raw.features,
                        &mut raw.capabilities.limits,
                    );
                    raw
                })
                .filter(|raw| self.adapter_allowed(raw));

            if desc.apply_limit_buckets {
                adapters.extend(backend_adapters.filter_map(limits::apply_limit_buckets));
            } else {
                adapters.extend(backend_adapters);
            }
        }

        match desc.power_preference {
            PowerPreference::LowPower => {
                sort(&mut adapters, true);
            }
            PowerPreference::HighPerformance => {
                sort(&mut adapters, false);
            }
            PowerPreference::None => {}
        };

        fn sort(adapters: &mut [hal::DynExposedAdapter], prefer_integrated_gpu: bool) {
            adapters
                .sort_by_key(|adapter| get_order(adapter.info.device_type, prefer_integrated_gpu));
        }

        fn get_order(device_type: wgt::DeviceType, prefer_integrated_gpu: bool) -> u8 {
            // Since devices of type "Other" might really be "Unknown" and come
            // from APIs like OpenGL that don't specify device type, Prefer more
            // Specific types over Other.
            //
            // This means that backends which do provide accurate device types
            // will be preferred if their device type indicates an actual
            // hardware GPU (integrated or discrete).
            match device_type {
                wgt::DeviceType::DiscreteGpu if prefer_integrated_gpu => 2,
                wgt::DeviceType::IntegratedGpu if prefer_integrated_gpu => 1,
                wgt::DeviceType::DiscreteGpu => 1,
                wgt::DeviceType::IntegratedGpu => 2,
                wgt::DeviceType::Other => 3,
                wgt::DeviceType::VirtualGpu => 4,
                wgt::DeviceType::Cpu => 5,
            }
        }

        // `request_adapter` can be a bit of a black box.
        // Shine some light on its decision in debug log.
        if adapters.is_empty() {
            log::debug!("Request adapter didn't find compatible adapters.");
        } else {
            log::debug!(
                "Found {} compatible adapters. Sorted by preference:",
                adapters.len()
            );
            for adapter in &adapters {
                log::debug!("* {:?}", adapter.info);
            }
        }

        if let Some(adapter) = adapters.into_iter().next() {
            api_log_debug!("Request adapter result {:?}", adapter.info);
            let adapter = Adapter::new(adapter, self.devices.clone(), self.flags);
            Ok(adapter)
        } else {
            Err(wgt::RequestAdapterError::NotFound {
                supported_backends: self.supported_backends,
                requested_backends: self.requested_backends,
                active_backends: self.active_backends(),
                no_fallback_backends,
                no_adapter_backends,
                incompatible_surface_backends,
            })
        }
    }

    /// This is similar to wgpu-hal's `adjust_raw_limits` but tailored to
    /// wgpu-core's constraints.
    fn adjust_limits_for_indirect_validation(&self, limits: &mut wgt::Limits) {
        // Indirect draw validation can't support u64 offsets,
        // lower max buffer and binding size to fit in an u32.
        if self.flags.contains(InstanceFlags::VALIDATION_INDIRECT_CALL) {
            limits.max_buffer_size = limits.max_buffer_size.min(u32::MAX as u64);
            limits.max_uniform_buffer_binding_size =
                limits.max_uniform_buffer_binding_size.min(u32::MAX as u64);
            limits.max_storage_buffer_binding_size = limits
                .max_storage_buffer_binding_size
                .min(u32::MAX as u64 & !(wgt::STORAGE_BINDING_SIZE_ALIGNMENT as u64 - 1));
        }
    }

    fn active_backends(&self) -> Backends {
        self.instance_per_backend
            .iter()
            .map(|&(backend, _)| Backends::from(backend))
            .collect()
    }

    /// Create an adapter from a HAL adapter.
    ///
    /// The HAL adapter may be obtained e.g. by calling `enumerate_adapters` on
    /// the HAL directly.
    ///
    /// If [limit bucketing][lt] is desired, [`crate::limits::apply_limit_buckets`]
    /// should be called with the HAL adapter before calling this function.
    ///
    /// # Safety
    ///
    /// `hal_adapter` must be created from this global internal instance handle.
    ///
    /// [lt]: crate::limits#Limit-bucketing
    pub unsafe fn create_adapter_from_hal(
        &self,
        hal_adapter: hal::DynExposedAdapter,
    ) -> Arc<Adapter> {
        profiling::scope!("Instance::create_adapter_from_hal");

        let adapter = Adapter::new(hal_adapter, self.devices.clone(), self.flags);

        resource_log!("Created Adapter {:?}", Arc::as_ptr(&adapter));
        adapter
    }

    /// Poll all devices on all backends.
    ///
    /// This is the implementation of `wgpu::Instance::poll_all`.
    ///
    /// Return `all_queue_empty` indicating whether there are more queue
    /// submissions still in flight.
    pub fn poll_all_devices(&self, force_wait: bool) -> Result<bool, WaitIdleError> {
        api_log!("poll_all_devices");
        let mut closures = UserClosures::default();
        let all_queue_empty = self.devices.poll_all_devices(force_wait, &mut closures)?;

        closures.fire();

        Ok(all_queue_empty)
    }
}

pub struct Surface {
    pub(crate) presentation: Mutex<Option<Presentation>>,
    pub surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>>,
}

impl ResourceType for Surface {
    const TYPE: &'static str = "Surface";
}
impl crate::storage::StorageItem for Surface {
    type Marker = markers::Surface;
}

impl Surface {
    pub fn get_capabilities(
        &self,
        adapter: &Adapter,
    ) -> Result<wgt::SurfaceCapabilities, GetSurfaceSupportError> {
        profiling::scope!("Surface::get_capabilities");
        let mut hal_caps = self.get_hal_capabilities(adapter)?;

        hal_caps
            .formats
            .sort_by_key(|fc| !fc.format.has_srgb_suffix());

        let usages = crate::conv::map_texture_usage_from_hal(hal_caps.usage);

        // `SurfaceCapabilities::formats` lists only the formats a
        // color-space-unaware application can configure via
        // `SurfaceColorSpace::Auto`, i.e. those for which `Auto` resolves to a
        // concrete color space. (The full `format_capabilities` still reports
        // every color space, including HDR ones, for explicit opt-in.)
        Ok(wgt::SurfaceCapabilities {
            formats: hal_caps
                .formats
                .iter()
                .filter(|fc| {
                    crate::device::surface_config::resolve_auto_color_space(
                        fc.format,
                        fc.color_spaces,
                    )
                    .is_some()
                })
                .map(|fc| fc.format)
                .collect(),
            format_capabilities: hal_caps.formats,
            present_modes: hal_caps.present_modes,
            alpha_modes: hal_caps.composite_alpha_modes,
            usages,
        })
    }

    pub fn get_hal_capabilities(
        &self,
        adapter: &Adapter,
    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
        self.get_capabilities_with_raw(&adapter.raw)
    }

    pub fn get_capabilities_with_raw(
        &self,
        adapter: &hal::DynExposedAdapter,
    ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
        let backend = adapter.backend();
        let suf = self
            .raw(backend)
            .ok_or(GetSurfaceSupportError::NotSupportedByBackend(backend))?;
        profiling::scope!("surface_capabilities");
        let caps = unsafe { adapter.adapter.surface_capabilities(suf) }
            .ok_or(GetSurfaceSupportError::FailedToRetrieveSurfaceCapabilitiesForAdapter)?;
        Ok(caps)
    }

    /// Returns the HDR / luminance characteristics of the display backing this
    /// surface on `adapter`.
    ///
    /// Falls back to [`wgt::DisplayHdrInfo::default`] (all fields `None`) when the
    /// surface is not on `adapter`'s backend or the backend reports nothing.
    pub fn display_hdr_info(&self, adapter: &Adapter) -> wgt::DisplayHdrInfo {
        profiling::scope!("Surface::display_hdr_info");
        self.display_hdr_info_with_raw(&adapter.raw)
    }

    pub fn display_hdr_info_with_raw(
        &self,
        adapter: &hal::DynExposedAdapter,
    ) -> wgt::DisplayHdrInfo {
        let backend = adapter.backend();
        let Some(suf) = self.raw(backend) else {
            return wgt::DisplayHdrInfo::default();
        };
        profiling::scope!("surface_display_hdr_info");
        unsafe { adapter.adapter.surface_display_hdr_info(suf) }.unwrap_or_default()
    }

    pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynSurface> {
        self.surface_per_backend
            .get(&backend)
            .map(|surface| surface.as_ref())
    }

    pub fn configure(
        self: &Arc<Self>,
        device: &Arc<Device>,
        config: &wgt::SurfaceConfiguration<Vec<wgt::TextureFormat>>,
    ) -> Option<ConfigureSurfaceError> {
        use ConfigureSurfaceError as E;
        profiling::scope!("Surface::configure");

        #[cfg(feature = "trace")]
        if let Some(ref mut trace) = *device.trace.lock() {
            use crate::device::trace::{Action, IntoTrace};

            trace.add(Action::ConfigureSurface(self.to_trace(), config.clone()));
        }

        log::debug!("configuring surface with {config:?}");

        let error = 'error: {
            // User callbacks must not be called while we are holding locks.
            let user_callbacks;
            {
                if let Err(e) = device.check_is_valid() {
                    break 'error e.into();
                }

                let caps = match self.get_hal_capabilities(&device.adapter) {
                    Ok(caps) => caps,
                    Err(_) => break 'error E::UnsupportedQueueFamily,
                };

                let mut hal_view_formats = Vec::new();
                for format in config.view_formats.iter() {
                    if *format == config.format {
                        continue;
                    }
                    if !caps.formats.iter().any(|fc| fc.format == config.format) {
                        break 'error E::UnsupportedFormat {
                            requested: config.format,
                            available: caps.texture_formats().collect(),
                        };
                    }
                    if config.format.remove_srgb_suffix() != format.remove_srgb_suffix() {
                        break 'error E::InvalidViewFormat(*format, config.format);
                    }
                    hal_view_formats.push(*format);
                }

                if !hal_view_formats.is_empty() {
                    if let Err(missing_flag) =
                        device.require_downlevel_flags(wgt::DownlevelFlags::SURFACE_VIEW_FORMATS)
                    {
                        break 'error E::MissingDownlevelFlags(missing_flag);
                    }
                }

                let maximum_frame_latency = config.desired_maximum_frame_latency.clamp(
                    *caps.maximum_frame_latency.start(),
                    *caps.maximum_frame_latency.end(),
                );
                let mut hal_config = hal::SurfaceConfiguration {
                    maximum_frame_latency,
                    present_mode: config.present_mode,
                    composite_alpha_mode: config.alpha_mode,
                    format: config.format,
                    color_space: config.color_space,
                    extent: wgt::Extent3d {
                        width: config.width,
                        height: config.height,
                        depth_or_array_layers: 1,
                    },
                    usage: crate::conv::map_texture_usage(
                        config.usage,
                        hal::FormatAspects::COLOR,
                        wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY
                            | wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY
                            | wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
                    ),
                    view_formats: hal_view_formats,
                };

                if let Err(error) = crate::device::surface_config::validate_surface_configuration(
                    &mut hal_config,
                    &caps,
                    device.limits.max_texture_dimension_2d,
                ) {
                    break 'error error;
                }

                // Wait for all work to finish before configuring the surface.
                let snatch_guard = device.snatchable_lock.read();

                let maintain_result;
                (user_callbacks, maintain_result) =
                    device.maintain(wgt::PollType::wait_indefinitely(), snatch_guard);

                match maintain_result {
                    // We're happy
                    Ok(wgt::PollStatus::QueueEmpty) => {}
                    Ok(wgt::PollStatus::WaitSucceeded) => {
                        // After the wait, the queue should be empty. It can only be non-empty
                        // if another thread is submitting at the same time.
                        break 'error E::GpuWaitTimeout;
                    }
                    Ok(wgt::PollStatus::Poll) => {
                        unreachable!("Cannot get a Poll result from a Wait action.")
                    }
                    Err(WaitIdleError::Timeout) if cfg!(target_family = "wasm") => {
                        // On wasm, you cannot actually successfully wait for the surface.
                        // However WebGL does not actually require you do this, so ignoring
                        // the failure is totally fine. See
                        // https://github.com/gfx-rs/wgpu/issues/7363
                    }
                    Err(e) => {
                        break 'error e.into();
                    }
                }

                // All textures must be destroyed before the surface can be re-configured.
                if let Some(present) = self.presentation.lock().take() {
                    if present.acquired_texture.is_some() {
                        break 'error E::PreviousOutputExists;
                    }
                }

                // TODO: Texture views may still be alive that point to the texture.
                // this will allow the user to render to the surface texture, long after
                // it has been removed.
                //
                // https://github.com/gfx-rs/wgpu/issues/4105

                let surface_raw = self.raw(device.backend()).unwrap();
                match unsafe { surface_raw.configure(device.raw(), &hal_config) } {
                    Ok(()) => (),
                    Err(error) => {
                        break 'error match error {
                            hal::SurfaceError::Outdated
                            | hal::SurfaceError::Lost
                            | hal::SurfaceError::Occluded
                            | hal::SurfaceError::Timeout => E::InvalidSurface,
                            hal::SurfaceError::Device(error) => {
                                E::Device(device.handle_hal_error(error))
                            }
                            hal::SurfaceError::Other(message) => {
                                log::error!("surface configuration failed: {message}");
                                E::InvalidSurface
                            }
                        }
                    }
                }

                let mut presentation = self.presentation.lock();
                *presentation = Some(Presentation {
                    device: Arc::clone(device),
                    config: config.clone(),
                    acquired_texture: None,
                });
            }

            user_callbacks.fire();
            return None;
        };

        Some(error)
    }
}

impl Drop for Surface {
    #[allow(trivial_casts)]
    fn drop(&mut self) {
        profiling::scope!("Surface::drop");

        api_log!("Surface::drop {:?}", self as *const _);
        if let Some(present) = self.presentation.lock().take() {
            for (&backend, surface) in &self.surface_per_backend {
                if backend == present.device.backend() {
                    unsafe { surface.unconfigure(present.device.raw()) };
                }
            }
        }
    }
}

pub struct Adapter {
    pub(crate) raw: hal::DynExposedAdapter,
    pub(crate) devices: InstanceDevices,
    pub(crate) instance_flags: InstanceFlags,
}

impl Adapter {
    pub(crate) fn new(
        raw: hal::DynExposedAdapter,
        devices: InstanceDevices,
        flags: InstanceFlags,
    ) -> Arc<Self> {
        Arc::new(Self {
            raw,
            devices,
            instance_flags: flags,
        })
    }

    /// Returns the backend this adapter is using.
    pub fn backend(&self) -> Backend {
        self.raw.backend()
    }

    pub fn is_surface_supported(&self, surface: &Surface) -> bool {
        // If get_capabilities returns Err, then the API does not advertise support for the surface.
        //
        // This could occur if the user is running their app on Wayland but Vulkan does not support
        // VK_KHR_wayland_surface.
        surface.get_hal_capabilities(self).is_ok()
    }

    pub fn get_info(&self) -> wgt::AdapterInfo {
        self.raw.info.clone()
    }

    pub fn features(&self) -> wgt::Features {
        self.raw.features
    }

    pub fn limits(&self) -> wgt::Limits {
        self.raw.capabilities.limits.clone()
    }

    pub fn downlevel_capabilities(&self) -> wgt::DownlevelCapabilities {
        self.raw.capabilities.downlevel.clone()
    }

    pub fn get_presentation_timestamp(&self) -> wgt::PresentationTimestamp {
        unsafe { self.raw.adapter.get_presentation_timestamp() }
    }

    pub fn cooperative_matrix_properties(&self) -> Vec<wgt::CooperativeMatrixProperties> {
        self.raw.capabilities.cooperative_matrix_properties.clone()
    }

    pub fn get_texture_format_features(
        &self,
        format: wgt::TextureFormat,
    ) -> wgt::TextureFormatFeatures {
        use hal::TextureFormatCapabilities as Tfc;

        let caps = unsafe { self.raw.adapter.texture_format_capabilities(format) };
        let mut allowed_usages = wgt::TextureUsages::empty();

        allowed_usages.set(wgt::TextureUsages::COPY_SRC, caps.contains(Tfc::COPY_SRC));
        allowed_usages.set(wgt::TextureUsages::COPY_DST, caps.contains(Tfc::COPY_DST));
        allowed_usages.set(
            wgt::TextureUsages::TEXTURE_BINDING,
            caps.contains(Tfc::SAMPLED),
        );
        allowed_usages.set(
            wgt::TextureUsages::STORAGE_BINDING,
            caps.intersects(
                Tfc::STORAGE_WRITE_ONLY
                    | Tfc::STORAGE_READ_ONLY
                    | Tfc::STORAGE_READ_WRITE
                    | Tfc::STORAGE_ATOMIC,
            ),
        );
        allowed_usages.set(
            wgt::TextureUsages::RENDER_ATTACHMENT | wgt::TextureUsages::TRANSIENT_ATTACHMENT,
            caps.intersects(Tfc::COLOR_ATTACHMENT | Tfc::DEPTH_STENCIL_ATTACHMENT),
        );
        allowed_usages.set(
            wgt::TextureUsages::STORAGE_ATOMIC,
            caps.contains(Tfc::STORAGE_ATOMIC),
        );

        let mut flags = wgt::TextureFormatFeatureFlags::empty();
        flags.set(
            wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY,
            caps.contains(Tfc::STORAGE_READ_ONLY),
        );
        flags.set(
            wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY,
            caps.contains(Tfc::STORAGE_WRITE_ONLY),
        );
        flags.set(
            wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
            caps.contains(Tfc::STORAGE_READ_WRITE),
        );

        flags.set(
            wgt::TextureFormatFeatureFlags::STORAGE_ATOMIC,
            caps.contains(Tfc::STORAGE_ATOMIC),
        );

        flags.set(
            wgt::TextureFormatFeatureFlags::FILTERABLE,
            caps.contains(Tfc::SAMPLED_LINEAR),
        );

        flags.set(
            wgt::TextureFormatFeatureFlags::BLENDABLE,
            caps.contains(Tfc::COLOR_ATTACHMENT_BLEND),
        );

        flags.set(
            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X2,
            caps.contains(Tfc::MULTISAMPLE_X2),
        );
        flags.set(
            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X4,
            caps.contains(Tfc::MULTISAMPLE_X4),
        );
        flags.set(
            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X8,
            caps.contains(Tfc::MULTISAMPLE_X8),
        );
        flags.set(
            wgt::TextureFormatFeatureFlags::MULTISAMPLE_X16,
            caps.contains(Tfc::MULTISAMPLE_X16),
        );

        flags.set(
            wgt::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
            caps.contains(Tfc::MULTISAMPLE_RESOLVE),
        );

        wgt::TextureFormatFeatures {
            allowed_usages,
            flags,
        }
    }

    /// # Safety
    ///
    /// - `hal_device` must be created from this adapter.
    /// - `desc` must be a subset of `hal_device` features and limits.
    pub unsafe fn create_device_and_queue_from_hal(
        self: &Arc<Self>,
        hal_device: hal::DynOpenDevice,
        desc: &DeviceDescriptor,
    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
        profiling::scope!("Adapter::create_device_and_queue_from_hal");
        api_log!("Adapter::create_device_and_queue_from_hal");

        let device = Device::new(hal_device.device, self, desc, self.instance_flags)?;
        let device = Arc::new(device);

        let queue = Queue::new(device.clone(), hal_device.queue, self.instance_flags)?;
        let queue = Arc::new(queue);

        device.set_queue(&queue);
        device.late_init_resources_with_queue()?;

        resource_log!("Created Device {:?}", Arc::as_ptr(&device));
        resource_log!("Created Queue {:?}", Arc::as_ptr(&queue));

        self.devices.push(&device);

        Ok((device, queue))
    }

    /// Validate a device descriptor.
    ///
    /// This validates the provided device descriptor as if it were passed to
    /// [`Self::request_device`]. If [`InstanceFlags::STRICT_WEBGPU_COMPLIANCE`] is active,
    /// the requested extensions in the descriptor will be filtered to remove `wgpu`
    /// extensions, except for those that are included in [`limits::EXEMPT_FEATURES`].
    ///
    /// This may be useful when it is necessary to obtain the device itself from a raw hal
    /// API, but the rest of the `request_device` validation is still desired.
    pub fn validate_device_descriptor(
        &self,
        desc: &mut DeviceDescriptor,
    ) -> Result<(), RequestDeviceError> {
        filter_features_and_limits(
            self.instance_flags,
            &mut desc.required_features,
            &mut desc.required_limits,
        );

        // Verify all features were exposed by the adapter
        if !self.raw.features.contains(desc.required_features) {
            return Err(RequestDeviceError::UnsupportedFeature(
                desc.required_features - self.raw.features,
            ));
        }

        // Check if experimental features are permitted to be enabled.
        if desc
            .required_features
            .intersects(wgt::Features::all_experimental_mask())
            && !desc.experimental_features.is_enabled()
        {
            return Err(RequestDeviceError::ExperimentalFeaturesNotEnabled(
                desc.required_features
                    .intersection(wgt::Features::all_experimental_mask()),
            ));
        }

        let caps = &self.raw.capabilities;
        if Backends::PRIMARY.contains(Backends::from(self.backend()))
            && !caps.downlevel.is_webgpu_compliant()
        {
            let missing_flags = wgt::DownlevelFlags::compliant() - caps.downlevel.flags;
            log::warn!("Missing downlevel flags: {missing_flags:?}\n{DOWNLEVEL_WARNING_MESSAGE}");
            log::warn!("{:#?}", caps.downlevel);
        }

        // Verify feature preconditions
        if desc
            .required_features
            .contains(wgt::Features::MAPPABLE_PRIMARY_BUFFERS)
            && self.raw.info.device_type == wgt::DeviceType::DiscreteGpu
        {
            log::warn!(
                "Feature MAPPABLE_PRIMARY_BUFFERS enabled on a discrete gpu. \
                        This is a massive performance footgun and likely not what you wanted"
            );
        }

        if let Some(failed) = check_limits(&desc.required_limits, &caps.limits).pop() {
            return Err(RequestDeviceError::LimitsExceeded(failed));
        }

        Ok(())
    }

    pub fn request_device(
        self: &Arc<Self>,
        desc: &DeviceDescriptor,
    ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
        profiling::scope!("Adapter::request_device");
        api_log!("Adapter::request_device");

        let mut desc = desc.clone();
        self.validate_device_descriptor(&mut desc)?;

        let open = unsafe {
            self.raw.adapter.open(
                desc.required_features,
                &desc.required_limits,
                &desc.memory_hints,
            )
        }
        .map_err(DeviceError::from_hal)?;

        unsafe { self.create_device_and_queue_from_hal(open, &desc) }
    }
}

impl Drop for Adapter {
    #[allow(trivial_casts)]
    fn drop(&mut self) {
        profiling::scope!("Adapter::drop");
        api_log!("Adapter::drop {:?}", self as *const _);
    }
}

crate::impl_resource_type!(Adapter);
crate::impl_storage_item!(Adapter);

#[derive(Clone, Debug, Error)]
#[non_exhaustive]
pub enum GetSurfaceSupportError {
    #[error("Surface is not supported for the specified backend {0}")]
    NotSupportedByBackend(Backend),
    #[error("Failed to retrieve surface capabilities for the specified adapter.")]
    FailedToRetrieveSurfaceCapabilitiesForAdapter,
}

#[derive(Clone, Debug, Error)]
/// Error when requesting a device from the adapter
#[non_exhaustive]
pub enum RequestDeviceError {
    #[error(transparent)]
    Device(#[from] DeviceError),
    #[error(transparent)]
    LimitsExceeded(#[from] FailedLimit),
    #[error("Failed to initialize Timestamp Normalizer")]
    TimestampNormalizerInitFailed(#[from] TimestampNormalizerInitError),
    #[error("Unsupported features were requested: {0}")]
    UnsupportedFeature(wgt::Features),
    #[error(
        "Some experimental features, {0}, were requested, but experimental features are not enabled"
    )]
    ExperimentalFeaturesNotEnabled(wgt::Features),
}

#[derive(Clone, Debug, Error)]
#[non_exhaustive]
pub enum CreateSurfaceError {
    #[error("The backend {0} was not enabled on the instance.")]
    BackendNotEnabled(Backend),
    #[error("Failed to create surface for any enabled backend: {0:?}")]
    FailedToCreateSurfaceForAnyBackend(HashMap<Backend, hal::InstanceError>),
    #[error("The display handle used to create this Instance does not match the one used to create a surface on it")]
    MismatchingDisplayHandle,
    #[error(
        "No `DisplayHandle` is available to create this surface with.  When creating a surface with `create_surface()` \
        you must specify a display handle in `InstanceDescriptor::display`.  \
        Rarely, if you need to create surfaces from different `DisplayHandle`s (ex. different Wayland or X11 connections), \
        you must use `create_surface_unsafe()`."
    )]
    MissingDisplayHandle,
}

impl Global {
    /// Creates a new surface targeting the given display/window handles.
    ///
    /// Internally attempts to create hal surfaces for all enabled backends.
    ///
    /// Fails only if creation for surfaces for all enabled backends fails in which case
    /// the error for each enabled backend is listed.
    /// Vice versa, if creation for any backend succeeds, success is returned.
    /// Surface creation errors are logged to the debug log in any case.
    ///
    /// id_in:
    /// - If `Some`, the id to assign to the surface. A new one will be generated otherwise.
    ///
    /// # Safety
    ///
    /// - `display_handle` must be a valid object to create a surface upon,
    ///   falls back to the instance display handle otherwise.
    /// - `window_handle` must remain valid as long as the returned
    ///   [`SurfaceId`] is being used.
    pub unsafe fn instance_create_surface(
        &self,
        display_handle: Option<raw_window_handle::RawDisplayHandle>,
        window_handle: raw_window_handle::RawWindowHandle,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe { self.instance.create_surface(display_handle, window_handle) }?;
        let id = self.surfaces.prepare(id_in).assign(surface);
        Ok(id)
    }

    /// Creates a new surface from the given drm configuration.
    ///
    /// # Safety
    ///
    /// - All parameters must point to valid DRM values.
    ///
    /// # Platform Support
    ///
    /// This function requires the `"drm"` feature, and is only available on
    /// non-apple Unix-like platforms (Linux, FreeBSD) and currently only works
    /// with the Vulkan backend.
    #[cfg(drm)]
    pub unsafe fn instance_create_surface_from_drm(
        &self,
        fd: i32,
        plane: u32,
        connector_id: u32,
        width: u32,
        height: u32,
        refresh_rate: u32,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe {
            self.instance.create_surface_from_drm(
                fd,
                plane,
                connector_id,
                width,
                height,
                refresh_rate,
            )
        }?;
        let id = self.surfaces.prepare(id_in).assign(surface);

        Ok(id)
    }

    /// # Safety
    ///
    /// `layer` must be a valid pointer.
    #[cfg(metal)]
    pub unsafe fn instance_create_surface_metal(
        &self,
        layer: *mut core::ffi::c_void,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe { self.instance.create_surface_metal(layer) }?;
        let id = self.surfaces.prepare(id_in).assign(surface);
        Ok(id)
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The visual must be valid and able to be used to make a swapchain with.
    pub unsafe fn instance_create_surface_from_visual(
        &self,
        visual: *mut core::ffi::c_void,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe { self.instance.create_surface_from_visual(visual) }?;
        let id = self.surfaces.prepare(id_in).assign(surface);
        Ok(id)
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The surface_handle must be valid and able to be used to make a swapchain with.
    pub unsafe fn instance_create_surface_from_surface_handle(
        &self,
        surface_handle: *mut core::ffi::c_void,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe {
            self.instance
                .create_surface_from_surface_handle(surface_handle)
        }?;
        let id = self.surfaces.prepare(id_in).assign(surface);
        Ok(id)
    }

    #[cfg(dx12)]
    /// # Safety
    ///
    /// The swap_chain_panel must be valid and able to be used to make a swapchain with.
    pub unsafe fn instance_create_surface_from_swap_chain_panel(
        &self,
        swap_chain_panel: *mut core::ffi::c_void,
        id_in: Option<SurfaceId>,
    ) -> Result<SurfaceId, CreateSurfaceError> {
        let surface = unsafe {
            self.instance
                .create_surface_from_swap_chain_panel(swap_chain_panel)
        }?;
        let id = self.surfaces.prepare(id_in).assign(surface);
        Ok(id)
    }

    pub fn surface_drop(&self, id: SurfaceId) {
        self.surfaces.remove(id);
    }

    pub fn enumerate_adapters(
        &self,
        backends: Backends,
        apply_limit_buckets: bool,
    ) -> Vec<AdapterId> {
        let adapters = self
            .instance
            .enumerate_adapters(backends, apply_limit_buckets);
        adapters
            .into_iter()
            .map(|adapter| self.hub.adapters.prepare(None).assign(adapter))
            .collect()
    }

    pub fn request_adapter(
        &self,
        desc: &RequestAdapterOptions,
        backends: Backends,
        id_in: Option<AdapterId>,
    ) -> Result<AdapterId, wgt::RequestAdapterError> {
        let compatible_surface = desc.compatible_surface.map(|id| self.surfaces.get(id));
        let desc = wgt::RequestAdapterOptions {
            power_preference: desc.power_preference,
            force_fallback_adapter: desc.force_fallback_adapter,
            compatible_surface: compatible_surface.as_deref(),
            apply_limit_buckets: desc.apply_limit_buckets,
        };
        let adapter = self.instance.request_adapter(&desc, backends)?;
        let id = self.hub.adapters.prepare(id_in).assign(adapter);
        Ok(id)
    }

    /// Create an adapter from a HAL adapter.
    ///
    /// The HAL adapter may be obtained e.g. by calling `enumerate_adapters` on
    /// the HAL directly.
    ///
    /// If [limit bucketing][lt] is desired, [`crate::limits::apply_limit_buckets`]
    /// should be called with the HAL adapter before calling this function.
    ///
    /// # Safety
    ///
    /// `hal_adapter` must be created from this global internal instance handle.
    ///
    /// [lt]: crate::limits#Limit-bucketing
    pub unsafe fn create_adapter_from_hal(
        &self,
        hal_adapter: hal::DynExposedAdapter,
        input: Option<AdapterId>,
    ) -> AdapterId {
        let fid = self.hub.adapters.prepare(input);
        fid.assign(unsafe { self.instance.create_adapter_from_hal(hal_adapter) })
    }

    pub fn adapter_get_info(&self, adapter_id: AdapterId) -> wgt::AdapterInfo {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.get_info()
    }

    pub fn adapter_get_texture_format_features(
        &self,
        adapter_id: AdapterId,
        format: wgt::TextureFormat,
    ) -> wgt::TextureFormatFeatures {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.get_texture_format_features(format)
    }

    pub fn adapter_features(&self, adapter_id: AdapterId) -> wgt::Features {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.features()
    }

    pub fn adapter_limits(&self, adapter_id: AdapterId) -> wgt::Limits {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.limits()
    }

    pub fn adapter_downlevel_capabilities(
        &self,
        adapter_id: AdapterId,
    ) -> wgt::DownlevelCapabilities {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.downlevel_capabilities()
    }

    pub fn adapter_get_presentation_timestamp(
        &self,
        adapter_id: AdapterId,
    ) -> wgt::PresentationTimestamp {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.get_presentation_timestamp()
    }

    pub fn adapter_cooperative_matrix_properties(
        &self,
        adapter_id: AdapterId,
    ) -> Vec<wgt::CooperativeMatrixProperties> {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.cooperative_matrix_properties()
    }

    pub fn adapter_drop(&self, adapter_id: AdapterId) {
        self.hub.adapters.remove(adapter_id);
    }
}

impl Global {
    pub fn adapter_request_device(
        &self,
        adapter_id: AdapterId,
        desc: &DeviceDescriptor,
        device_id_in: Option<DeviceId>,
        queue_id_in: Option<QueueId>,
    ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
        let device_fid = self.hub.devices.prepare(device_id_in);
        let queue_fid = self.hub.queues.prepare(queue_id_in);

        let adapter = self.hub.adapters.get(adapter_id);
        let (device, queue) = adapter.request_device(desc)?;

        let device_id = device_fid.assign(device);
        resource_log!("Created Device {:?}", device_id);

        let queue_id = queue_fid.assign(queue);
        resource_log!("Created Queue {:?}", queue_id);

        Ok((device_id, queue_id))
    }

    pub fn adapter_validate_device_descriptor(
        &self,
        adapter_id: AdapterId,
        desc: &mut DeviceDescriptor,
    ) -> Result<(), RequestDeviceError> {
        let adapter = self.hub.adapters.get(adapter_id);
        adapter.validate_device_descriptor(desc)
    }

    /// # Safety
    ///
    /// - `hal_device` must be created from `adapter_id` or its internal handle.
    /// - `desc` must be a subset of `hal_device` features and limits.
    pub unsafe fn create_device_from_hal(
        &self,
        adapter_id: AdapterId,
        hal_device: hal::DynOpenDevice,
        desc: &DeviceDescriptor,
        device_id_in: Option<DeviceId>,
        queue_id_in: Option<QueueId>,
    ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
        let devices_fid = self.hub.devices.prepare(device_id_in);
        let queues_fid = self.hub.queues.prepare(queue_id_in);

        let adapter = self.hub.adapters.get(adapter_id);
        let (device, queue) =
            unsafe { adapter.create_device_and_queue_from_hal(hal_device, desc) }?;

        let device_id = devices_fid.assign(device);

        let queue_id = queues_fid.assign(queue);

        Ok((device_id, queue_id))
    }
}

/// This function checks that the adapter obeys WebGPU's adapter capability
/// guarantees. Most of the limits are adjusted in wgpu-hal's
/// `adjust_raw_limits` fn. So we only check the remaining properties here.
/// See <https://gpuweb.github.io/gpuweb/#adapter-capability-guarantees>.
fn adapter_allowed(
    flags: InstanceFlags,
    info: &impl fmt::Debug,
    limits: &wgt::Limits,
    downlevel: &wgt::DownlevelCapabilities,
) -> bool {
    // Check "All alignment-class limits must be powers of 2."
    //
    // Even if the application has not requested strict WebGPU compliance,
    // non-power-of-two alignment limits are nonsensical, so don't attempt
    // to use such a device.
    let min_uniform_buffer_offset_alignment = limits.min_uniform_buffer_offset_alignment;
    if !min_uniform_buffer_offset_alignment.is_power_of_two() {
        log::error!(
            "Adapter {:?} min_uniform_buffer_offset_alignment limit is not a power of 2: {:?}",
            info,
            min_uniform_buffer_offset_alignment
        );
        return false;
    }
    let min_storage_buffer_offset_alignment = limits.min_storage_buffer_offset_alignment;
    if !min_storage_buffer_offset_alignment.is_power_of_two() {
        log::error!(
            "Adapter {:?} min_storage_buffer_offset_alignment limit is not a power of 2: {:?}",
            info,
            min_storage_buffer_offset_alignment
        );
        return false;
    }

    // Following checks are only enabled if `STRICT_WEBGPU_COMPLIANCE` is set.
    if !flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
        return true;
    }

    // Check "All supported limits must be either the default value or better."
    let mut min_limits = wgt::Limits::defaults();
    min_limits.zero_native_only();
    let failed_limits = check_limits(&min_limits, limits);
    if !failed_limits.is_empty() {
        log::debug!(
            "Adapter {:?} is not WebGPU compliant due to limits: {:?}",
            info,
            failed_limits
        );
        return false;
    }

    if !downlevel.is_webgpu_compliant() {
        let missing_flags = wgt::DownlevelFlags::compliant() - downlevel.flags;
        log::debug!(
            "Adapter {:?} is not WebGPU compliant due to missing downlevel flags: {:?}",
            info,
            missing_flags
        );
        return false;
    }

    true
}

fn filter_features_and_limits(
    flags: InstanceFlags,
    features: &mut wgt::Features,
    limits: &mut wgt::Limits,
) {
    if flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
        *features &= wgt::Features::all_webgpu_mask() | limits::EXEMPT_FEATURES;
        limits.zero_native_only();
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn compliant_downlevel() -> wgt::DownlevelCapabilities {
        wgt::DownlevelCapabilities {
            flags: wgt::DownlevelFlags::compliant(),
            ..Default::default()
        }
    }

    #[test]
    fn non_power_of_two_uniform_alignment_always_rejected() {
        let limits = wgt::Limits {
            min_uniform_buffer_offset_alignment: 3,
            ..wgt::Limits::defaults()
        };
        assert!(!adapter_allowed(
            InstanceFlags::empty(),
            &"",
            &limits,
            &compliant_downlevel()
        ));
        assert!(!adapter_allowed(
            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
            &"",
            &limits,
            &compliant_downlevel()
        ));
    }

    #[test]
    fn non_power_of_two_storage_alignment_always_rejected() {
        let limits = wgt::Limits {
            min_storage_buffer_offset_alignment: 96,
            ..wgt::Limits::defaults()
        };
        assert!(!adapter_allowed(
            InstanceFlags::empty(),
            &"",
            &limits,
            &compliant_downlevel()
        ));
        assert!(!adapter_allowed(
            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
            &"",
            &limits,
            &compliant_downlevel()
        ));
    }

    #[test]
    fn low_limits_allowed_without_strict_compliance() {
        let limits = wgt::Limits {
            max_texture_dimension_1d: 1,
            ..wgt::Limits::defaults()
        };
        assert!(adapter_allowed(
            InstanceFlags::empty(),
            &"",
            &limits,
            &wgt::DownlevelCapabilities::default()
        ));
    }

    #[test]
    fn low_limits_rejected_with_strict_compliance() {
        let limits = wgt::Limits {
            max_texture_dimension_1d: 1,
            ..wgt::Limits::defaults()
        };
        assert!(!adapter_allowed(
            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
            &"",
            &limits,
            &compliant_downlevel()
        ));
    }

    #[test]
    fn missing_downlevel_flags_rejected_with_strict_compliance() {
        let downlevel = wgt::DownlevelCapabilities {
            flags: wgt::DownlevelFlags::empty(),
            ..Default::default()
        };
        assert!(!adapter_allowed(
            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
            &"",
            &wgt::Limits::defaults(),
            &downlevel
        ));
    }

    #[test]
    fn fully_compliant_adapter_always_allowed() {
        assert!(adapter_allowed(
            InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
            &"",
            &wgt::Limits::defaults(),
            &compliant_downlevel()
        ));
    }
}