Sync wiki -> header.

This commit is contained in:
Ryan C. Gordon 2021-07-14 17:07:04 -04:00
parent f8c1fc49d9
commit c88eb7a896
No known key found for this signature in database
GPG key ID: FA148B892AB48044
31 changed files with 635 additions and 654 deletions

View file

@ -77,21 +77,21 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
* application links to a dynamic library and both it and SDL use the same
* search path.
*
* If you specify a non-NULL `path`, an application should retrieve
* all of the Vulkan functions it uses from the dynamic library using
* SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path`
* points to the same vulkan loader library the application linked to.
* If you specify a non-NULL `path`, an application should retrieve all of the
* Vulkan functions it uses from the dynamic library using
* SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points
* to the same vulkan loader library the application linked to.
*
* On Apple devices, if `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, on macOS, SDL will attempt
* to load `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
* `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that
* order. On iOS, SDL will attempt to load `libMoltenVK.dylib`.
* Applications using a dynamic framework or .dylib must ensure it is included
* in its application bundle.
* `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, on macOS, SDL will attempt to load
* `vulkan.framework/vulkan`, `libvulkan.1.dylib`,
* `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On
* iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a
* dynamic framework or .dylib must ensure it is included in its application
* bundle.
*
* 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
@ -111,8 +111,8 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
/**
* Get the address of the `vkGetInstanceProcAddr` function.
*
* This should be called after either calling SDL_Vulkan_LoadLibrary()
* or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
* This should be called after either calling SDL_Vulkan_LoadLibrary() or
* creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
*
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
*/
@ -128,29 +128,27 @@ extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
/**
* Get the names of the Vulkan instance extensions needed
* to create a surface with SDL_Vulkan_CreateSurface.
* Get the names of the Vulkan instance extensions needed to create a surface
* with SDL_Vulkan_CreateSurface.
*
* If `pNames` is NULL, then the number of required Vulkan instance
* extensions is returned in `pCount`. Otherwise, `pCount` must point
* to a variable set to the number of elements in the `pNames` array, and
* on return the variable is overwritten with the number of names actually
* written to `pNames`. If `pCount` is less than the number of
* required extensions, at most `pCount` structures will be written. If
* `pCount` is smaller than the number of required extensions,
* SDL_FALSE will be returned instead of SDL_TRUE, to indicate
* that not all the required extensions were returned.
* If `pNames` is NULL, then the number of required Vulkan instance extensions
* is returned in `pCount`. Otherwise, `pCount` must point to a variable set
* to the number of elements in the `pNames` array, and on return the variable
* is overwritten with the number of names actually written to `pNames`. If
* `pCount` is less than the number of required extensions, at most `pCount`
* structures will be written. If `pCount` is smaller than the number of
* required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
* indicate that not all the required extensions were returned.
*
* The `window` parameter is currently needed to be valid as of
* SDL 2.0.8, however, this parameter will likely be removed in future
* releases
* The `window` parameter is currently needed to be valid as of SDL 2.0.8,
* however, this parameter will likely be removed in future releases
*
* \param window A window for which the required Vulkan instance extensions
* should be retrieved (will be deprecated in a future release)
* \param pCount A pointer to an unsigned int corresponding to the
* number of extensions to be returned
* \param pCount A pointer to an unsigned int corresponding to the number of
* extensions to be returned
* \param pNames NULL or a pointer to an array to be filled with required
* Vulkan instance extensions
* Vulkan instance extensions
* \returns SDL_TRUE on success, SDL_FALSE on error.
*
* \since This function is available in SDL 2.0.8
@ -187,8 +185,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
* Get the size of the window's underlying drawable dimensions in pixels.
*
* 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
* 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 `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint.
*
* \param window an SDL_Window for which the size is to be queried