Merge cherrypicks of [1234511] into android-games-sdk-releaseandroid-games-sdk-unity-releaseandroid-games-sdk-unity-dev

Change-Id: I0e08547a73baf7d14f6172d98703e93be654a191

2 files changed, 59 insertions, 18 deletions

diff --git a/include/swappy/swappyVk.h b/include/swappy/swappyVk.h
index dbb42db3..1be8d0bb 100644
--- a/include/swappy/swappyVk.h
+++ b/include/swappy/swappyVk.h
@@ -256,28 +256,51 @@ uint64_t SwappyVk_getFenceTimeoutNS();
 void SwappyVk_injectTracer(const SwappyTracer *tracer);
 
 /**
- * A structure to enable you to provide your own Vulkan function wrappers.
+ * @brief A structure enabling you to provide your own Vulkan function wrappers
+ * by calling ::SwappyVk_setFunctionProvider.
+ *
+ * Usage of this functionality is optional.
  */
-struct SwappyVkFunctionProvider {
-    // Called before any functions are requested. E.g. so you can call dlopen on
-    // the Vulkan library.
+typedef struct SwappyVkFunctionProvider {
+    /**
+     * @brief Callback to initialize the function provider.
+     *
+     * This function is called by Swappy before any functions are requested. E.g. so you can
+     * call dlopen on the Vulkan library.
+     */
     bool (*init)();
-    // Called to get the address of a Vulkan function.
+
+    /**
+     * @brief Callback to get the address of a function.
+     *
+     * This function is called by Swappy to get the address of a Vulkan function.
+     * @param name The null-terminated name of the function.
+     */
     void* (*getProcAddr)(const char* name);
-    // Called when no more functions will be requested, e.g. so you can call
-    // dlclose on the Vulkan library.
+
+    /**
+     * @brief Callback to close any resources owned by the function provider.
+     * 
+     * This function is called by Swappy when no more functions will be requested,
+     * e.g. so you can call dlclose on the Vulkan library.
+     */
     void (*close)();
-};
+} SwappyVkFunctionProvider;
 
 /**
  * @brief Set the Vulkan function provider.
  *
- * This enables you to provide an object that will be used to look up Vulkan functions.
+ * This enables you to provide an object that will be used to look up Vulkan functions, e.g. to
+ * hook usage of these functions.
+ *
  * To use this functionality, you *must* call this function before any others.
+ * 
+ * Usage of this function is entirely optional. If you do not use it, the Vulkan functions required
+ * by Swappy will be dynamically loaded from libvulkan.so.
  *
  * @param[in] provider - provider object
  */
-void SwappyVk_setFunctionProvider(const struct SwappyVkFunctionProvider* pSwappyVkFunctionProvider);
+void SwappyVk_setFunctionProvider(const SwappyVkFunctionProvider* pSwappyVkFunctionProvider);
 
 #ifdef __cplusplus
 }  // extern "C"
diff --git a/include/swappy/swappy_common.h b/include/swappy/swappy_common.h
index 455b2a72..b29e815b 100644
--- a/include/swappy/swappy_common.h
+++ b/include/swappy/swappy_common.h
@@ -47,24 +47,37 @@
 #define SWAPPY_VERSION_CONCAT(PREFIX, MAJOR, MINOR) SWAPPY_VERSION_CONCAT_NX(PREFIX, MAJOR, MINOR)
 #define SWAPPY_VERSION_SYMBOL SWAPPY_VERSION_CONCAT(Swappy_version, SWAPPY_MAJOR_VERSION, SWAPPY_MINOR_VERSION)
 
+/** @endcond */
+
 /** @brief Id of a thread returned by an external thread manager. */
 typedef uint64_t SwappyThreadId;
 
 /**
- * @brief Thread management functions.
+ * @brief A structure enabling you to set how Swappy starts and joins threads by calling
+ * ::Swappy_setThreadFunctions.
+ *
+ * Usage of this functionality is optional.
  */
 typedef struct SwappyThreadFunctions {
-    /**
-     * Called to start thread_func on a new thread with the single argument given.
-     * Should return 0 if the thread was started and also set the thread_id.
+    /** @brief Thread start callback.
+     *
+     * This function is called by Swappy to start thread_func on a new thread.
+     * @param user_data A value to be passed the thread function.
+     * If the thread was started, this function should set the thread_id and return 0.
+     * If the thread was not started, this function should return a non-zero value.
      */
     int (*start)(SwappyThreadId* thread_id, void *(*thread_func)(void*), void* user_data);
-    /**
-     * Called to join the thread with given id.
+
+    /** @brief Thread join callback.
+     *
+     * This function is called by Swappy to join the thread with given id.
      */
     void (*join)(SwappyThreadId thread_id);
-    /**
-     * Return whether the thread with the given id is joinable.
+
+    /** @brief Thread joinable callback.
+     *
+     * This function is called by Swappy to discover whether the thread with the given id
+     * is joinable.
      */
     bool (*joinable)(SwappyThreadId thread_id);
 } SwappyThreadFunctions;
@@ -73,6 +86,8 @@ typedef struct SwappyThreadFunctions {
 extern "C" {
 #endif
 
+/** @cond INTERNAL */
+
 // Internal function to track Swappy version bundled in a binary. Do not call directly.
 // If you are getting linker errors related to Swappy_version_x_y, you probably have a
 // mismatch between the header used at compilation and the actually library used by the linker.
@@ -87,6 +102,9 @@ uint32_t Swappy_version();
 
 /**
  * @brief Call this before any other functions in order to use a custom thread manager.
+ *
+ * Usage of this function is entirely optional. Swappy uses std::thread by default.
+ *
  */
 void Swappy_setThreadFunctions(const SwappyThreadFunctions* thread_functions);