From: Mikko Rasa Date: Wed, 3 Mar 2021 18:05:28 +0000 (+0200) Subject: Add some comments to the more complex parts of the GLSL compiler X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=b7702a7162bba41718dd56b875e5d911f5ab3edb;p=libs%2Fgl.git 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 90128a18..02021a4c 100644 --- 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::iterator i = block->variables.find(var.name); @@ -157,6 +160,8 @@ void VariableResolver::visit(VariableReference &var) map::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::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 &linked_vars = iface_block->linked_block->members.variables; map::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 &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 &prev_blocks = stage->previous->interface_blocks; @@ -613,6 +629,7 @@ void InterfaceGenerator::visit(Passthrough &pass) { vector pass_vars; + // Pass through all input variables of this stage. for(map::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 3356a3c9..a7786295 100644 --- 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 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::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;