aux/vk: Docs for Vulkan native import helpers.

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