Initial support for uniform parameters on entry points (#815)

* Initial support for uniform parameters on entry points

The basic feature this work adds is the ability to define a shader entry point like:

```hlsl
[shader("fragment")]
float4 main(
    uniform Texture2D    t,
    uniform SamplerState s,
            float2       uv : UV)
{
    return t.Sample(s,uv);
}
```

In this example, the `uniform` keyword is used to mark that the given entry point parameters are *not* varying input/output flowing through the pipeline, but rather uniform shader parameters that should function as if the shader was declared more like:

```hlsl
Texture2D    t,
SamplerState s,

[shader("fragment")]
float4 main(
    float2 uv : UV)
{
    return t.Sample(s,uv);
}
```

Allowing `uniform` parameters on entry points makes it easier to define multiple entry points in one file without accidentally polluting the global scope with shader parameters that only certain entry points care about.
This feature is also more or less a prerequisite for allowing generic type parameters directly on entry point functions, since the main use case for those type parameters is for determining what goes in various `ConstantBuffer`s or `ParameterBlock`s.

There are two main pieces to the implementation.
First, we need to be able to compute appropriate layout information for entry points that include `uniform` parameters.
Second, we need to transform the entry point function to move any `uniform` parameters to be ordinary global-scope shader parameters, to make sure that all other back-end passes don't need to worry about this special case.

The latter piece of the implementation is, relatively speaking, simpler.
The pass in `ir-entry-point-uniforms.{h,cpp}` converts entry point parameters that are determined to be uniform (using the already-computed layout information) into fields of a `struct` type and then declares a global shader parameter based on that `struct` type (and applies already-computed layout information to that parameter).
After that, the remaining IR passes (notably including type legalization) will handle things just as for any other global shader parameter.

The changes to the layout step are more significant, but most of the changes are just cleanups and fixes to enable the feature.
The two major changes that enable entry-point `uniform` parameters are:

* In `collectEntryPointParameters` we now dispatch out to a new `computeEntryPointParameterTypeLayout` function, which decided whether to compute the type layout for a `uniform` parameter, or for a varying parameter (what used to be the default behavior handled by `processEntryPointParameterDecl`).

* The main `generateParameterBindings` routine was extended so that it allocates registers/bindings to the resources required by each entry point (using `completeBindingsForParameter`) after it has allocated registers/binding to all of the global-scope parameters (this addition is mirrored in `specializeProgramLayout`).

The effect of these changes is that the `uniform` parameters of any entry points specified in a compile request will be laid out after the global-scope parameters, in the order the entry points were specified in the compile request.

A bunch of smaller changes were made around parameter layout that are worth enumerating so that the diffs make some sense:

* The `EntryPointLayout` type was changed so that instead of trying to *be* a `StructTypeLayout`, it instead *owns* one, in the same fashion as `ProgramLayout`. This commonality was factored into a base class `ScopeLayout`, and a bunch of edits followed from that change.

* Because `uniform` parameters are moved out of the entry point parameter list early in the IR transformations, the logic in `ir-glsl-legalize.cpp` that tried to look up parameter layout information by index would no longer work if the entry point parameter list had been altered. Instead, that logic now looks for the decorations directly on the parameters.

* The `UsedRange` type in `parameter-binding.cpp` was tracking the existing parameter associated with a range using a `ParameterInfo*` (which accounts for the possibility of multiple `VarDecl`s mapping to the same logical shader parameter), when just using a `VarLayout*` is sufficient for all current use cases. The overhead of allocating a `ParameterInfo` seems like overkill for entry-point parameters, where there can't possibly be multiple declarations of the "same" parameter, so avoiding these overheads was a focus when trying to deduplicate code between the global and entry-point parameter cases.

* A bunch of parameter binding logic that was specific to GLSL input has been deleted completely. There was no way to even execute this code in the compiler today, and there is pretty much zero chance of us needing (or wanting) to deal with GLSL input in the future. This includes custom `UsedRangeSet`s specific to each translation unit, which were only needed for global-scope `in` and `out` varying declarations in GLSL.

* A bunch of functions with `EntryPointParameter` in their names were renamed to use `EntryPointVaryingParameter` to help distinguish that they only apply to the varying case, while entry point `uniform` parameters are handled elsewhere.

* The `completeBindingsForParameter` function was re-worked into something that can be used for both global-scope shader parameters (where we have a `ParameterInfo` and possibly explicit bindings) and entry-point parameters (where we expect to have neither). This helps unify the (fairly subtle) logic for how we allocate and assign bindings for resources, constant buffers, parameter blocks, etc.

* A small change was made so that the entry-point stage is attached directly to top-level parameters of the entry point, and *not* recursively to every field along the way. This could be a breaking change for some applications, but it makes more logical sense (to me); we'll have to check if this affects Falcor. This change produces different output for several of the reflection tests, but the changes are consistent with no longer attaching stage information to sub-fields of varying `struct`-type parameters.

* Because there is a bunch of repeated logic in `parameter-binding.cpp` that has to do with computing a `struct` layout for ordinary/uniform data, I tried to factor that into a single `ScopeLayoutBuilder` type, which handles computing the offsets for any parameters with ordinary data, and then also handles wrapping up the layout in a constant buffer layout if there was any ordinary data at the end.

* A similar convenience routine `maybeAllocateConstantBufferBinding` was added because I noticed multiple places in `parameter-binding.cpp` that were trying to allocate a constant buffer binding for global uniforms, and they were wildly inconsistent (and in most cases used logic that would only work for D3D).

* The main `generateParameterBindings` routine is significantly shortened by using all of these utilities that were introduced. I tried to comment the places that changed to explain the overall flow correctly.

* The `specializeProgramLayout` routine (used to take a `ProgramLayout` from `generateParameterBindings` and specialize it based on knowledge of global generic arguments) had basically been rewritten with more explicit commenting/rationale for what happens in each step. It makes use of the same shared utilities as `generateParameterBindings` and `collectEntryPointParameters`.

In terms of testing:

* I added a test case to specifically test the new behavior, and in particular I made sure to include a mix of both global and entry-point parameters and also to have entry-point parameters of both ordinary and resource/object types.

* I tweaked an existing test for global type parameters to use an entry-point `uniform` parameter instead of a global one, in an effort to migrate it toward being able to use an explicitly generic entry point.

* fixups from merge

1 files changed, 423 insertions, 0 deletions

diff --git a/source/slang/ir-entry-point-uniforms.cpp b/source/slang/ir-entry-point-uniforms.cpp
new file mode 100644
index 000000000..64deec1c5
--- /dev/null
+++ b/source/slang/ir-entry-point-uniforms.cpp
@@ -0,0 +1,423 @@
+// ir-entry-point-uniforms.cpp
+#include "ir-entry-point-uniforms.h"
+
+#include "ir.h"
+#include "ir-insts.h"
+
+#include "mangle.h"
+
+namespace Slang
+{
+
+
+// The transformation in this file will solve the problem of taking
+// code like the following:
+//
+//      float4 fragmentMain(
+//          uniform Texture2D    t,
+//          uniform SamplerState s;
+//          uniform float4       c,
+//                  float2       uv : UV) : SV_Target
+//      {
+//          return t.Sample(s, uv) + c;
+//      }
+//
+// and transforming into code like this:
+//
+//      struct Params
+//      {
+//          Texture2D    t;
+//          SamplerState s;
+//          float4       c;
+//      }
+//      ConstantBuffer<Params> params;
+//
+//      float4 fragmentMain(
+//          float2 uv : UV) : SV_Target
+//      {
+//          return params.t.Sample(params.s, uv) + params.c;
+//      }
+//
+// As can be seen in this example, the `uniform` parameters
+// declared as entry point parameters have been moved into
+// a `struct` declaration that we then use to declare a global
+// shader parameter that is a `ConstantBuffer`. We then
+// rewrite references to those parameters to refer to the
+// contents of the new constant buffer instead.
+//
+// We perform this transformation after the target-specific
+// linking step, because that will have attached layout information
+// to the entry point and its parameters. We need that layout
+// information so that we can:
+//
+// * Identify which parameters are uniform vs. varying.
+// * Have an appropriate layout to attached to the synthesized
+//   global shader parameter `params`.
+//
+// One additional wrinkle this pass has to deal with is that
+// in the case where the shader doesn't have any "ordinary"
+// uniform parameters like `c` (e.g., it only has resource/object
+// parameters), we do *not* wrap the parameter `struct` in
+// a `ConstantBuffer`. For example, suppose we have:
+//
+//      float4 fragmentMain(
+//          uniform Texture2D    t,
+//          uniform SamplerState s;
+//                  float2       uv : UV) : SV_Target
+//      {
+//          return t.Sample(s, uv);
+//      }
+//
+// In this case the output of the transformation shold be:
+//
+//      struct Params
+//      {
+//          Texture2D    t;
+//          SamplerState s;
+//      }
+//      Params params;
+//
+//      float4 fragmentMain(
+//          float2 uv : UV) : SV_Target
+//      {
+//          return params.t.Sample(params.s, uv) + params.c;
+//      }
+//
+// Note that this pass should always come before type legalization,
+// which will take responsibility for turning a variable like
+// `params` above into individual variables for the `t` and
+// `s` fields.
+
+// The overall structure here is similar to many other IR passes.
+// We define a "context" structure to encapsulate the pass.
+//
+struct MoveEntryPointUniformParametersToGlobalScope
+{
+    // We'll hang on to the module we are processing,
+    // so that we can refer to it when setting up `IRBuilder`s.
+    //
+    IRModule* module;
+
+    // We will process a whole module by visiting all
+    // its global functions, looking for entry points.
+    //
+    void processModule()
+    {
+        // Note that we are only looking at true global-scope
+        // functions and not functions nested inside of
+        // IR generics. When using generic entry points, this
+        // pass should be run after the entry point(s) have
+        // been specialized to their generic type parameters.
+
+        for( auto inst : module->getGlobalInsts() )
+        {
+            // We are only interested in entry points.
+            //
+            // Every entry point must be a function.
+            //
+            auto func = as<IRFunc>(inst);
+            if( !func )
+                continue;
+
+            // Entry points will always have the `[entryPoint]`
+            // decoration to differentiate them from ordinary
+            // functions.
+            //
+            // TODO: we could make `IREntryPoint` a subclass of
+            // `IRFunc` if desired, to avoid having to attach
+            // an explicit decoration to identify them.
+            //
+            if( !func->findDecorationImpl(kIROp_EntryPointDecoration) )
+                continue;
+
+            // If we fine a candidate entry point, then we
+            // will process it.
+            //
+            processEntryPoint(func);
+        }
+    }
+
+    void processEntryPoint(IRFunc* func)
+    {
+        // We expect all entry points to have explicit layout information attached.
+        //
+        // We will assert that we have the information we need, but try to be
+        // defensive and bail out in the failure case in release builds.
+        //
+        auto funcLayoutDecoration = func->findDecoration<IRLayoutDecoration>();
+        SLANG_ASSERT(funcLayoutDecoration);
+        if(!funcLayoutDecoration)
+            return;
+
+        auto entryPointLayout = dynamic_cast<EntryPointLayout*>(funcLayoutDecoration->getLayout());
+        SLANG_ASSERT(entryPointLayout);
+        if(!entryPointLayout)
+            return;
+
+        // The parameter layout for an entry point will either be a structure
+        // type layout, or a constant buffer (a case of parameter group)
+        // wrapped around such a structure.
+        //
+        // If we are in the latter case we will need to make sure to allocate
+        // an explicit IR constant buffer for that wrapper, 
+        //
+        auto entryPointParamsLayout = entryPointLayout->parametersLayout;
+        bool needConstantBuffer = entryPointParamsLayout->typeLayout.as<ParameterGroupTypeLayout>() != nullptr;
+
+        // We will set up an IR builder so that we are ready to generate code.
+        //
+        SharedIRBuilder sharedBuilderStorage;
+        auto sharedBuilder = &sharedBuilderStorage;
+        sharedBuilder->module = module;
+        sharedBuilder->session = module->getSession();
+
+        IRBuilder builderStorage;
+        auto builder = &builderStorage;
+        builder->sharedBuilder = sharedBuilder;
+
+        // *If* the entry point has any uniform parameter then we want to create a
+        // structure type to house them, and a global shader parameter (either
+        // an instance of that type or a constant buffer).
+        //
+        // We only want to create these if actually needed, so we will declare
+        // them here and then initialize them on-demand.
+        //
+        IRStructType* paramStructType = nullptr;
+        IRGlobalParam* globalParam = nullptr;
+
+        // We will be removing any uniform parameters we run into, so we
+        // need to iterate the parameter list carefully to deal with
+        // us modifying it along the way.
+        //
+        IRParam* nextParam = nullptr;
+        for( IRParam* param = func->getFirstParam(); param; param = nextParam )
+        {
+            nextParam = param->getNextParam();
+
+            // We expect all entry-point parameters to have layout information,
+            // but we will be defensive and skip parameters without the required
+            // information when we are in a release build.
+            //
+            auto layoutDecoration = param->findDecoration<IRLayoutDecoration>();
+            SLANG_ASSERT(layoutDecoration);
+            if(!layoutDecoration)
+                continue;
+            auto paramLayout = dynamic_cast<VarLayout*>(layoutDecoration->getLayout());
+            SLANG_ASSERT(paramLayout);
+            if(!paramLayout)
+                continue;
+
+            // A parameter that has varying input/output behavior should be left alone,
+            // since this pass is only supposed to apply to uniform (non-varying)
+            // parameters.
+            //
+            if(isVaryingParameter(paramLayout))
+                continue;
+
+            // At this point we know that `param` is not a varying shader parameter,
+            // so that we want to turn it into an equivalent global shader parameter.
+            //
+            // If this is the first parameter we are running into, then we need
+            // to deal with creating the structure type and global shader
+            // parameter that our transformed entry point will use.
+            //
+            if( !paramStructType )
+            {
+                // First we create the structure to hold the parameters.
+                //
+                builder->setInsertBefore(func);
+                paramStructType = builder->createStructType();
+
+                if( needConstantBuffer )
+                {
+                    // If we need a constant buffer, then the global
+                    // shader parameter will be a `ConstantBuffer<paramStructType>`
+                    //
+                    auto constantBufferType = builder->getConstantBufferType(paramStructType);
+                    globalParam = builder->createGlobalParam(constantBufferType);
+                }
+                else
+                {
+                    // Otherwise, the global shader parameter is just
+                    // an instance of `paramStructType`.
+                    //
+                    globalParam = builder->createGlobalParam(paramStructType);
+                }
+
+                // No matter what, the global shader parameter should have the layout
+                // information from the entry point attached to it, so that the
+                // contained parameters will end up in the right place(s).
+                //
+                builder->addLayoutDecoration(globalParam, entryPointParamsLayout);
+            }
+
+            // Now that we've ensured the global `struct` type and shader paramter
+            // exist, we need to add a field to the `struct` to represent the
+            // current parameter.
+            //
+
+            auto paramType = param->getFullType();
+
+            builder->setInsertBefore(paramStructType);
+            auto paramFieldKey = builder->createStructKey();
+            auto paramField = builder->createStructField(paramStructType, paramFieldKey, paramType);
+            SLANG_UNUSED(paramField);
+
+            // We will transfer all decorations on the parameter over to the key
+            // so that they can affect downstream emit logic.
+            //
+            // TODO: We should double-check whether any of the decorations should
+            // be moved to the *field* instead.
+            //
+            param->transferDecorationsTo(paramFieldKey);
+
+            // There is a bit of a hacky issue, where downstream passes (notably
+            // type legalization) require the field keys for `struct` types to
+            // have mangled names, because those mangled names will be used to
+            // lookup field layout information inside of the layout information
+            // for the `struct` type.
+            //
+            // TODO: We should fix that design choice in how layout information
+            // is stored, to avoid the reliance on name strings.
+            //
+            builder->addExportDecoration(paramFieldKey, getMangledName(paramLayout->varDecl).getUnownedSlice());
+
+            // At this point we want to eliminate the original entry point
+            // parameter, in favor of the `struct` field we declared.
+            // That required replacing any uses of the parameter with
+            // appropriate code to pull out the field.
+            //
+            // We *could* extract the field at the start of the shader
+            // and then do a `replaceAllUsesWith` to propragate it
+            // down, but in practice we expect that it is better for
+            // performance to "rematerialize" the value of a shader
+            // parameter as close to where it is used as possible.
+            //
+            // We are therefore going to replace the uses one at a time.
+            //
+            while(auto use = param->firstUse )
+            {
+                // Given a `use` of the paramter, we will insert
+                // the replacement code right before the instruction
+                // that is doing the using.
+                //
+                builder->setInsertBefore(use->getUser());
+
+                // The way to extract the field that corresponds
+                // to the parameter depends on whether or not
+                // we generated a constant buffer.
+                //
+                IRInst* fieldVal = nullptr;
+                if( needConstantBuffer )
+                {
+                    // A constant buffer behaves like a pointer
+                    // at the IR level, so we first do a pointer
+                    // offset operation to compute what amounts
+                    // to `&cb->field`, and then load from that address.
+                    //
+                    auto fieldAddress = builder->emitFieldAddress(
+                        builder->getPtrType(paramType),
+                        globalParam,
+                        paramFieldKey);
+                    fieldVal = builder->emitLoad(fieldAddress);
+                }
+                else
+                {
+                    // In the ordinary struct case, the parameter
+                    // has an ordinary `struct` type (not a pointer),
+                    // so we just extract the field directly.
+                    //
+                    fieldVal = builder->emitFieldExtract(
+                        paramType,
+                        globalParam,
+                        paramFieldKey);
+                }
+
+                // We replace the value used at this use site, which
+                // will have a side effect of making `use` no longer
+                // be on the list of uses for `param`, so that when
+                // we get back to the top of the loop the list of
+                // uses will be shorter.
+                //
+                use->set(fieldVal);
+            }
+
+            // Once we've replaced all the uses of `param`, we
+            // can go ahead and remove it completely.
+            //
+            param->removeAndDeallocate();
+        }
+    }
+
+    // We need to be able to determine if a parameter is logically
+    // a "varying" parameter based on its layout.
+    //
+    bool isVaryingParameter(VarLayout* layout)
+    {
+        // If *any* of the resources consumed by the parameter
+        // is a varying resource kind (e.g., varying input) then
+        // we consider the whole parameter to be varying.
+        //
+        // This is reasonable because there is no way to declare
+        // a parameter that mixes varying and non-varying fields.
+        //
+        for( auto resInfo : layout->resourceInfos )
+        {
+            if(isVaryingResourceKind(resInfo.kind))
+                return true;
+        }
+
+        // Varying parameters with "system value" semantics currently show up as
+        // consuming no resources, so we need to special-case that here.
+        //
+        // Note: an empty `struct` parameter would also show up the same way, but
+        // we should eliminate any such parameters later on during type legalization.
+        //
+        if(layout->resourceInfos.Count() == 0)
+            return true;
+
+        // if none of the above tests determined that the
+        // parameter was varying, then we can safely consider
+        // it to be non-varying (uniform):
+        return false;
+    }
+
+    // In order to determine whether a parameter is varying based on its
+    // layout, we need to know which resource kinds represent varying
+    // shader parameters.
+    //
+    bool isVaryingResourceKind(LayoutResourceKind kind)
+    {
+        switch( kind )
+        {
+        default:
+            return false;
+
+            // Note: The set of cases that are considered
+            // varying here would need to be extended if we
+            // add more fine-grained resource kinds (e.g.,
+            // if we ever add an explicit resource kind
+            // for geometry shader output streams).
+            //
+            // Ordinary varying input/output:
+        case LayoutResourceKind::VaryingInput:
+        case LayoutResourceKind::VaryingOutput:
+            //
+            // Ray-tracing shader input/output:
+        case LayoutResourceKind::CallablePayload:
+        case LayoutResourceKind::HitAttributes:
+        case LayoutResourceKind::RayPayload:
+            return true;
+        }
+    }
+};
+
+void moveEntryPointUniformParamsToGlobalScope(
+    IRModule*   module)
+{
+    MoveEntryPointUniformParametersToGlobalScope context;
+    context.module = module;
+    context.processModule();
+}
+
+}