SDL 3.0
SDL_vulkan.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 2017, Mark Callow
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 * # CategoryVulkan
24 *
25 * Functions for creating Vulkan surfaces on SDL windows.
26 */
27
28#ifndef SDL_vulkan_h_
29#define SDL_vulkan_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_video.h>
34
35#include <SDL3/SDL_begin_code.h>
36/* Set up for C function definitions, even when using C++ */
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/* Avoid including vulkan.h, don't define VkInstance if it's already included */
42#ifdef VULKAN_H_
43#define NO_SDL_VULKAN_TYPEDEFS
44#endif
45#ifndef NO_SDL_VULKAN_TYPEDEFS
46#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
47
48#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
49#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
50#else
51#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
52#endif
53
54VK_DEFINE_HANDLE(VkInstance)
55VK_DEFINE_HANDLE(VkPhysicalDevice)
57struct VkAllocationCallbacks;
58
59#endif /* !NO_SDL_VULKAN_TYPEDEFS */
60
61/**
62 * \name Vulkan support functions
63 */
64/* @{ */
65
66/**
67 * Dynamically load the Vulkan loader library.
68 *
69 * This should be called after initializing the video driver, but before
70 * creating any Vulkan windows. If no Vulkan loader library is loaded, the
71 * default library will be loaded upon creation of the first Vulkan window.
72 *
73 * It is fairly common for Vulkan applications to link with libvulkan instead
74 * of explicitly loading it at run time. This will work with SDL provided the
75 * application links to a dynamic library and both it and SDL use the same
76 * search path.
77 *
78 * If you specify a non-NULL `path`, an application should retrieve all of the
79 * Vulkan functions it uses from the dynamic library using
80 * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
81 * to the same vulkan loader library the application linked to.
82 *
83 * On Apple devices, if `path` is NULL, SDL will attempt to find the
84 * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
85 * process. This is because it is fairly common for Vulkan applications to
86 * link with libvulkan (and historically MoltenVK was provided as a static
87 * library). If it is not found, on macOS, SDL will attempt to load
88 * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
89 * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
90 * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
91 * dynamic framework or .dylib must ensure it is included in its application
92 * bundle.
93 *
94 * On non-Apple devices, application linking with a static libvulkan is not
95 * supported. Either do not link to the Vulkan loader or link to a dynamic
96 * library version.
97 *
98 * \param path the platform dependent Vulkan loader library name or NULL.
99 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
100 * for more information.
101 *
102 * \since This function is available since SDL 3.0.0.
103 *
104 * \sa SDL_Vulkan_GetVkGetInstanceProcAddr
105 * \sa SDL_Vulkan_UnloadLibrary
106 */
107extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
108
109/**
110 * Get the address of the `vkGetInstanceProcAddr` function.
111 *
112 * This should be called after either calling SDL_Vulkan_LoadLibrary() or
113 * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
114 *
115 * The actual type of the returned function pointer is
116 * PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan
117 * headers are not included here. You should cast the return value of this
118 * function to that type, e.g.
119 *
120 * `vkGetInstanceProcAddr =
121 * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
122 *
123 * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on
124 * failure; call SDL_GetError() for more information.
125 *
126 * \since This function is available since SDL 3.0.0.
127 */
129
130/**
131 * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary().
132 *
133 * \since This function is available since SDL 3.0.0.
134 *
135 * \sa SDL_Vulkan_LoadLibrary
136 */
137extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
138
139/**
140 * Get the Vulkan instance extensions needed for vkCreateInstance.
141 *
142 * This should be called after either calling SDL_Vulkan_LoadLibrary() or
143 * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
144 *
145 * On return, the variable pointed to by `count` will be set to the number of
146 * elements returned, suitable for using with
147 * VkInstanceCreateInfo::enabledExtensionCount, and the returned array can be
148 * used with VkInstanceCreateInfo::ppEnabledExtensionNames, for calling
149 * Vulkan's vkCreateInstance API.
150 *
151 * You should not free the returned array; it is owned by SDL.
152 *
153 * \param count a pointer filled in with the number of extensions returned.
154 * \returns an array of extension name strings on success, NULL on failure;
155 * call SDL_GetError() for more information.
156 *
157 * \since This function is available since SDL 3.0.0.
158 *
159 * \sa SDL_Vulkan_CreateSurface
160 */
161extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtensions(Uint32 *count);
162
163/**
164 * Create a Vulkan rendering surface for a window.
165 *
166 * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
167 * `instance` must have been created with extensions returned by
168 * SDL_Vulkan_GetInstanceExtensions() enabled.
169 *
170 * If `allocator` is NULL, Vulkan will use the system default allocator. This
171 * argument is passed directly to Vulkan and isn't used by SDL itself.
172 *
173 * \param window the window to which to attach the Vulkan surface.
174 * \param instance the Vulkan instance handle.
175 * \param allocator a VkAllocationCallbacks struct, which lets the app set the
176 * allocator that creates the surface. Can be NULL.
177 * \param surface a pointer to a VkSurfaceKHR handle to output the newly
178 * created surface.
179 * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
180 * for more information.
181 *
182 * \since This function is available since SDL 3.0.0.
183 *
184 * \sa SDL_Vulkan_GetInstanceExtensions
185 * \sa SDL_Vulkan_DestroySurface
186 */
187extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
188 VkInstance instance,
189 const struct VkAllocationCallbacks *allocator,
190 VkSurfaceKHR* surface);
191
192/**
193 * Destroy the Vulkan rendering surface of a window.
194 *
195 * This should be called before SDL_DestroyWindow, if SDL_Vulkan_CreateSurface
196 * was called after SDL_CreateWindow.
197 *
198 * The `instance` must have been created with extensions returned by
199 * SDL_Vulkan_GetInstanceExtensions() enabled and `surface` must have been
200 * created successfully by an SDL_Vulkan_CreateSurface() call.
201 *
202 * If `allocator` is NULL, Vulkan will use the system default allocator. This
203 * argument is passed directly to Vulkan and isn't used by SDL itself.
204 *
205 * \param instance the Vulkan instance handle.
206 * \param surface vkSurfaceKHR handle to destroy.
207 * \param allocator a VkAllocationCallbacks struct, which lets the app set the
208 * allocator that destroys the surface. Can be NULL.
209 *
210 * \since This function is available since SDL 3.0.0.
211 *
212 * \sa SDL_Vulkan_GetInstanceExtensions
213 * \sa SDL_Vulkan_CreateSurface
214 */
215extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance,
216 VkSurfaceKHR surface,
217 const struct VkAllocationCallbacks *allocator);
218
219/**
220 * Query support for presentation via a given physical device and queue
221 * family.
222 *
223 * The `instance` must have been created with extensions returned by
224 * SDL_Vulkan_GetInstanceExtensions() enabled.
225 *
226 * \param instance the Vulkan instance handle.
227 * \param physicalDevice a valid Vulkan physical device handle.
228 * \param queueFamilyIndex a valid queue family index for the given physical
229 * device.
230 * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error
231 * occurred.
232 *
233 * \since This function is available since SDL 3.0.0.
234 *
235 * \sa SDL_Vulkan_GetInstanceExtensions
236 */
237extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance,
238 VkPhysicalDevice physicalDevice,
239 Uint32 queueFamilyIndex);
240
241/* @} *//* Vulkan support functions */
242
243/* Ends C function definitions when using C++ */
244#ifdef __cplusplus
245}
246#endif
247#include <SDL3/SDL_close_code.h>
248
249#endif /* SDL_vulkan_h_ */
void(* SDL_FunctionPointer)(void)
uint32_t Uint32
Definition SDL_stdinc.h:353
bool SDL_bool
Definition SDL_stdinc.h:301
struct SDL_Window SDL_Window
Definition SDL_video.h:144
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object)
Definition SDL_vulkan.h:51
SDL_FunctionPointer SDL_Vulkan_GetVkGetInstanceProcAddr(void)
SDL_bool SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex)
#define VK_DEFINE_HANDLE(object)
Definition SDL_vulkan.h:46
SDL_bool SDL_Vulkan_LoadLibrary(const char *path)
char const *const * SDL_Vulkan_GetInstanceExtensions(Uint32 *count)
void SDL_Vulkan_DestroySurface(VkInstance instance, VkSurfaceKHR surface, const struct VkAllocationCallbacks *allocator)
SDL_bool SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR *surface)
void SDL_Vulkan_UnloadLibrary(void)