[PATCH v4 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. -- v4: 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. https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
From: Francisco Casas <fcasas(a)codeweavers.com> --- libs/vkd3d-shader/hlsl.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/libs/vkd3d-shader/hlsl.h b/libs/vkd3d-shader/hlsl.h index c1fa37be..3122f382 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -501,13 +501,25 @@ 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. + * The path is lowered to this single offset -- whose value may vary between SM1 and SM4 -- + * 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 3122f382..4d1ff0fc 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; -- GitLab 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 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; }; -- 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 07718316..3317bd6f 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -598,9 +598,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
From: Francisco Casas <fcasas(a)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 bc5b5fb6..07718316 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; }; -- 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 4d1ff0fc..bc5b5fb6 100644 --- a/libs/vkd3d-shader/hlsl.h +++ b/libs/vkd3d-shader/hlsl.h @@ -612,15 +612,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
This merge request was approved by Giovanni Mascellani. -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
This merge request was approved by Henri Verbeet. -- https://gitlab.winehq.org/wine/vkd3d/-/merge_requests/61
participants (4)
-
Francisco Casas -
Francisco Casas (＠fcasas)
-
Giovanni Mascellani (＠giomasce)
-
Henri Verbeet (＠hverbeet)