From e053d62aa573651abdd78666d299272c8219a3aa Mon Sep 17 00:00:00 2001 From: Ian Romanick Date: Sat, 18 Sep 2010 16:08:38 +0200 Subject: glsl: Add doxygen comments --- src/glsl/ast.h | 42 ++++++++++++++++++++++++--- src/glsl/ir.h | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 121 insertions(+), 12 deletions(-) (limited to 'src/glsl') diff --git a/src/glsl/ast.h b/src/glsl/ast.h index 44c31b6e62..d7bf90925c 100644 --- a/src/glsl/ast.h +++ b/src/glsl/ast.h @@ -33,6 +33,20 @@ struct _mesa_glsl_parse_state; struct YYLTYPE; +/** + * \defgroup AST Abstract syntax tree node definitions + * + * An abstract syntax tree is generated by the parser. This is a fairly + * direct representation of the gramma derivation for the source program. + * No symantic checking is done during the generation of the AST. Only + * syntactic checking is done. Symantic checking is performed by a later + * stage that converts the AST to a more generic intermediate representation. + * + *@{ + */ +/** + * Base class of all abstract syntax tree nodes + */ class ast_node { public: /* Callers of this talloc-based new need not call delete. It's @@ -54,7 +68,14 @@ public: talloc_free(table); } + /** + * Print an AST node in something approximating the original GLSL code + */ virtual void print(void) const; + + /** + * Convert the AST node to the high-level intermediate representation + */ virtual ir_rvalue *hir(exec_list *instructions, struct _mesa_glsl_parse_state *state); @@ -91,19 +112,29 @@ public: this->location.column = locp.first_column; } + /** + * Source location of the AST node. + */ struct { - unsigned source; - unsigned line; - unsigned column; + unsigned source; /**< GLSL source number. */ + unsigned line; /**< Line number within the source string. */ + unsigned column; /**< Column in the line. */ } location; exec_node link; protected: + /** + * The only constructor is protected so that only derived class objects can + * be created. + */ ast_node(void); }; +/** + * Operators for AST expression nodes. + */ enum ast_operators { ast_assign, ast_plus, /**< Unary + operator. */ @@ -161,6 +192,9 @@ enum ast_operators { ast_sequence }; +/** + * Representation of any sort of expression. + */ class ast_expression : public ast_node { public: ast_expression(int oper, ast_expression *, @@ -651,7 +685,7 @@ public: ast_function *prototype; ast_compound_statement *body; }; - +/*@}*/ extern void _mesa_ast_to_hir(exec_list *instructions, struct _mesa_glsl_parse_state *state); diff --git a/src/glsl/ir.h b/src/glsl/ir.h index b3b15bb08e..909f8242a7 100644 --- a/src/glsl/ir.h +++ b/src/glsl/ir.h @@ -41,7 +41,31 @@ extern "C" { #define ARRAY_SIZE(x) (sizeof(x) / sizeof(x[0])) #endif +/** + * \defgroup IR Intermediate representation nodes + * + * @{ + */ + +/** + * Class tags + * + * Each concrete class derived from \c ir_instruction has a value in this + * enumerant. The value for the type is stored in \c ir_instruction::ir_type + * by the constructor. While using type tags is not very C++, it is extremely + * convenient. For example, during debugging you can simply inspect + * \c ir_instruction::ir_type to find out the actual type of the object. + * + * In addition, it is possible to use a switch-statement based on \c + * \c ir_instruction::ir_type to select different behavior for different object + * types. For functions that have only slight differences for several object + * types, this allows writing very straightforward, readable code. + */ enum ir_node_type { + /** + * Zero is unused so that the IR validator can detect cases where + * \c ir_instruction::ir_type has not been initialized. + */ ir_type_unset, ir_type_variable, ir_type_assignment, @@ -156,9 +180,12 @@ protected: }; +/** + * Variable storage classes + */ enum ir_variable_mode { - ir_var_auto = 0, - ir_var_uniform, + ir_var_auto = 0, /**< Function local variables and globals. */ + ir_var_uniform, /**< Variable declared as a uniform. */ ir_var_in, ir_var_out, ir_var_inout, @@ -209,6 +236,9 @@ public: */ unsigned component_slots() const; + /** + * Delcared name of the variable + */ const char *name; /** @@ -218,11 +248,28 @@ public: */ unsigned max_array_access; + /** + * Is the variable read-only? + * + * This is set for variables declared as \c const, shader inputs, + * and uniforms. + */ unsigned read_only:1; unsigned centroid:1; unsigned invariant:1; + /** + * Storage class of the variable. + * + * \sa ir_variable_mode + */ unsigned mode:3; + + /** + * Interpolation mode for shader inputs / outputs + * + * \sa ir_variable_interpolation + */ unsigned interpolation:2; /** @@ -233,9 +280,13 @@ public: */ unsigned array_lvalue:1; - /* ARB_fragment_coord_conventions */ + /** + * \name ARB_fragment_coord_conventions + * @{ + */ unsigned origin_upper_left:1; unsigned pixel_center_integer:1; + /*@}*/ /** * Storage location of the base of this variable @@ -724,9 +775,22 @@ public: virtual ir_expression *clone(void *mem_ctx, struct hash_table *ht) const; + /** + * Attempt to constant-fold the expression + * + * If the expression cannot be constant folded, this method will return + * \c NULL. + */ virtual ir_constant *constant_expression_value(); + /** + * Determine the number of operands used by an expression + */ static unsigned int get_num_operands(ir_expression_operation); + + /** + * Determine the number of operands used by an expression + */ unsigned int get_num_operands() const { return get_num_operands(operation); @@ -813,6 +877,9 @@ public: return callee->function_name(); } + /** + * Get the function signature bound to this function call + */ ir_function_signature *get_callee() { return callee; @@ -977,11 +1044,11 @@ public: * Texture sampling opcodes used in ir_texture */ enum ir_texture_opcode { - ir_tex, /* Regular texture look-up */ - ir_txb, /* Texture look-up with LOD bias */ - ir_txl, /* Texture look-up with explicit LOD */ - ir_txd, /* Texture look-up with partial derivatvies */ - ir_txf /* Texel fetch with explicit LOD */ + ir_tex, /**< Regular texture look-up */ + ir_txb, /**< Texture look-up with LOD bias */ + ir_txl, /**< Texture look-up with explicit LOD */ + ir_txd, /**< Texture look-up with partial derivatvies */ + ir_txf /**< Texel fetch with explicit LOD */ }; @@ -1384,9 +1451,17 @@ private: ir_constant(void); }; +/*@}*/ + +/** + * Apply a visitor to each IR node in a list + */ void visit_exec_list(exec_list *list, ir_visitor *visitor); +/** + * Validate invariants on each IR node in a list + */ void validate_ir_tree(exec_list *instructions); /** -- cgit v1.2.3