[PATCH 0/6] MR61: vkd3d-shader/hlsl: Add field-level documentation to the most important structs in hlsl.h. (PART 2/2)

[Francisco Casas (＠fcasas)]

Second part of !50.

[PATCH 1/6] vkd3d-shader/hlsl: Add documentation to struct hlsl_reg.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index f365f588..875203ea 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -210,10 +210,18 @@ struct hlsl_struct_field
     size_t name_bytecode_offset;
 };

+/* Information of the register allocated for an instruction node or variable.
+ * These values are initialized at the end of hlsl_emit_bytecode(), after the compilation passes,
+ *   just before writing the bytecode.
+ * For numeric registers, a writemask can be provided to indicate the reserve of only some of the
+ *   4 components.
+ * The type of register (register class) is implied from its use, so it is not stored in this
+ *   struct. */
 struct hlsl_reg
 {
     uint32_t id;
     unsigned int writemask;
+    /* If the register has been allocated already. */
     bool allocated;
 };

@@ -545,6 +553,7 @@ struct hlsl_ir_constant
         float f;
         double d;
     } value[4];
+    /* Constant register of type 'c' where the constant value is stored for SM1. */
     struct hlsl_reg reg;
 };

[PATCH 2/6] vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_deref.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index 875203ea..b71666cb 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -493,13 +493,24 @@ struct hlsl_ir_swizzle
     DWORD swizzle;
 };

+/* Reference to a variable, or a part of it (e.g. a vector within a matrix within a struct). */
 struct hlsl_deref
 {
     struct hlsl_ir_var *var;

+    /* An array of references to instruction nodes, of data type uint, that are used to reach the
+     *   desired part of the variable.
+     * If path_len is 0, then this is a reference to the whole variable.
+     * The value of each instruction node in the path corresponds to the index of the element/field
+     *   that has to be selected on each nesting level to reach this part.
+     * The path shall not contain additional values once a type that cannot be subdivided
+     *   (a.k.a. "component") is reached. */
     unsigned int path_len;
     struct hlsl_src *path;

+    /* Single instruction node of data type uint used to represent the register offset (in register
+     *   components), from the start of the variable, of the part referenced.
+     * Currently, the path is being lowered to this single offset before writing the bytecode. */
     struct hlsl_src offset;
 };

[PATCH 3/6] vkd3d-shader/hlsl: Add documentation to small hlsl.h structs.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index b71666cb..37ae8e36 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -185,6 +185,8 @@ struct hlsl_type
     size_t bytecode_offset;
 };

