[PATCH vkd3d 5/5] include: Document struct vkd3d_shader_interface_info.

[Zebediah Figura]

Signed-off-by: Zebediah Figura <z.figura12 at gmail.com>
---
 include/vkd3d_shader.h | 108 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 100 insertions(+), 8 deletions(-)

diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h
index 01393327..96a6e7fe 100644
--- a/include/vkd3d_shader.h
+++ b/include/vkd3d_shader.h
@@ -105,15 +105,23 @@ struct vkd3d_shader_compile_option
     unsigned int value;
 };
 
+/** Describes which shader stages a resource is visible to. */
 enum vkd3d_shader_visibility
 {
+    /** The resource is visible to all shader stages. */
     VKD3D_SHADER_VISIBILITY_ALL = 0,
+    /** The resource is visible only to the vertex shader. */
     VKD3D_SHADER_VISIBILITY_VERTEX = 1,
+    /** The resource is visible only to the hull shader. */
     VKD3D_SHADER_VISIBILITY_HULL = 2,
+    /** The resource is visible only to the domain shader. */
     VKD3D_SHADER_VISIBILITY_DOMAIN = 3,
+    /** The resource is visible only to the geometry shader. */
     VKD3D_SHADER_VISIBILITY_GEOMETRY = 4,
+    /** The resource is visible only to the pixel shader. */
     VKD3D_SHADER_VISIBILITY_PIXEL = 5,
 
+    /** The resource is visible only to the compute shader. */
     VKD3D_SHADER_VISIBILITY_COMPUTE = 1000000000,
 
     VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_VISIBILITY),
@@ -128,21 +136,36 @@ struct vkd3d_shader_code
     size_t size;
 };
 
+/** The type of a shader resource descriptor. */
 enum vkd3d_shader_descriptor_type
 {
-    VKD3D_SHADER_DESCRIPTOR_TYPE_SRV     = 0x0, /* t#  */
+    /** The descriptor is a shader resource view, bound to a t# register. */
+    VKD3D_SHADER_DESCRIPTOR_TYPE_SRV     = 0x0,
+    /** The descriptor is an unordered access view, bound to a u# register. */
     VKD3D_SHADER_DESCRIPTOR_TYPE_UAV     = 0x1, /* u#  */
+    /** The descriptor is a constant buffer view, bound to a cb# register. */
     VKD3D_SHADER_DESCRIPTOR_TYPE_CBV     = 0x2, /* cb# */
+    /** The descriptor is a sampler, bound to a s# register. */
     VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, /* s#  */
 
     VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_TYPE),
 };
 
+/**
+ * A common structure describing the mapping a DXBC descriptor or descriptor
+ * array to a SPIR-V descriptor or descriptor array.
+ */
 struct vkd3d_shader_descriptor_binding
 {
+    /** The set of the Vulkan descriptor. */
     unsigned int set;
+    /** The binding index, within the set, of the Vulkan descriptor. */
     unsigned int binding;
-    unsigned int count; /* This must be 1 in this version of vkd3d-shader. */
+    /**
+     * The size of this descriptor array. Descriptor arrays are not supported in
+     * this version of vkd3d-shader, and therefore this value must be 1.
+     */
+    unsigned int count;
 };
 
 enum vkd3d_shader_binding_flag
@@ -203,67 +226,136 @@ struct vkd3d_shader_parameter
     } u;
 };
 
+/**
+ * Describes the mapping of a single DXBC resource or resource array to SPIR-V.
+ * This structure is used in struct vkd3d_shader_interface_info.
+ */
 struct vkd3d_shader_resource_binding
 {
+    /** The type of this descriptor. */
     enum vkd3d_shader_descriptor_type type;
+    /**
+     * Register space of the DXBC descriptor. If the source format does not
+     * support multiple register spaces, this parameter must be set to 0.
+     */
     unsigned int register_space;
+    /** Register index of the DXBC descriptor. */
     unsigned int register_index;
     enum vkd3d_shader_visibility shader_visibility;
-    unsigned int flags; /* vkd3d_shader_binding_flag */
+    /** A combination of zero or more elements of vkd3d_shader_binding_flag. */
+    unsigned int flags;
 
     struct vkd3d_shader_descriptor_binding binding;
 };
 
 #define VKD3D_SHADER_DUMMY_SAMPLER_INDEX ~0u
 
