Mesa (main): vulkan,docs: Document vk_device

[GitLab Mirror]

Module: Mesa
Branch: main
Commit: dd340ce1a1f3f899d26dfe827a9624365ada7804
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=dd340ce1a1f3f899d26dfe827a9624365ada7804

Author: Jason Ekstrand <jason.ekstrand at collabora.com>
Date:   Tue Mar 22 17:20:06 2022 -0500

vulkan,docs: Document vk_device

Acked-by: Iago Toral Quiroga <itoral at igalia.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/15472>

---

 docs/vulkan/base-objs.rst      |  9 +++++++++
 src/vulkan/runtime/vk_device.h | 25 ++++++++++++++++++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/vulkan/base-objs.rst b/docs/vulkan/base-objs.rst
index b16a2f76f70..b3ba9bde880 100644
--- a/docs/vulkan/base-objs.rst
+++ b/docs/vulkan/base-objs.rst
@@ -173,3 +173,12 @@ vk_physical_device
 
 .. doxygenfunction:: vk_physical_device_init
 .. doxygenfunction:: vk_physical_device_finish
+
+vk_device
+------------------
+
+.. doxygenstruct:: vk_device
+   :members:
+
+.. doxygenfunction:: vk_device_init
+.. doxygenfunction:: vk_device_finish
diff --git a/src/vulkan/runtime/vk_device.h b/src/vulkan/runtime/vk_device.h
index d1dc154ac8c..b45501c2ad8 100644
--- a/src/vulkan/runtime/vk_device.h
+++ b/src/vulkan/runtime/vk_device.h
@@ -254,8 +254,27 @@ struct vk_device {
 };
 
 VK_DEFINE_HANDLE_CASTS(vk_device, base, VkDevice,
-                       VK_OBJECT_TYPE_DEVICE)
+                       VK_OBJECT_TYPE_DEVICE);
 
+/** Initialize a vk_device
+ *
+ * Along with initializing the data structures in `vk_device`, this function
+ * checks that every extension specified by
+ * `VkInstanceCreateInfo::ppEnabledExtensionNames` is actually supported by
+ * the physical device and returns `VK_ERROR_EXTENSION_NOT_PRESENT` if an
+ * unsupported extension is requested.  It also checks all the feature struct
+ * chained into the `pCreateInfo->pNext` chain against the features returned
+ * by `vkGetPhysicalDeviceFeatures2` and returns
+ * `VK_ERROR_FEATURE_NOT_PRESENT` if an unsupported feature is requested.
+ *
+ * @param[out] device               The device to initialize
+ * @param[in]  physical_device      The physical device
+ * @param[in]  dispatch_table       Device-level dispatch table
+ * @param[in]  pCreateInfo          VkDeviceCreateInfo pointer passed to
+ *                                  `vkCreateDevice()`
+ * @param[in]  alloc                Allocation callbacks passed to
+ *                                  `vkCreateDevice()`
+ */
 VkResult MUST_CHECK
 vk_device_init(struct vk_device *device,
                struct vk_physical_device *physical_device,
@@ -269,6 +288,10 @@ vk_device_set_drm_fd(struct vk_device *device, int drm_fd)
    device->drm_fd = drm_fd;
 }
 
+/** Tears down a vk_device
+ *
+ * @param[out] device               The device to tear down
+ */
 void
 vk_device_finish(struct vk_device *device);