SDL 2.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 * Header file for functions to creating Vulkan surfaces on SDL windows.
26 */
27
28#ifndef SDL_vulkan_h_
29#define SDL_vulkan_h_
30
31#include "SDL_video.h"
32
33#include "begin_code.h"
34/* Set up for C function definitions, even when using C++ */
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/* Avoid including vulkan.h, don't define VkInstance if it's already included */
40#ifdef VULKAN_H_
41#define NO_SDL_VULKAN_TYPEDEFS
42#endif
43#ifndef NO_SDL_VULKAN_TYPEDEFS
44#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
45
46#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
47#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
48#else
49#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
50#endif
51
52VK_DEFINE_HANDLE(VkInstance)
54
55/* Make sure to undef to avoid issues in case of later vulkan include */
56#undef VK_DEFINE_HANDLE
57#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE
58
59#endif /* !NO_SDL_VULKAN_TYPEDEFS */
60
61typedef VkInstance SDL_vulkanInstance;
62typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
63
64/**
65 * \name Vulkan support functions
66 *
67 * \note SDL_Vulkan_GetInstanceExtensions & SDL_Vulkan_CreateSurface API
68 * is compatable with Tizen's implementation of Vulkan in SDL.
69 */
70/* @{ */
71
72/**
73 * Dynamically load the Vulkan loader library.
74 *
75 * This should be called after initializing the video driver, but before
76 * creating any Vulkan windows. If no Vulkan loader library is loaded, the
77 * default library will be loaded upon creation of the first Vulkan window.
78 *
79 * It is fairly common for Vulkan applications to link with libvulkan instead
80 * of explicitly loading it at run time. This will work with SDL provided the
81 * application links to a dynamic library and both it and SDL use the same
82 * search path.
83 *
84 * If you specify a non-NULL `path`, an application should retrieve all of the
85 * Vulkan functions it uses from the dynamic library using
86 * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
87 * to the same vulkan loader library the application linked to.
88 *
89 * On Apple devices, if `path` is NULL, SDL will attempt to find the
90 * `vkGetInstanceProcAddr` address within all the Mach-O images of the current
91 * process. This is because it is fairly common for Vulkan applications to
92 * link with libvulkan (and historically MoltenVK was provided as a static
93 * library). If it is not found, on macOS, SDL will attempt to load
94 * `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
95 * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
96 * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
97 * dynamic framework or .dylib must ensure it is included in its application
98 * bundle.
99 *
100 * On non-Apple devices, application linking with a static libvulkan is not
101 * supported. Either do not link to the Vulkan loader or link to a dynamic
102 * library version.
103 *
104 * \param path The platform dependent Vulkan loader library name or NULL.
105 * \returns 0 on success or -1 if the library couldn't be loaded; call
106 * SDL_GetError() for more information.
107 *
108 * \since This function is available since SDL 2.0.6.
109 *
110 * \sa SDL_Vulkan_GetVkGetInstanceProcAddr
111 * \sa SDL_Vulkan_UnloadLibrary
112 */
113extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
114
115/**
116 * Get the address of the `vkGetInstanceProcAddr` function.
117 *
118 * This should be called after either calling SDL_Vulkan_LoadLibrary() or
119 * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
120 *
121 * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
122 *
123 * \since This function is available since SDL 2.0.6.
124 */
125extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
126
127/**
128 * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary()
129 *
130 * \since This function is available since SDL 2.0.6.
131 *
132 * \sa SDL_Vulkan_LoadLibrary
133 */
134extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
135
136/**
137 * Get the names of the Vulkan instance extensions needed to create a surface
138 * with SDL_Vulkan_CreateSurface.
139 *
140 * If `pNames` is NULL, then the number of required Vulkan instance extensions
141 * is returned in `pCount`. Otherwise, `pCount` must point to a variable set
142 * to the number of elements in the `pNames` array, and on return the variable
143 * is overwritten with the number of names actually written to `pNames`. If
144 * `pCount` is less than the number of required extensions, at most `pCount`
145 * structures will be written. If `pCount` is smaller than the number of
146 * required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
147 * indicate that not all the required extensions were returned.
148 *
149 * The `window` parameter is currently needed to be valid as of SDL 2.0.8,
150 * however, this parameter will likely be removed in future releases
151 *
152 * \param window A window for which the required Vulkan instance extensions
153 * should be retrieved (will be deprecated in a future release).
154 * \param pCount A pointer to an unsigned int corresponding to the number of
155 * extensions to be returned.
156 * \param pNames NULL or a pointer to an array to be filled with required
157 * Vulkan instance extensions.
158 * \returns SDL_TRUE on success, SDL_FALSE on error.
159 *
160 * \since This function is available since SDL 2.0.6.
161 *
162 * \sa SDL_Vulkan_CreateSurface
163 */
165 unsigned int *pCount,
166 const char **pNames);
167
168/**
169 * Create a Vulkan rendering surface for a window.
170 *
171 * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and
172 * `instance` must have been created with extensions returned by
173 * SDL_Vulkan_GetInstanceExtensions() enabled.
174 *
175 * \param window The window to which to attach the Vulkan surface.
176 * \param instance The Vulkan instance handle.
177 * \param surface A pointer to a VkSurfaceKHR handle to output the newly
178 * created surface.
179 * \returns SDL_TRUE on success, SDL_FALSE on error.
180 *
181 * \since This function is available since SDL 2.0.6.
182 *
183 * \sa SDL_Vulkan_GetInstanceExtensions
184 * \sa SDL_Vulkan_GetDrawableSize
185 */
186extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
187 VkInstance instance,
188 VkSurfaceKHR* surface);
189
190/**
191 * Get the size of the window's underlying drawable dimensions in pixels.
192 *
193 * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
194 * drawable, i.e. the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a
195 * platform with high-DPI support (Apple calls this "Retina"), and not
196 * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
197 *
198 * \param window an SDL_Window for which the size is to be queried.
199 * \param w Pointer to the variable to write the width to or NULL.
200 * \param h Pointer to the variable to write the height to or NULL.
201 *
202 * \since This function is available since SDL 2.0.6.
203 *
204 * \sa SDL_GetWindowSize
205 * \sa SDL_CreateWindow
206 * \sa SDL_Vulkan_CreateSurface
207 */
208extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
209 int *w, int *h);
210
211/* @} *//* Vulkan support functions */
212
213/* Ends C function definitions when using C++ */
214#ifdef __cplusplus
215}
216#endif
217#include "close_code.h"
218
219#endif /* SDL_vulkan_h_ */
SDL_bool
Definition SDL_stdinc.h:187
struct SDL_Window SDL_Window
Definition SDL_video.h:95
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object)
Definition SDL_vulkan.h:49
void SDL_Vulkan_GetDrawableSize(SDL_Window *window, int *w, int *h)
SDL_bool SDL_Vulkan_GetInstanceExtensions(SDL_Window *window, unsigned int *pCount, const char **pNames)
#define VK_DEFINE_HANDLE(object)
Definition SDL_vulkan.h:44
void * SDL_Vulkan_GetVkGetInstanceProcAddr(void)
int SDL_Vulkan_LoadLibrary(const char *path)
VkInstance SDL_vulkanInstance
Definition SDL_vulkan.h:61
VkSurfaceKHR SDL_vulkanSurface
Definition SDL_vulkan.h:62
SDL_bool SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, VkSurfaceKHR *surface)
void SDL_Vulkan_UnloadLibrary(void)