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, }, id::markers, 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}; #[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)] pub(crate) struct InstanceDevices(Mutex>); impl Default for InstanceDevices { fn default() -> Self { Self::new() } } impl InstanceDevices { pub(crate) fn new() -> Self { Self(Mutex::new(rank::INSTANCE_DEVICES, WeakVec::new())) } pub(crate) fn push(&self, device: &Arc) { 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 { 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)>, /// 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>, /// 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, ) -> Arc { 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); Arc::new(this) } /// Helper for `Instance::new()`; attempts to add a single `wgpu-hal` backend to this instance. fn try_add_hal( &mut self, _: A, instance_desc: &wgt::InstanceDescriptor, telemetry: Option, ) { // 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 fn from_hal_instance( name: String, hal_instance: ::Instance, ) -> Arc { Arc::new(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(&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 /// [`Surface`] is being used. pub unsafe fn create_surface( &self, display_handle: Option, window_handle: raw_window_handle::RawWindowHandle, ) -> Result, 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, CreateSurfaceError> { profiling::scope!("Instance::create_surface_from_drm"); let mut errors = HashMap::default(); let mut surface_per_backend: HashMap> = HashMap::default(); #[cfg(vulkan)] { let instance = unsafe { self.as_hal::() } .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, CreateSurfaceError> { profiling::scope!("Instance::create_surface_metal"); let instance = unsafe { self.as_hal::() } .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 = 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, CreateSurfaceError> { let instance = unsafe { self.as_hal::() } .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Dx12))?; let surface: Box = 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, 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, 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, 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: &Arc, backends: Backends, apply_limit_buckets: bool, ) -> Vec> { 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.clone()); api_log_debug!("Adapter {:?}", adapter.raw.info); adapter }), ); } adapters } pub fn request_adapter( self: &Arc, desc: &wgt::RequestAdapterOptions<&Surface>, backends: Backends, ) -> Result, 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.clone()); 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: &Arc, hal_adapter: hal::DynExposedAdapter, ) -> Arc { profiling::scope!("Instance::create_adapter_from_hal"); let adapter = Adapter::new(hal_adapter, self.clone()); 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 { 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>, pub surface_per_backend: HashMap>, } 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 { 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 { self.get_capabilities_with_raw(&adapter.raw) } pub fn get_capabilities_with_raw( &self, adapter: &hal::DynExposedAdapter, ) -> Result { 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, device: &Arc, config: &wgt::SurfaceConfiguration>, ) -> Option { 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) instance: Arc, } impl Adapter { pub(crate) fn new(raw: hal::DynExposedAdapter, instance: Arc) -> Arc { Arc::new(Self { raw, instance }) } /// 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 { 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, hal_device: hal::DynOpenDevice, desc: &DeviceDescriptor, ) -> Result<(Arc, Arc), 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.instance.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, desc: &DeviceDescriptor, ) -> Result<(Arc, Arc), 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), #[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, } /// 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 . 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() )); } }