WebSVN – Games.Prince of Persia – Diff – /SDL2.framework/Headers/SDL_vulkan.h

 /**
  *  \brief Dynamically load a Vulkan loader library.
+ *
  *  \param [in] path The platform dependent Vulkan loader library name, or
- *              \c NULL to open the default Vulkan loader library.
+ *              \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 done after initializing the video driver, but before
+ *  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 \a path, you should retrieve all of the
+ *  \note If you specify a non-NULL \c path, an application should retrieve all
- *        Vulkan functions used in your program from the dynamic library using
+ *        of the Vulkan functions it uses from the dynamic library using
  *        \c SDL_Vulkan_GetVkGetInstanceProcAddr() unless you can guarantee
- *        \a path points to the same vulkan loader library that you linked to.
+ *        \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 the currently (v0.17.0)
+ *        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,
- *        recommended MoltenVK (Vulkan on Metal) usage is as a static library.
+ *        \c MoltenVK.framework/MoltenVK and \c libMoltenVK.dylib in that order.
- *        If it is not found then SDL will attempt to load \c libMoltenVK.dylib.
+ *        On iOS SDL will attempt to load \c libMoltenVK.dylib. Applications
- *        Applications using the dylib alternative therefore do not need to do
+ *        using a dynamic framework or .dylib must ensure it is included in its
- *        anything special when calling SDL.
+ *        application bundle.
+ *
- *  \note On non-Apple devices, SDL requires you to either not link to the
+ *  \note On non-Apple devices, application linking with a static libvulkan is
- *        Vulkan loader or link to a dynamic library version. This limitation
+ *        not supported. Either do not link to the Vulkan loader or link to a
- *        may be removed in a future version of SDL.
+ *        dynamic library version.
+ *
  *  \note This function will fail if there are no working Vulkan drivers
  *        installed.
+ *
  *  \sa SDL_Vulkan_GetVkGetInstanceProcAddr()
 /**
  *  \brief Get the names of the Vulkan instance extensions needed to create
  *         a surface with \c SDL_Vulkan_CreateSurface().
+ *
- *  \param [in]     window Window for which the required Vulkan instance
+ *  \param [in]     \c NULL or window Window for which the required Vulkan instance
  *                  extensions should be retrieved
- *  \param [in,out] count pointer to an \c unsigned related to the number of
+ *  \param [in,out] pCount pointer to an \c unsigned related to the number of
  *                  required Vulkan instance extensions
- *  \param [out]    names \c NULL or a pointer to an array to be filled with the
+ *  \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
  *  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.
+ *  \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(window, &count, NULL))
+ *  if(!SDL_Vulkan_GetInstanceExtensions(NULL, &count, NULL))
  *      handle_error();
+ *
  *  static const char *const additionalExtensions[] =
  *  {
  *      VK_EXT_DEBUG_REPORT_EXTENSION_NAME, // example additional extension
  *  const char **names = malloc(sizeof(const char *) * extensionCount);
  *  if(!names)
  *      handle_error();
+ *
  *  // get names of required extensions
- *  if(!SDL_Vulkan_GetInstanceExtensions(window, &count, names))
+ *  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];
+ *
  * 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,

Subversion Repositories Games.Prince of Persia

Games.Prince of Persia/SDL2.framework/Headers/SDL_vulkan.h – Rev 1 → 8