1use alloc::{borrow::ToOwned as _, boxed::Box, string::String, sync::Arc, vec, vec::Vec};
2use core::{fmt, sync::atomic::AtomicBool};
3
4use hashbrown::HashMap;
5use thiserror::Error;
6
7use crate::{
8 api_log, api_log_debug,
9 device::{queue::Queue, resource::Device, DeviceDescriptor, DeviceError},
10 global::Global,
11 id::{markers, AdapterId, DeviceId, QueueId, SurfaceId},
12 limits::{self, check_limits, FailedLimit},
13 lock::{rank, Mutex},
14 present::Presentation,
15 resource::ResourceType,
16 resource_log,
17 timestamp_normalization::TimestampNormalizerInitError,
18 DOWNLEVEL_WARNING_MESSAGE,
19};
20
21use wgt::{Backend, Backends, InstanceFlags, PowerPreference};
22
23pub type RequestAdapterOptions = wgt::RequestAdapterOptions<SurfaceId>;
24
25#[test]
26fn downlevel_default_limits_less_than_default_limits() {
27 let res = check_limits(&wgt::Limits::downlevel_defaults(), &wgt::Limits::default());
28 assert!(
29 res.is_empty(),
30 "Downlevel limits are greater than default limits",
31 )
32}
33
34#[derive(Default)]
35pub struct Instance {
36 _name: String,
37
38 instance_per_backend: Vec<(Backend, Box<dyn hal::DynInstance>)>,
42
43 requested_backends: Backends,
45
46 supported_backends: Backends,
54
55 pub flags: InstanceFlags,
56
57 display: Option<Box<dyn wgt::WgpuHasDisplayHandle>>,
63}
64
65impl Instance {
66 pub fn new(
67 name: &str,
68 mut instance_desc: wgt::InstanceDescriptor,
69 telemetry: Option<hal::Telemetry>,
70 ) -> Self {
71 let mut this = Self {
72 _name: name.to_owned(),
73 instance_per_backend: Vec::new(),
74 requested_backends: instance_desc.backends,
75 supported_backends: Backends::empty(),
76 flags: instance_desc.flags,
77 display: instance_desc.display.take(),
81 };
82
83 #[cfg(all(vulkan, not(target_os = "netbsd")))]
84 this.try_add_hal(hal::api::Vulkan, &instance_desc, telemetry);
85 #[cfg(metal)]
86 this.try_add_hal(hal::api::Metal, &instance_desc, telemetry);
87 #[cfg(dx12)]
88 this.try_add_hal(hal::api::Dx12, &instance_desc, telemetry);
89 #[cfg(gles)]
90 this.try_add_hal(hal::api::Gles, &instance_desc, telemetry);
91 #[cfg(feature = "noop")]
92 this.try_add_hal(hal::api::Noop, &instance_desc, telemetry);
93
94 this
95 }
96
97 fn try_add_hal<A: hal::Api>(
99 &mut self,
100 _: A,
101 instance_desc: &wgt::InstanceDescriptor,
102 telemetry: Option<hal::Telemetry>,
103 ) {
104 self.supported_backends |= A::VARIANT.into();
107
108 if !instance_desc.backends.contains(A::VARIANT.into()) {
109 log::trace!("Instance::new: backend {:?} not requested", A::VARIANT);
110 return;
111 }
112
113 assert!(instance_desc.display.is_none());
115
116 let hal_desc = hal::InstanceDescriptor {
117 name: "wgpu",
118 flags: self.flags,
119 memory_budget_thresholds: instance_desc.memory_budget_thresholds,
120 backend_options: instance_desc.backend_options.clone(),
121 telemetry,
122 display: self.display.as_ref().map(|hdh| {
125 hdh.display_handle()
126 .expect("Implementation did not provide a DisplayHandle")
127 }),
128 };
129
130 use hal::Instance as _;
131 match unsafe { A::Instance::init(&hal_desc) } {
133 Ok(instance) => {
134 log::debug!("Instance::new: created {:?} backend", A::VARIANT);
135 self.instance_per_backend
136 .push((A::VARIANT, Box::new(instance)));
137 }
138 Err(err) => {
139 log::debug!(
140 "Instance::new: failed to create {:?} backend: {:?}",
141 A::VARIANT,
142 err
143 );
144 }
145 }
146 }
147
148 pub(crate) fn from_hal_instance<A: hal::Api>(
149 name: String,
150 hal_instance: <A as hal::Api>::Instance,
151 ) -> Self {
152 Self {
153 _name: name,
154 instance_per_backend: vec![(A::VARIANT, Box::new(hal_instance))],
155 requested_backends: A::VARIANT.into(),
156 supported_backends: A::VARIANT.into(),
157 flags: InstanceFlags::default(),
158 display: None, }
160 }
161
162 pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynInstance> {
163 self.instance_per_backend
164 .iter()
165 .find_map(|(instance_backend, instance)| {
166 (*instance_backend == backend).then(|| instance.as_ref())
167 })
168 }
169
170 pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
174 self.raw(A::VARIANT).map(|instance| {
175 instance
176 .as_any()
177 .downcast_ref()
178 .expect("Stored instance is not of the correct type")
180 })
181 }
182
183 pub unsafe fn create_surface(
199 &self,
200 display_handle: Option<raw_window_handle::RawDisplayHandle>,
201 window_handle: raw_window_handle::RawWindowHandle,
202 ) -> Result<Surface, CreateSurfaceError> {
203 profiling::scope!("Instance::create_surface");
204
205 let instance_display_handle = self.display.as_ref().map(|d| {
206 d.display_handle()
207 .expect("Implementation did not provide a DisplayHandle")
208 .as_raw()
209 });
210 let display_handle = match (instance_display_handle, display_handle) {
211 (Some(a), Some(b)) => {
212 if a != b {
213 return Err(CreateSurfaceError::MismatchingDisplayHandle);
214 }
215 a
216 }
217 (Some(hnd), None) => hnd,
218 (None, Some(hnd)) => hnd,
219 (None, None) => return Err(CreateSurfaceError::MissingDisplayHandle),
220 };
221
222 let mut errors = HashMap::default();
223 let mut surface_per_backend = HashMap::default();
224
225 for (backend, instance) in &self.instance_per_backend {
226 match unsafe {
227 instance
228 .as_ref()
229 .create_surface(display_handle, window_handle)
230 } {
231 Ok(raw) => {
232 surface_per_backend.insert(*backend, raw);
233 }
234 Err(err) => {
235 log::debug!(
236 "Instance::create_surface: failed to create surface for {backend:?}: {err:?}"
237 );
238 errors.insert(*backend, err);
239 }
240 }
241 }
242
243 if surface_per_backend.is_empty() {
244 Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
245 errors,
246 ))
247 } else {
248 let surface = Surface {
249 presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
250 keep_images: AtomicBool::new(false),
251 surface_per_backend,
252 };
253
254 Ok(surface)
255 }
256 }
257
258 #[cfg(drm)]
270 #[cfg_attr(not(vulkan), expect(unused_variables, unused_mut))]
271 pub unsafe fn create_surface_from_drm(
272 &self,
273 fd: i32,
274 plane: u32,
275 connector_id: u32,
276 width: u32,
277 height: u32,
278 refresh_rate: u32,
279 ) -> Result<Surface, CreateSurfaceError> {
280 profiling::scope!("Instance::create_surface_from_drm");
281
282 let mut errors = HashMap::default();
283 let mut surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>> =
284 HashMap::default();
285
286 #[cfg(vulkan)]
287 {
288 let instance = unsafe { self.as_hal::<hal::api::Vulkan>() }
289 .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Vulkan))?;
290
291 match unsafe {
293 instance.create_surface_from_drm(
294 fd,
295 plane,
296 connector_id,
297 width,
298 height,
299 refresh_rate,
300 )
301 } {
302 Ok(surface) => {
303 surface_per_backend.insert(Backend::Vulkan, Box::new(surface));
304 }
305 Err(err) => {
306 errors.insert(Backend::Vulkan, err);
307 }
308 }
309 }
310
311 if surface_per_backend.is_empty() {
312 Err(CreateSurfaceError::FailedToCreateSurfaceForAnyBackend(
313 errors,
314 ))
315 } else {
316 let surface = Surface {
317 presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
318 keep_images: AtomicBool::new(false),
319 surface_per_backend,
320 };
321
322 Ok(surface)
323 }
324 }
325
326 #[cfg(metal)]
330 pub unsafe fn create_surface_metal(
331 &self,
332 layer: *mut core::ffi::c_void,
333 ) -> Result<Surface, CreateSurfaceError> {
334 profiling::scope!("Instance::create_surface_metal");
335
336 let instance = unsafe { self.as_hal::<hal::api::Metal>() }
337 .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Metal))?;
338
339 let layer = layer.cast();
340 let layer = unsafe { &*layer };
352 let raw_surface: Box<dyn hal::DynSurface> =
353 Box::new(instance.create_surface_from_layer(layer));
354
355 let surface = Surface {
356 presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
357 keep_images: AtomicBool::new(false),
358 surface_per_backend: core::iter::once((Backend::Metal, raw_surface)).collect(),
359 };
360
361 Ok(surface)
362 }
363
364 #[cfg(dx12)]
365 fn create_surface_dx12(
366 &self,
367 create_surface_func: impl FnOnce(&hal::dx12::Instance) -> hal::dx12::Surface,
368 ) -> Result<Surface, CreateSurfaceError> {
369 let instance = unsafe { self.as_hal::<hal::api::Dx12>() }
370 .ok_or(CreateSurfaceError::BackendNotEnabled(Backend::Dx12))?;
371 let surface: Box<dyn hal::DynSurface> = Box::new(create_surface_func(instance));
372
373 let surface = Surface {
374 presentation: Mutex::new(rank::SURFACE_PRESENTATION, None),
375 keep_images: AtomicBool::new(false),
376 surface_per_backend: core::iter::once((Backend::Dx12, surface)).collect(),
377 };
378
379 Ok(surface)
380 }
381
382 #[cfg(dx12)]
383 pub unsafe fn create_surface_from_visual(
387 &self,
388 visual: *mut core::ffi::c_void,
389 ) -> Result<Surface, CreateSurfaceError> {
390 profiling::scope!("Instance::instance_create_surface_from_visual");
391 self.create_surface_dx12(|inst| unsafe { inst.create_surface_from_visual(visual) })
392 }
393
394 #[cfg(dx12)]
395 pub unsafe fn create_surface_from_surface_handle(
399 &self,
400 surface_handle: *mut core::ffi::c_void,
401 ) -> Result<Surface, CreateSurfaceError> {
402 profiling::scope!("Instance::instance_create_surface_from_surface_handle");
403 self.create_surface_dx12(|inst| unsafe {
404 inst.create_surface_from_surface_handle(surface_handle)
405 })
406 }
407
408 #[cfg(dx12)]
409 pub unsafe fn create_surface_from_swap_chain_panel(
413 &self,
414 swap_chain_panel: *mut core::ffi::c_void,
415 ) -> Result<Surface, CreateSurfaceError> {
416 profiling::scope!("Instance::instance_create_surface_from_swap_chain_panel");
417 self.create_surface_dx12(|inst| unsafe {
418 inst.create_surface_from_swap_chain_panel(swap_chain_panel)
419 })
420 }
421
422 fn adapter_allowed(&self, raw: &hal::DynExposedAdapter) -> bool {
423 adapter_allowed(
424 self.flags,
425 &raw.info,
426 &raw.capabilities.limits,
427 &raw.capabilities.downlevel,
428 )
429 }
430
431 pub fn enumerate_adapters(
432 &self,
433 backends: Backends,
434 apply_limit_buckets: bool,
435 ) -> Vec<Adapter> {
436 profiling::scope!("Instance::enumerate_adapters");
437 api_log!("Instance::enumerate_adapters");
438
439 let mut adapters = Vec::new();
440 for (_backend, instance) in self
441 .instance_per_backend
442 .iter()
443 .filter(|(backend, _)| backends.contains(Backends::from(*backend)))
444 {
445 profiling::scope!("enumerating", &*alloc::format!("{_backend:?}"));
448
449 let hal_adapters = unsafe { instance.enumerate_adapters(None) };
450
451 adapters.extend(
452 hal_adapters
453 .into_iter()
454 .map(|mut raw| {
455 self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
456 raw
457 })
458 .map(|mut raw| {
459 filter_features_and_limits(
460 self.flags,
461 &mut raw.features,
462 &mut raw.capabilities.limits,
463 );
464 raw
465 })
466 .filter(|raw| self.adapter_allowed(raw))
467 .filter_map(|raw| {
468 if apply_limit_buckets {
469 limits::apply_limit_buckets(raw)
470 } else {
471 Some(raw)
472 }
473 })
474 .map(|raw| {
475 let adapter = Adapter::new(raw);
476 api_log_debug!("Adapter {:?}", adapter.raw.info);
477 adapter
478 }),
479 );
480 }
481 adapters
482 }
483
484 pub fn request_adapter(
485 &self,
486 desc: &wgt::RequestAdapterOptions<&Surface>,
487 backends: Backends,
488 ) -> Result<Adapter, wgt::RequestAdapterError> {
489 profiling::scope!("Instance::request_adapter");
490 api_log!("Instance::request_adapter");
491
492 let mut adapters = Vec::new();
493 let mut incompatible_surface_backends = Backends::empty();
494 let mut no_fallback_backends = Backends::empty();
495 let mut no_adapter_backends = Backends::empty();
496
497 for &(backend, ref instance) in self
498 .instance_per_backend
499 .iter()
500 .filter(|&&(backend, _)| backends.contains(Backends::from(backend)))
501 {
502 let compatible_hal_surface = desc
503 .compatible_surface
504 .and_then(|surface| surface.raw(backend));
505
506 let mut backend_adapters =
507 unsafe { instance.enumerate_adapters(compatible_hal_surface) };
508 if backend_adapters.is_empty() {
509 log::debug!("enabled backend `{backend:?}` has no adapters");
510 no_adapter_backends |= Backends::from(backend);
511 continue;
513 }
514
515 if desc.force_fallback_adapter {
516 log::debug!("Filtering `{backend:?}` for `force_fallback_adapter`");
517 backend_adapters.retain(|exposed| {
518 let keep = exposed.info.device_type == wgt::DeviceType::Cpu;
519 if !keep {
520 log::debug!("* Eliminating adapter `{}`", exposed.info.name);
521 }
522 keep
523 });
524 if backend_adapters.is_empty() {
525 log::debug!("* Backend `{backend:?}` has no fallback adapters");
526 no_fallback_backends |= Backends::from(backend);
527 continue;
528 }
529 }
530
531 if let Some(surface) = desc.compatible_surface {
532 backend_adapters.retain(|exposed| {
533 let capabilities = surface.get_capabilities_with_raw(exposed);
534 if let Err(err) = capabilities {
535 log::debug!(
536 "Adapter {:?} not compatible with surface: {}",
537 exposed.info,
538 err
539 );
540 incompatible_surface_backends |= Backends::from(backend);
541 false
542 } else {
543 true
544 }
545 });
546 if backend_adapters.is_empty() {
547 incompatible_surface_backends |= Backends::from(backend);
548 continue;
549 }
550 }
551
552 let backend_adapters = backend_adapters
553 .into_iter()
554 .map(|mut raw| {
555 self.adjust_limits_for_indirect_validation(&mut raw.capabilities.limits);
556 raw
557 })
558 .map(|mut raw| {
559 filter_features_and_limits(
560 self.flags,
561 &mut raw.features,
562 &mut raw.capabilities.limits,
563 );
564 raw
565 })
566 .filter(|raw| self.adapter_allowed(raw));
567
568 if desc.apply_limit_buckets {
569 adapters.extend(backend_adapters.filter_map(limits::apply_limit_buckets));
570 } else {
571 adapters.extend(backend_adapters);
572 }
573 }
574
575 match desc.power_preference {
576 PowerPreference::LowPower => {
577 sort(&mut adapters, true);
578 }
579 PowerPreference::HighPerformance => {
580 sort(&mut adapters, false);
581 }
582 PowerPreference::None => {}
583 };
584
585 fn sort(adapters: &mut [hal::DynExposedAdapter], prefer_integrated_gpu: bool) {
586 adapters
587 .sort_by_key(|adapter| get_order(adapter.info.device_type, prefer_integrated_gpu));
588 }
589
590 fn get_order(device_type: wgt::DeviceType, prefer_integrated_gpu: bool) -> u8 {
591 match device_type {
599 wgt::DeviceType::DiscreteGpu if prefer_integrated_gpu => 2,
600 wgt::DeviceType::IntegratedGpu if prefer_integrated_gpu => 1,
601 wgt::DeviceType::DiscreteGpu => 1,
602 wgt::DeviceType::IntegratedGpu => 2,
603 wgt::DeviceType::Other => 3,
604 wgt::DeviceType::VirtualGpu => 4,
605 wgt::DeviceType::Cpu => 5,
606 }
607 }
608
609 if adapters.is_empty() {
612 log::debug!("Request adapter didn't find compatible adapters.");
613 } else {
614 log::debug!(
615 "Found {} compatible adapters. Sorted by preference:",
616 adapters.len()
617 );
618 for adapter in &adapters {
619 log::debug!("* {:?}", adapter.info);
620 }
621 }
622
623 if let Some(adapter) = adapters.into_iter().next() {
624 api_log_debug!("Request adapter result {:?}", adapter.info);
625 let adapter = Adapter::new(adapter);
626 Ok(adapter)
627 } else {
628 Err(wgt::RequestAdapterError::NotFound {
629 supported_backends: self.supported_backends,
630 requested_backends: self.requested_backends,
631 active_backends: self.active_backends(),
632 no_fallback_backends,
633 no_adapter_backends,
634 incompatible_surface_backends,
635 })
636 }
637 }
638
639 fn adjust_limits_for_indirect_validation(&self, limits: &mut wgt::Limits) {
642 if self.flags.contains(InstanceFlags::VALIDATION_INDIRECT_CALL) {
645 limits.max_buffer_size = limits.max_buffer_size.min(u32::MAX as u64);
646 limits.max_uniform_buffer_binding_size =
647 limits.max_uniform_buffer_binding_size.min(u32::MAX as u64);
648 limits.max_storage_buffer_binding_size = limits
649 .max_storage_buffer_binding_size
650 .min(u32::MAX as u64 & !(wgt::STORAGE_BINDING_SIZE_ALIGNMENT as u64 - 1));
651 }
652 }
653
654 fn active_backends(&self) -> Backends {
655 self.instance_per_backend
656 .iter()
657 .map(|&(backend, _)| Backends::from(backend))
658 .collect()
659 }
660}
661
662pub struct Surface {
663 pub(crate) presentation: Mutex<Option<Presentation>>,
664 pub(crate) keep_images: AtomicBool,
667 pub surface_per_backend: HashMap<Backend, Box<dyn hal::DynSurface>>,
668}
669
670impl ResourceType for Surface {
671 const TYPE: &'static str = "Surface";
672}
673impl crate::storage::StorageItem for Surface {
674 type Marker = markers::Surface;
675}
676
677impl Surface {
678 pub fn get_capabilities(
679 &self,
680 adapter: &Adapter,
681 ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
682 self.get_capabilities_with_raw(&adapter.raw)
683 }
684
685 pub fn get_capabilities_with_raw(
686 &self,
687 adapter: &hal::DynExposedAdapter,
688 ) -> Result<hal::SurfaceCapabilities, GetSurfaceSupportError> {
689 let backend = adapter.backend();
690 let suf = self
691 .raw(backend)
692 .ok_or(GetSurfaceSupportError::NotSupportedByBackend(backend))?;
693 profiling::scope!("surface_capabilities");
694 let caps = unsafe { adapter.adapter.surface_capabilities(suf) }
695 .ok_or(GetSurfaceSupportError::FailedToRetrieveSurfaceCapabilitiesForAdapter)?;
696 Ok(caps)
697 }
698
699 pub fn display_hdr_info(&self, adapter: &Adapter) -> wgt::DisplayHdrInfo {
705 self.display_hdr_info_with_raw(&adapter.raw)
706 }
707
708 pub fn display_hdr_info_with_raw(
709 &self,
710 adapter: &hal::DynExposedAdapter,
711 ) -> wgt::DisplayHdrInfo {
712 let backend = adapter.backend();
713 let Some(suf) = self.raw(backend) else {
714 return wgt::DisplayHdrInfo::default();
715 };
716 profiling::scope!("surface_display_hdr_info");
717 unsafe { adapter.adapter.surface_display_hdr_info(suf) }.unwrap_or_default()
718 }
719
720 pub fn raw(&self, backend: Backend) -> Option<&dyn hal::DynSurface> {
721 self.surface_per_backend
722 .get(&backend)
723 .map(|surface| surface.as_ref())
724 }
725}
726
727impl Drop for Surface {
728 fn drop(&mut self) {
729 if let Some(present) = self.presentation.lock().take() {
730 for (&backend, surface) in &self.surface_per_backend {
731 if backend == present.device.backend() {
732 unsafe { surface.unconfigure(present.device.raw()) };
733 }
734 }
735 }
736 }
737}
738
739pub struct Adapter {
740 pub(crate) raw: hal::DynExposedAdapter,
741}
742
743impl Adapter {
744 pub fn new(raw: hal::DynExposedAdapter) -> Self {
745 Self { raw }
746 }
747
748 pub fn backend(&self) -> Backend {
750 self.raw.backend()
751 }
752
753 pub fn is_surface_supported(&self, surface: &Surface) -> bool {
754 surface.get_capabilities(self).is_ok()
759 }
760
761 pub fn get_info(&self) -> wgt::AdapterInfo {
762 self.raw.info.clone()
763 }
764
765 pub fn features(&self) -> wgt::Features {
766 self.raw.features
767 }
768
769 pub fn limits(&self) -> wgt::Limits {
770 self.raw.capabilities.limits.clone()
771 }
772
773 pub fn downlevel_capabilities(&self) -> wgt::DownlevelCapabilities {
774 self.raw.capabilities.downlevel.clone()
775 }
776
777 pub fn get_presentation_timestamp(&self) -> wgt::PresentationTimestamp {
778 unsafe { self.raw.adapter.get_presentation_timestamp() }
779 }
780
781 pub fn cooperative_matrix_properties(&self) -> Vec<wgt::CooperativeMatrixProperties> {
782 self.raw.capabilities.cooperative_matrix_properties.clone()
783 }
784
785 pub fn get_texture_format_features(
786 &self,
787 format: wgt::TextureFormat,
788 ) -> wgt::TextureFormatFeatures {
789 use hal::TextureFormatCapabilities as Tfc;
790
791 let caps = unsafe { self.raw.adapter.texture_format_capabilities(format) };
792 let mut allowed_usages = wgt::TextureUsages::empty();
793
794 allowed_usages.set(wgt::TextureUsages::COPY_SRC, caps.contains(Tfc::COPY_SRC));
795 allowed_usages.set(wgt::TextureUsages::COPY_DST, caps.contains(Tfc::COPY_DST));
796 allowed_usages.set(
797 wgt::TextureUsages::TEXTURE_BINDING,
798 caps.contains(Tfc::SAMPLED),
799 );
800 allowed_usages.set(
801 wgt::TextureUsages::STORAGE_BINDING,
802 caps.intersects(
803 Tfc::STORAGE_WRITE_ONLY
804 | Tfc::STORAGE_READ_ONLY
805 | Tfc::STORAGE_READ_WRITE
806 | Tfc::STORAGE_ATOMIC,
807 ),
808 );
809 allowed_usages.set(
810 wgt::TextureUsages::RENDER_ATTACHMENT | wgt::TextureUsages::TRANSIENT_ATTACHMENT,
811 caps.intersects(Tfc::COLOR_ATTACHMENT | Tfc::DEPTH_STENCIL_ATTACHMENT),
812 );
813 allowed_usages.set(
814 wgt::TextureUsages::STORAGE_ATOMIC,
815 caps.contains(Tfc::STORAGE_ATOMIC),
816 );
817
818 let mut flags = wgt::TextureFormatFeatureFlags::empty();
819 flags.set(
820 wgt::TextureFormatFeatureFlags::STORAGE_READ_ONLY,
821 caps.contains(Tfc::STORAGE_READ_ONLY),
822 );
823 flags.set(
824 wgt::TextureFormatFeatureFlags::STORAGE_WRITE_ONLY,
825 caps.contains(Tfc::STORAGE_WRITE_ONLY),
826 );
827 flags.set(
828 wgt::TextureFormatFeatureFlags::STORAGE_READ_WRITE,
829 caps.contains(Tfc::STORAGE_READ_WRITE),
830 );
831
832 flags.set(
833 wgt::TextureFormatFeatureFlags::STORAGE_ATOMIC,
834 caps.contains(Tfc::STORAGE_ATOMIC),
835 );
836
837 flags.set(
838 wgt::TextureFormatFeatureFlags::FILTERABLE,
839 caps.contains(Tfc::SAMPLED_LINEAR),
840 );
841
842 flags.set(
843 wgt::TextureFormatFeatureFlags::BLENDABLE,
844 caps.contains(Tfc::COLOR_ATTACHMENT_BLEND),
845 );
846
847 flags.set(
848 wgt::TextureFormatFeatureFlags::MULTISAMPLE_X2,
849 caps.contains(Tfc::MULTISAMPLE_X2),
850 );
851 flags.set(
852 wgt::TextureFormatFeatureFlags::MULTISAMPLE_X4,
853 caps.contains(Tfc::MULTISAMPLE_X4),
854 );
855 flags.set(
856 wgt::TextureFormatFeatureFlags::MULTISAMPLE_X8,
857 caps.contains(Tfc::MULTISAMPLE_X8),
858 );
859 flags.set(
860 wgt::TextureFormatFeatureFlags::MULTISAMPLE_X16,
861 caps.contains(Tfc::MULTISAMPLE_X16),
862 );
863
864 flags.set(
865 wgt::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE,
866 caps.contains(Tfc::MULTISAMPLE_RESOLVE),
867 );
868
869 wgt::TextureFormatFeatures {
870 allowed_usages,
871 flags,
872 }
873 }
874
875 fn create_device_and_queue_from_hal(
876 self: &Arc<Self>,
877 hal_device: hal::DynOpenDevice,
878 desc: &DeviceDescriptor,
879 instance_flags: InstanceFlags,
880 ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
881 api_log!("Adapter::create_device");
882
883 let device = Device::new(hal_device.device, self, desc, instance_flags)?;
884 let device = Arc::new(device);
885
886 let queue = Queue::new(device.clone(), hal_device.queue, instance_flags)?;
887 let queue = Arc::new(queue);
888
889 device.set_queue(&queue);
890 device.late_init_resources_with_queue()?;
891
892 Ok((device, queue))
893 }
894
895 pub fn create_device_and_queue(
896 self: &Arc<Self>,
897 desc: &DeviceDescriptor,
898 instance_flags: InstanceFlags,
899 ) -> Result<(Arc<Device>, Arc<Queue>), RequestDeviceError> {
900 let mut desc = desc.clone();
901 filter_features_and_limits(
902 instance_flags,
903 &mut desc.required_features,
904 &mut desc.required_limits,
905 );
906
907 if !self.raw.features.contains(desc.required_features) {
909 return Err(RequestDeviceError::UnsupportedFeature(
910 desc.required_features - self.raw.features,
911 ));
912 }
913
914 if desc
916 .required_features
917 .intersects(wgt::Features::all_experimental_mask())
918 && !desc.experimental_features.is_enabled()
919 {
920 return Err(RequestDeviceError::ExperimentalFeaturesNotEnabled(
921 desc.required_features
922 .intersection(wgt::Features::all_experimental_mask()),
923 ));
924 }
925
926 let caps = &self.raw.capabilities;
927 if Backends::PRIMARY.contains(Backends::from(self.backend()))
928 && !caps.downlevel.is_webgpu_compliant()
929 {
930 let missing_flags = wgt::DownlevelFlags::compliant() - caps.downlevel.flags;
931 log::warn!("Missing downlevel flags: {missing_flags:?}\n{DOWNLEVEL_WARNING_MESSAGE}");
932 log::warn!("{:#?}", caps.downlevel);
933 }
934
935 if desc
937 .required_features
938 .contains(wgt::Features::MAPPABLE_PRIMARY_BUFFERS)
939 && self.raw.info.device_type == wgt::DeviceType::DiscreteGpu
940 {
941 log::warn!(
942 "Feature MAPPABLE_PRIMARY_BUFFERS enabled on a discrete gpu. \
943 This is a massive performance footgun and likely not what you wanted"
944 );
945 }
946
947 if let Some(failed) = check_limits(&desc.required_limits, &caps.limits).pop() {
948 return Err(RequestDeviceError::LimitsExceeded(failed));
949 }
950
951 let open = unsafe {
952 self.raw.adapter.open(
953 desc.required_features,
954 &desc.required_limits,
955 &desc.memory_hints,
956 )
957 }
958 .map_err(DeviceError::from_hal)?;
959
960 self.create_device_and_queue_from_hal(open, &desc, instance_flags)
961 }
962}
963
964crate::impl_resource_type!(Adapter);
965crate::impl_storage_item!(Adapter);
966
967#[derive(Clone, Debug, Error)]
968#[non_exhaustive]
969pub enum GetSurfaceSupportError {
970 #[error("Surface is not supported for the specified backend {0}")]
971 NotSupportedByBackend(Backend),
972 #[error("Failed to retrieve surface capabilities for the specified adapter.")]
973 FailedToRetrieveSurfaceCapabilitiesForAdapter,
974}
975
976#[derive(Clone, Debug, Error)]
977#[non_exhaustive]
979pub enum RequestDeviceError {
980 #[error(transparent)]
981 Device(#[from] DeviceError),
982 #[error(transparent)]
983 LimitsExceeded(#[from] FailedLimit),
984 #[error("Failed to initialize Timestamp Normalizer")]
985 TimestampNormalizerInitFailed(#[from] TimestampNormalizerInitError),
986 #[error("Unsupported features were requested: {0}")]
987 UnsupportedFeature(wgt::Features),
988 #[error(
989 "Some experimental features, {0}, were requested, but experimental features are not enabled"
990 )]
991 ExperimentalFeaturesNotEnabled(wgt::Features),
992}
993
994#[derive(Clone, Debug, Error)]
995#[non_exhaustive]
996pub enum CreateSurfaceError {
997 #[error("The backend {0} was not enabled on the instance.")]
998 BackendNotEnabled(Backend),
999 #[error("Failed to create surface for any enabled backend: {0:?}")]
1000 FailedToCreateSurfaceForAnyBackend(HashMap<Backend, hal::InstanceError>),
1001 #[error("The display handle used to create this Instance does not match the one used to create a surface on it")]
1002 MismatchingDisplayHandle,
1003 #[error(
1004 "No `DisplayHandle` is available to create this surface with. When creating a surface with `create_surface()` \
1005 you must specify a display handle in `InstanceDescriptor::display`. \
1006 Rarely, if you need to create surfaces from different `DisplayHandle`s (ex. different Wayland or X11 connections), \
1007 you must use `create_surface_unsafe()`."
1008 )]
1009 MissingDisplayHandle,
1010}
1011
1012impl Global {
1013 pub unsafe fn instance_create_surface(
1032 &self,
1033 display_handle: Option<raw_window_handle::RawDisplayHandle>,
1034 window_handle: raw_window_handle::RawWindowHandle,
1035 id_in: Option<SurfaceId>,
1036 ) -> Result<SurfaceId, CreateSurfaceError> {
1037 let surface = unsafe { self.instance.create_surface(display_handle, window_handle) }?;
1038 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1039 Ok(id)
1040 }
1041
1042 #[cfg(drm)]
1054 pub unsafe fn instance_create_surface_from_drm(
1055 &self,
1056 fd: i32,
1057 plane: u32,
1058 connector_id: u32,
1059 width: u32,
1060 height: u32,
1061 refresh_rate: u32,
1062 id_in: Option<SurfaceId>,
1063 ) -> Result<SurfaceId, CreateSurfaceError> {
1064 let surface = unsafe {
1065 self.instance.create_surface_from_drm(
1066 fd,
1067 plane,
1068 connector_id,
1069 width,
1070 height,
1071 refresh_rate,
1072 )
1073 }?;
1074 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1075
1076 Ok(id)
1077 }
1078
1079 #[cfg(metal)]
1083 pub unsafe fn instance_create_surface_metal(
1084 &self,
1085 layer: *mut core::ffi::c_void,
1086 id_in: Option<SurfaceId>,
1087 ) -> Result<SurfaceId, CreateSurfaceError> {
1088 let surface = unsafe { self.instance.create_surface_metal(layer) }?;
1089 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1090 Ok(id)
1091 }
1092
1093 #[cfg(dx12)]
1094 pub unsafe fn instance_create_surface_from_visual(
1098 &self,
1099 visual: *mut core::ffi::c_void,
1100 id_in: Option<SurfaceId>,
1101 ) -> Result<SurfaceId, CreateSurfaceError> {
1102 let surface = unsafe { self.instance.create_surface_from_visual(visual) }?;
1103 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1104 Ok(id)
1105 }
1106
1107 #[cfg(dx12)]
1108 pub unsafe fn instance_create_surface_from_surface_handle(
1112 &self,
1113 surface_handle: *mut core::ffi::c_void,
1114 id_in: Option<SurfaceId>,
1115 ) -> Result<SurfaceId, CreateSurfaceError> {
1116 let surface = unsafe {
1117 self.instance
1118 .create_surface_from_surface_handle(surface_handle)
1119 }?;
1120 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1121 Ok(id)
1122 }
1123
1124 #[cfg(dx12)]
1125 pub unsafe fn instance_create_surface_from_swap_chain_panel(
1129 &self,
1130 swap_chain_panel: *mut core::ffi::c_void,
1131 id_in: Option<SurfaceId>,
1132 ) -> Result<SurfaceId, CreateSurfaceError> {
1133 let surface = unsafe {
1134 self.instance
1135 .create_surface_from_swap_chain_panel(swap_chain_panel)
1136 }?;
1137 let id = self.surfaces.prepare(id_in).assign(Arc::new(surface));
1138 Ok(id)
1139 }
1140
1141 pub fn surface_drop(&self, id: SurfaceId) {
1142 profiling::scope!("Surface::drop");
1143
1144 api_log!("Surface::drop {id:?}");
1145
1146 self.surfaces.remove(id);
1147 }
1148
1149 pub fn enumerate_adapters(
1150 &self,
1151 backends: Backends,
1152 apply_limit_buckets: bool,
1153 ) -> Vec<AdapterId> {
1154 let adapters = self
1155 .instance
1156 .enumerate_adapters(backends, apply_limit_buckets);
1157 adapters
1158 .into_iter()
1159 .map(|adapter| self.hub.adapters.prepare(None).assign(Arc::new(adapter)))
1160 .collect()
1161 }
1162
1163 pub fn request_adapter(
1164 &self,
1165 desc: &RequestAdapterOptions,
1166 backends: Backends,
1167 id_in: Option<AdapterId>,
1168 ) -> Result<AdapterId, wgt::RequestAdapterError> {
1169 let compatible_surface = desc.compatible_surface.map(|id| self.surfaces.get(id));
1170 let desc = wgt::RequestAdapterOptions {
1171 power_preference: desc.power_preference,
1172 force_fallback_adapter: desc.force_fallback_adapter,
1173 compatible_surface: compatible_surface.as_deref(),
1174 apply_limit_buckets: desc.apply_limit_buckets,
1175 };
1176 let adapter = self.instance.request_adapter(&desc, backends)?;
1177 let id = self.hub.adapters.prepare(id_in).assign(Arc::new(adapter));
1178 Ok(id)
1179 }
1180
1181 pub unsafe fn create_adapter_from_hal(
1195 &self,
1196 hal_adapter: hal::DynExposedAdapter,
1197 input: Option<AdapterId>,
1198 ) -> AdapterId {
1199 profiling::scope!("Instance::create_adapter_from_hal");
1200
1201 let fid = self.hub.adapters.prepare(input);
1202 let id = fid.assign(Arc::new(Adapter::new(hal_adapter)));
1203
1204 resource_log!("Created Adapter {:?}", id);
1205 id
1206 }
1207
1208 pub fn adapter_get_info(&self, adapter_id: AdapterId) -> wgt::AdapterInfo {
1209 let adapter = self.hub.adapters.get(adapter_id);
1210 adapter.get_info()
1211 }
1212
1213 pub fn adapter_get_texture_format_features(
1214 &self,
1215 adapter_id: AdapterId,
1216 format: wgt::TextureFormat,
1217 ) -> wgt::TextureFormatFeatures {
1218 let adapter = self.hub.adapters.get(adapter_id);
1219 adapter.get_texture_format_features(format)
1220 }
1221
1222 pub fn adapter_features(&self, adapter_id: AdapterId) -> wgt::Features {
1223 let adapter = self.hub.adapters.get(adapter_id);
1224 adapter.features()
1225 }
1226
1227 pub fn adapter_limits(&self, adapter_id: AdapterId) -> wgt::Limits {
1228 let adapter = self.hub.adapters.get(adapter_id);
1229 adapter.limits()
1230 }
1231
1232 pub fn adapter_downlevel_capabilities(
1233 &self,
1234 adapter_id: AdapterId,
1235 ) -> wgt::DownlevelCapabilities {
1236 let adapter = self.hub.adapters.get(adapter_id);
1237 adapter.downlevel_capabilities()
1238 }
1239
1240 pub fn adapter_get_presentation_timestamp(
1241 &self,
1242 adapter_id: AdapterId,
1243 ) -> wgt::PresentationTimestamp {
1244 let adapter = self.hub.adapters.get(adapter_id);
1245 adapter.get_presentation_timestamp()
1246 }
1247
1248 pub fn adapter_cooperative_matrix_properties(
1249 &self,
1250 adapter_id: AdapterId,
1251 ) -> Vec<wgt::CooperativeMatrixProperties> {
1252 let adapter = self.hub.adapters.get(adapter_id);
1253 adapter.cooperative_matrix_properties()
1254 }
1255
1256 pub fn adapter_drop(&self, adapter_id: AdapterId) {
1257 profiling::scope!("Adapter::drop");
1258 api_log!("Adapter::drop {adapter_id:?}");
1259
1260 self.hub.adapters.remove(adapter_id);
1261 }
1262}
1263
1264impl Global {
1265 pub fn adapter_request_device(
1266 &self,
1267 adapter_id: AdapterId,
1268 desc: &DeviceDescriptor,
1269 device_id_in: Option<DeviceId>,
1270 queue_id_in: Option<QueueId>,
1271 ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
1272 profiling::scope!("Adapter::request_device");
1273 api_log!("Adapter::request_device");
1274
1275 let device_fid = self.hub.devices.prepare(device_id_in);
1276 let queue_fid = self.hub.queues.prepare(queue_id_in);
1277
1278 let adapter = self.hub.adapters.get(adapter_id);
1279 let (device, queue) = adapter.create_device_and_queue(desc, self.instance.flags)?;
1280
1281 let device_id = device_fid.assign(device);
1282 resource_log!("Created Device {:?}", device_id);
1283
1284 let queue_id = queue_fid.assign(queue);
1285 resource_log!("Created Queue {:?}", queue_id);
1286
1287 Ok((device_id, queue_id))
1288 }
1289
1290 pub unsafe fn create_device_from_hal(
1295 &self,
1296 adapter_id: AdapterId,
1297 hal_device: hal::DynOpenDevice,
1298 desc: &DeviceDescriptor,
1299 device_id_in: Option<DeviceId>,
1300 queue_id_in: Option<QueueId>,
1301 ) -> Result<(DeviceId, QueueId), RequestDeviceError> {
1302 profiling::scope!("Global::create_device_from_hal");
1303
1304 let devices_fid = self.hub.devices.prepare(device_id_in);
1305 let queues_fid = self.hub.queues.prepare(queue_id_in);
1306
1307 let adapter = self.hub.adapters.get(adapter_id);
1308 let (device, queue) =
1309 adapter.create_device_and_queue_from_hal(hal_device, desc, self.instance.flags)?;
1310
1311 let device_id = devices_fid.assign(device);
1312 resource_log!("Created Device {:?}", device_id);
1313
1314 let queue_id = queues_fid.assign(queue);
1315 resource_log!("Created Queue {:?}", queue_id);
1316
1317 Ok((device_id, queue_id))
1318 }
1319}
1320
1321fn adapter_allowed(
1326 flags: InstanceFlags,
1327 info: &impl fmt::Debug,
1328 limits: &wgt::Limits,
1329 downlevel: &wgt::DownlevelCapabilities,
1330) -> bool {
1331 let min_uniform_buffer_offset_alignment = limits.min_uniform_buffer_offset_alignment;
1337 if !min_uniform_buffer_offset_alignment.is_power_of_two() {
1338 log::error!(
1339 "Adapter {:?} min_uniform_buffer_offset_alignment limit is not a power of 2: {:?}",
1340 info,
1341 min_uniform_buffer_offset_alignment
1342 );
1343 return false;
1344 }
1345 let min_storage_buffer_offset_alignment = limits.min_storage_buffer_offset_alignment;
1346 if !min_storage_buffer_offset_alignment.is_power_of_two() {
1347 log::error!(
1348 "Adapter {:?} min_storage_buffer_offset_alignment limit is not a power of 2: {:?}",
1349 info,
1350 min_storage_buffer_offset_alignment
1351 );
1352 return false;
1353 }
1354
1355 if !flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1357 return true;
1358 }
1359
1360 let mut min_limits = wgt::Limits::defaults();
1362 min_limits.zero_native_only();
1363 let failed_limits = check_limits(&min_limits, limits);
1364 if !failed_limits.is_empty() {
1365 log::debug!(
1366 "Adapter {:?} is not WebGPU compliant due to limits: {:?}",
1367 info,
1368 failed_limits
1369 );
1370 return false;
1371 }
1372
1373 if !downlevel.is_webgpu_compliant() {
1374 let missing_flags = wgt::DownlevelFlags::compliant() - downlevel.flags;
1375 log::debug!(
1376 "Adapter {:?} is not WebGPU compliant due to missing downlevel flags: {:?}",
1377 info,
1378 missing_flags
1379 );
1380 return false;
1381 }
1382
1383 true
1384}
1385
1386fn filter_features_and_limits(
1387 flags: InstanceFlags,
1388 features: &mut wgt::Features,
1389 limits: &mut wgt::Limits,
1390) {
1391 if flags.contains(InstanceFlags::STRICT_WEBGPU_COMPLIANCE) {
1392 *features &= wgt::Features::all_webgpu_mask() | limits::EXEMPT_FEATURES;
1393 limits.zero_native_only();
1394 }
1395}
1396
1397#[cfg(test)]
1398mod tests {
1399 use super::*;
1400
1401 fn compliant_downlevel() -> wgt::DownlevelCapabilities {
1402 wgt::DownlevelCapabilities {
1403 flags: wgt::DownlevelFlags::compliant(),
1404 ..Default::default()
1405 }
1406 }
1407
1408 #[test]
1409 fn non_power_of_two_uniform_alignment_always_rejected() {
1410 let limits = wgt::Limits {
1411 min_uniform_buffer_offset_alignment: 3,
1412 ..wgt::Limits::defaults()
1413 };
1414 assert!(!adapter_allowed(
1415 InstanceFlags::empty(),
1416 &"",
1417 &limits,
1418 &compliant_downlevel()
1419 ));
1420 assert!(!adapter_allowed(
1421 InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1422 &"",
1423 &limits,
1424 &compliant_downlevel()
1425 ));
1426 }
1427
1428 #[test]
1429 fn non_power_of_two_storage_alignment_always_rejected() {
1430 let limits = wgt::Limits {
1431 min_storage_buffer_offset_alignment: 96,
1432 ..wgt::Limits::defaults()
1433 };
1434 assert!(!adapter_allowed(
1435 InstanceFlags::empty(),
1436 &"",
1437 &limits,
1438 &compliant_downlevel()
1439 ));
1440 assert!(!adapter_allowed(
1441 InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1442 &"",
1443 &limits,
1444 &compliant_downlevel()
1445 ));
1446 }
1447
1448 #[test]
1449 fn low_limits_allowed_without_strict_compliance() {
1450 let limits = wgt::Limits {
1451 max_texture_dimension_1d: 1,
1452 ..wgt::Limits::defaults()
1453 };
1454 assert!(adapter_allowed(
1455 InstanceFlags::empty(),
1456 &"",
1457 &limits,
1458 &wgt::DownlevelCapabilities::default()
1459 ));
1460 }
1461
1462 #[test]
1463 fn low_limits_rejected_with_strict_compliance() {
1464 let limits = wgt::Limits {
1465 max_texture_dimension_1d: 1,
1466 ..wgt::Limits::defaults()
1467 };
1468 assert!(!adapter_allowed(
1469 InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1470 &"",
1471 &limits,
1472 &compliant_downlevel()
1473 ));
1474 }
1475
1476 #[test]
1477 fn missing_downlevel_flags_rejected_with_strict_compliance() {
1478 let downlevel = wgt::DownlevelCapabilities {
1479 flags: wgt::DownlevelFlags::empty(),
1480 ..Default::default()
1481 };
1482 assert!(!adapter_allowed(
1483 InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1484 &"",
1485 &wgt::Limits::defaults(),
1486 &downlevel
1487 ));
1488 }
1489
1490 #[test]
1491 fn fully_compliant_adapter_always_allowed() {
1492 assert!(adapter_allowed(
1493 InstanceFlags::STRICT_WEBGPU_COMPLIANCE,
1494 &"",
1495 &wgt::Limits::defaults(),
1496 &compliant_downlevel()
1497 ));
1498 }
1499}