Atlas - SDL_openxr.h
Home / ext / SDL / include / SDL3
Lines: 1 | Size: 7872 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1/*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2026 Sam Lantinga <[email protected]>
4
5  This software is provided 'as-is', without any express or implied
6  warranty.  In no event will the authors be held liable for any damages
7  arising from the use of this software.
8
9  Permission is granted to anyone to use this software for any purpose,
10  including commercial applications, and to alter it and redistribute it
11  freely, subject to the following restrictions:
12
13  1. The origin of this software must not be misrepresented; you must not
14     claim that you wrote the original software. If you use this software
15     in a product, an acknowledgment in the product documentation would be
16     appreciated but is not required.
17  2. Altered source versions must be plainly marked as such, and must not be
18     misrepresented as being the original software.
19  3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * # CategoryOpenXR
24 *
25 * Functions for creating OpenXR handles for SDL_gpu contexts.
26 *
27 * For the most part, OpenXR operates independent of SDL, but 
28 * the graphics initialization depends on direct support from SDL_gpu.
29 *
30 */
31
32#ifndef SDL_openxr_h_
33#define SDL_openxr_h_
34
35#include <SDL3/SDL_stdinc.h>
36#include <SDL3/SDL_gpu.h>
37
38#include <SDL3/SDL_begin_code.h>
39/* Set up for C function definitions, even when using C++ */
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44#if defined(OPENXR_H_)
45#define NO_SDL_OPENXR_TYPEDEFS 1
46#endif /* OPENXR_H_ */
47
48#if !defined(NO_SDL_OPENXR_TYPEDEFS)
49#define XR_NULL_HANDLE 0
50
51#if !defined(XR_DEFINE_HANDLE)
52    #define XR_DEFINE_HANDLE(object) typedef Uint64 object;
53#endif /* XR_DEFINE_HANDLE */
54
55typedef enum XrStructureType {
56    XR_TYPE_SESSION_CREATE_INFO = 8,
57    XR_TYPE_SWAPCHAIN_CREATE_INFO = 9,
58} XrStructureType;
59
60XR_DEFINE_HANDLE(XrInstance)
61XR_DEFINE_HANDLE(XrSystemId)
62XR_DEFINE_HANDLE(XrSession)
63XR_DEFINE_HANDLE(XrSwapchain)
64
65typedef struct {
66    XrStructureType type;
67    const void* next;
68} XrSessionCreateInfo;
69typedef struct {
70    XrStructureType type;
71    const void* next;
72} XrSwapchainCreateInfo;
73
74typedef enum XrResult {
75    XR_ERROR_FUNCTION_UNSUPPORTED = -7,
76    XR_ERROR_HANDLE_INVALID = -12,
77} XrResult;
78
79#define PFN_xrGetInstanceProcAddr SDL_FunctionPointer
80#endif /* NO_SDL_OPENXR_TYPEDEFS */
81
82/**
83 * Creates an OpenXR session.
84 *
85 * The OpenXR system ID is pulled from the passed GPU context.
86 *
87 * \param device a GPU context.
88 * \param createinfo the create info for the OpenXR session, sans the system
89 *                   ID.
90 * \param session a pointer filled in with an OpenXR session created for the
91 *                given device.
92 * \returns the result of the call.
93 *
94 * \since This function is available since SDL 3.6.0.
95 *
96 * \sa SDL_CreateGPUDeviceWithProperties
97 */
98extern SDL_DECLSPEC XrResult SDLCALL SDL_CreateGPUXRSession(SDL_GPUDevice *device, const XrSessionCreateInfo *createinfo, XrSession *session);
99
100/**
101 * Queries the GPU device for supported XR swapchain image formats.
102 *
103 * The returned pointer should be allocated with SDL_malloc() and will be
104 * passed to SDL_free().
105 *
106 * \param device a GPU context.
107 * \param session an OpenXR session created for the given device.
108 * \param num_formats a pointer filled with the number of supported XR
109 *                    swapchain formats.
110 * \returns a 0 terminated array of supported formats or NULL on failure; call
111 *          SDL_GetError() for more information. This should be freed with
112 *          SDL_free() when it is no longer needed.
113 *
114 * \since This function is available since SDL 3.6.0.
115 *
116 * \sa SDL_CreateGPUXRSwapchain
117 */
118extern SDL_DECLSPEC SDL_GPUTextureFormat * SDLCALL SDL_GetGPUXRSwapchainFormats(SDL_GPUDevice *device, XrSession session, int *num_formats);
119
120/**
121 * Creates an OpenXR swapchain.
122 *
123 * The array returned via `textures` is sized according to
124 * `xrEnumerateSwapchainImages`, and thus should only be accessed via index
125 * values returned from `xrAcquireSwapchainImage`.
126 *
127 * Applications are still allowed to call `xrEnumerateSwapchainImages` on the
128 * returned XrSwapchain if they need to get the exact size of the array.
129 *
130 * \param device a GPU context.
131 * \param session an OpenXR session created for the given device.
132 * \param createinfo the create info for the OpenXR swapchain, sans the
133 *                   format.
134 * \param format a supported format for the OpenXR swapchain.
135 * \param swapchain a pointer filled in with the created OpenXR swapchain.
136 * \param textures a pointer filled in with the array of created swapchain
137 *                 images.
138 * \returns the result of the call.
139 *
140 * \since This function is available since SDL 3.6.0.
141 *
142 * \sa SDL_CreateGPUDeviceWithProperties
143 * \sa SDL_CreateGPUXRSession
144 * \sa SDL_GetGPUXRSwapchainFormats
145 * \sa SDL_DestroyGPUXRSwapchain
146 */
147extern SDL_DECLSPEC XrResult SDLCALL SDL_CreateGPUXRSwapchain(
148    SDL_GPUDevice *device,
149    XrSession session,
150    const XrSwapchainCreateInfo *createinfo, 
151    SDL_GPUTextureFormat format,
152    XrSwapchain *swapchain,
153    SDL_GPUTexture ***textures);
154
155/**
156 * Destroys and OpenXR swapchain previously returned by
157 * SDL_CreateGPUXRSwapchain.
158 *
159 * \param device a GPU context.
160 * \param swapchain a swapchain previously returned by
161 *                  SDL_CreateGPUXRSwapchain.
162 * \param swapchainImages an array of swapchain images returned by the same
163 *                        call to SDL_CreateGPUXRSwapchain.
164 * \returns the result of the call.
165 *
166 * \since This function is available since SDL 3.6.0.
167 *
168 * \sa SDL_CreateGPUDeviceWithProperties
169 * \sa SDL_CreateGPUXRSession
170 * \sa SDL_CreateGPUXRSwapchain
171 */
172extern SDL_DECLSPEC XrResult SDLCALL SDL_DestroyGPUXRSwapchain(SDL_GPUDevice *device, XrSwapchain swapchain, SDL_GPUTexture **swapchainImages);
173
174/**
175 * Dynamically load the OpenXR loader.
176 *
177 * This can be called at any time.
178 *
179 * SDL keeps a reference count of the OpenXR loader, calling this function
180 * multiple times will increment that count, rather than loading the library
181 * multiple times.
182 *
183 * If not called, this will be implicitly called when creating a GPU device
184 * with OpenXR.
185 *
186 * This function will use the platform default OpenXR loader name, unless the
187 * `SDL_HINT_OPENXR_LIBRARY` hint is set.
188 *
189 * \returns true on success or false on failure; call SDL_GetError() for more
190 *          information.
191 *
192 * \threadsafety This function is not thread safe.
193 *
194 * \since This function is available since SDL 3.6.0.
195 *
196 * \sa SDL_HINT_OPENXR_LIBRARY
197 */
198extern SDL_DECLSPEC bool SDLCALL SDL_OpenXR_LoadLibrary(void);
199
200/**
201 * Unload the OpenXR loader previously loaded by SDL_OpenXR_LoadLibrary.
202 *
203 * SDL keeps a reference count of the OpenXR loader, calling this function
204 * will decrement that count. Once the reference count reaches zero, the
205 * library is unloaded.
206 *
207 * \threadsafety This function is not thread safe.
208 *
209 * \since This function is available since SDL 3.6.0.
210 */
211extern SDL_DECLSPEC void SDLCALL SDL_OpenXR_UnloadLibrary(void);
212
213/**
214 * Get the address of the `xrGetInstanceProcAddr` function.
215 *
216 * This should be called after either calling SDL_OpenXR_LoadLibrary() or
217 * creating an OpenXR SDL_GPUDevice.
218 *
219 * The actual type of the returned function pointer is
220 * PFN_xrGetInstanceProcAddr, but that isn't always available. You should
221 * include the OpenXR headers before this header, or cast the return value of
222 * this function to the correct type.
223 *
224 * \returns the function pointer for `xrGetInstanceProcAddr` or NULL on
225 *          failure; call SDL_GetError() for more information.
226 *
227 * \since This function is available since SDL 3.6.0.
228 */
229extern SDL_DECLSPEC PFN_xrGetInstanceProcAddr SDLCALL SDL_OpenXR_GetXrGetInstanceProcAddr(void);
230
231/* Ends C function definitions when using C++ */
232#ifdef __cplusplus
233}
234#endif
235#include <SDL3/SDL_close_code.h>
236
237#endif /* SDL_openxr_h_ */
238
[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.