util/vulkan: Add vk_outarray (v2)

This is a wrapper for a Vulkan output array. A Vulkan output array is
one that follows the convention of the parameters to
vkGetPhysicalDeviceQueueFamilyProperties().

v2: Replace vk_outarray_is_incomplete() with vk_outarray_status(). For
    Jason.

Reviewed-by: Jason Ekstrand <jason@jlekstrand.net>

src/util/vk_util.h

@@ -40,4 +40,144 @@ struct vk_struct_common {
    for (const struct vk_struct_common *__iter = (const struct vk_struct_common *)(__start); \
         __iter; __iter = __iter->pNext)
 
+/**
+ * A wrapper for a Vulkan output array. A Vulkan output array is one that
+ * follows the convention of the parameters to
+ * vkGetPhysicalDeviceQueueFamilyProperties().
+ *
+ * Example Usage:
+ *
+ *    VkResult
+ *    vkGetPhysicalDeviceQueueFamilyProperties(
+ *       VkPhysicalDevice           physicalDevice,
+ *       uint32_t*                  pQueueFamilyPropertyCount,
+ *       VkQueueFamilyProperties*   pQueueFamilyProperties)
+ *    {
+ *       VK_OUTARRAY_MAKE(props, pQueueFamilyProperties,
+ *                         pQueueFamilyPropertyCount);
+ *
+ *       vk_outarray_append(&props, p) {
+ *          p->queueFlags = ...;
+ *          p->queueCount = ...;
+ *       }
+ *
+ *       vk_outarray_append(&props, p) {
+ *          p->queueFlags = ...;
+ *          p->queueCount = ...;
+ *       }
+ *
+ *       return vk_outarray_status(&props);
+ *    }
+ */
+struct __vk_outarray {
+   /** May be null. */
+   void *data;
+
+   /**
+    * Capacity, in number of elements. Capacity is unlimited (UINT32_MAX) if
+    * data is null.
+    */
+   uint32_t cap;
+
+   /**
+    * Count of elements successfully written to the array. Every write is
+    * considered successful if data is null.
+    */
+   uint32_t *filled_len;
+
+   /**
+    * Count of elements that would have been written to the array if its
+    * capacity were sufficient. Vulkan functions often return VK_INCOMPLETE
+    * when `*filled_len < wanted_len`.
+    */
+   uint32_t wanted_len;
+};
+
+static inline void
+__vk_outarray_init(struct __vk_outarray *a,
+                   void *data, uint32_t *restrict len)
+{
+   a->data = data;
+   a->cap = *len;
+   a->filled_len = len;
+   *a->filled_len = 0;
+   a->wanted_len = 0;
+
+   if (a->data == NULL)
+      a->cap = UINT32_MAX;
+}
+
+static inline VkResult
+__vk_outarray_status(const struct __vk_outarray *a)
+{
+   if (*a->filled_len < a->wanted_len)
+      return VK_INCOMPLETE;
+   else
+      return VK_SUCCESS;
+}
+
+static inline void *
+__vk_outarray_next(struct __vk_outarray *a, size_t elem_size)
+{
+   void *p = NULL;
+
+   a->wanted_len += 1;
+
+   if (*a->filled_len >= a->cap)
+      return NULL;
+
+   if (a->data != NULL)
+      p = a->data + (*a->filled_len) * elem_size;
+
+   *a->filled_len += 1;
+
+   return p;
+}
+
+#define vk_outarray(elem_t) \
+   struct { \
+      struct __vk_outarray base; \
+      elem_t meta[]; \
+   }
+
+#define vk_outarray_typeof_elem(a) __typeof__((a)->meta[0])
+#define vk_outarray_sizeof_elem(a) sizeof((a)->meta[0])
+
+#define vk_outarray_init(a, data, len) \
+   __vk_outarray_init(&(a)->base, (data), (len))
+
+#define VK_OUTARRAY_MAKE(name, data, len) \
+   vk_outarray(__typeof__((data)[0])) name; \
+   vk_outarray_init(&name, (data), (len))
+
+#define vk_outarray_status(a) \
+   __vk_outarray_status(&(a)->base)
+
+#define vk_outarray_next(a) \
+   ((vk_outarray_typeof_elem(a) *) \
+      __vk_outarray_next(&(a)->base, vk_outarray_sizeof_elem(a)))
+
+/**
+ * Append to a Vulkan output array.
+ *
+ * This is a block-based macro. For example:
+ *
+ *    vk_outarray_append(&a, elem) {
+ *       elem->foo = ...;
+ *       elem->bar = ...;
+ *    }
+ *
+ * The array `a` has type `vk_outarray(elem_t) *`. It is usually declared with
+ * VK_OUTARRAY_MAKE(). The variable `elem` is block-scoped and has type
+ * `elem_t *`.
+ *
+ * The macro unconditionally increments the array's `wanted_len`. If the array
+ * is not full, then the macro also increment its `filled_len` and then
+ * executes the block. When the block is executed, `elem` is non-null and
+ * points to the newly appended element.
+ */
+#define vk_outarray_append(a, elem) \
+   for (vk_outarray_typeof_elem(a) *elem = vk_outarray_next(a); \
+        elem != NULL; elem = NULL)
+
 #endif /* VK_UTIL_H */