From 1f7db1ebcfc3a82b405b7212adeca7775db2b501 Mon Sep 17 00:00:00 2001
From: Aaron Benjamin <[EMAIL REDACTED]>
Date: Sun, 1 Feb 2026 14:57:32 -0500
Subject: [PATCH] Improve OpenXR loader error messages
When the OpenXR loader library fails to load, provide a detailed error
message explaining:
- On Windows: need openxr_loader.dll in app directory or PATH
- On Linux: install libopenxr-loader package or set LD_LIBRARY_PATH
- Can use SDL_HINT_OPENXR_LIBRARY hint to specify path
Also update D3D12 backend to include the error in its warning log,
and remove redundant SDL_SetError in Vulkan backend that was
overwriting the detailed message.
---
src/gpu/d3d12/SDL_gpu_d3d12.c | 2 +-
src/gpu/vulkan/SDL_gpu_vulkan.c | 2 +-
src/gpu/xr/SDL_openxrdyn.c | 5 ++++-
3 files changed, 6 insertions(+), 3 deletions(-)
diff --git a/src/gpu/d3d12/SDL_gpu_d3d12.c b/src/gpu/d3d12/SDL_gpu_d3d12.c
index f53a2d4c17801..58638b75f2212 100644
--- a/src/gpu/d3d12/SDL_gpu_d3d12.c
+++ b/src/gpu/d3d12/SDL_gpu_d3d12.c
@@ -8686,7 +8686,7 @@ static bool D3D12_PrepareDriver(SDL_VideoDevice *_this, SDL_PropertiesID props)
bool xr = SDL_GetBooleanProperty(props, SDL_PROP_GPU_DEVICE_CREATE_XR_ENABLE_BOOLEAN, false);
if (xr) {
if (!SDL_OpenXR_LoadLibrary()) {
- SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "D3D12: Failed to load OpenXR");
+ SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "D3D12: Failed to load OpenXR: %s", SDL_GetError());
return false;
}
diff --git a/src/gpu/vulkan/SDL_gpu_vulkan.c b/src/gpu/vulkan/SDL_gpu_vulkan.c
index efe91099ba1f9..53b91e9b0d56f 100644
--- a/src/gpu/vulkan/SDL_gpu_vulkan.c
+++ b/src/gpu/vulkan/SDL_gpu_vulkan.c
@@ -12738,7 +12738,7 @@ static bool VULKAN_PrepareDriver(SDL_VideoDevice *_this, SDL_PropertiesID props)
if (xr) {
if (!SDL_OpenXR_LoadLibrary()) {
- SDL_SetError("Failed to load OpenXR loader or a required symbol");
+ /* SDL_GetError() already has the detailed message from SDL_OpenXR_LoadLibrary() */
SDL_Vulkan_UnloadLibrary();
return false;
}
diff --git a/src/gpu/xr/SDL_openxrdyn.c b/src/gpu/xr/SDL_openxrdyn.c
index 79093e67b6143..081c196752926 100644
--- a/src/gpu/xr/SDL_openxrdyn.c
+++ b/src/gpu/xr/SDL_openxrdyn.c
@@ -259,7 +259,10 @@ SDL_DECLSPEC bool SDLCALL SDL_OpenXR_LoadLibrary(void)
}
if (!openxr_loader.lib) {
- SDL_SetError("Failed loading OpenXR library");
+ SDL_SetError("Failed to load OpenXR loader library. "
+ "On Windows, ensure openxr_loader.dll is in your application directory or PATH. "
+ "On Linux, install the OpenXR loader package (libopenxr-loader) or set LD_LIBRARY_PATH. "
+ "You can also use the SDL_HINT_OPENXR_LIBRARY hint to specify the loader path.");
openxr_load_refcount--;
return false;
}