vulkan,docs: Document vk_object_base

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

src/vulkan/runtime/vk_object.h

@@ -38,10 +38,23 @@ struct hash_table;
 
 struct vk_device;
 
+/** Base struct for all Vulkan objects */
 struct vk_object_base {
    VK_LOADER_DATA _loader_data;
+
+   /** Type of this object
+    *
+    * This is used for runtime type checking when casting to and from Vulkan
+    * handle types since compile-time type checking doesn't always work.
+    */
    VkObjectType type;
 
+   /** Pointer to the device in which this object exists, if any
+    *
+    * This is NULL for instances and physical devices but should point to a
+    * valid vk_device for almost everything else.  (There are a few WSI
+    * objects that don't inherit from a device.)
+    */
    struct vk_device *device;
 
    /* True if this object is fully constructed and visible to the client */
@@ -54,9 +67,20 @@ struct vk_object_base {
    char *object_name;
 };
 
+/** Initialize a vk_base_object
+ *
+ * @param[in]  device   The vk_device this object was created from or NULL
+ * @param[out] base     The vk_object_base to initialize
+ * @param[in]  obj_type The VkObjectType of the object being initialized
+ */
 void vk_object_base_init(struct vk_device *device,
                          struct vk_object_base *base,
                          VkObjectType obj_type);
+
+/** Tear down a vk_object_base
+ *
+ * @param[out] base     The vk_object_base being torn down
+ */
 void vk_object_base_finish(struct vk_object_base *base);
 
 static inline void
@@ -74,6 +98,26 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
    return base;
 }
 
+/** Define handle cast macros for the given dispatchable handle type
+ *
+ * For a given `driver_struct`, this defines `driver_struct_to_handle()` and
+ * `driver_struct_from_handle()` helpers which provide type-safe (as much as
+ * possible with Vulkan handle types) casts to and from the `driver_struct`
+ * type.  As an added layer of protection, these casts use the provided
+ * `VkObjectType` to assert that the object is of the correct type when
+ * running with a debug build.
+ *
+ * @param __driver_type The name of the driver struct; it is assumed this is
+ *                      the name of a struct type and `struct` will be
+ *                      prepended automatically
+ *
+ * @param __base        The name of the vk_base_object member
+ *
+ * @param __VkType      The Vulkan object type such as VkImage
+ *
+ * @param __VK_TYPE     The VkObjectType corresponding to __VkType, such as
+ *                      VK_OBJECT_TYPE_IMAGE
+ */
 #define VK_DEFINE_HANDLE_CASTS(__driver_type, __base, __VkType, __VK_TYPE) \
    static inline struct __driver_type *                                    \
    __driver_type ## _from_handle(__VkType _handle)                         \
@@ -93,6 +137,26 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
       return (__VkType) _obj;                                              \
    }
 
+/** Define handle cast macros for the given non-dispatchable handle type
+ *
+ * For a given `driver_struct`, this defines `driver_struct_to_handle()` and
+ * `driver_struct_from_handle()` helpers which provide type-safe (as much as
+ * possible with Vulkan handle types) casts to and from the `driver_struct`
+ * type.  As an added layer of protection, these casts use the provided
+ * `VkObjectType` to assert that the object is of the correct type when
+ * running with a debug build.
+ *
+ * @param __driver_type The name of the driver struct; it is assumed this is
+ *                      the name of a struct type and `struct` will be
+ *                      prepended automatically
+ *
+ * @param __base        The name of the vk_base_object member
+ *
+ * @param __VkType      The Vulkan object type such as VkImage
+ *
+ * @param __VK_TYPE     The VkObjectType corresponding to __VkType, such as
+ *                      VK_OBJECT_TYPE_IMAGE
+ */
 #define VK_DEFINE_NONDISP_HANDLE_CASTS(__driver_type, __base, __VkType, __VK_TYPE) \
    static inline struct __driver_type *                                    \
    __driver_type ## _from_handle(__VkType _handle)                         \
@@ -113,6 +177,17 @@ vk_object_base_from_u64_handle(uint64_t handle, VkObjectType obj_type)
       return (__VkType)(uintptr_t) _obj;                                   \
    }
 
+/** Declares a __driver_type pointer which represents __handle
+ *
+ * @param __driver_type The name of the driver struct; it is assumed this is
+ *                      the name of a struct type and `struct` will be
+ *                      prepended automatically
+ *
+ * @param __name        The name of the declared pointer
+ *
+ * @param __handle      The Vulkan object handle with which to initialize
+ *                      `__name`
+ */
 #define VK_FROM_HANDLE(__driver_type, __name, __handle) \
    struct __driver_type *__name = __driver_type ## _from_handle(__handle)