GPU: OpenXR integration (#14837)

Based on Beyley's initial draft in #11601.

Co-authored-by: Beyley Cardellio <ep1cm1n10n123@gmail.com>
Co-authored-by: Ethan Lee <flibitijibibo@gmail.com>

include/SDL3/SDL_gpu.h

@@ -2364,6 +2364,20 @@ extern SDL_DECLSPEC SDL_GPUDevice * SDLCALL SDL_CreateGPUDeviceWithProperties(
 #define SDL_PROP_GPU_DEVICE_CREATE_VULKAN_OPTIONS_POINTER                       "SDL.gpu.device.create.vulkan.options"
 #define SDL_PROP_GPU_DEVICE_CREATE_METAL_ALLOW_MACFAMILY1_BOOLEAN               "SDL.gpu.device.create.metal.allowmacfamily1"
 
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_ENABLE_BOOLEAN                            "SDL.gpu.device.create.xr.enable"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_INSTANCE_POINTER                          "SDL.gpu.device.create.xr.instance_out"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_SYSTEM_ID_POINTER                         "SDL.gpu.device.create.xr.system_id_out"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_VERSION_NUMBER                            "SDL.gpu.device.create.xr.version"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_FORM_FACTOR_NUMBER                        "SDL.gpu.device.create.xr.form_factor"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_EXTENSION_COUNT_NUMBER                    "SDL.gpu.device.create.xr.extensions.count"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_EXTENSION_NAMES_POINTER                   "SDL.gpu.device.create.xr.extensions.names"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_LAYER_COUNT_NUMBER                        "SDL.gpu.device.create.xr.layers.count"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_LAYER_NAMES_POINTER                       "SDL.gpu.device.create.xr.layers.names"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_APPLICATION_NAME_STRING                   "SDL.gpu.device.create.xr.application.name"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_APPLICATION_VERSION_NUMBER                "SDL.gpu.device.create.xr.application.version"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_ENGINE_NAME_STRING                        "SDL.gpu.device.create.xr.engine.name"
+#define SDL_PROP_GPU_DEVICE_CREATE_XR_ENGINE_VERSION_NUMBER                     "SDL.gpu.device.create.xr.engine.version"
+
 
 /**
  * A structure specifying additional options when using Vulkan.

include/SDL3/SDL_hints.h

@@ -1145,6 +1145,18 @@ extern "C" {
  */
 #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER"
 
+/**
+ * A variable that specifies the library name to use when loading the OpenXR loader.
+ *
+ * By default, SDL will try the system default name, but on some platforms like Windows,
+ * debug builds of the OpenXR loader have a different name, and are not always directly compatible with release applications.
+ * Setting this hint allows you to compensate for this difference in your app when applicable.
+ *
+ * This hint should be set before the OpenXR loader is loaded.
+ * For example, creating an OpenXR GPU device will load the OpenXR loader.
+ */
+#define SDL_HINT_OPENXR_LIBRARY "SDL_OPENXR_LIBRARY"
+
 /**
  * A variable to control whether SDL_hid_enumerate() enumerates all HID
  * devices or only controllers.

include/SDL3/SDL_openxr.h

@@ -0,0 +1,207 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2026 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ * # CategoryOpenXR
+ *
+ * Functions for creating OpenXR handles for SDL_gpu contexts.
+ *
+ * For the most part, OpenXR operates independent of SDL, but 
+ * the graphics initialization depends on direct support from SDL_gpu.
+ *
+ */
+
+#ifndef SDL_openxr_h_
+#define SDL_openxr_h_
+
+#include <SDL3/SDL_stdinc.h>
+#include <SDL3/SDL_gpu.h>
+
+#include <SDL3/SDL_begin_code.h>
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if defined(OPENXR_H_)
+#define NO_SDL_OPENXR_TYPEDEFS 1
+#endif /* OPENXR_H_ */
+
+#if !defined(NO_SDL_OPENXR_TYPEDEFS)
+#define XR_NULL_HANDLE 0
+
+#if !defined(XR_DEFINE_HANDLE)
+    #define XR_DEFINE_HANDLE(object) typedef Uint64 object;
+#endif /* XR_DEFINE_HANDLE */
+
+typedef enum XrStructureType {
+    XR_TYPE_SESSION_CREATE_INFO = 8,
+    XR_TYPE_SWAPCHAIN_CREATE_INFO = 9,
+} XrStructureType;
+
+XR_DEFINE_HANDLE(XrInstance)
+XR_DEFINE_HANDLE(XrSystemId)
+XR_DEFINE_HANDLE(XrSession)
+XR_DEFINE_HANDLE(XrSwapchain)
+
+typedef struct {
+    XrStructureType type;
+    const void* next;
+} XrSessionCreateInfo;
+typedef struct {
+    XrStructureType type;
+    const void* next;
+} XrSwapchainCreateInfo;
+
+typedef enum XrResult {
+    XR_ERROR_FUNCTION_UNSUPPORTED = -7,
+    XR_ERROR_HANDLE_INVALID = -12,
+} XrResult;
+
+#define PFN_xrGetInstanceProcAddr SDL_FunctionPointer
+#endif /* NO_SDL_OPENXR_TYPEDEFS */
+
+/**
+ * Creates an OpenXR session. The OpenXR system ID is pulled from the passed GPU context.
+ * 
+ * \param device a GPU context.
+ * \param createinfo the create info for the OpenXR session, sans the system ID.
+ * \param session a pointer filled in with an OpenXR session created for the given device.
+ * \returns the result of the call.
+ * 
+ * \sa SDL_CreateGPUDeviceWithProperties
+ */
+extern SDL_DECLSPEC XrResult SDLCALL SDL_CreateGPUXRSession(SDL_GPUDevice *device, const XrSessionCreateInfo *createinfo, XrSession *session);
+
+/**
+ * Queries the GPU device for supported XR swapchain image formats.
+ *
+ * The returned pointer should be allocated with SDL_malloc() and will be
+ * passed to SDL_free().
+ *
+ * \param device a GPU context.
+ * \param session an OpenXR session created for the given device.
+ * \param num_formats a pointer filled with the number of supported XR swapchain formats.
+ * \returns a 0 terminated array of supported formats or NULL on failure;
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
+ *
+ * \sa SDL_CreateGPUXRSwapchain
+ */
+extern SDL_DECLSPEC SDL_GPUTextureFormat * SDLCALL SDL_GetGPUXRSwapchainFormats(SDL_GPUDevice *device, XrSession session, int *num_formats);
+
+/**
+ * Creates an OpenXR swapchain.
+ *
+ * The array returned via `textures` is sized according to
+ *`xrEnumerateSwapchainImages`, and thus should only be accessed via index
+ * values returned from `xrAcquireSwapchainImage`.
+ *
+ * Applications are still allowed to call `xrEnumerateSwapchainImages` on the
+ * returned XrSwapchain if they need to get the exact size of the array.
+ *
+ * \param device a GPU context.
+ * \param session an OpenXR session created for the given device.
+ * \param createinfo the create info for the OpenXR swapchain, sans the format.
+ * \param format a supported format for the OpenXR swapchain.
+ * \param swapchain a pointer filled in with the created OpenXR swapchain.
+ * \param textures a pointer filled in with the array of created swapchain images.
+ * \returns the result of the call.
+ * 
+ * \sa SDL_CreateGPUDeviceWithProperties
+ * \sa SDL_CreateGPUXRSession
+ * \sa SDL_GetGPUXRSwapchainFormats
+ * \sa SDL_DestroyGPUXRSwapchain
+ */
+extern SDL_DECLSPEC XrResult SDLCALL SDL_CreateGPUXRSwapchain(
+    SDL_GPUDevice *device,
+    XrSession session,
+    const XrSwapchainCreateInfo *createinfo, 
+    SDL_GPUTextureFormat format,
+    XrSwapchain *swapchain,
+    SDL_GPUTexture ***textures);
+
+/**
+ * Destroys and OpenXR swapchain previously returned by SDL_CreateGPUXRSwapchain.
+ * 
+ * \param device a GPU context.
+ * \param swapchain a swapchain previously returned by SDL_CreateGPUXRSwapchain.
+ * \param swapchainImages an array of swapchain images returned by the same call to SDL_CreateGPUXRSwapchain.
+ * \returns the result of the call.
+ * 
+ * \sa SDL_CreateGPUDeviceWithProperties
+ * \sa SDL_CreateGPUXRSession
+ * \sa SDL_CreateGPUXRSwapchain
+ */
+extern SDL_DECLSPEC XrResult SDLCALL SDL_DestroyGPUXRSwapchain(SDL_GPUDevice *device, XrSwapchain swapchain, SDL_GPUTexture **swapchainImages);
+
+/**
+ * Dynamically load the OpenXR loader. This can be called at any time.
+ * 
+ * SDL keeps a reference count of the OpenXR loader, calling this function multiple 
+ * times will increment that count, rather than loading the library multiple times.
+ * 
+ * If not called, this will be implicitly called when creating a GPU device with OpenXR.
+ * 
+ * This function will use the platform default OpenXR loader name, 
+ * unless the `SDL_HINT_OPENXR_LIBRARY` hint is set.
+ * 
+ * \returns true on success or false on failure; call SDL_GetError() for more
+ *          information.
+ * 
+ * \threadsafety This function is not thread safe.
+ * 
+ * \sa SDL_HINT_OPENXR_LIBRARY
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_OpenXR_LoadLibrary(void);
+
+/**
+ * Unload the OpenXR loader previously loaded by SDL_OpenXR_LoadLibrary.
+ * 
+ * SDL keeps a reference count of the OpenXR loader, calling this function will decrement that count. 
+ * Once the reference count reaches zero, the library is unloaded.
+ * 
+ * \threadsafety This function is not thread safe.
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_OpenXR_UnloadLibrary(void);
+
+/**
+ * Get the address of the `xrGetInstanceProcAddr` function.
+ * 
+ * This should be called after either calling SDL_OpenXR_LoadLibrary() or
+ * creating an OpenXR SDL_GPUDevice.
+ * 
+ * The actual type of the returned function pointer is PFN_xrGetInstanceProcAddr, 
+ * but that isn't always available. You should include the OpenXR headers before this header, 
+ * or cast the return value of this function to the correct type.
+ * 
+ * \returns the function pointer for `xrGetInstanceProcAddr` or NULL on
+ *          failure; call SDL_GetError() for more information.
+ */
+extern SDL_DECLSPEC PFN_xrGetInstanceProcAddr SDLCALL SDL_OpenXR_GetXrGetInstanceProcAddr(void);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include <SDL3/SDL_close_code.h>
+
+#endif /* SDL_openxr_h_ */

include/build_config/SDL_build_config.h.cmake

@@ -488,6 +488,7 @@
 #cmakedefine SDL_GPU_D3D12 1
 #cmakedefine SDL_GPU_VULKAN 1
 #cmakedefine SDL_GPU_METAL 1
+#cmakedefine HAVE_GPU_OPENXR 1
 
 #cmakedefine SDL_GPU_PRIVATE 1
 

include/build_config/SDL_build_config_android.h

@@ -193,6 +193,7 @@
 #define SDL_VIDEO_VULKAN 1
 #define SDL_VIDEO_RENDER_VULKAN 1
 #define SDL_GPU_VULKAN 1
+#define HAVE_GPU_OPENXR 1
 #define SDL_VIDEO_RENDER_GPU 1
 #endif
 

include/build_config/SDL_build_config_windows.h

@@ -289,6 +289,7 @@ typedef unsigned int uintptr_t;
 #endif
 #define SDL_GPU_D3D12 1
 #define SDL_GPU_VULKAN 1
+#define HAVE_GPU_OPENXR 1
 #define SDL_VIDEO_RENDER_GPU 1
 
 /* Enable system power support */