[PATCH 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. -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)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 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; }; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)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 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; }; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)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 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; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)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 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; }; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)codeweavers.com> --- 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; }; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)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 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; }; -- GitLab https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
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". -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61#note_20824
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." -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61#note_20826
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). -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61#note_20825
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 -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61#note_20827
participants (3)
-
Francisco Casas -
Francisco Casas (＠fcasas)
-
Zebediah Figura (＠zfigura)