include/SDL_vulkan.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 27 Aug 2017 22:27:45 -0700
changeset 11373 1a70b29cbb7b
parent 11365 a9bd2625fa01
child 11376 91e5e5a2cb71
permissions -rw-r--r--
Don't define Vulkan types if vulkan.h has already been included
     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 */
    40 #ifndef VULKAN_H_
    41 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
    42 
    43 #if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
    44 #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
    45 #else
    46 #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
    47 #endif
    48 
    49 VK_DEFINE_HANDLE(VkInstance)
    50 VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
    51 
    52 #endif /* !VULKAN_H_ */
    53 
    54 typedef VkInstance SDL_vulkanInstance;
    55 typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
    56 
    57 /**
    58  *  \name Vulkan support functions
    59  *
    60  *  \note SDL_Vulkan_GetInstanceExtensions & SDL_Vulkan_CreateSurface API
    61  *        is compatable with Tizen's implementation of Vulkan in SDL.
    62  */
    63 /* @{ */
    64 
    65 /**
    66  *  \brief Dynamically load a Vulkan loader library.
    67  *
    68  *  \param [in] path The platform dependent Vulkan loader library name, or
    69  *              \c NULL to open the default Vulkan loader library.
    70  *
    71  *  \return \c 0 on success, or \c -1 if the library couldn't be loaded.
    72  *
    73  *  This should be done after initializing the video driver, but before
    74  *  creating any Vulkan windows. If no Vulkan loader library is loaded, the
    75  *  default library will be loaded upon creation of the first Vulkan window.
    76  *
    77  *  \note If you specify a non-NULL \a path, you should retrieve all of the
    78  *        Vulkan functions used in your program from the dynamic library using
    79  *        \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
    80  *        \a path points to the same vulkan loader library that you linked to.
    81  *
    82  *  \note On Apple devices, if \a path is NULL, SDL will attempt to find
    83  *        the vkGetInstanceProcAddr address within all the mach-o images of
    84  *        the current process. This is because the currently (v0.17.0)
    85  *        recommended MoltenVK (Vulkan on Metal) usage is as a static library.
    86  *        If it is not found then SDL will attempt to load \c libMoltenVK.dylib.
    87  *        Applications using the dylib alternative therefore do not need to do
    88  *        anything special when calling SDL.
    89  *
    90  *  \note On non-Apple devices, SDL requires you to either not link to the
    91  *        Vulkan loader or link to a dynamic library version. This limitation
    92  *        may be removed in a future version of SDL.
    93  *
    94  *  \note This function will fail if there are no working Vulkan drivers
    95  *        installed.
    96  *
    97  *  \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
    98  *  \sa SDL_Vulkan_UnloadLibrary()
    99  */
   100 extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
   101 
   102 /**
   103  *  \brief Get the address of the \c vkGetInstanceProcAddr function.
   104  *
   105  *  \note This should be called after either calling SDL_Vulkan_LoadLibrary
   106  *        or creating an SDL_Window with the SDL_WINDOW_VULKAN flag.
   107  */
   108 extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
   109 
   110 /**
   111  *  \brief Unload the Vulkan loader library previously loaded by
   112  *         \c SDL_Vulkan_LoadLibrary().
   113  *
   114  *  \sa SDL_Vulkan_LoadLibrary()
   115  */
   116 extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
   117 
   118 /**
   119  *  \brief Get the names of the Vulkan instance extensions needed to create
   120  *         a surface with \c SDL_Vulkan_CreateSurface().
   121  *
   122  *  \param [in]     window Window for which the required Vulkan instance
   123  *                  extensions should be retrieved
   124  *  \param [in,out] count pointer to an \c unsigned related to the number of
   125  *                  required Vulkan instance extensions
   126  *  \param [out]    names \c NULL or a pointer to an array to be filled with the
   127  *                  required Vulkan instance extensions
   128  *
   129  *  \return \c SDL_TRUE on success, \c SDL_FALSE on error.
   130  *
   131  *  If \a pNames is \c NULL, then the number of required Vulkan instance
   132  *  extensions is returned in pCount. Otherwise, \a pCount must point to a
   133  *  variable set to the number of elements in the \a pNames array, and on
   134  *  return the variable is overwritten with the number of names actually
   135  *  written to \a pNames. If \a pCount is less than the number of required
   136  *  extensions, at most \a pCount structures will be written. If \a pCount
   137  *  is smaller than the number of required extensions, \c SDL_FALSE will be
   138  *  returned instead of \c SDL_TRUE, to indicate that not all the required
   139  *  extensions were returned.
   140  *
   141  *  \note The returned list of extensions will contain \c VK_KHR_surface
   142  *        and zero or more platform specific extensions
   143  *
   144  *  \note The extension names queried here must be enabled when calling
   145  *        VkCreateInstance, otherwise surface creation will fail.
   146  *
   147  *  \note \c window should have been created with the \c SDL_WINDOW_VULKAN flag.
   148  *
   149  *  \code
   150  *  unsigned count;
   151  *  // get count of required extensions
   152  *  if(!SDL_Vulkan_GetInstanceExtensions(window, &count, NULL))
   153  *      handle_error();
   154  *
   155  *  static const char *const additionalExtensions[] =
   156  *  {
   157  *      VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
   158  *  };
   159  *  size_t additionalExtensionsCount = sizeof(additionalExtensions) / sizeof(additionalExtensions[0]);
   160  *  size_t extensionCount = count + additionalExtensionsCount;
   161  *  const char **names = malloc(sizeof(const char *) * extensionCount);
   162  *  if(!names)
   163  *      handle_error();
   164  *
   165  *  // get names of required extensions
   166  *  if(!SDL_Vulkan_GetInstanceExtensions(window, &count, names))
   167  *      handle_error();
   168  *
   169  *  // copy additional extensions after required extensions
   170  *  for(size_t i = 0; i < additionalExtensionsCount; i++)
   171  *      names[i + count] = additionalExtensions[i];
   172  *
   173  *  VkInstanceCreateInfo instanceCreateInfo = {};
   174  *  instanceCreateInfo.enabledExtensionCount = extensionCount;
   175  *  instanceCreateInfo.ppEnabledExtensionNames = names;
   176  *  // fill in rest of instanceCreateInfo
   177  *
   178  *  VkInstance instance;
   179  *  // create the Vulkan instance
   180  *  VkResult result = vkCreateInstance(&instanceCreateInfo, NULL, &instance);
   181  *  free(names);
   182  *  \endcode
   183  *
   184  *  \sa SDL_Vulkan_CreateSurface()
   185  */
   186 extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(
   187 														SDL_Window *window,
   188 														unsigned *pCount,
   189 														const char **pNames);
   190 
   191 /**
   192  *  \brief Create a Vulkan rendering surface for a window.
   193  *
   194  *  \param [in]  window   SDL_Window to which to attach the rendering surface.
   195  *  \param [in]  instance handle to the Vulkan instance to use.
   196  *  \param [out] surface  pointer to a VkSurfaceKHR handle to receive the
   197  *                        handle of the newly created surface.
   198  *
   199  *  \return \c SDL_TRUE on success, \c SDL_FALSE on error.
   200  *
   201  *  \code
   202  *  VkInstance instance;
   203  *  SDL_Window *window;
   204  *
   205  *  // create instance and window
   206  *
   207  *  // create the Vulkan surface
   208  *  VkSurfaceKHR surface;
   209  *  if(!SDL_Vulkan_CreateSurface(window, instance, &surface))
   210  *      handle_error();
   211  *  \endcode
   212  *
   213  *  \note \a window should have been created with the \c SDL_WINDOW_VULKAN flag.
   214  *
   215  *  \note \a instance should have been created with the extensions returned
   216  *        by \c SDL_Vulkan_CreateSurface() enabled.
   217  *
   218  *  \sa SDL_Vulkan_GetInstanceExtensions()
   219  */
   220 extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(
   221 												SDL_Window *window,
   222 												VkInstance instance,
   223 												VkSurfaceKHR* surface);
   224 
   225 /**
   226  *  \brief Get the size of a window's underlying drawable in pixels (for use
   227  *         with setting viewport, scissor & etc).
   228  *
   229  *  \param window   SDL_Window from which the drawable size should be queried
   230  *  \param w        Pointer to variable for storing the width in pixels,
   231  *                  may be NULL
   232  *  \param h        Pointer to variable for storing the height in pixels,
   233  *                  may be NULL
   234  *
   235  * This may differ from SDL_GetWindowSize() if we're rendering to a high-DPI
   236  * drawable, i.e. the window was created with SDL_WINDOW_ALLOW_HIGHDPI on a
   237  * platform with high-DPI support (Apple calls this "Retina"), and not disabled
   238  * by the \c SDL_HINT_VIDEO_HIGHDPI_DISABLED hint.
   239  *
   240  *  \sa SDL_GetWindowSize()
   241  *  \sa SDL_CreateWindow()
   242  */
   243 extern DECLSPEC void SDLCALL SDL_Vulkan_GetDrawableSize(SDL_Window * window,
   244                                                         int *w, int *h);
   245 
   246 /* @} *//* Vulkan support functions */
   247 
   248 /* Ends C function definitions when using C++ */
   249 #ifdef __cplusplus
   250 }
   251 #endif
   252 #include "close_code.h"
   253 
   254 #endif /* SDL_vulkan_h_ */