279 lines
10 KiB
C
279 lines
10 KiB
C
|
/*
|
||
|
|
Simple DirectMedia Layer
|
||
|
|
Copyright (C) 2017, Mark Callow
|
||
|
|
|
||
|
|
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.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \file SDL_vulkan.h
|
||
|
|
*
|
||
|
|
* Header file for functions to creating Vulkan surfaces on SDL windows.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef SDL_vulkan_h_
|
||
|
|
#define SDL_vulkan_h_
|
||
|
|
|
||
|
|
#include "SDL_video.h"
|
||
|
|
|
||
|
|
#include "begin_code.h"
|
||
|
|
/* Set up for C function definitions, even when using C++ */
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/* Avoid including vulkan.h, don't define VkInstance if it's already included */
|
||
|
|
#ifdef VULKAN_H_
|
||
|
|
#define NO_SDL_VULKAN_TYPEDEFS
|
||
|
|
#endif
|
||
|
|
#ifndef NO_SDL_VULKAN_TYPEDEFS
|
||
|
|
#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
|
||
|
|
|
||
|
|
#if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
|
||
|
|
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
|
||
|
|
#else
|
||
|
|
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
|
||
|
|
#endif
|
||
|
|
|
||
|
|
VK_DEFINE_HANDLE(VkInstance)
|
||
|
|
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
|
||
|
|
|
||
|
|
#endif /* !NO_SDL_VULKAN_TYPEDEFS */
|
||
|
|
|
||
|
|
typedef VkInstance SDL_vulkanInstance;
|
||
|
|
typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \name Vulkan support functions
|
||
|
|
*
|
||
|
|
* \note SDL_Vulkan_GetInstanceExtensions & SDL_Vulkan_CreateSurface API
|
||
|
|
* is compatable with Tizen's implementation of Vulkan in SDL.
|
||
|
|
*/
|
||
|
|
/* @{ */
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Dynamically load a Vulkan loader library.
|
||
|
|
*
|
||
|
|
* \param [in] path The platform dependent Vulkan loader library name, or
|
||
|
|
* \c NULL.
|
||
|
|
*
|
||
|
|
* \return \c 0 on success, or \c -1 if the library couldn't be loaded.
|
||
|
|
*
|
||
|
|
* If \a path is NULL SDL will use the value of the environment variable
|
||
|
|
* \c SDL_VULKAN_LIBRARY, if set, otherwise it loads the default Vulkan
|
||
|
|
* loader library.
|
||
|
|
*
|
||
|
|
* This should be called after initializing the video driver, but before
|
||
|
|
* creating any Vulkan windows. If no Vulkan loader library is loaded, the
|
||
|
|
* default library will be loaded upon creation of the first Vulkan window.
|
||
|
|
*
|
||
|
|
* \note It is fairly common for Vulkan applications to link with \a libvulkan
|
||
|
|
* instead of explicitly loading it at run time. This will work with
|
||
|
|
* SDL provided the application links to a dynamic library and both it
|
||
|
|
* and SDL use the same search path.
|
||
|
|
*
|
||
|
|
* \note If you specify a non-NULL \c path, an application should retrieve all
|
||
|
|
* of the Vulkan functions it uses from the dynamic library using
|
||
|
|
* \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
|
||
|
|
* \c path points to the same vulkan loader library the application
|
||
|
|
* linked to.
|
||
|
|
*
|
||
|
|
* \note On Apple devices, if \a path is NULL, SDL will attempt to find
|
||
|
|
* the vkGetInstanceProcAddr address within all the mach-o images of
|
||
|
|
* the current process. This is because it is fairly common for Vulkan
|
||
|
|
* applications to link with libvulkan (and historically MoltenVK was
|
||
|
|
* provided as a static library). If it is not found then, on macOS, SDL
|
||
|
|
* will attempt to load \c vulkan.framework/vulkan, \c libvulkan.1.dylib,
|
||
|
|
* followed by \c libvulkan.dylib, in that order.
|
||
|
|
* On iOS SDL will attempt to load \c libvulkan.dylib only. Applications
|
||
|
|
* using a dynamic framework or .dylib must ensure it is included in its
|
||
|
|
* application bundle.
|
||
|
|
*
|
||
|
|
* \note On non-Apple devices, application linking with a static libvulkan is
|
||
|
|
* not supported. Either do not link to the Vulkan loader or link to a
|
||
|
|
* dynamic library version.
|
||
|
|
*
|
||
|
|
* \note This function will fail if there are no working Vulkan drivers
|
||
|
|
* installed.
|
||
|
|
*
|
||
|
|
* \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
|
||
|
|
* \sa SDL_Vulkan_UnloadLibrary()
|
||
|
|
*/
|
||
|
|
extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Get the address of the \c vkGetInstanceProcAddr function.
|
||
|
|
*
|
||
|
|
* \note This should be called after either calling SDL_Vulkan_LoadLibrary
|
||
|
|
* or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
|
||
|
|
*/
|
||
|
|
extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Unload the Vulkan loader library previously loaded by
|
||
|
|
* \c SDL_Vulkan_LoadLibrary().
|
||
|
|
*
|
||
|
|
* \sa SDL_Vulkan_LoadLibrary()
|
||
|
|
*/
|
||
|
|
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Get the names of the Vulkan instance extensions needed to create
|
||
|
|
* a surface with \c SDL_Vulkan_CreateSurface().
|
||
|
|
*
|
||
|
|
* \param [in] \c NULL or window Window for which the required Vulkan instance
|
||
|
|
* extensions should be retrieved
|
||
|
|
* \param [in,out] pCount pointer to an \c unsigned related to the number of
|
||
|
|
* required Vulkan instance extensions
|
||
|
|
* \param [out] pNames \c NULL or a pointer to an array to be filled with the
|
||
|
|
* required Vulkan instance extensions
|
||
|
|
*
|
||
|
|
* \return \c SDL_TRUE on success, \c SDL_FALSE on error.
|
||
|
|
*
|
||
|
|
* If \a pNames is \c NULL, then the number of required Vulkan instance
|
||
|
|
* extensions is returned in pCount. Otherwise, \a pCount must point to a
|
||
|
|
* variable set to the number of elements in the \a pNames array, and on
|
||
|
|
* return the variable is overwritten with the number of names actually
|
||
|
|
* written to \a pNames. If \a pCount is less than the number of required
|
||
|
|
* extensions, at most \a pCount structures will be written. If \a pCount
|
||
|
|
* is smaller than the number of required extensions, \c SDL_FALSE will be
|
||
|
|
* returned instead of \c SDL_TRUE, to indicate that not all the required
|
||
|
|
* extensions were returned.
|
||
|
|
*
|
||
|
|
* \note If \c window is not NULL, it will be checked against its creation
|
||
|
|
* flags to ensure that the Vulkan flag is present. This parameter
|
||
|
|
* will be removed in a future major release.
|
||
|
|
*
|
||
|
|
* \note The returned list of extensions will contain \c VK_KHR_surface
|
||
|
|
* and zero or more platform specific extensions
|
||
|
|
*
|
||
|
|
* \note The extension names queried here must be enabled when calling
|
||
|
|
* VkCreateInstance, otherwise surface creation will fail.
|
||
|
|
*
|
||
|
|
* \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag
|
||
|
|
* or be \c NULL
|
||
|
|
*
|
||
|
|
* \code
|
||
|
|
* unsigned int count;
|
||
|
|
* // get count of required extensions
|
||
|
|
* if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
|
||
|
|
* handle_error();
|
||
|
|
*
|
||
|
|
* static const char *const additionalExtensions[] =
|
||
|
|
* {
|
||
|
|
* VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
|
||
|
|
* };
|
||
|
|
* size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
|
||
|
|
* size_t extensionCount = count + additionalExtensionsCount;
|
||
|
|
* const char **names = malloc(sizeof(const char *) * extensionCount);
|
||
|
|
* if(!names)
|
||
|
|
* handle_error();
|
||
|
|
*
|
||
|
|
* // get names of required extensions
|
||
|
|
* if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, names))
|
||
|
|
* handle_error();
|
||
|
|
*
|
||
|
|
* // copy additional extensions after required extensions
|
||
|
|
* for(size_t i = 0; i < additionalExtensionsCount; i++)
|
||
|
|
* names[i + count] = additionalExtensions[i];
|
||
|
|
*
|
||
|
|
* VkInstanceCreateInfo instanceCreateInfo = {};
|
||
|
|
* instanceCreateInfo.enabledExtensionCount = extensionCount;
|
||
|
|
* instanceCreateInfo.ppEnabledExtensionNames = names;
|
||
|
|
* // fill in rest of instanceCreateInfo
|
||
|
|
*
|
||
|
|
* VkInstance instance;
|
||
|
|
* // create the Vulkan instance
|
||
|
|
* VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
|
||
|
|
* free(names);
|
||
|
|
* \endcode
|
||
|
|
*
|
||
|
|
* \sa SDL_Vulkan_CreateSurface()
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(
|
||
|
|
SDL_Window *window,
|
||
|
|
unsigned int *pCount,
|
||
|
|
const char **pNames);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Create a Vulkan rendering surface for a window.
|
||
|
|
*
|
||
|
|
* \param [in] window SDL_Window to which to attach the rendering surface.
|
||
|
|
* \param [in] instance handle to the Vulkan instance to use.
|
||
|
|
* \param [out] surface pointer to a VkSurfaceKHR handle to receive the
|
||
|
|
* handle of the newly created surface.
|
||
|
|
*
|
||
|
|
* \return \c SDL_TRUE on success, \c SDL_FALSE on error.
|
||
|
|
*
|
||
|
|
* \code
|
||
|
|
* VkInstance instance;
|
||
|
|
* SDL_Window *window;
|
||
|
|
*
|
||
|
|
* // create instance and window
|
||
|
|
*
|
||
|
|
* // create the Vulkan surface
|
||
|
|
* VkSurfaceKHR surface;
|
||
|
|
* if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
|
||
|
|
* handle_error();
|
||
|
|
* \endcode
|
||
|
|
*
|
||
|
|
* \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
|
||
|
|
*
|
||
|
|
* \note \a instance should have been created with the extensions returned
|
||
|
|
* by \c SDL_Vulkan_CreateSurface() enabled.
|
||
|
|
*
|
||
|
|
* \sa SDL_Vulkan_GetInstanceExtensions()
|
||
|
|
*/
|
||
|
|
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(
|
||
|
|
SDL_Window *window,
|
||
|
|
VkInstance instance,
|
||
|
|
VkSurfaceKHR* surface);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* \brief Get the size of a window's underlying drawable in pixels (for use
|
||
|
|
* with setting viewport, scissor & etc).
|
||
|
|
*
|
||
|
|
* \param window SDL_Window from which the drawable size should be queried
|
||
|
|
* \param w Pointer to variable for storing the width in pixels,
|
||
|
|
* may be NULL
|
||
|
|
* \param h Pointer to variable for storing the height in pixels,
|
||
|
|
* may be NULL
|
||
|
|
*
|
||
|
|
* This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
|
||
|
|
* drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
|
||
|
|
* platform with high-DPI support (Apple calls this "Retina"), and not disabled
|
||
|
|
* by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
|
||
|
|
*
|
||
|
|
* \note On macOS high-DPI support must be enabled for an application by
|
||
|
|
* setting NSHighResolutionCapable to true in its Info.plist.
|
||
|
|
*
|
||
|
|
* \sa SDL_GetWindowSize()
|
||
|
|
* \sa SDL_CreateWindow()
|
||
|
|
*/
|
||
|
|
extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
|
||
|
|
int *w, int *h);
|
||
|
|
|
||
|
|
/* @} *//* Vulkan support functions */
|
||
|
|
|
||
|
|
/* Ends C function definitions when using C++ */
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
#include "close_code.h"
|
||
|
|
|
||
|
|
#endif /* SDL_vulkan_h_ */
|