From ed694eda89779e32f5cdee030cd28840d4fd2b5a Mon Sep 17 00:00:00 2001
From: Andreas Reich <r_andreas2@web.de>
Date: Sun, 8 Dec 2024 14:44:55 +0100
Subject: [PATCH] Improve logging around surface creation (#6511)

* additional debug logging for request_adapter, demote some messages to debug

* unrelated log messages that annoyed me in Vulkan: debug utils disabled is now `debug`, it being enabled is `info`

* document compatible_surface requirement for WebGL directly on wgt::RequestAdapterOptions

* make adapterenumarge_adapters & request_adapters results info log again when api_log is enabled
---
 wgpu-core/Cargo.toml            |  1 +
 wgpu-core/src/instance.rs       | 35 ++++++++++++++++++++++++++++-----
 wgpu-core/src/lib.rs            | 11 +++++++++++
 wgpu-hal/src/vulkan/instance.rs |  4 ++--
 wgpu-types/src/lib.rs           |  1 +
 5 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml
index 34bb25fc87..31606b9b62 100644
--- a/wgpu-core/Cargo.toml
+++ b/wgpu-core/Cargo.toml
@@ -38,6 +38,7 @@ ignored = ["cfg_aliases"]
 counters = ["wgt/counters"]
 
 ## Log all API entry points at info instead of trace level.
+## Also, promotes certain debug log calls to info.
 api_log_info = []
 
 ## Log resource lifecycle management at info instead of trace level.
diff --git a/wgpu-core/src/instance.rs b/wgpu-core/src/instance.rs
index 2f4365e927..07f9d158e6 100644
--- a/wgpu-core/src/instance.rs
+++ b/wgpu-core/src/instance.rs
@@ -2,7 +2,7 @@ use std::sync::Arc;
 use std::{borrow::Cow, collections::HashMap};
 
 use crate::{
-    api_log,
+    api_log, api_log_debug,
     device::{queue::Queue, resource::Device, DeviceDescriptor, DeviceError},
     global::Global,
     hal_api::HalApi,
@@ -305,7 +305,7 @@ impl Instance {
             let hal_adapters = unsafe { instance.enumerate_adapters(None) };
             for raw in hal_adapters {
                 let adapter = Adapter::new(raw);
-                log::info!("Adapter {:?}", adapter.raw.info);
+                api_log_debug!("Adapter {:?}", adapter.raw.info);
                 adapters.push(adapter);
             }
         }
@@ -336,8 +336,19 @@ impl Instance {
                 backend_adapters.retain(|exposed| exposed.info.device_type == wgt::DeviceType::Cpu);
             }
             if let Some(surface) = desc.compatible_surface {
-                backend_adapters
-                    .retain(|exposed| surface.get_capabilities_with_raw(exposed).is_ok());
+                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
+                        );
+                        false
+                    } else {
+                        true
+                    }
+                });
             }
             adapters.extend(backend_adapters);
         }
@@ -378,8 +389,22 @@ impl Instance {
             }
         }
 
+        // `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() {
-            log::info!("Adapter {:?}", adapter.info);
+            api_log_debug!("Request adapter result {:?}", adapter.info);
             let adapter = Adapter::new(adapter);
             Ok(adapter)
         } else {
diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs
index 1edb27e7ab..9362eeeb93 100644
--- a/wgpu-core/src/lib.rs
+++ b/wgpu-core/src/lib.rs
@@ -162,7 +162,18 @@ macro_rules! api_log {
 macro_rules! api_log {
     ($($arg:tt)+) => (log::trace!($($arg)+))
 }
+
+#[cfg(feature = "api_log_info")]
+macro_rules! api_log_debug {
+    ($($arg:tt)+) => (log::info!($($arg)+))
+}
+#[cfg(not(feature = "api_log_info"))]
+macro_rules! api_log_debug {
+    ($($arg:tt)+) => (log::debug!($($arg)+))
+}
+
 pub(crate) use api_log;
+pub(crate) use api_log_debug;
 
 #[cfg(feature = "resource_log_info")]
 macro_rules! resource_log {
diff --git a/wgpu-hal/src/vulkan/instance.rs b/wgpu-hal/src/vulkan/instance.rs
index 6ec300ec77..5292fa628a 100644
--- a/wgpu-hal/src/vulkan/instance.rs
+++ b/wgpu-hal/src/vulkan/instance.rs
@@ -344,11 +344,11 @@ impl super::Instance {
                     callback_data: debug_utils_create_info.callback_data,
                 })
             } else {
-                log::info!("Debug utils not enabled: extension not listed");
+                log::debug!("Debug utils not enabled: extension not listed");
                 None
             }
         } else {
-            log::info!(
+            log::debug!(
                 "Debug utils not enabled: \
                         debug_utils_user_data not passed to Instance::from_raw"
             );
diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index c024b771a8..4bb38b8a73 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -180,6 +180,7 @@ pub struct RequestAdapterOptions<S> {
     pub force_fallback_adapter: bool,
     /// Surface that is required to be presentable with the requested adapter. This does not
     /// create the surface, only guarantees that the adapter can present to said surface.
+    /// For WebGL, this is strictly required, as an adapter can not be created without a surface.
     pub compatible_surface: Option<S>,
 }