mirror of
https://github.com/storytold/wgpu.git
synced 2026-11-19 14:01:08 +01:00
1531 lines
54 KiB
Rust
1531 lines
54 KiB
Rust
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<WeakVec<Device>>);
|
|
|
|
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<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>,
|
|
) -> Arc<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);
|
|
|
|
Arc::new(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 fn from_hal_instance<A: hal::Api>(
|
|
name: String,
|
|
hal_instance: <A as hal::Api>::Instance,
|
|
) -> Arc<Self> {
|
|
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<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
|
|
/// [`Surface`] 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: &Arc<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.clone());
|
|
api_log_debug!("Adapter {:?}", adapter.raw.info);
|
|
adapter
|
|
}),
|
|
);
|
|
}
|
|
adapters
|
|
}
|
|
|
|
pub fn request_adapter(
|
|
self: &Arc<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.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<Self>,
|
|
hal_adapter: hal::DynExposedAdapter,
|
|
) -> Arc<Adapter> {
|
|
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<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) instance: Arc<Instance>,
|
|
}
|
|
|
|
impl Adapter {
|
|
pub(crate) fn new(raw: hal::DynExposedAdapter, instance: Arc<Instance>) -> Arc<Self> {
|
|
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<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.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<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,
|
|
}
|
|
|
|
/// 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()
|
|
));
|
|
}
|
|
}
|