+/* In HLSL, a semantic is a string linked to a variable (or a field) to be recognized across
+ *   different shader stages in the graphics pipeline. */
 struct hlsl_semantic
 {
     const char *name;
@@ -275,6 +277,7 @@ struct hlsl_ir_node

struct hlsl_block
 {
+    /* List containing instruction nodes; linked by the hlsl_ir_node.entry fields. */
     struct list instrs;
 };

@@ -322,6 +325,8 @@ struct hlsl_attribute

#define HLSL_ARRAY_ELEMENTS_COUNT_IMPLICIT 0

+/* Reservation of a specific register to a variable, field, or buffer, written in the HLSL source
+ *   using the register(·) syntax */
 struct hlsl_reg_reservation
 {
     char type;

[PATCH 4/6] vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_buffer.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index 37ae8e36..e14e121c 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -603,15 +603,25 @@ enum hlsl_buffer_type
     HLSL_BUFFER_TEXTURE,
 };

+/* In SM4, uniform variables are organized in different buffers. Besides buffers defined in the
+ *   source code, there is also the implicit $Globals buffer and the implicit $Params buffer,
+ *   to which uniform globals and parameters belong by default. */
 struct hlsl_buffer
 {
     struct vkd3d_shader_location loc;
     enum hlsl_buffer_type type;
     const char *name;
+    /* Register reserved for this buffer, if any.
+     * If provided, it should be of type 'b' if type is HLSL_BUFFER_CONSTANT and 't' if type is
+     *   HLSL_BUFFER_TEXTURE. */
     struct hlsl_reg_reservation reservation;
+    /* Item entry for hlsl_ctx.buffers */
     struct list entry;

+    /* The size of the buffer (in register components), and the size of the buffer as determined
+     *   by its last variable that's actually used. */
     unsigned size, used_size;
+    /* Register of type 'b' on which the buffer is allocated. */
     struct hlsl_reg reg;
 };

[PATCH 5/6] vkd3d-shader/hlsl: Add field-level documentation to function structs.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index e14e121c..73fbb4af 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -383,22 +383,37 @@ struct hlsl_ir_var

struct hlsl_ir_function
 {
+    /* Item entry in hlsl_ctx.functions */
     struct rb_entry entry;
+
     const char *name;
+    /* Container for hlsl_ir_function-decl.entry, containing all the function definitions. Which
+     *   may be more than one (overloading). */
     struct rb_tree overloads;
+
     bool intrinsic;
 };

struct hlsl_ir_function_decl
 {
     struct hlsl_type *return_type;
+    /* Synthetic variable used to store the return value of the function. */
     struct hlsl_ir_var *return_var;
+
     struct vkd3d_shader_location loc;
+    /* Item entry in hlsl_ir_function.overloads. The paremeters' types are used as key. */
     struct rb_entry entry;
+
+    /* Function to which this declaration corresponds. */
     struct hlsl_ir_function *func;
+    /* List containing one variable for each parameter of the function; linked by the
+     *   hlsl_ir_var.param_entry fields. */
     struct list *parameters;
+
     struct hlsl_block body;
     bool has_body;
+    /* Array of attributes (like earlydepthstencil) specified just before the function declaration.
+     * Not to be confused with the function parameters! */
     unsigned int attr_count;
     const struct hlsl_attribute *const *attrs;
 };

[PATCH 6/6] vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_scope.

[Francisco Casas]

From: Francisco Casas

---
 libs/vkd3d-shader/hlsl.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h
index 73fbb4af..2d18e15e 100644
--- a/libs/vkd3d-shader/hlsl.h
+++ b/libs/vkd3d-shader/hlsl.h
@@ -590,9 +590,15 @@ struct hlsl_ir_constant

struct hlsl_scope
 {
+    /* Item entry for hlsl_ctx.scopes. */
     struct list entry;
+
+    /* List containing the variables declared in this scope; linked by hlsl_ir_var->scope_entry. */
     struct list vars;
+    /* Tree map containing the types declared in this scope, using hlsl_tree.name as key.
+     * The types are attached through the hlsl_type.scope_entry fields. */
     struct rb_tree types;
+    /* Scope containing this scope. This value is NULL for the global scope. */
     struct hlsl_scope *upper;
 };

[Zebediah Figura (＠zfigura)]

Zebediah Figura (@zfigura) commented about libs/vkd3d-shader/hlsl.h:
>  size_t name_bytecode_offset;
>
> };
>
> +/* Information of the register allocated for an instruction node or variable.
> -
> - These values are initialized at the end of hlsl_emit_bytecode(), after the compilation passes,
> -
> - just before writing the bytecode.
> -
> - For numeric registers, a writemask can be provided to indicate the reserve of only some of the
> -
> - 4 components.

English nitpick: "reservation" rather than "reserve".

[Zebediah Figura (＠zfigura)]

Zebediah Figura (@zfigura) commented about libs/vkd3d-shader/hlsl.h:
>  size_t name_bytecode_offset;
>
> };
>
> +/* Information of the register allocated for an instruction node or variable.
> -
> - These values are initialized at the end of hlsl_emit_bytecode(), after the compilation passes,
> -
> - just before writing the bytecode.
> -
> - For numeric registers, a writemask can be provided to indicate the reserve of only some of the
> -
> - 4 components.
> -
> - The type of register (register class) is implied from its use, so it is not stored in this
> -
> - struct. */
>
> struct hlsl_reg
>  {
>      uint32_t id;
>      unsigned int writemask;
> - /* If the register has been allocated already. */

Yeah, though "already" only covers the connotation relevant to RA itself. The other connotation is "is this register even used?" which matters for uniforms. I dunno how I'd reword this at all, except maybe to just delete the "already" (also, 'whether' rather than 'if' probably, but that's just a language nitpick).

[Zebediah Figura (＠zfigura)]

Zebediah Figura (@zfigura) commented about libs/vkd3d-shader/hlsl.h:
> struct hlsl_ir_function
>  {
> - /* Item entry in hlsl_ctx.functions */
> struct rb_entry entry;
> - const char *name;
> - /* Container for hlsl_ir_function-decl.entry, containing all the function definitions. Which
> -
> *   may be more than one (overloading). */
> struct rb_tree overloads;

Besides not really being grammatical, this seems a bit redundant, given that the field is named "overloads". Also, hlsl_ir_function_decl in this comment has a dash in place of an underscore. I'd advocate something like "Tree of function overloads, stored as hlsl_ir_function_decl structures."

[Zebediah Figura (＠zfigura)]

Zebediah Figura (@zfigura) commented about libs/vkd3d-shader/hlsl.h:
>  struct hlsl_ir_var *return_var;
> - struct vkd3d_shader_location loc;
> - /* Item entry in hlsl_ir_function.overloads. The paremeters' types are used as key. */
> struct rb_entry entry;
> -
> - /* Function to which this declaration corresponds. */
> struct hlsl_ir_function *func;
> - /* List containing one variable for each parameter of the function; linked by the
> -
> *   hlsl_ir_var.param_entry fields. */
> struct list *parameters;
> - struct hlsl_block body;
>    bool has_body;
> - /* Array of attributes (like earlydepthstencil) specified just before the function declaration.
> -
> * Not to be confused with the function parameters! */

Or [numthreads], which is the only one we actually implement :D