Add some comments to the more complex parts of the GLSL compiler

diff --git a/source/glsl/generate.cpp b/source/glsl/generate.cpp
index 90128a18e1a7bbdfcaa023579c9665cac27c9a78..02021a4c39993c999f544c8718ea40292a4b0806 100644 (file)
--- a/source/glsl/generate.cpp
+++ b/source/glsl/generate.cpp
@@ -139,6 +139,9 @@ void VariableResolver::visit(VariableReference &var)
 {
        var.declaration = 0;
        r_members = 0;
+       /* Look for variable declarations in the block hierarchy first.  Interface
+       blocks are always defined in the top level so we can't accidentally skip
+       one. */
        for(Block *block=current_block; (!var.declaration && block); block=block->parent)
        {
                map<string, VariableDeclaration *>::iterator i = block->variables.find(var.name);
@@ -157,6 +160,8 @@ void VariableResolver::visit(VariableReference &var)
                map<string, InterfaceBlock *>::const_iterator i = blocks.find(var.name);
                if(i!=blocks.end() && i->second->instance_name==var.name)
                {
+                       /* The name refers to an interface block with an instance name rather
+                       than a variable.  Prepare a new syntax tree node accordingly. */
                        r_iface_ref = new InterfaceBlockReference;
                        r_iface_ref->name = var.name;
                        r_iface_ref->declaration = i->second;
@@ -164,6 +169,7 @@ void VariableResolver::visit(VariableReference &var)
                }
                else
                {
+                       // Look for the variable in anonymous interface blocks.
                        for(i=blocks.begin(); (!var.declaration && i!=blocks.end()); ++i)
                                if(i->second->instance_name.empty())
                                {
@@ -178,6 +184,8 @@ void VariableResolver::visit(VariableReference &var)
        {
                if(r_assignment_target)
                {
+                       /* More than one variable reference found in assignment target.
+                       Unable to determine what the primary target is. */
                        record_target = false;
                        r_assignment_target = 0;
                }
@@ -240,6 +248,8 @@ void VariableResolver::visit(BinaryExpression &binary)
        if(binary.oper->token[0]=='[')
        {
                {
+                       /* The subscript expression is not a part of the primary assignment
+                       target. */
                        SetFlag set(record_target, false);
                        binary.right->visit(*this);
                }
@@ -338,6 +348,7 @@ void FunctionResolver::visit(FunctionDeclaration &func)
        {
                stage_decl = &func;
 
+               // Set all previous declarations to use this definition.
                for(vector<FunctionDeclaration *>::iterator i=decls.begin(); i!=decls.end(); ++i)
                {
                        (*i)->definition = func.definition;
@@ -416,6 +427,8 @@ bool InterfaceGenerator::generate_interface(VariableDeclaration &var, const stri
        iface_var->interface = iface;
        iface_var->type = var.type;
        iface_var->name = name;
+       /* Geometry shader inputs are always arrays.  But if we're bringing in an
+       entire block, the array is on the block and not individual variables. */
        if(stage->type==Stage::GEOMETRY && !copy_block)
                iface_var->array = ((var.array && var.interface!="in") || iface=="in");
        else
@@ -491,7 +504,7 @@ void InterfaceGenerator::visit(VariableReference &var)
 {
        if(var.declaration || !stage->previous)
                return;
-       /* Don't pull a variable from previous stage if we just generated an out
+       /* Don't pull a variable from previous stage if we just generated an output
        interface in this stage */
        if(stage->content.variables.count(var.name))
                return;
@@ -539,6 +552,7 @@ void InterfaceGenerator::visit(VariableDeclaration &var)
        {
                if(iface_block->linked_block)
                {
+                       // Link all variables to their counterparts in the linked block.
                        const map<string, VariableDeclaration *> &linked_vars = iface_block->linked_block->members.variables;
                        map<string, VariableDeclaration *>::const_iterator i = linked_vars.find(var.name);
                        if(i!=linked_vars.end())
@@ -549,8 +563,8 @@ void InterfaceGenerator::visit(VariableDeclaration &var)
 
        if(var.interface=="out")
        {
-               /* For out variables in function scope, generate a global interface and
-               replace the local declaration with an assignment. */
+               /* For output variables in function scope, generate a global interface
+               and replace the local declaration with an assignment. */
                if(function_scope && generate_interface(var, "out", var.name))
                {
                        nodes_to_remove.insert(&var);
@@ -565,8 +579,8 @@ void InterfaceGenerator::visit(VariableDeclaration &var)
        }
        else if(var.interface=="in")
        {
-               /* Try to link in variables in global scope with out variables from
-               previous stage */
+               /* Try to link input variables in global scope with output variables from
+               previous stage. */
                if(current_block==&stage->content && !var.linked_declaration && stage->previous)
                {
                        const map<string, VariableDeclaration *> &prev_vars = stage->previous->content.variables;
@@ -586,6 +600,8 @@ void InterfaceGenerator::visit(InterfaceBlock &iface)
 {
        if(iface.interface=="in")
        {
+               /* Try to link input blocks with output blocks sharing the same block
+               name from previous stage. */
                if(!iface.linked_block && stage->previous)
                {
                        const map<string, InterfaceBlock *> &prev_blocks = stage->previous->interface_blocks;
@@ -613,6 +629,7 @@ void InterfaceGenerator::visit(Passthrough &pass)
 {
        vector<VariableDeclaration *> pass_vars;
 
+       // Pass through all input variables of this stage.
        for(map<string, VariableDeclaration *>::const_iterator i=stage->content.variables.begin(); i!=stage->content.variables.end(); ++i)
                if(i->second->interface=="in")
                        pass_vars.push_back(i->second);
@@ -625,6 +642,8 @@ void InterfaceGenerator::visit(Passthrough &pass)
                        if(i->second->interface!="out")
                                continue;
 
+                       /* Pass through output variables from the previous stage, but only
+                       those which are not already linked to an input here. */
                        if(!i->second->linked_declaration && generate_interface(*i->second, "in", i->second->name))
                                pass_vars.push_back(i->second);
                }
@@ -632,6 +651,8 @@ void InterfaceGenerator::visit(Passthrough &pass)
 
        if(stage->type==Stage::GEOMETRY)
        {
+               /* Special case for geometry shader: copy gl_Position from input to
+               output. */
                InterfaceBlockReference *ref = new InterfaceBlockReference;
                ref->name = "gl_in";
 

diff --git a/source/glsl/optimize.cpp b/source/glsl/optimize.cpp
index 3356a3c9aa6282c59dc1e0fa707f8224c44fa4f8..a7786295f6e8c117e94f345c66ba615873d79e96 100644 (file)
--- a/source/glsl/optimize.cpp
+++ b/source/glsl/optimize.cpp
@@ -23,6 +23,8 @@ void InlineableFunctionLocator::visit(FunctionCall &call)
        {
                unsigned &count = refcounts[def];
                ++count;
+               /* Don't inline functions which are called more than once or are called
+               recursively. */
                if(count>1 || def==current_function)
                        inlineable.erase(def);
        }
@@ -163,6 +165,8 @@ void InlineContentInjector::visit(Return &ret)
 
        if(ret.expression)
        {
+               /* Create a new variable to hold the return value of the inlined
+               function. */
                r_result_name = create_unused_name("return", true);
                RefPtr<VariableDeclaration> var = new VariableDeclaration;
                var->source = ret.source;
@@ -243,7 +247,7 @@ void FunctionInliner::visit(FunctionCall &call)
        {
                string result_name = InlineContentInjector().apply(*stage, *current_function, *current_block, insert_point, *def);
 
-               // This will later get removed by UnusedVariableRemover
+               // This will later get removed by UnusedVariableRemover.
                if(result_name.empty())
                        result_name = "msp_unused_from_inline";
 
@@ -419,8 +423,12 @@ bool UnusedVariableRemover::apply(Stage &stage)
        BlockVariableMap &global_variables = variables.back();
        for(BlockVariableMap::iterator i=global_variables.begin(); i!=global_variables.end(); ++i)
        {
+               /* Don't remove output variables which are used by the next stage or the
+               graphics API. */
                if(i->first->interface=="out" && (stage.type==Stage::FRAGMENT || i->first->linked_declaration || !i->first->name.compare(0, 3, "gl_")))
                        continue;
+
+               // Mark other unreferenced global variables as unused.
                if(!i->second.referenced)
                {
                        unused_nodes.insert(i->first);
@@ -443,6 +451,7 @@ void UnusedVariableRemover::visit(VariableReference &var)
        if(var.declaration && !assignment_target)
        {
                VariableInfo &var_info = variables.back()[var.declaration];
+               // Previous assignments are used by this reference.
                clear_assignments(var_info, false);
                var_info.referenced = true;
        }
@@ -495,12 +504,16 @@ void UnusedVariableRemover::visit(Assignment &assign)
 void UnusedVariableRemover::visit(FunctionCall &call)
 {
        TraversingVisitor::visit(call);
+       /* Treat function calls as having side effects so expression statements
+       consisting of nothing but a function call won't be optimized away. */
        r_side_effects = true;
 }
 
 void UnusedVariableRemover::record_assignment(VariableDeclaration &var, Node &node, bool chained)
 {
        VariableInfo &var_info = variables.back()[&var];
+       /* An assignment which completely replaces the value of the variable causes
+       any previous unreferenced assignments to be unused. */
        if(!chained)
                clear_assignments(var_info, true);
        var_info.assignments.push_back(&node);
@@ -566,11 +579,18 @@ void UnusedVariableRemover::visit(FunctionDeclaration &func)
        func.body.visit(*this);
 
        BlockVariableMap &block_variables = variables.back();
+
+       /* Mark global variables as conditionally assigned so assignments in other
+       functions won't be removed. */
        for(BlockVariableMap::iterator i=block_variables.begin(); i!=block_variables.end(); ++i)
                if(!i->second.local)
                        i->second.conditionally_assigned = true;
+
+       /* Always treat function parameters as referenced.  Removing unused
+       parameters is not currently supported. */
        for(NodeArray<VariableDeclaration>::iterator i=func.parameters.begin(); i!=func.parameters.end(); ++i)
                block_variables[i->get()].referenced = true;
+
        merge_down_variables();
 }
 
@@ -584,6 +604,8 @@ void UnusedVariableRemover::merge_down_variables()
                {
                        if(!i->second.referenced)
                                unused_nodes.insert(i->first);
+                       /* Any unreferenced assignments when a variable runs out of scope
+                       become unused. */
                        clear_assignments(i->second, true);
                        continue;
                }
@@ -593,6 +615,7 @@ void UnusedVariableRemover::merge_down_variables()
                        parent_variables.insert(*i);
                else
                {
+                       // Merge a non-local variable's state into the parent scope.
                        if(i->second.referenced || !i->second.conditionally_assigned)
                                clear_assignments(j->second, !i->second.referenced);
                        j->second.conditionally_assigned = i->second.conditionally_assigned;
@@ -613,20 +636,25 @@ void UnusedVariableRemover::visit(Conditional &cond)
        swap(variables.back(), if_variables);
        cond.else_body.visit(*this);
 
+       // Combine variables from both branches.
        BlockVariableMap &else_variables = variables.back();
        for(BlockVariableMap::iterator i=else_variables.begin(); i!=else_variables.end(); ++i)
        {
                BlockVariableMap::iterator j = if_variables.find(i->first);
                if(j!=if_variables.end())
                {
+                       // The variable was found in both branches.
                        i->second.assignments.insert(i->second.assignments.end(), j->second.assignments.begin(), j->second.assignments.end());
                        i->second.conditionally_assigned |= j->second.conditionally_assigned;
                        if_variables.erase(j);
                }
                else
+                       // Mark variables found in only one branch as conditionally assigned.
                        i->second.conditionally_assigned = true;
        }
 
+       /* Move variables which were only used in the if block into the combined
+       block. */
        for(BlockVariableMap::iterator i=if_variables.begin(); i!=if_variables.end(); ++i)
        {
                i->second.conditionally_assigned = true;