SDL_vulkan.h: Improve SDL_Vulkan_LoadLibrary/SDL_Vulkan_UnloadLibrary docs.

Fixes #9541.

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