+/**
+ * Describes the mapping of a DXBC resource-sampler pair to a SPIR-V combined
+ * sampler (i.e. sampled image). This structure is used in struct
+ * vkd3d_shader_interface_info.
+ */
 struct vkd3d_shader_combined_resource_sampler
 {
+    /**
+     * Register space of the DXBC resource. Ifthe source format does not
+     * support multiple register spaces, this parameter must be set to 0.
+     */
     unsigned int resource_space;
+    /** Register index of the DXBC resource. */
     unsigned int resource_index;
+    /**
+     * Register space of the DXBC sampler. Ifthe source format does not
+     * support multiple register spaces, this parameter must be set to 0.
+     */
     unsigned int sampler_space;
+    /** Register index of the DXBC sampler. */
     unsigned int sampler_index;
     enum vkd3d_shader_visibility shader_visibility;
-    unsigned int flags; /* vkd3d_shader_binding_flag */
+    /** A combination of zero or more elements of vkd3d_shader_binding_flag. */
+    unsigned int flags;
 
     struct vkd3d_shader_descriptor_binding binding;
 };
 
+/**
+ * Describes the mapping of a single DXBC UAV counter to SPIR-V. This structure
+ * is used in struct vkd3d_shader_interface_info.
+ */
 struct vkd3d_shader_uav_counter_binding
 {
+    /**
+     * Register space of the DXBC UAV descriptor. If the source format does not
+     * support multiple register spaces, this parameter must be set to 0.
+     */
     unsigned int register_space;
-    unsigned int register_index; /* u# */
+    /** Register index of the DXBC UAV descriptor. */
+    unsigned int register_index;
     enum vkd3d_shader_visibility shader_visibility;
 
     struct vkd3d_shader_descriptor_binding binding;
     unsigned int offset;
 };
 
+/**
+ * Describes the mapping of a single Direct3D push constant buffer to SPIR-V.
+ * This structure is used in struct vkd3d_shader_interface_info.
+ */
 struct vkd3d_shader_push_constant_buffer
 {
+    /**
+     * Register space of the Direct3D descriptor. If the source format does not
+     * support multiple register spaces, this parameter must be set to 0.
+     */
     unsigned int register_space;
+    /** Register index of the DXBC descriptor. */
     unsigned int register_index;
     enum vkd3d_shader_visibility shader_visibility;
 
-    unsigned int offset; /* in bytes */
-    unsigned int size;   /* in bytes */
+    /** Offset, in bytes, in the SPIR-V push constant buffer. */
+    unsigned int offset;
+    /** Size, in bytes. */
+    unsigned int size;
 };
 
-/* Extends vkd3d_shader_compile_info. */
+/**
+ * A chained structure describing the correspondence between source and target
+ * bindings of a compiled shader. This structure consists of several similar
+ * arrays of structures, each element of which describes a single mapping from
+ * a DXBC binding descriptor to a SPIR-V binding descriptor.
+ *
+ * This structure is optional. If omitted, vkd3d_shader_compile() will behave
+ * as if no descriptors had been passed.
+ *
+ * This structure extends vkd3d_shader_compile_info.
+ *
+ * This structure contains only input parameters.
+ */
 struct vkd3d_shader_interface_info
 {
+    /** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_INTERFACE_INFO. */
     enum vkd3d_shader_structure_type type;
+    /** Optional pointer to a structure containing further parameters. */
     const void *next;
 
+    /** An array of bindings for shader resource descriptors. */
     const struct vkd3d_shader_resource_binding *bindings;
+    /** Size, in elements, of \ref bindings. */
     unsigned int binding_count;
 
+    /** An array of bindings for push constant buffers. */
     const struct vkd3d_shader_push_constant_buffer *push_constant_buffers;
+    /** Size, in elements, of \ref push_constant_buffers. */
     unsigned int push_constant_buffer_count;
 
+    /** An array of bindings for combined samplers. */
     const struct vkd3d_shader_combined_resource_sampler *combined_samplers;
+    /** Size, in elements, of \ref combined_samplers. */
     unsigned int combined_sampler_count;
 
+    /** An array of bindings for UAV counters. */
     const struct vkd3d_shader_uav_counter_binding *uav_counters;
+    /** Size, in elements, of \ref uav_counters. */
     unsigned int uav_counter_count;
 };
 
-- 
2.28.0