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