Mesa (master): glsl: Add doxygen comments
Ian Romanick
idr at kemper.freedesktop.org
Mon Sep 20 14:14:39 UTC 2010
Module: Mesa
Branch: master
Commit: e053d62aa573651abdd78666d299272c8219a3aa
URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=e053d62aa573651abdd78666d299272c8219a3aa
Author: Ian Romanick <ian.d.romanick at intel.com>
Date: Sat Sep 18 16:08:38 2010 +0200
glsl: Add doxygen comments
---
src/glsl/ast.h | 42 +++++++++++++++++++++++--
src/glsl/ir.h | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 121 insertions(+), 12 deletions(-)
diff --git a/src/glsl/ast.h b/src/glsl/ast.h
index 44c31b6..d7bf909 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 b3b15bb..909f824 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);
/**
More information about the mesa-commit
mailing list