From 07ef5326817c4d9cf4d7d1ec0368edb729359f42 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 22 Jul 2025 13:19:30 -0400
Subject: [PATCH] hints: Renamed SDL_HINT_LOG_BACKENDS to SDL_DEBUG_LOGGING.
This still logs backend choices, but we might use it for other things. For
example, what Android device is being used, or all the devices we enumerated,
etc.
Ideally this eventually logs all the stuff we often have to ask followup
questions about.
---
include/SDL3/SDL_hints.h | 21 ++++++++++++---------
src/SDL_utils.c | 9 +++++----
src/SDL_utils_c.h | 2 +-
src/audio/SDL_audio.c | 2 +-
src/camera/SDL_camera.c | 2 +-
src/gpu/SDL_gpu.c | 2 +-
src/io/io_uring/SDL_asyncio_liburing.c | 4 ++--
src/io/windows/SDL_asyncio_windows_ioring.c | 4 ++--
src/render/SDL_render.c | 2 +-
src/storage/SDL_storage.c | 4 ++--
src/video/SDL_video.c | 2 +-
11 files changed, 29 insertions(+), 25 deletions(-)
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index d330c1d681016..09c918b13ac29 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -4396,26 +4396,29 @@ extern "C" {
#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS"
/**
- * A variable controlling whether SDL backend information is logged.
+ * A variable controlling whether SDL logs some debug information.
*
* The variable can be set to the following values:
*
- * - "0": Subsystem information will not be logged. (default)
- * - "1": Subsystem information will be logged.
+ * - "0": SDL debug information will not be logged. (default)
+ * - "1": SDL debug information will be logged.
*
* This is generally meant to be used as an environment variable to let
- * end-users report what subsystems were chosen on their system, to aid in
- * debugging. Logged information is sent through SDL_Log(), which means by
- * default they appear on stdout on most platforms or maybe
- * OutputDebugString() on Windows, and can be funneled by the app with
- * SDL_SetLogOutputFunction(), etc.
+ * end-users report what subsystems were chosen on their system, perhaps what
+ * sort of hardware they are running on, etc, to aid in debugging. Logged
+ * information is sent through SDL_Log(), which means by default they appear
+ * on stdout on most platforms, or maybe OutputDebugString() on Windows, and
+ * can be funneled by the app with SDL_SetLogOutputFunction(), etc.
+ *
+ * The specific output might change between SDL versions; more information
+ * might be deemed useful in the future.
*
* This hint can be set anytime, but the specific logs are generated during
* subsystem init.
*
* \since This hint is available since SDL 3.4.0.
*/
-#define SDL_HINT_LOG_BACKENDS "SDL_LOG_BACKENDS"
+#define SDL_HINT_DEBUG_LOGGING "SDL_DEBUG_LOGGING"
/**
* An enumeration of hint priorities.
diff --git a/src/SDL_utils.c b/src/SDL_utils.c
index ec2c435a92069..47fa28c06d46f 100644
--- a/src/SDL_utils.c
+++ b/src/SDL_utils.c
@@ -553,11 +553,12 @@ char *SDL_CreateDeviceName(Uint16 vendor, Uint16 product, const char *vendor_nam
return name;
}
-void SDL_LogBackend(const char *subsystem, const char *backend)
+#define SDL_DEBUG_LOG_INTRO "SDL_DEBUG: "
+
+void SDL_DebugLogBackend(const char *subsystem, const char *backend)
{
- if (SDL_GetHintBoolean(SDL_HINT_LOG_BACKENDS, false)) {
- SDL_Log("SDL_BACKEND: %s -> '%s'", subsystem, backend);
+ if (SDL_GetHintBoolean(SDL_HINT_DEBUG_LOGGING, false)) {
+ SDL_Log(SDL_DEBUG_LOG_INTRO "chose %s backend '%s'", subsystem, backend);
}
}
-
diff --git a/src/SDL_utils_c.h b/src/SDL_utils_c.h
index 2929e7f1f1902..b70b64e963a70 100644
--- a/src/SDL_utils_c.h
+++ b/src/SDL_utils_c.h
@@ -76,6 +76,6 @@ extern const char *SDL_GetPersistentString(const char *string);
extern char *SDL_CreateDeviceName(Uint16 vendor, Uint16 product, const char *vendor_name, const char *product_name, const char *default_name);
// Log what backend a subsystem chose, if a hint was set to do so. Useful for debugging.
-extern void SDL_LogBackend(const char *subsystem, const char *backend);
+extern void SDL_DebugLogBackend(const char *subsystem, const char *backend);
#endif // SDL_utils_h_
diff --git a/src/audio/SDL_audio.c b/src/audio/SDL_audio.c
index 56033912c4880..b1956175c6c66 100644
--- a/src/audio/SDL_audio.c
+++ b/src/audio/SDL_audio.c
@@ -1007,7 +1007,7 @@ bool SDL_InitAudio(const char *driver_name)
}
if (initialized) {
- SDL_LogBackend("audio", current_audio.name);
+ SDL_DebugLogBackend("audio", current_audio.name);
} else {
// specific drivers will set the error message if they fail, but otherwise we do it here.
if (!tried_to_init) {
diff --git a/src/camera/SDL_camera.c b/src/camera/SDL_camera.c
index 7385426afc998..48c6b500dff4a 100644
--- a/src/camera/SDL_camera.c
+++ b/src/camera/SDL_camera.c
@@ -1525,7 +1525,7 @@ bool SDL_CameraInit(const char *driver_name)
}
if (initialized) {
- SDL_LogBackend("camera", camera_driver.name);
+ SDL_DebugLogBackend("camera", camera_driver.name);
} else {
// specific drivers will set the error message if they fail, but otherwise we do it here.
if (!tried_to_init) {
diff --git a/src/gpu/SDL_gpu.c b/src/gpu/SDL_gpu.c
index 3e0002f0581ac..ad5a16da3f80c 100644
--- a/src/gpu/SDL_gpu.c
+++ b/src/gpu/SDL_gpu.c
@@ -711,7 +711,7 @@ SDL_GPUDevice *SDL_CreateGPUDeviceWithProperties(SDL_PropertiesID props)
selectedBackend = SDL_GPUSelectBackend(props);
if (selectedBackend != NULL) {
- SDL_LogBackend("gpu", selectedBackend->name);
+ SDL_DebugLogBackend("gpu", selectedBackend->name);
debug_mode = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN, true);
preferLowPower = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN, false);
diff --git a/src/io/io_uring/SDL_asyncio_liburing.c b/src/io/io_uring/SDL_asyncio_liburing.c
index 8b4738f9cabcc..4aef5f4b12ea0 100644
--- a/src/io/io_uring/SDL_asyncio_liburing.c
+++ b/src/io/io_uring/SDL_asyncio_liburing.c
@@ -512,12 +512,12 @@ static void MaybeInitializeLibUring(void)
{
if (SDL_ShouldInit(&liburing_init)) {
if (LoadLibUring()) {
- SDL_LogBackend("asyncio", "liburing");
+ SDL_DebugLogBackend("asyncio", "liburing");
CreateAsyncIOQueue = SDL_SYS_CreateAsyncIOQueue_liburing;
QuitAsyncIO = SDL_SYS_QuitAsyncIO_liburing;
AsyncIOFromFile = SDL_SYS_AsyncIOFromFile_liburing;
} else { // can't use liburing? Use the "generic" threadpool implementation instead.
- SDL_LogBackend("asyncio", "generic");
+ SDL_DebugLogBackend("asyncio", "generic");
CreateAsyncIOQueue = SDL_SYS_CreateAsyncIOQueue_Generic;
QuitAsyncIO = SDL_SYS_QuitAsyncIO_Generic;
AsyncIOFromFile = SDL_SYS_AsyncIOFromFile_Generic;
diff --git a/src/io/windows/SDL_asyncio_windows_ioring.c b/src/io/windows/SDL_asyncio_windows_ioring.c
index fd659210150eb..52683c6ab29e7 100644
--- a/src/io/windows/SDL_asyncio_windows_ioring.c
+++ b/src/io/windows/SDL_asyncio_windows_ioring.c
@@ -511,12 +511,12 @@ static void MaybeInitializeWinIoRing(void)
{
if (SDL_ShouldInit(&ioring_init)) {
if (LoadWinIoRing()) {
- SDL_LogBackend("asyncio", "ioring");
+ SDL_DebugLogBackend("asyncio", "ioring");
CreateAsyncIOQueue = SDL_SYS_CreateAsyncIOQueue_ioring;
QuitAsyncIO = SDL_SYS_QuitAsyncIO_ioring;
AsyncIOFromFile = SDL_SYS_AsyncIOFromFile_ioring;
} else { // can't use ioring? Use the "generic" threadpool implementation instead.
- SDL_LogBackend("asyncio", "generic");
+ SDL_DebugLogBackend("asyncio", "generic");
CreateAsyncIOQueue = SDL_SYS_CreateAsyncIOQueue_Generic;
QuitAsyncIO = SDL_SYS_QuitAsyncIO_Generic;
AsyncIOFromFile = SDL_SYS_AsyncIOFromFile_Generic;
diff --git a/src/render/SDL_render.c b/src/render/SDL_render.c
index a3351ce1fc440..e139d3754bfab 100644
--- a/src/render/SDL_render.c
+++ b/src/render/SDL_render.c
@@ -1064,7 +1064,7 @@ SDL_Renderer *SDL_CreateRendererWithProperties(SDL_PropertiesID props)
}
if (rc) {
- SDL_LogBackend("render", renderer->name);
+ SDL_DebugLogBackend("render", renderer->name);
} else {
if (driver_name) {
SDL_SetError("%s not available", driver_name);
diff --git a/src/storage/SDL_storage.c b/src/storage/SDL_storage.c
index dd3343b0e293b..643a2be1c1531 100644
--- a/src/storage/SDL_storage.c
+++ b/src/storage/SDL_storage.c
@@ -119,7 +119,7 @@ SDL_Storage *SDL_OpenTitleStorage(const char *override, SDL_PropertiesID props)
}
}
if (storage) {
- SDL_LogBackend("title_storage", titlebootstrap[i]->name);
+ SDL_DebugLogBackend("title_storage", titlebootstrap[i]->name);
} else {
if (driver_name) {
SDL_SetError("%s not available", driver_name);
@@ -163,7 +163,7 @@ SDL_Storage *SDL_OpenUserStorage(const char *org, const char *app, SDL_Propertie
}
}
if (storage) {
- SDL_LogBackend("user_storage", userbootstrap[i]->name);
+ SDL_DebugLogBackend("user_storage", userbootstrap[i]->name);
} else {
if (driver_name) {
SDL_SetError("%s not available", driver_name);
diff --git a/src/video/SDL_video.c b/src/video/SDL_video.c
index 1b29fc42d31ca..72b6149f445e3 100644
--- a/src/video/SDL_video.c
+++ b/src/video/SDL_video.c
@@ -680,7 +680,7 @@ bool SDL_VideoInit(const char *driver_name)
}
}
if (video) {
- SDL_LogBackend("video", bootstrap[i]->name);
+ SDL_DebugLogBackend("video", bootstrap[i]->name);
} else {
if (driver_name) {
SDL_SetError("%s not available", driver_name);