From cf08cbba78ff51b51622f575a2bed4b8528ad196 Mon Sep 17 00:00:00 2001
From: Ryan Pavlik <ryan.pavlik@collabora.com>
Date: Tue, 6 Apr 2021 17:56:49 -0500
Subject: [PATCH] aux/vk: Docs for Vulkan native import helpers.

---
 src/xrt/auxiliary/vk/vk_helpers.h | 39 +++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/src/xrt/auxiliary/vk/vk_helpers.h b/src/xrt/auxiliary/vk/vk_helpers.h
index 43941f57a..77c8d6b40 100644
--- a/src/xrt/auxiliary/vk/vk_helpers.h
+++ b/src/xrt/auxiliary/vk/vk_helpers.h
@@ -430,6 +430,24 @@ vk_alloc_and_bind_image_memory(struct vk_bundle *vk,
                                VkDeviceSize *out_size);
 
 /*!
+ *
+ * @brief Creates a Vulkan device memory and image from a native graphics buffer handle.
+ *
+ * In case of error, ownership is never transferred and the caller should close the handle themselves.
+ *
+ * In case of success, the underlying Vulkan functionality's ownership semantics apply: ownership of the @p image_native
+ * handle may have transferred, a reference may have been added, or the Vulkan objects may rely on the caller to keep
+ * the native handle alive until the Vulkan objects are destroyed. Which option applies depends on the particular native
+ * handle type used.
+ *
+ * See the corresponding specification texts:
+ *
+ * - Windows:
+ *   https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VkImportMemoryWin32HandleInfoKHR
+ * - Linux: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VkImportMemoryFdInfoKHR
+ * - Android:
+ *   https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VkImportAndroidHardwareBufferInfoANDROID
+ *
  * @ingroup aux_vk
  */
 VkResult
@@ -440,12 +458,33 @@ vk_create_image_from_native(struct vk_bundle *vk,
                             VkDeviceMemory *out_mem);
 
 /*!
+ * @brief Creates a Vulkan fence from a native graphics sync handle.
+ *
+ * In case of error, ownership is never transferred and the caller should close the handle themselves.
+ *
+ * In case of success, the underlying Vulkan functionality's ownership semantics apply: ownership of the @p native
+ * handle may have transferred, a reference may have been added, or the Vulkan object may rely on the caller to keep the
+ * native handle alive until the Vulkan object is destroyed. Which option applies depends on the particular native
+ * handle type used.
+ *
+ * See the corresponding Vulkan specification text:
+ * https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#synchronization-fences-importing
+ *
  * @ingroup aux_vk
  */
 VkResult
 vk_create_fence_sync_from_native(struct vk_bundle *vk, xrt_graphics_sync_handle_t native, VkFence *out_fence);
 
 /*!
+ * @brief Creates a Vulkan semaphore from a native graphics sync handle.
+ *
+ * In case of error, ownership is never transferred and the caller should close the handle themselves.
+ *
+ * In case of success, the underlying Vulkan functionality's ownership semantics apply: ownership of the @p native
+ * handle may have transferred, a reference may have been added, or the Vulkan object may rely on the caller to keep the
+ * native handle alive until the Vulkan object is destroyed. Which option applies depends on the particular native
+ * handle type used.
+ *
  * @ingroup aux_vk
  */
 VkResult