From 18c6958cae8ada93efd67057e4fe8443dd3eaf13 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sat, 4 Jan 2025 03:22:34 -0500
Subject: [PATCH] SDL_vulkan.h: Improve
SDL_Vulkan_LoadLibrary/SDL_Vulkan_UnloadLibrary docs.
Fixes #9541.
---
include/SDL3/SDL_vulkan.h | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h
index 1ce0e34c65bdc..a749a99c02dcb 100644
--- a/include/SDL3/SDL_vulkan.h
+++ b/include/SDL3/SDL_vulkan.h
@@ -87,6 +87,14 @@ struct VkAllocationCallbacks;
* creating any Vulkan windows. If no Vulkan loader library is loaded, the
* default library will be loaded upon creation of the first Vulkan window.
*
+ * SDL keeps a counter of how many times this function has been successfully
+ * called, so it is safe to call this function multiple times, so long as it
+ * is eventually paired with an equivalent number of calls to
+ * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is
+ * no library currently loaded, and and the library isn't actually unloaded
+ * until there have been an equivalent number of calls to
+ * SDL_Vulkan_UnloadLibrary.
+ *
* It is fairly common for Vulkan applications to link with 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
@@ -116,6 +124,8 @@ struct VkAllocationCallbacks;
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function is not thread safe.
+ *
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_Vulkan_GetVkGetInstanceProcAddr
@@ -147,6 +157,19 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcA
/**
* Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary().
*
+ * SDL keeps a counter of how many times this function has been called, so it
+ * is safe to call this function multiple times, so long as it is paired with
+ * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't
+ * actually unloaded until there have been an equivalent number of calls to
+ * SDL_Vulkan_UnloadLibrary.
+ *
+ * Once the library has actually been unloaded, if any Vulkan instances
+ * remain, they will likely crash the program. Clean up any existing Vulkan
+ * resources, and destroy appropriate windows, renderers and GPU devices
+ * before calling this function.
+ *
+ * \threadsafety This function is not thread safe.
+ *
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_Vulkan_LoadLibrary