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

[libs/gl.git] / source / glsl / optimize.cpp

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;