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

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

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";