[PATCH v3 0/6] MR61: vkd3d-shader/hlsl: Add field-level documentation to the most important structs in hlsl.h. (PART 2/2)
Second part of !50.
-- v3: vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_scope. vkd3d-shader/hlsl: Add field-level documentation to function structs. vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_buffer. vkd3d-shader/hlsl: Add documentation to small hlsl.h structs. vkd3d-shader/hlsl: Add field-level documentation to struct hlsl_deref. vkd3d-shader/hlsl: Add documentation to struct hlsl_reg.
From: Francisco Casas fcasas@codeweavers.com
--- 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 14070239..c1fa37be 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 reservation 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; + /* Whether the register has been allocated. */ bool allocated; };
@@ -553,6 +561,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; };
From: Francisco Casas fcasas@codeweavers.com
--- 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 c1fa37be..865478ea 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -501,13 +501,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; };
From: Francisco Casas fcasas@codeweavers.com
--- 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 865478ea..f8a09966 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; @@ -276,6 +278,7 @@ struct hlsl_ir_node
struct hlsl_block { + /* List containing instruction nodes; linked by the hlsl_ir_node.entry fields. */ struct list instrs; };
@@ -323,6 +326,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;
From: Francisco Casas fcasas@codeweavers.com
--- 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 f8a09966..99ebb984 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -611,15 +611,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; };
From: Francisco Casas fcasas@codeweavers.com
--- libs/vkd3d-shader/hlsl.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h index 99ebb984..3c2c1eef 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -384,21 +384,35 @@ struct hlsl_ir_var
struct hlsl_ir_function { + /* Item entry in hlsl_ctx.functions */ struct rb_entry entry; + const char *name; + /* Tree containing function definitions, stored as hlsl_ir_function_decl structures, which would + * be more than one in case of function overloading. */ struct rb_tree overloads; };
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 numthreads) specified just before the function declaration. + * Not to be confused with the function parameters! */ unsigned int attr_count; const struct hlsl_attribute *const *attrs; };
From: Francisco Casas fcasas@codeweavers.com
--- 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 3c2c1eef..1a38918f 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -597,9 +597,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; };
Giovanni Mascellani (@giomasce) commented about libs/vkd3d-shader/hlsl.h:
{ 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. */
The combination of "currently", "is being" and "before ..." makes it hard for me to understand whatever timing seems to be implied by this sentence. I'd drop the "currently" (all comments are assumed to be "current", hopefully) and use the present tense: "The path is lowered to this single offset before writing the bytecode". I might even add a note mentioning that the value stored here depends (also) on the shader model.
Giovanni Mascellani (@giomasce) commented about libs/vkd3d-shader/hlsl.h:
#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 */
Are we sure we want non-ASCII characters in vkd3d? Not that I have any strong objections, and it's unlikely that this happening in a comment will ever cause significant issues, but maybe we can avoid the risk altogether by using an ASCII ellipsis: "...".
On Wed Jan 18 14:49:09 2023 +0000, Giovanni Mascellani wrote:
Are we sure we want non-ASCII characters in vkd3d? Not that I have any strong objections, and it's unlikely that this happening in a comment will ever cause significant issues, but maybe we can avoid the risk altogether by using an ASCII ellipsis: "...".
Well, at the very least we already have a couple of UTF-8 ö's in the vkd3d source...
More generally, I don't see much of a reason to avoid non-ASCII in vkd3d at this point, and I've certainly added my share to e.g. d2d1 in Wine.
On Wed Jan 18 15:22:03 2023 +0000, Henri Verbeet wrote:
Well, at the very least we already have a couple of UTF-8 ö's in the vkd3d source... More generally, I don't see much of a reason to avoid non-ASCII in vkd3d at this point, and I've certainly added my share to e.g. d2d1 in Wine.
Ok, fine for me.
-
Francisco Casas -
Francisco Casas (＠fcasas)
-
Giovanni Mascellani (＠giomasce)
-
Henri Verbeet (＠hverbeet)