Major overhaul of Renderer abstraction, to support a new example (#624)

The original goal here was to bring up a second example program: `model-viewer`.
While the existing `hello-world` example is enough to get somebody up to speed with the basics of the Slang API (as a drop-in replacement for `D3DCompile` or similar), it doesn't really show any of the big-picture stuff that Slang is meant to enable.
There wasn't any use of D3D12/Vulkan descriptor tables/sets, and there wasn't any use of interfaces, generics, or `ParameterBlock`s in the shader code.

The `model-viewer` example addresses these issues. Its shader code involves generics, interfaces, and multiple `ParameterBlock`s, and the host-side code demonstrates a few key things for working with Slang:

* There is an application-level abstraction for parameter blocks, that combines the graphics-API descriptor set object with Slang type information

* There is a shader cache layer used to look up an appropriate variant of a rendering effect by using parameter block types to "plug in" global type variables

* There is a clear separation between the phases of compilation: a first phase that does semantic checking and enables reflection-based allocation of graphics API objects, followed by one or more code generation passes for specialized kernels.

This example is certainly not perfect, and it will need to be revamped more going forward. In particular:

* The output picture is ugly as sin. We need a plan for how to get this to load better content, perhaps even popping up an error message to note that the required input data isn't present in the basic repository.

* The shader code is too simplistic. There isn't any real material variety, and the `IMaterial` abstraction is completely wrong.

* The use of parameter blocks is facile because there are no resource parameters right now. Fixing that will likely expose issues around interfacing with Slang's reflection API.

* The whole example exposes the issue that Slang's current APIs aren't really designed for the benefit of two-phase compilation (since our many client application has been stuck on one-phase compilation).

* Global type parameters are actually a Bad Idea that we only did for compatibility with existing codebases. We should not be showing them off in an example of the Right Way to use Slang, but the language support for type parameters on entry points is still not complete.

Of course, the majority of the changes here are *not* inside the example applications, and instead involve a major overhaul of the `Renderer` abstraction that is used for both tests and examples. The main thrust of the change is to make the abstraction layer be closer to the D3D12/Vulkan model than to a D3D11-style model. This is important for the `model-viewer` example, since it aspires to show how Slang can be incorporated into a renderer that targets a modern API. The most important bit is actually the use of descriptor sets and "pipeline layouts" a la Vulkan, since without these Slang's `ParameterBlock` abstraction won't make a lot of sense.

Implementation of the abstraction for the various APIs has very much been on an as-needed basis. The current implementation is just enough for the two examples to work, plus enough to get all the tests to pass in both debug and release builds on Windows.

A big missing feature in the API abstraction right now is memory lifetime management. The code had been trending toward something D3D11-like where a constant buffer could be mapped per-frame with the implementation doing behind-the-scenes allocation for targets like D3D12/Vulkan. I'd like to shift more toward a model of just exposing "transient" allocations that are only valid for one frame, because these are more representation of how an efficient renderer for next-generation APIs will work. That transition isn't actually complete, though, so there are problems with the existing examples where `hello-world` is actually scribbling into memory that the GPU might still be using, while `model-viewer` is doing full-on heavy-weight allocations on a per-frame basis with no real concern for the performance implications.

All together, there are a lot of things here that need more work, but this branch has been way too long-lived already, and so I'd like to get this checked in as long as all the tests pass.

7 files changed, 2055 insertions, 0 deletions

diff --git a/examples/model-viewer/README.md b/examples/model-viewer/README.md
new file mode 100644
index 000000000..a350a48a2
--- /dev/null
+++ b/examples/model-viewer/README.md
@@ -0,0 +1,25 @@
+Model Viewer Example
+====================
+
+This example expands on the simple Slang API integration from the "Hello, World" example by actually loading and rendering model data with extremely basic surface and light shading.
+
+This time, the shader code is making use of various Slang language features, so readers may want to read through `shaders.slang` to see an example of how the various mechanisms can be used to build out a more complicated shader library.
+While the shader code in this example is still simplistic, it shows examples of:
+
+* Using multiple Slang `ParameterBlock`s to manage the space of shader parameter bindings in a graphics-API-independent fashion, while still taking advantage of the performance opportunities afforded by D3D12 and Vulkan.
+
+* Using `interface`s and generics to express multiple variations of a feature with static specialization, in place of more traditional preprocessor techniques.
+
+The application code in `main.cpp` also shows a more advanced integration of the Slang API than that in the "Hello, World" example, including examples of:
+
+* Loading a library of Slang shader code to perform reflection on its types *without* specifying a particular entry point to generate code for
+
+* Using Slang's reflection information to allocate graphics-API objects to implement parameter blocks (e.g., D3D12/Vulkan descriptor tables/sets)
+
+* Performing on-demand specialization of Slang's generics using type information from parameter blocks to achieve simple shader specialization
+
+It is perhaps worth taking note of the two things this example intentionally does *not* do:
+
+* There is no use of the C-style preprocessor in the shader code presented, in order to demonstrate that shader specialization can be achieved without preprocessor techniques.
+
+* There is no use of explicit parameter binding decorations (e.g., HLSL `regsiter` or GLSL `layout` modifiers), in order to demonstrate that these are not needed in order to achieve high-performance shader parameter binding.
diff --git a/examples/model-viewer/cube.mtl b/examples/model-viewer/cube.mtl
new file mode 100644
index 000000000..6634af823
--- /dev/null
+++ b/examples/model-viewer/cube.mtl
@@ -0,0 +1,8 @@
+newmtl Material
+Ns 96.078431
+Ka 0.000000 0.000000 0.000000
+Kd 0.640000 0.640000 0.640000
+Ks 0.500000 0.500000 0.500000
+Ni 1.000000
+d 1.000000
+illum 2
diff --git a/examples/model-viewer/cube.obj b/examples/model-viewer/cube.obj
new file mode 100644
index 000000000..7226aaa77
--- /dev/null
+++ b/examples/model-viewer/cube.obj
@@ -0,0 +1,24 @@
+mtllib cube.mtl
+o Cube
+v  1.000000 -1.000000 -1.000000
+v  1.000000 -1.000000  1.000000
+v -1.000000 -1.000000  1.000000
+v -1.000000 -1.000000 -1.000000
+v  1.000000  1.000000 -1.000000
+v  1.000000  1.000000  1.000000
+v -1.000000  1.000000  1.000000
+v -1.000000  1.000000 -1.000000
+vn  0.000000 -1.000000  0.000000
+vn  0.000000  1.000000  0.000000
+vn  1.000000  0.000000  0.000000
+vn  0.000000  0.000000  1.000000
+vn -1.000000  0.000000  0.000000
+vn  0.000000  0.000000 -1.000000
+usemtl Material
+s off
+f 1//1 2//1 3//1 4//1
+f 5//2 8//2 7//2 6//2
+f 1//3 5//3 6//3 2//3
+f 2//4 6//4 7//4 3//4
+f 3//5 7//5 8//5 4//5
+f 5//6 1//6 4//6 8//6
diff --git a/examples/model-viewer/main.cpp b/examples/model-viewer/main.cpp
new file mode 100644
index 000000000..cd6b404ee
--- /dev/null
+++ b/examples/model-viewer/main.cpp
@@ -0,0 +1,1618 @@
+// main.cpp
+
+//
+// This example is much more involved than the `hello-world` example,
+// so readers are encouraged to work through the simpler code first
+// before diving into this application. We will gloss over parts of
+// the code that are similar to the code in `hello-world`, and
+// instead focus on the new code that is required to use Slang in
+// more advanced ways.
+//
+
+// We still need to include the Slang header to use the Slang API
+//
+#include <slang.h>
+
+// We will again make use of a simple graphics API abstraction
+// layer, just to keep the examples short and to the point.
+//
+#include "gfx/model.h"
+#include "gfx/render.h"
+#include "gfx/render-d3d11.h"
+#include "gfx/vector-math.h"
+#include "gfx/window.h"
+using namespace gfx;
+
+// We will use a few utilities from the C++ standard library,
+// just to keep the code short. Note that the Slang API does
+// not use or require any C++ standard library features.
+//
+#include <memory>
+#include <vector>
+
+// A larger application will typically want to load/compile
+// multiple modules/files of shader code. When using the
+// Slang API, some one-time setup work can be amortized
+// across multiple modules by using a single Slang
+// "session" across multiple compiles.
+//
+// To that end, our application will use a function-`static`
+// variable to create a session on demand and re-use it
+// for the duration of the application.
+//
+SlangSession* getSlangSession()
+{
+    static SlangSession* slangSession = spCreateSession(NULL);
+    return slangSession;
+}
+
+// This application is going to build its own layered
+// application-specific abstractions on top of Slang,
+// so it will have its own notion of a shader "module,"
+// which comprises the results of a Slang compilation,
+// including the reflection information.
+//
+struct ShaderModule : RefObject
+{
+    // The file that the module was loaded from.
+    std::string                 inputPath;
+
+    // Slang compile request and reflection data.
+    SlangCompileRequest*        slangRequest;
+    slang::ShaderReflection*    slangReflection;
+
+    // Reference to the renderer, used to service requests
+    // that load graphics API objects based on the module.
+    RefPtr<gfx::Renderer>       renderer;
+};
+//
+// In order to load a shader module from a `.slang` file on
+// disk, we will use a Slang compile session, much like
+// how the earlier Hello World example loaded shader code.
+//
+// We will point out major differences between the earlier
+// example's `loadShaderProgram()` function, and how this function
+// loads a module for reflection purposes.
+//
+RefPtr<ShaderModule> loadShaderModule(Renderer* renderer, char const* inputPath)
+{
+    auto slangSession = getSlangSession();
+    SlangCompileRequest* slangRequest = spCreateCompileRequest(slangSession);
+
+    // When *loading* the shader library, we will request that concrete
+    // kernel code *not* be generated, because the module might have
+    // unspecialized generic parameters. Instead, we will generate kernels
+    // on demand at runtime.
+    //
+    spSetCompileFlags(
+        slangRequest,
+        SLANG_COMPILE_FLAG_NO_CODEGEN);
+
+    // The main logic for specifying target information and loading source
+    // code is the same as before with the notable change that we are *not*
+    // specifying specific vertex/fragment entry points to compile here.
+    //
+    // Instead, the `[shader(...)]` attributes used in `shaders.slang` will
+    // identify the entry points in the shader library to the compiler with
+    // specific action needing to be taken in the application.
+    //
+    int targetIndex = spAddCodeGenTarget(slangRequest, SLANG_DXBC);
+    spSetTargetProfile(slangRequest, targetIndex, spFindProfile(slangSession, "sm_4_0"));
+    int translationUnitIndex = spAddTranslationUnit(slangRequest, SLANG_SOURCE_LANGUAGE_SLANG, nullptr);
+    spAddTranslationUnitSourceFile(slangRequest, translationUnitIndex, inputPath);
+    int compileErr = spCompile(slangRequest);
+    if(auto diagnostics = spGetDiagnosticOutput(slangRequest))
+    {
+        reportError("%s", diagnostics);
+    }
+    if(compileErr)
+    {
+        spDestroyCompileRequest(slangRequest);
+        spDestroySession(slangSession);
+        return nullptr;
+    }
+    auto slangReflection = (slang::ShaderReflection*) spGetReflection(slangRequest);
+
+    // We will not destroy the Slang compile request here, because we want to
+    // keep it around to service reflection quries made from the application code.
+    //
+    RefPtr<ShaderModule> module = new ShaderModule();
+    module->renderer = renderer;
+    module->inputPath = inputPath;
+    module->slangRequest = slangRequest;
+    module->slangReflection = slangReflection;
+    return module;
+}
+
+// Once a shader moduel has been loaded, it is possible to look up
+// individual entry points by their name to get reflection information,
+// including the stage for which the entry point was compiled.
+//
+// As with `ShaderModule` above, the `EntryPoint` type is the application's
+// wrapper around a Slang entry point. In this case it caches the
+// identity of the target stage as encoded for the graphics API.
+//
+struct EntryPoint : RefObject
+{
+    // Name of the entry point function
+    std::string name;
+
+    // Stage targetted by the entry point (Slang version)
+    SlangStage  slangStage;
+
+    // Stage targetted by the entry point (graphics API version)
+    gfx::StageType   apiStage;
+};
+//
+// Loading an entry point from a module is a straightforward
+// application of the Slang reflection API.
+//
+RefPtr<EntryPoint> loadEntryPoint(
+    ShaderModule*   module,
+    char const*     name)
+{
+    auto slangReflection = module->slangReflection;
+
+    // Look up the Slang entry point based on its name, and bail
+    // out with an error if it isn't found.
+    //
+    auto slangEntryPoint = slangReflection->findEntryPointByName(name);
+    if(!slangEntryPoint) return nullptr;
+
+    // Extract the stage of the entry point using the Slang API,
+    // and then try to map it to the corresponding stage as
+    // exposed by the graphics API.
+    //
+    auto slangStage = slangEntryPoint->getStage();
+    StageType apiStage = StageType::Unknown;
+    switch(slangStage)
+    {
+    default:
+        return nullptr;
+
+    case SLANG_STAGE_VERTEX:    apiStage = gfx::StageType::Vertex;   break;
+    case SLANG_STAGE_FRAGMENT:  apiStage = gfx::StageType::Fragment; break;
+    }
+
+    // Allocate an application object to hold on to this entry point
+    // so that we can use it in later specialization steps.
+    //
+    RefPtr<EntryPoint> entryPoint = new EntryPoint();
+    entryPoint->name = name;
+    entryPoint->slangStage = slangEntryPoint->getStage();
+    entryPoint->apiStage = apiStage;
+    return entryPoint;
+}
+
+// In this application a `Program` represents a combination of entry
+// points that will be used together (e.g., matching vertex and fragment
+// entry points).
+//
+// Along with the entry points themselves, the `Program` object will
+// cache information gleaned from Slang's reflection interface. Notably:
+//
+// * The number of `ParamterBlock`s that the program uses
+// * Information about generic (type) parameters
+//
+struct Program : RefObject
+{
+    // The shader module that the program was loaded from.
+    RefPtr<ShaderModule> shaderModule;
+
+    // The entry points that comprise the program
+    // (e.g., both a vertex and a fragment entry point).
+    std::vector<RefPtr<EntryPoint>> entryPoints;
+
+    // The number of parameter blocks that are used by the shader
+    // program. This will be used by our rendering code later to
+    // decide how many descriptor set bindings should affect
+    // specialization/execution using this program.
+    //
+    int parameterBlockCount;
+
+    // We will store information about the generic (type) parameters
+    // of the program. In particular, for each generic parameter
+    // we are going to find a parameter block that uses that
+    // generic type parameter.
+    //
+    // E.g., given input code like:
+    //
+    //      type_param A;
+    //      type_param B;
+    //
+    //      ParameterBlock<B>   x; // block 0
+    //      ParameterBlock<Foo> y; // block 1
+    //      ParameterBlock<A>   z; // block 2
+    //
+    // We would have two `GenericParam` entries. The first one,
+    // for `A`, would store a `parameterBlockIndex` of `2`, because
+    // `A` is used as the type of the `x` parameter block.
+    //
+    // This information will be used later when we want to specialize
+    // shader code, because if `z` is bound using a `ParameterBlock<Bar>`
+    // then we can infer that `A` should be bound to `Bar`.
+    //
+    struct GenericParam
+    {
+        int parameterBlockIndex;
+    };
+    std::vector<GenericParam>       genericParams;
+};
+//
+// As with entry points, loading a program is done with
+// the help of Slang's reflection API.
+//
+RefPtr<Program> loadProgram(
+    ShaderModule*       module,
+    int                 entryPointCount,
+    const char* const*  entryPointNames)
+{
+    auto slangReflection = module->slangReflection;
+
+    RefPtr<Program> program = new Program();
+    program->shaderModule = module;
+
+    // We will loop over the entry point names that were requested,
+    // loading each and adding it to our program.
+    //
+    for(int ee = 0; ee < entryPointCount; ++ee)
+    {
+        auto entryPoint = loadEntryPoint(module, entryPointNames[ee]);
+        if(!entryPoint)
+            return nullptr;
+        program->entryPoints.push_back(entryPoint);
+    }
+
+    // Next, we will look at the reflection information to see how
+    // many generic type parameters were declared, and allocate
+    // space in the `genericParams` array for them.
+    //
+    // We don't yet have enough information to fill in the
+    // `parameterBlockIndex` field.
+    //
+    auto genericParamCount = slangReflection->getTypeParameterCount();
+    for(unsigned int pp = 0; pp < genericParamCount; ++pp)
+    {
+        auto slangGenericParam = slangReflection->getTypeParameterByIndex(pp);
+
+        Program::GenericParam genericParam  = {};
+        program->genericParams.push_back(genericParam);
+    }
+
+    // We want to specialize our shaders based on what gets bound
+    // in parameter blocks, so we will scan the shader parameters
+    // looking for `ParameterBlock<G>` where `G` is one of our
+    // generic type parameters.
+    //
+    // We do this by iterating over *all* the global shader paramters,
+    // and looking for those that happen to be parameter blocks, and
+    // of those the ones where the "element type" of the parameter block
+    // is a generic type parameter.
+    //
+    auto paramCount = slangReflection->getParameterCount();
+    int parameterBlockCounter = 0;
+    for(unsigned int pp = 0; pp < paramCount; ++pp)
+    {
+        auto slangParam = slangReflection->getParameterByIndex(pp);
+
+        // Is it a parameter block? If not, skip it.
+        if(slangParam->getType()->getKind() != slang::TypeReflection::Kind::ParameterBlock)
+            continue;
+
+        // Okay, we've found another parameter block, so we can compute its zero-based index.
+        int parameterBlockIndex = parameterBlockCounter++;
+
+        // Get the element type of the parameter block, and if it isn't a generic type
+        // parameter, then skip it.
+        auto slangElementTypeLayout = slangParam->getTypeLayout()->getElementTypeLayout();
+        if(slangElementTypeLayout->getKind() != slang::TypeReflection::Kind::GenericTypeParameter)
+            continue;
+
+        // At this point we've found a `ParameterBlock<G>` where `G` is a `type_param`,
+        // so we can store the index of the parameter block back into our array of
+        // generic type parameter info.
+        //
+        auto genericParamIndex = slangElementTypeLayout->getGenericParamIndex();
+        program->genericParams[genericParamIndex].parameterBlockIndex = parameterBlockIndex;
+    }
+
+    // The above loop over the global shader parameters will have found all the
+    // parameter blocks that were specified in the shader code, so now we know
+    // how many parameter blocks are expected to be bound when this program is used.
+    //
+    program->parameterBlockCount = parameterBlockCounter;
+
+    return program;
+}
+//
+// As a convenience, we will define a simple wrapper around `loadProgram` for the case
+// where we have just two entry points, since that is what the application actually uses.
+//
+RefPtr<Program> loadProgram(ShaderModule* module, char const* entryPoint0, char const* entryPoint1)
+{
+    char const* entryPointNames[] = { entryPoint0, entryPoint1 };
+    return loadProgram(module, 2, entryPointNames);
+}
+
+// The `ParameterBlock<T>` type is supported by the Slang language and compiler,
+// but it is up to each application to map it down to whatever graphics API
+// abstraction is most fitting.
+//
+// For our application, a parameter block will be implemented as a combination
+// of Slang type reflection information (to determine the layout) plus a
+// graphics API descriptor set object.
+//
+// Note: the example graphics API abstraction we are using exposes descriptor sets
+// similar to those in Vulkan, and then maps these down to efficient alternatives
+// on other APIs including D3D12, D3D11, and OpenGL.
+//
+// Every parameter block is allocated based on a particular layout, and we
+// can share the same layout across multiple blocks:
+//
+struct ParameterBlockLayout : RefObject
+{
+    // The graphics API device that should be used to allocate parameter
+    // block instances.
+    //
+    RefPtr<gfx::Renderer>                renderer;
+
+    // The Slang type layout information that will be used to decide
+    // how much space is needed in instances of this layout.
+    //
+    // If the user declares a `ParameterBlock<Batman>` parameter, then
+    // this will be the type layout information for `Batman`.
+    //
+    slang::TypeLayoutReflection*    slangTypeLayout;
+
+    // The size of the "primary" constant buffer that will hold any
+    // "ordinary" (not-resource) fields in the `slangTypeLayout` above.
+    //
+    size_t                          primaryConstantBufferSize;
+
+    // API-specific layout information computes from `slangTypelayout`.
+    //
+    RefPtr<gfx::DescriptorSetLayout>     descriptorSetLayout;
+};
+//
+// A parameter block layout can be computed for any `struct` type
+// declared in the user's shade code. We extract the relevant
+// information from the type using the Slang reflection API.
+//
+RefPtr<ParameterBlockLayout> getParameterBlockLayout(
+    ShaderModule*   module,
+    char const*     name)
+{
+    auto slangReflection = module->slangReflection;
+    auto renderer = module->renderer;
+
+    // Look up the type with the given name, and bail out
+    // if no such type is found in the module.
+    //
+    auto type = slangReflection->findTypeByName(name);
+    if(!type) return nullptr;
+
+    // Request layout information for the type. Note that a single
+    // type might be laid out differently for different compilation
+    // targets, or based on how it is used (e.g., as a `cbuffer`
+    // field vs. in a `StructuredBuffer`).
+    //
+    auto typeLayout = slangReflection->getTypeLayout(type);
+    if(!typeLayout) return nullptr;
+
+    // If the type that is going in the parameter block has
+    // any ordinary data in it (as opposed to resources), then
+    // a constant buffer will be needed to hold that data.
+    //
+    // In turn any resource parameters would need to go into
+    // the descriptor set *after* this constant buffer.
+    //
+    size_t primaryConstantBufferSize = typeLayout->getSize(SLANG_PARAMETER_CATEGORY_UNIFORM);
+
+    // We need to use the Slang reflection information to
+    // create a graphics-API-level descriptor-set layout that
+    // is compatible with the original declaration.
+    //
+    std::vector<gfx::DescriptorSetLayout::SlotRangeDesc> slotRanges;
+
+    // If the type has any ordinary data, then the descriptor set
+    // will need a constant buffer to be the first thing it stores.
+    //
+    // Note: for a renderer only targetting D3D12, it might make
+    // sense to allocate this "primary" constant buffer as a root
+    // descriptor instead of inside the descriptor set (or at least
+    // do this *if* there are no non-uniform parameters). Policy
+    // decisions like that are up to the application, not Slang.
+    // This example application just does something simple.
+    //
+    if(primaryConstantBufferSize)
+    {
+        slotRanges.push_back(
+            gfx::DescriptorSetLayout::SlotRangeDesc(
+                gfx::DescriptorSlotType::UniformBuffer));
+    }
+
+    // Next, the application will recursively walk
+    // the structure of `typeLayout` to figure out what resource
+    // binding ranges are required for the target API.
+    //
+    // TODO: This application doesn't yet use any resource parameters,
+    // so we are skipping this step, but it is obviously needed
+    // for a fully fleshed-out example.
+
+    // Now that we've collected the graphics-API level binding
+    // information, we can construct a graphics API descriptor set
+    // layout.
+    gfx::DescriptorSetLayout::Desc descriptorSetLayoutDesc;
+    descriptorSetLayoutDesc.slotRangeCount = slotRanges.size();
+    descriptorSetLayoutDesc.slotRanges = slotRanges.data();
+    auto descriptorSetLayout = renderer->createDescriptorSetLayout(descriptorSetLayoutDesc);
+    if(!descriptorSetLayout) return nullptr;
+
+    RefPtr<ParameterBlockLayout> parameterBlockLayout = new ParameterBlockLayout();
+    parameterBlockLayout->renderer = renderer;
+    parameterBlockLayout->primaryConstantBufferSize = primaryConstantBufferSize;
+    parameterBlockLayout->slangTypeLayout = typeLayout;
+    parameterBlockLayout->descriptorSetLayout = descriptorSetLayout;
+    return parameterBlockLayout;
+}
+
+// A `ParameterBlock` abstracts over the allocated storage
+// for a descriptor set, based on some `ParameterBlockLayout`
+//
+struct ParameterBlock : RefObject
+{
+    // The graphics API device used to allocate this block.
+    RefPtr<gfx::Renderer>           renderer;
+
+    // The associated parameter block layout.
+    RefPtr<ParameterBlockLayout>    layout;
+
+    // The (optional) constant buffer that holds the values
+    // for any ordinay fields. This will be null if
+    // `layout->primaryConstantBufferSize` is zero.
+    RefPtr<BufferResource>          primaryConstantBuffer;
+
+    // The graphics-API descriptor set that provides storage
+    // for any resource fields.
+    RefPtr<gfx::DescriptorSet>           descriptorSet;
+
+    // Map/unmap operations are provided to access the
+    // contents of the primary constant buffer.
+    void* map();
+    void unmap();
+
+    // A a convenience, `pb->mapAs<X>()` map be used as
+    // a declaration of intent, instead of `(X*) pb->map()`
+    template<typename T>
+    T* mapAs() { return (T*)map(); }
+};
+
+// Allocating a parameter block is mostly a matter of allocating
+// the required graphics API objects.
+//
+RefPtr<ParameterBlock> allocateParameterBlockImpl(
+    ParameterBlockLayout*   layout)
+{
+    auto renderer = layout->renderer;
+
+    // A descriptor set is then used to provide the storage for all
+    // resource parameters (including the primary constant buffer, if any).
+    //
+    auto descriptorSet = renderer->createDescriptorSet(
+        layout->descriptorSetLayout);
+
+    // If the parameter block has any ordinary data, then it requires
+    // a "primary" constant buffer to hold that data.
+    //
+    RefPtr<gfx::BufferResource> primaryConstantBuffer = nullptr;
+    if(auto primaryConstantBufferSize = layout->primaryConstantBufferSize)
+    {
+        gfx::BufferResource::Desc bufferDesc;
+        bufferDesc.init(primaryConstantBufferSize);
+        bufferDesc.setDefaults(gfx::Resource::Usage::ConstantBuffer);
+        bufferDesc.cpuAccessFlags = gfx::Resource::AccessFlag::Write;
+        primaryConstantBuffer = renderer->createBufferResource(
+            gfx::Resource::Usage::ConstantBuffer,
+            bufferDesc);
+
+        // The primary constant buffer will always be the first thing
+        // stored in the descriptor set for a parameter block.
+        //
+        descriptorSet->setConstantBuffer(0, 0, primaryConstantBuffer);
+    }
+
+    // Now that we've allocated the graphics API objects, we can just
+    // allocate our application-side wrapper object to tie everything
+    // together.
+    //
+    RefPtr<ParameterBlock> parameterBlock = new ParameterBlock();
+    parameterBlock->renderer = renderer;
+    parameterBlock->layout = layout;
+    parameterBlock->primaryConstantBuffer = primaryConstantBuffer;
+    parameterBlock->descriptorSet = descriptorSet;
+    return parameterBlock;
+}
+
+// A full-featured high-performance application would likely draw
+// a distinction between "persistent" parameter blocks that are
+// filled in once and then used over many frames, and "transient"
+// blocks that are allocated, filled in, and discarded within
+// a single frame.
+//
+// These two cases warrant very different allocation strategies,
+// but for now we are using the same logic in both cases.
+//
+RefPtr<ParameterBlock> allocatePersistentParameterBlock(
+    ParameterBlockLayout*   layout)
+{
+    return allocateParameterBlockImpl(layout);
+}
+RefPtr<ParameterBlock> allocateTransientParameterBlock(
+    ParameterBlockLayout*   layout)
+{
+    return allocateParameterBlockImpl(layout);
+}
+
+// As described earlier, it is convenient to be able
+// to easily map the primary constant buffer of a parameter
+// block, since this will hold the values for any ordinary fields.
+//
+void* ParameterBlock::map()
+{
+    return renderer->map(
+        primaryConstantBuffer,
+        MapFlavor::WriteDiscard);
+}
+void ParameterBlock::unmap()
+{
+    renderer->unmap(primaryConstantBuffer);
+}
+
+// Our application code has a rudimentary material system,
+// to match the `IMaterial` abstraction used in the shade code.
+//
+struct Material : RefObject
+{
+    // The key feature of a matrial in our application is that
+    // it can provide a parameter block that describes it and
+    // its parameters. The contents of the parameter block will
+    // be any colors, textures, etc. that the material needs,
+    // while the Slang type that was used to allocate the
+    // block will be an implementation of `IMaterial` that
+    // provides the evaluation logic for the material.
+
+    // Each subclass of `Material` will provide a routine to
+    // create a parameter block of its chosen type/layout.
+    virtual RefPtr<ParameterBlock> createParameterBlock() = 0;
+
+    // The parameter block for a material will be stashed here
+    // after it is created.
+    RefPtr<ParameterBlock> parameterBlock;
+};
+
+// For now we have only a single implementation of `Material`,
+// which corresponds to the `SimpleMaterial` type in our shader
+// code.
+//
+struct SimpleMaterial : Material
+{
+    // The `SimpleMaterial` shader type has only uniform data,
+    // so we declare a `struct` type for that data here.
+    struct Uniforms
+    {
+        glm::vec3   diffuseColor;
+        float       pad;
+    };
+    Uniforms uniforms;
+
+    // When asked to create a parameter block, the `SimpleMaterial`
+    // type will allocate a block based on the corresponding
+    // shader type, and fill it in based on the data in the C++
+    // object.
+    //
+    RefPtr<ParameterBlock> createParameterBlock() override
+    {
+        auto parameterBlockLayout = gParameterBlockLayout;
+        auto parameterBlock = allocatePersistentParameterBlock(
+            parameterBlockLayout);
+
+        if(auto u = parameterBlock->mapAs<Uniforms>())
+        {
+            *u = uniforms;
+            parameterBlock->unmap();
+        }
+
+        return parameterBlock;
+    }
+
+    // We cache the corresponding parameter block layout for
+    // `SimpleMaterial` in a static variable so that we don't
+    // load it more than once.
+    //
+    static RefPtr<ParameterBlockLayout> gParameterBlockLayout;
+};
+RefPtr<ParameterBlockLayout> SimpleMaterial::gParameterBlockLayout;
+
+// With the `Material` abstraction defined, we can go on to define
+// the representation for loaded models that we will use.
+//
+// A `Model` will own vertex/index buffers, along with a list of meshes,
+// while each `Mesh` will own a material and a range of indices.
+// For this example we will be loading models from `.obj` files, but
+// that is just a simple lowest-common-denominator choice.
+//
+struct Mesh : RefObject 
+{
+    RefPtr<Material>    material;
+    int                 firstIndex;
+    int                 indexCount;
+};
+struct Model : RefObject
+{
+    typedef ModelLoader::Vertex Vertex;
+
+    RefPtr<BufferResource>      vertexBuffer;
+    RefPtr<BufferResource>      indexBuffer;
+    PrimitiveTopology           primitiveTopology;
+    int                         vertexCount;
+    int                         indexCount;
+    std::vector<RefPtr<Mesh>>   meshes;
+};
+//
+// Loading a model from disk is done with the help of some utility
+// code for parsing the `.obj` file format, so that the application
+// mostly just registers some callbacks to allocate the objects
+// used for its representation.
+//
+RefPtr<Model> loadModel(
+    Renderer*               renderer,
+    char const*             inputPath,
+    ModelLoader::LoadFlags  loadFlags = 0,
+    float                   scale = 1.0f)
+{
+    // The model loading interface using a C++ interface of
+    // callback functions to handle creating the application-specific
+    // representation of meshes, materials, etc.
+    //
+    struct Callbacks : ModelLoader::ICallbacks
+    {
+        void* createMaterial(MaterialData const& data) override
+        {
+            SimpleMaterial* material = new SimpleMaterial();
+            material->uniforms.diffuseColor = data.diffuseColor;
+
+            material->parameterBlock = material->createParameterBlock();
+
+            return material;
+        }
+
+        void* createMesh(MeshData const& data) override
+        {
+            Mesh* mesh = new Mesh();
+            mesh->firstIndex = data.firstIndex;
+            mesh->indexCount = data.indexCount;
+            mesh->material = (Material*)data.material;
+            return mesh;
+        }
+
+        void* createModel(ModelData const& data) override
+        {
+            Model* model = new Model();
+            model->vertexBuffer = data.vertexBuffer;
+            model->indexBuffer = data.indexBuffer;
+            model->primitiveTopology = data.primitiveTopology;
+            model->vertexCount = data.vertexCount;
+            model->indexCount = data.indexCount;
+
+            int meshCount = data.meshCount;
+            for(int ii = 0; ii < meshCount; ++ii)
+                model->meshes.push_back((Mesh*)data.meshes[ii]);
+
+            return model;
+        }
+    };
+    Callbacks callbacks;
+
+    // We instantiate a model loader object and then use it to
+    // try and load a model from the chosen path.
+    //
+    ModelLoader loader;
+    loader.renderer = renderer;
+    loader.loadFlags = loadFlags;
+    loader.scale = scale;
+    loader.callbacks = &callbacks;
+    Model* model = nullptr;
+    if(SLANG_FAILED(loader.load(inputPath, (void**)&model)))
+    {
+        log("failed to load '%s'\n", inputPath);
+        return nullptr;
+    }
+
+    return model;
+}
+
+// The core of our application's rendering abstraction is
+// the notion of an "effect," which ties together a particular
+// set of shader entry points (as a `Program`), with graphics
+// API state objects for the fixed-function parts of the pipeline.
+//
+// Note that the program here is an *unspecialized* program,
+// which might have unbound global `type_param`s. Thus the
+// `Effect` type here is not one-to-one with a "pipeline state
+// object," because the same effect could be used to instantiate
+// multiple pipeline state objects based on how things get
+// specialized.
+//
+struct Effect : RefObject
+{
+    // The shader program entry point(s) to execute
+    RefPtr<Program>     program;
+
+    // Additional state corresponding to the data needed
+    // to create a graphics-API pipeline state object.
+    RefPtr<gfx::InputLayout>    inputLayout;
+    Int                         renderTargetCount;
+};
+
+// In order to render using the `Effect` abstraction, our
+// application will be creating various specialized
+// shader kernels and pipeline states on-demand.
+//
+// We'll start with the representation of a specialized
+// "variant" of an effect.
+//
+struct EffectVariant : RefObject
+{
+    // The graphics API pipeline layout and state
+    // that need to be bound in order to use this
+    // effect.
+    //
+    RefPtr<gfx::PipelineLayout>  pipelineLayout;
+    RefPtr<gfx::PipelineState>   pipelineState;
+};
+//
+// A specialized variant is created based on a base effect
+// and the types that will be bound to its parameter blocks.
+//
+RefPtr<EffectVariant> createEffectVaraint(
+    Effect*                         effect,
+    UInt                            parameterBlockCount,
+    ParameterBlockLayout* const*    parameterBlockLayouts)
+{
+    // One note to make at the very start is that the creation
+    // of a specialized variant is based on the *layout* of
+    // the parameter blocks in use and not on the particular
+    // parameter blocks themselves. This is important because
+    // it means that, e.g., two materials that use the same code,
+    // but different parameter values (different textures, colors,
+    // etc.) do *not* require switching between different
+    // shader code or specialized PSOs.
+
+    // We'll start by extracting some of the pieces of
+    // information taht we need into local variables,
+    // just to simplify the remaining code.
+    //
+    auto program = effect->program;
+    auto shaderModule = program->shaderModule;
+    auto renderer = shaderModule->renderer;
+
+    // Our specialized effect is going to need a few things:
+    //
+    // 1. A specialized pipeline layout, based on the layout
+    // of the bound parameter blocks.
+    //
+    // 2. Specialized shader kernels, based on "plugging in"
+    // the parameter block types for generic type parameters
+    // as needed.
+    //
+    // 3. A specialized pipeline state object that ties the
+    // above items together with the fixed-function state
+    // already specified in the effect.
+    //
+    // We will now go through these steps in order.
+
+    // (1) The pipline layout (aka D3D12 "root signature") will
+    // be determined based on the descriptor-set layouts
+    // already cached in the given parameter block layouts.
+    //
+    std::vector<PipelineLayout::DescriptorSetDesc> descriptorSets;
+    for(UInt pp = 0; pp < parameterBlockCount; ++pp)
+    {
+        descriptorSets.emplace_back(
+            parameterBlockLayouts[pp]->descriptorSetLayout);
+    }
+    PipelineLayout::Desc pipelineLayoutDesc;
+    pipelineLayoutDesc.renderTargetCount = 1;
+    pipelineLayoutDesc.descriptorSetCount = descriptorSets.size();
+    pipelineLayoutDesc.descriptorSets = descriptorSets.data();
+    auto pipelineLayout = renderer->createPipelineLayout(pipelineLayoutDesc);
+
+    // (2) The final shader kernels to bind will be computed
+    // from the kernels we extracted into an application `EntryPoint`
+    // plus the types of the bound paramter blocks, as needed.
+    //
+    // We will "infer" a type argument for each of the generic
+    // parameters of our shader program by looking for a
+    // parameter block that is declared using that generic
+    // type.
+    //
+    std::vector<const char*> genericArgs;
+    for(auto gp : program->genericParams)
+    {
+        int parameterBlockIndex = gp.parameterBlockIndex;
+        auto typeName = parameterBlockLayouts[parameterBlockIndex]->slangTypeLayout->getName();
+        genericArgs.push_back(typeName);
+    }
+
+    // Now that we are ready to generate specialized shader code,
+    // we wil invoke the Slang compiler again. This time we leave
+    // full code generation turned on, and we also specify the
+    // entry points that we want explicitly (so that we don't
+    // generate code for any other entry points).
+    //
+    auto slangSession = getSlangSession();
+    SlangCompileRequest* slangRequest = spCreateCompileRequest(slangSession);
+    int targetIndex = spAddCodeGenTarget(slangRequest, SLANG_DXBC);
+    spSetTargetProfile(slangRequest, targetIndex, spFindProfile(slangSession, "sm_4_0"));
+    int translationUnitIndex = spAddTranslationUnit(slangRequest, SLANG_SOURCE_LANGUAGE_SLANG, nullptr);
+    spAddTranslationUnitSourceFile(slangRequest, translationUnitIndex, program->shaderModule->inputPath.c_str());
+
+    int entryPointCont = program->entryPoints.size();
+    for(int ii = 0; ii < entryPointCont; ++ii)
+    {
+        auto entryPoint = program->entryPoints[ii];
+
+        // We are using the `spAddEntryPointEx` API so that we
+        // can specify the type names to use for the generic
+        // type parameters of the program.
+        //
+        spAddEntryPointEx(
+            slangRequest,
+            translationUnitIndex,
+            entryPoint->name.c_str(),
+            entryPoint->slangStage,
+            genericArgs.size(),
+            genericArgs.data());
+    }
+
+    // We expect compilation to go through without a hitch, because the
+    // code was already statically checked back in `loadShaderModule()`.
+    // It is still possible for errors to arise if, e.g., the application
+    // tries to specialize code based on a type that doesn't implement
+    // a required interface.
+    //
+    int compileErr = spCompile(slangRequest);
+    if(auto diagnostics = spGetDiagnosticOutput(slangRequest))
+    {
+        reportError("%s", diagnostics);
+    }
+    if(compileErr)
+    {
+        spDestroyCompileRequest(slangRequest);
+        assert(!"unexected");
+        return nullptr;
+    }
+
+    // Once compilation is done we can extract the kernel code
+    // for each of the entry points, and set them up for passing
+    // to the graphics APIs loading logic.
+    //
+    std::vector<ISlangBlob*> kernelBlobs;
+    std::vector<gfx::ShaderProgram::KernelDesc> kernelDescs;
+    for(int ii = 0; ii < entryPointCont; ++ii)
+    {
+        auto entryPoint = program->entryPoints[ii];
+
+        ISlangBlob* blob = nullptr;
+        spGetEntryPointCodeBlob(slangRequest, ii, 0, &blob);
+
+        kernelBlobs.push_back(blob);
+
+        ShaderProgram::KernelDesc kernelDesc;
+
+        char const* codeBegin = (char const*) blob->getBufferPointer();
+        char const* codeEnd = codeBegin + blob->getBufferSize();
+
+        kernelDesc.stage = entryPoint->apiStage;
+        kernelDesc.codeBegin = codeBegin;
+        kernelDesc.codeEnd = codeEnd;
+
+        kernelDescs.push_back(kernelDesc);
+    }
+
+    // Once we've extracted the "blobs" of compiled code,
+    // we are done with the Slang compilation request.
+    //
+    // Note that all of our reflection was performed on the unspecialized
+    // shader code at load time, but we know that information is still
+    // applicable to specialized kernels because of the guarantees
+    // the Slang compiler makes about type layout.
+    //
+    spDestroyCompileRequest(slangRequest);
+
+    // We use the graphics API to load a program into the GPU
+    gfx::ShaderProgram::Desc programDesc;
+    programDesc.pipelineType = gfx::PipelineType::Graphics;
+    programDesc.kernels = kernelDescs.data();
+    programDesc.kernelCount = kernelDescs.size();
+    auto specializedProgram = renderer->createProgram(programDesc);
+
+    // Then we unload our "blobs" of kernel code once the graphics
+    // API is doen with their data.
+    //
+    for(auto blob : kernelBlobs)
+    {
+        blob->release();
+    }
+
+    // (3) We construct a full graphics API pipeline state
+    // object that combines our new program and pipeline layout
+    // with the other state objects from the `Effect`.
+    //
+    gfx::GraphicsPipelineStateDesc pipelineStateDesc = {};
+    pipelineStateDesc.program = specializedProgram;
+    pipelineStateDesc.pipelineLayout = pipelineLayout;
+    pipelineStateDesc.inputLayout = effect->inputLayout;
+    pipelineStateDesc.renderTargetCount = effect->renderTargetCount;
+    auto pipelineState = renderer->createGraphicsPipelineState(pipelineStateDesc);
+
+    RefPtr<EffectVariant> variant = new EffectVariant();
+    variant->pipelineLayout = pipelineLayout;
+    variant->pipelineState = pipelineState;
+    return variant;
+}
+
+// A more advanced application might add logic to
+// pre-populate the shader cache with shader variants
+// that were compiled offline.
+//
+struct ShaderCache : RefObject
+{
+    struct VariantKey
+    {
+        Effect*                 effect;
+        UInt                    parameterBlockCount;
+        ParameterBlockLayout*   parameterBlockLayouts[8];
+
+        // In order to be used as a hash-table key, our
+        // variant key representation must support
+        // equality comparison and a matching hashin function.
+
+        bool operator==(VariantKey const& other) const
+        {
+            if(effect != other.effect) return false;
+            if(parameterBlockCount != other.parameterBlockCount) return false;
+            for( UInt ii = 0; ii < parameterBlockCount; ++ii )
+            {
+                if(parameterBlockLayouts[ii] != other.parameterBlockLayouts[ii]) return false;
+            }
+            return true;
+        }
+
+        UInt GetHashCode() const
+        {
+            auto hash = ::GetHashCode(effect);
+            hash = combineHash(hash, ::GetHashCode(parameterBlockCount));
+            for( UInt ii = 0; ii < parameterBlockCount; ++ii )
+            {
+                hash = combineHash(hash, ::GetHashCode(parameterBlockLayouts[ii]));
+            }
+            return hash;
+        }
+    };
+
+    // The shader cache is mostly just a dictionary mapping
+    // variant keys to the associated variant, generated on-demand.
+    //
+    // TODO: A more advanced application might support removing
+    // entries from the shader cache when effects get unloaded,
+    // or in order to respond to operations like a "hot reload"
+    // key in a development build (e.g., just clear the
+    // cache of variants and allow the ordinary loading logic
+    // to re-populate it).
+    //
+    Dictionary<VariantKey, RefPtr<EffectVariant> > variants;
+
+    // Getting a variant is just a matter of looking for an
+    // existing entry in the dictionary, and creating one
+    // on demand in case of a miss.
+    //
+    RefPtr<EffectVariant> getEffectVariant(
+        VariantKey const&   key)
+    {
+        RefPtr<EffectVariant> variant;
+        if(variants.TryGetValue(key, variant))
+            return variant;
+
+        variant = createEffectVaraint(
+            key.effect,
+            key.parameterBlockCount,
+            key.parameterBlockLayouts);
+
+        variants.Add(key, variant);
+        return variant;
+    }
+};
+
+
+// In order to render using the `Effect` abstraction, our
+// application will use its own rendering context type
+// to manage the state that it is binding. This layer
+// performs a small amount of shadowing on top of the
+// underlying graphics API.
+//
+// Note: for the purposes of our examples the "graphcis API"
+// in a cross-platform abstraction over multiple APIs, but
+// we do not actually advocate that real applications should
+// be built in terms of distinct layers for cross-platform
+// GPU API abstraction and "effect" state management.
+//
+// A high-performance application built on top of this approach
+// would instead implement the concepts like `ParameterBlock`
+// and `RenderContext` on a per-API basis, making use of
+// whatever is most efficeint on that API without any
+// additional abstraction layers in between.
+//
+// We've done things differently in this example program in
+// order to avoid getting bogged down in the specifics of
+// any one GPU API.
+//
+// With that disclaimer out of the way, let's talk through
+// the `RenderContext` type in this application.
+//
+struct RenderContext
+{
+private:
+    // The `RenderContext` type is used to wrap the graphics
+    // API "context" or "command list" type for submission.
+    // Our current abstraction layer lumps this all together
+    // with the "device."
+    //
+    RefPtr<gfx::Renderer>               renderer;
+
+    // We also retain a pointer to the shader cache, which
+    // will be used to implement lookup of the right
+    // effect variant to execute based on bound parameter
+    // blocks.
+    //
+    RefPtr<ShaderCache>     shaderCache;
+
+    // We will establish a small upper bound on how many
+    // parameter blocks can be used simultaneously. In
+    // practice, most shaders won't need more than about
+    // four parameter blocks, and attempting to use more
+    // than that under Vulkan can cause portability issues.
+    //
+    enum { kMaxParameterBlocks = 8 };
+
+    // The overall "state" of the rendering context consists of:
+    //
+    // * The currently selected "effect"
+    // * The parameter blocks that are used to specialize and
+    //   provide parameters for that effects.
+    //
+    RefPtr<Effect>                  effect;
+    RefPtr<ParameterBlock>          parameterBlocks[kMaxParameterBlocks];
+
+    // Along with the retained state above, we also store
+    // state in exactly the form required for looking up
+    // an effect variant in our shader cache, to minimize
+    // the work that needs to be done when looking up state.
+    //
+    ShaderCache::VariantKey variantKey;
+
+    // When state gets changed, we track a few dirty flags rather than
+    // flush changes to the GPU right away.
+
+    // Tracks whether any state has changed in a way that requires computing
+    // and binding a new GPU pipeline state object (PSO).
+    //
+    // E.g., changing the current effect would set this flag, but changing
+    // a parameter block binding to one with a new layout would also set the flag.
+    bool                    pipelineStateDirty = true;
+
+    // The `minDirtyBlockBinding` flag tracks the lowest-numbered parameter
+    // block binding that needs to be flushed to the GPU. That is, if
+    // parameters blocks [0,N) have been bound to the GPU, and then the user
+    // tries to set block K, then the range [0,K-1) will be left alone,
+    // while the range [K,N) needs to be set again.
+    //
+    // This is an optimization that can be exploited on the Vulkan API
+    // (and potentially others) if switching pipeline layouts doesn't invalidate
+    // all currently-bound descriptor sets.
+    //
+    int                     minDirtyBlockBinding = 0;
+
+    // Finally, we cache the specialized effect variant that has been
+    // most recently bound to the GPU state, so that we can use the
+    // information it stores (specifically the pipeline layout) when
+    // binding descriptor sets.
+    //
+    RefPtr<EffectVariant>   currentEffectVariant;
+
+public:
+    // Initializing a render context just sets its pointer to the GPU API device
+    RenderContext(
+        gfx::Renderer*  renderer,
+        ShaderCache*    shaderCache)
+        : renderer(renderer)
+        , shaderCache(shaderCache)
+    {}
+
+    void setEffect(
+        Effect* inEffect)
+    {
+        // Bail out if nothing is changing.
+        if( inEffect == effect )
+            return;
+
+        effect = inEffect;
+        variantKey.effect = effect;
+        variantKey.parameterBlockCount = effect->program->parameterBlockCount;
+
+        // Binding a new effect invalidates the current state object, since
+        // it will be a specialization of some other effect.
+        //
+        pipelineStateDirty = true;
+    }
+
+    void setParameterBlock(
+        int             index,
+        ParameterBlock* parameterBlock)
+    {
+        // Bail out if nothing is changing.
+        if(parameterBlock == parameterBlocks[index])
+            return;
+
+        parameterBlocks[index] = parameterBlock;
+
+        // This parameter block needs to be bound to the GPU, and any
+        // parameter blocks after it in the list will also get re-bound
+        // (even if they haven't changed). This is a reasonable choice
+        // if parameter blocks are ordered based on expected frequency
+        // of update (so that lower-numbered blocks change less often).
+        //
+        minDirtyBlockBinding = std::min(index, minDirtyBlockBinding);
+
+        // Next, check if the layout for the block we just bound
+        // is different than the one that was in place before,
+        // as stored in the "variant key"
+        //
+        auto layout = parameterBlock->layout;
+        if(layout.Ptr() == variantKey.parameterBlockLayouts[index])
+            return;
+
+        variantKey.parameterBlockLayouts[index] = layout;
+
+        // Changing the layout of a parameter block (which includes
+        // the underlying Slang type) requires computing a new
+        // pipeline state object, because it may lead to differently
+        // specialized code being generated.
+        //
+        pipelineStateDirty = true;
+    }
+
+    void flushState()
+    {
+        // The `flushState()` operation must be used by the application
+        // any time it binds a different effect or parameter block(s),
+        // to ensure that the GPU state is fully configured for rendering.
+        // It is thus important that this function do as little work
+        // as possible, especially in the common case where state
+        // doesn't actually need to change.
+        //
+        // The first check we do is to see if any change might require
+        // a different set of shader kernels.
+        //
+        if(pipelineStateDirty)
+        {
+            pipelineStateDirty = false;
+
+            // Almost all of the logic for retrieving or creating
+            // a new pipeline state with specialized kernels is
+            // handled by our shader cache.
+            //
+            // In the common case, the desired variant will already
+            // be present in the cache, and this function returns
+            // without much effort.
+            //
+            auto variant = shaderCache->getEffectVariant(variantKey);
+
+            // In order to adapt to a change in shader variant,
+            // we simply bind its PSO into the GPU state, and
+            // remember the variant we've selected.
+            //
+            renderer->setPipelineState(PipelineType::Graphics, variant->pipelineState);
+            currentEffectVariant = variant;
+        }
+
+        // Even if the current pipeline state was fine, we may need to
+        // bind one or more descriptor sets. We do this by walking
+        // from our lowest-numbered "dirty" set up to the number
+        // of sets expected by the current effect and binding them.
+        //
+        // If `minDirtyBlockBinding` is greater than or equal to the
+        // `parameterBlockCount` of the currently bound effect, then
+        // this will be a no-op.
+        //
+        // The common case in a tight drawing loop will be that only
+        // the last block will be dirty, and we will only execute
+        // one iteration of this loop.
+        //
+        auto program = effect->program;
+        auto parameterBlockCount = program->parameterBlockCount;
+        auto pipelineLayout = currentEffectVariant->pipelineLayout;
+        for(int ii = minDirtyBlockBinding; ii < parameterBlockCount; ++ii)
+        {
+            renderer->setDescriptorSet(
+                PipelineType::Graphics,
+                pipelineLayout,
+                ii,
+                parameterBlocks[ii]->descriptorSet);
+        }
+        minDirtyBlockBinding = parameterBlockCount;
+    }
+};
+
+// We will again structure our example application as a C++ `struct`,
+// so that we can scope its allocations for easy cleanup, rather than
+// use global variables.
+//
+struct ModelViewer {
+
+Window* gWindow;
+RefPtr<gfx::Renderer> gRenderer;
+RefPtr<gfx::ResourceView> gDepthTarget;
+
+// We keep a pointer to the one effect we are using (for a forward
+// rendering pass), plus the parameter-block layouts for our `PerView`
+// and `PerModel` shader types.
+//
+RefPtr<Effect> gEffect;
+RefPtr<ParameterBlockLayout> gPerViewParameterBlockLayout;
+RefPtr<ParameterBlockLayout> gPerModelParameterBlockLayout;
+
+RefPtr<ShaderCache> shaderCache;
+
+// Most of the application state is stored in the list of loaded models.
+//
+std::vector<RefPtr<Model>> gModels;
+
+// During startup the application will load one or more models and
+// add them to the `gModels` list.
+//
+void loadAndAddModel(
+    char const*             inputPath,
+    ModelLoader::LoadFlags  loadFlags = 0,
+    float                   scale = 1.0f)
+{
+    auto model = loadModel(gRenderer, inputPath, loadFlags, scale);
+    if(!model) return;
+    gModels.push_back(model);
+}
+
+int gWindowWidth = 1024;
+int gWindowHeight = 768;
+
+// For this more complex example we will be passing multiple
+// parameter blocks into the shader code, and each will
+// need its own `struct` type the define the layout of the
+// uniform data.
+//
+struct PerView
+{
+    glm::mat4x4 viewProjection;
+
+    glm::vec3   lightDir;
+    float       pad0;
+
+    glm::vec3   lightColor;
+    float       pad1;
+};
+struct PerModel
+{
+    glm::mat4x4 modelTransform;
+    glm::mat4x4 inverseTransposeModelTransform;
+};
+
+// The overall initialization logic is quite similar to
+// the earlier example. The biggest difference is that we
+// create instances of our application-specific parameter
+// block layout and effect types instead of just creating
+// raw graphics API objects.
+//
+Result initialize()
+{
+    WindowDesc windowDesc;
+    windowDesc.title = "Model Viewer";
+    windowDesc.width = gWindowWidth;
+    windowDesc.height = gWindowHeight;
+    gWindow = createWindow(windowDesc);
+
+    gRenderer = createD3D11Renderer();
+    Renderer::Desc rendererDesc;
+    rendererDesc.width = gWindowWidth;
+    rendererDesc.height = gWindowHeight;
+    gRenderer->initialize(rendererDesc, getPlatformWindowHandle(gWindow));
+
+    InputElementDesc inputElements[] = {
+        {"POSITION", 0, Format::RGB_Float32, offsetof(Model::Vertex, position) },
+        {"NORMAL",   0, Format::RGB_Float32, offsetof(Model::Vertex, normal) },
+        {"UV",       0, Format::RG_Float32,  offsetof(Model::Vertex, uv) },
+    };
+    auto inputLayout = gRenderer->createInputLayout(
+        &inputElements[0],
+        3);
+    if(!inputLayout) return SLANG_FAIL;
+
+    // Because we are rendering more than a single triangle this time, we
+    // require a depth buffer to resolve visibility.
+    //
+    TextureResource::Desc depthBufferDesc = gRenderer->getSwapChainTextureDesc();
+    depthBufferDesc.format = Format::D_Float32;
+    depthBufferDesc.setDefaults(Resource::Usage::DepthWrite);
+    auto depthTexture = gRenderer->createTextureResource(
+        Resource::Usage::DepthWrite,
+        depthBufferDesc);
+    if(!depthTexture) return SLANG_FAIL;
+
+    ResourceView::Desc textureViewDesc;
+    textureViewDesc.type = ResourceView::Type::DepthStencil;
+    auto depthTarget = gRenderer->createTextureView(depthTexture, textureViewDesc);
+    if (!depthTarget) return SLANG_FAIL;
+
+    gDepthTarget = depthTarget;
+
+    // Unlike the earlier example, we will not generate final shader kernel
+    // code during initialization. Instead, we simply load the shader module
+    // so that we can perform reflection and allocate resources.
+    //
+    auto shaderModule = loadShaderModule(gRenderer, "shaders.slang");
+    if(!shaderModule) return SLANG_FAIL;
+
+    // Once the shader code has been loaded, we can look up types declared
+    // in the shader code by name and perform reflection on them to determine
+    // parameter block layouts, etc.
+    //
+    // A more advanced application might load this information on-demand
+    // and potentially tie into an application-level reflection system
+    // that already knows the string names of its types (e.g., to connect
+    // the `PerView` type in shader code to the `PerView` type declared
+    // in the application code).
+    //
+    gPerViewParameterBlockLayout = getParameterBlockLayout(
+        shaderModule, "PerView");
+    gPerModelParameterBlockLayout = getParameterBlockLayout(
+        shaderModule, "PerModel");
+    //
+    // Note how we are able to load the type definition for `SimpleMaterial`
+    // from the Slang shader module even though the `SimpleMaterial` type
+    // is not actually *used* by any entry point in the file.
+    //
+    SimpleMaterial::gParameterBlockLayout = getParameterBlockLayout(
+        shaderModule, "SimpleMaterial");
+
+    // We also load a shader program based on vertex/fragment shaders in our
+    // module, and then use this to create an application-level effect.
+    //
+    // Note that the `loadProgram` operation here does *not* invoke any
+    // Slang compilation, because the shader module was already completely
+    // parsed, checked, etc. by the logic in `loadShaderModule()` above.
+    //
+    auto program = loadProgram(shaderModule, "vertexMain", "fragmentMain");
+    if(!program) return SLANG_FAIL;
+
+    RefPtr<Effect> effect = new Effect();
+    effect->program = program;
+    effect->inputLayout = inputLayout;
+    effect->renderTargetCount = 1;
+    gEffect = effect;
+
+    // In order to create specialized variants of the effect(s) that
+    // get used for rendering, we will use a shader cache.
+    //
+    shaderCache = new ShaderCache();
+
+    // Once we have created all our graphcis API and application resources,
+    // we can start to load models. For now we are keeping things extremely
+    // simple by using a trivial `.obj` file that can be checked into source
+    // control.
+    //
+    // Support for loading more interesting/complex models will be added
+    // to this example over time (although model loading is *not* the focus).
+    //
+    loadAndAddModel("cube.obj");
+
+    showWindow(gWindow);
+
+    return SLANG_OK;
+}
+
+// With the setup work done, we can look at the per-frame rendering
+// logic to see how the application will drive the `RenderContext`
+// type to perform both shader parameter binding and code specialization.
+//
+void renderFrame()
+{
+    // In order to see that things are rendering properly we need some
+    // kind of animation, so we will compute a crude delta-time value here.
+    //
+    static uint64_t lastTime = getCurrentTime();
+    uint64_t currentTime = getCurrentTime();
+    float deltaTime = float(currentTime - lastTime) / float(getTimerFrequency());
+    lastTime = currentTime;
+
+    // We will use the GLM library to do the matrix math required
+    // to set up our various transformation matrices.
+    //
+    glm::mat4x4 identity = glm::mat4x4(1.0f);
+
+    glm::mat4x4 projection = glm::perspective(
+        glm::radians(60.0f),
+        float(gWindowWidth) / float(gWindowHeight),
+        0.1f,
+        1000.0f);
+
+    glm::mat4x4 view = identity;
+    view = translate(view, glm::vec3(0, 0, -5));
+
+    glm::mat4x4 viewProjection = projection * view;
+
+    // We set up a light source with a simple animation applied
+    // to its direction.
+    //
+    glm::vec3 lightDir = normalize(glm::vec3(10, 10, -10));
+    glm::vec3 lightColor = glm::vec3(1, 1, 1);
+    static float angle = 0.0f;
+    angle += 0.5f * deltaTime;
+    glm::mat4x4 lightTransform = identity;
+    lightTransform = rotate(lightTransform, angle, glm::vec3(0, 1, 0));
+    lightDir = glm::vec3(lightTransform * glm::vec4(lightDir, 0));
+
+    // Some of the basic rendering setup is identical to the previous example.
+    //
+    static const float kClearColor[] = { 0.25, 0.25, 0.25, 1.0 };
+    gRenderer->setClearColor(kClearColor);
+    gRenderer->clearFrame();
+    gRenderer->setDepthStencilTarget(gDepthTarget);
+    gRenderer->setPrimitiveTopology(PrimitiveTopology::TriangleList);
+
+    // Now we will start in on the more interesting rendering logic,
+    // by creating the `RenderContext` we will use for submission.
+    //
+    // Note: in a multi-threaded submission case, the application would
+    // need to use a distinct `RenderContext` on each thread.
+    //
+    RenderContext context(gRenderer, shaderCache);
+
+    // Next we set the effect that we will use for our forward rendering
+    // pass. Note that an example with multiple passes would use a
+    // distinct effect for each pass.
+    //
+    context.setEffect(gEffect);
+
+    // We are only rendering one view, so we can fill in a per-view
+    // parameter block once and use it across all draw calls.
+    // This parameter block will be different every frame, so we
+    // allocate a transient parameter block rather than try to
+    // carefully track and re-use an allocation.
+    //
+    auto viewParameterBlock = allocateTransientParameterBlock(
+        gPerViewParameterBlockLayout);
+    if(auto perView = viewParameterBlock->mapAs<PerView>())
+    {
+        perView->viewProjection = viewProjection;
+        perView->lightDir = lightDir;
+        perView->lightColor = lightColor;
+
+        viewParameterBlock->unmap();
+    }
+    //
+    // Note: the assignment of indices to parameter blocks is driven
+    // by their order of declaration in the shader code, so we know
+    // that the per-view parameter block has index zero. Alternatively,
+    // an application could use reflection API operations to look up
+    // the index of a parameter block based on its name.
+    //
+    context.setParameterBlock(0, viewParameterBlock);
+
+    // The majority of our rendering logic is handled as a loop
+    // over the models in the scene, and their meshes.
+    //
+    for(auto& model : gModels)
+    {
+        gRenderer->setVertexBuffer(0, model->vertexBuffer, sizeof(Model::Vertex));
+        gRenderer->setIndexBuffer(model->indexBuffer, Format::R_UInt32);
+
+        // For each model we provide a parameter
+        // block that holds the per-model transformation
+        // parameters, corresponding to the `PerModel` type
+        // in the shader code.
+        //
+        // Like the view parameter block, it makes sense
+        // to allocate this block as a transient allocation,
+        // since its contents would be different on the next
+        // frame anyway.
+        //
+        glm::mat4x4 modelTransform = identity;
+        glm::mat4x4 inverseTransposeModelTransform = inverse(transpose(modelTransform));
+
+        auto modelParameterBlock = allocateTransientParameterBlock(
+            gPerModelParameterBlockLayout);
+        if(auto perModel = modelParameterBlock->mapAs<PerModel>())
+        {
+            perModel->modelTransform = modelTransform;
+            perModel->inverseTransposeModelTransform = inverseTransposeModelTransform;
+
+            modelParameterBlock->unmap();
+        }
+        context.setParameterBlock(1, modelParameterBlock);
+
+        // Now we loop over the meshes in the model.
+        //
+        // A more advanced rendering loop would sort things by material
+        // rather than by model, to avoid overly frequent state changes.
+        // We are just doing something simple for the purposes of an
+        // exmple program.
+        //
+        for(auto& mesh : model->meshes)
+        {
+            // Each mesh has a material, and each material has its own
+            // parameter block that was created at load time, so we
+            // can just re-use the persistent parameter block for the
+            // chosen material.
+            //
+            // Note that binding the material parameter block here is
+            // both selecting the values to use for various material
+            // parameters as well as the *code* to use for material
+            // evaluation (based on the concrete shader type that
+            // is implementing the `IMaterial` interface).
+            //
+            context.setParameterBlock(
+                2,
+                mesh->material->parameterBlock);
+
+            // Once we've set up all the parameter blocks needed
+            // for a given drawing operation, we need to flush
+            // any pending state changes (e.g., if the type of
+            // material changed, a shader switch might be
+            // required).
+            //
+            context.flushState();
+
+            gRenderer->drawIndexed(mesh->indexCount, mesh->firstIndex);
+        }
+    }
+
+    gRenderer->presentFrame();
+}
+
+void finalize()
+{
+    // Because we've stored a reference to some graphics API objects
+    // in a class-static variable (effectively a global) we need
+    // to clear those out before tearing down the application so
+    // that we aren't relying on C++ global destructors to tear
+    // down our application cleanly.
+    //
+    SimpleMaterial::gParameterBlockLayout = nullptr;
+}
+
+};
+
+void innerMain(ApplicationContext* context)
+{
+    ModelViewer app;
+    if(SLANG_FAILED(app.initialize()))
+    {
+        exitApplication(context, 1);
+    }
+
+    while(dispatchEvents(context))
+    {
+        app.renderFrame();
+    }
+
+    app.finalize();
+}
+GFX_UI_MAIN(innerMain)
diff --git a/examples/model-viewer/model-viewer.vcxproj b/examples/model-viewer/model-viewer.vcxproj
new file mode 100644
index 000000000..ea7ee1521
--- /dev/null
+++ b/examples/model-viewer/model-viewer.vcxproj
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <ItemGroup Label="ProjectConfigurations">
+    <ProjectConfiguration Include="Debug|Win32">
+      <Configuration>Debug</Configuration>
+      <Platform>Win32</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Debug|x64">
+      <Configuration>Debug</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|Win32">
+      <Configuration>Release</Configuration>
+      <Platform>Win32</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|x64">
+      <Configuration>Release</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+  </ItemGroup>
+  <PropertyGroup Label="Globals">
+    <ProjectGuid>{639B13F2-CF07-CFEC-98FB-664A0427F154}</ProjectGuid>
+    <IgnoreWarnCompileDuplicatedFilename>true</IgnoreWarnCompileDuplicatedFilename>
+    <Keyword>Win32Proj</Keyword>
+    <RootNamespace>model-viewer</RootNamespace>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <CharacterSet>Unicode</CharacterSet>
+    <PlatformToolset>v140</PlatformToolset>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <CharacterSet>Unicode</CharacterSet>
+    <PlatformToolset>v140</PlatformToolset>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <CharacterSet>Unicode</CharacterSet>
+    <PlatformToolset>v140</PlatformToolset>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <CharacterSet>Unicode</CharacterSet>
+    <PlatformToolset>v140</PlatformToolset>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+  <ImportGroup Label="ExtensionSettings">
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets" Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <PropertyGroup Label="UserMacros" />
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <LinkIncremental>true</LinkIncremental>
+    <OutDir>..\..\bin\windows-x86\debug\</OutDir>
+    <IntDir>..\..\intermediate\windows-x86\debug\model-viewer\</IntDir>
+    <TargetName>model-viewer</TargetName>
+    <TargetExt>.exe</TargetExt>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <LinkIncremental>true</LinkIncremental>
+    <OutDir>..\..\bin\windows-x64\debug\</OutDir>
+    <IntDir>..\..\intermediate\windows-x64\debug\model-viewer\</IntDir>
+    <TargetName>model-viewer</TargetName>
+    <TargetExt>.exe</TargetExt>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <LinkIncremental>false</LinkIncremental>
+    <OutDir>..\..\bin\windows-x86\release\</OutDir>
+    <IntDir>..\..\intermediate\windows-x86\release\model-viewer\</IntDir>
+    <TargetName>model-viewer</TargetName>
+    <TargetExt>.exe</TargetExt>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <LinkIncremental>false</LinkIncremental>
+    <OutDir>..\..\bin\windows-x64\release\</OutDir>
+    <IntDir>..\..\intermediate\windows-x64\release\model-viewer\</IntDir>
+    <TargetName>model-viewer</TargetName>
+    <TargetExt>.exe</TargetExt>
+  </PropertyGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
+    <ClCompile>
+      <PrecompiledHeader>NotUsing</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <AdditionalIncludeDirectories>..\..;..\..\tools;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <DebugInformationFormat>EditAndContinue</DebugInformationFormat>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <ClCompile>
+      <PrecompiledHeader>NotUsing</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <AdditionalIncludeDirectories>..\..;..\..\tools;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <DebugInformationFormat>EditAndContinue</DebugInformationFormat>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebug</RuntimeLibrary>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
+    <ClCompile>
+      <PrecompiledHeader>NotUsing</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <AdditionalIncludeDirectories>..\..;..\..\tools;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <Optimization>Full</Optimization>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+      <MinimalRebuild>false</MinimalRebuild>
+      <StringPooling>true</StringPooling>
+      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <ClCompile>
+      <PrecompiledHeader>NotUsing</PrecompiledHeader>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <AdditionalIncludeDirectories>..\..;..\..\tools;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <Optimization>Full</Optimization>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+      <MinimalRebuild>false</MinimalRebuild>
+      <StringPooling>true</StringPooling>
+      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemGroup>
+    <ClCompile Include="main.cpp" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="shaders.slang" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\source\slang\slang.vcxproj">
+      <Project>{DB00DA62-0533-4AFD-B59F-A67D5B3A0808}</Project>
+    </ProjectReference>
+    <ProjectReference Include="..\..\source\core\core.vcxproj">
+      <Project>{F9BE7957-8399-899E-0C49-E714FDDD4B65}</Project>
+    </ProjectReference>
+    <ProjectReference Include="..\..\tools\gfx\gfx.vcxproj">
+      <Project>{222F7498-B40C-4F3F-A704-DDEB91A4484A}</Project>
+    </ProjectReference>
+  </ItemGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+  <ImportGroup Label="ExtensionTargets">
+  </ImportGroup>
+</Project>
\ No newline at end of file
diff --git a/examples/model-viewer/model-viewer.vcxproj.filters b/examples/model-viewer/model-viewer.vcxproj.filters
new file mode 100644
index 000000000..a02cb79fc
--- /dev/null
+++ b/examples/model-viewer/model-viewer.vcxproj.filters
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <ItemGroup>
+    <Filter Include="Source Files">
+      <UniqueIdentifier>{E9C7FDCE-D52A-8D73-7EB0-C5296AF258F6}</UniqueIdentifier>
+    </Filter>
+  </ItemGroup>
+  <ItemGroup>
+    <ClCompile Include="main.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="shaders.slang">
+      <Filter>Source Files</Filter>
+    </None>
+  </ItemGroup>
+</Project>
\ No newline at end of file
diff --git a/examples/model-viewer/shaders.slang b/examples/model-viewer/shaders.slang
new file mode 100644
index 000000000..b79636d15
--- /dev/null
+++ b/examples/model-viewer/shaders.slang
@@ -0,0 +1,178 @@
+// shaders.slang
+
+//
+// This example builds on the simplistic shaders presented in the
+// "Hello, World" example by adding support for (intentionally
+// simplistic) surface materil and light shading.
+//
+// The code here is not meant to exemplify state-of-the-art material
+// and lighting techniques, but rather to show how a shader
+// library can be developed in a modular fashion without reliance
+// on the C preprocessor manual parameter-binding decorations.
+//
+
+// We will start with a `struct` for per-view parameters that
+// will be allocated into a `ParameterBlock`.
+//
+// As written, this isn't very different from using an HLSL
+// `cbuffer` declaration, but importantly this code will
+// continue to work if we add one or more resources (e.g.,
+// an enironment map texture) to the `PerView` type.
+//
+struct PerView
+{
+    float4x4    viewProjection;
+
+    float3      lightDir;
+    float3      lightColor;
+};
+ParameterBlock<PerView>     gViewParams;
+
+// Declaring a block for per-model parameter data is
+// similarly simple.
+//
+struct PerModel
+{
+    float4x4    modelTransform;
+    float4x4    inverseTransposeModelTransform;
+};
+ParameterBlock<PerModel>    gModelParams;
+
+
+// Next, we are going to demonstrate a simplistic interface
+// for surface materials. As written, materials can only
+// determine how to compute the diffuse color component
+// of a surface; a more advanced example would fold
+// the entire BRDF into the material interface.
+//
+interface IMaterial
+{
+    float3 getDiffuseColor();
+};
+
+// In order for our shader to be able to take a material
+// as a parameter, we need to declare a `ParameterBlock<M>`
+// for some material type `M`. Rather than hard-code the
+// specific material type to use, or select one via the
+// preprocessor, we will use Slang's support for generics,
+// by defining a "global type parameter":
+//
+type_param TMaterial : IMaterial;
+//
+// This declaration declares a shader parameter `TMaterial`
+// that is a to-be-determined *type*. The `TMaterial`
+// type parameter is *constrained* to only support types
+// that implement our `IMaterial` interface.
+//
+// With the `TMaterial` parameter declared, we can
+// declare that our shader takes as input a parameter block
+// containing material data:
+//
+ParameterBlock<TMaterial>   gMaterial;
+
+// For now, we will define only a single implementation
+// of the `IMaterial` interface, which is a simple material
+// with a uniform diffuse color:
+//
+struct SimpleMaterial : IMaterial
+{
+    float3 diffuseColor;
+
+    float3 getDiffuseColor()
+    {
+        return diffuseColor;
+    }
+};
+//
+// Note that no other code in this file statically
+// references the `SimpleMaterial` type, and instead
+// it is up to the application to "plug in" this type,
+// or another `IMaterial` implementation for the
+// `TMaterial` parameter.
+//
+
+// Our vertex shader entry point is only marginally more
+// complicated than the Hello World example. We will
+// start by declaring the various "connector" `struct`s.
+//
+struct AssembledVertex
+{
+    float3 position : POSITION;
+    float3 normal   : NORMAL;
+    float2 uv       : UV;
+};
+struct CoarseVertex
+{
+    float3 worldPosition;
+    float3 worldNormal;
+    float2 uv;
+};
+struct VertexStageOutput
+{
+    CoarseVertex    coarseVertex    : CoarseVertex;
+    float4          sv_position     : SV_Position;
+};
+
+// Perhaps most interesting new feature of the entry
+// point decalrations is that we use a `[shader(...)]`
+// attribute (as introduced in HLSL Shader Model 6.x)
+// in order to tag our entry points.
+//
+// This attribute informs the Slang compiler which
+// functions are intended to be compiled as shader
+// entry points (and what stage they target), so that
+// the programmer no longer needs to specify the
+// entry point name/stage through the API (or on
+// the command line when using `slangc`).
+//
+// While HLSL added this feature only in newer versions,
+// the Slang compiler supports this attribute across
+// *all* targets, so that it is okay to use whether you
+// want DXBC, DXIL, or SPIR-V output.
+//
+[shader("vertex")]
+VertexStageOutput vertexMain(
+    AssembledVertex assembledVertex)
+{
+    VertexStageOutput output;
+
+    float3 position = assembledVertex.position;
+    float3 normal   = assembledVertex.normal;
+    float2 uv       = assembledVertex.uv;
+
+    float3 worldPosition = mul(gModelParams.modelTransform, float4(position, 1.0)).xyz;
+    float3 worldNormal = mul(gModelParams.inverseTransposeModelTransform, float4(normal, 0.0)).xyz;
+
+    output.coarseVertex.worldPosition = worldPosition;
+    output.coarseVertex.worldNormal   = worldNormal;
+    output.coarseVertex.uv            = uv;
+
+    output.sv_position = mul(gViewParams.viewProjection, float4(worldPosition, 1.0));
+
+    return output;
+}
+
+// Our fragment shader is almost trivial, with the most interesting
+// thing being how it uses the `TMaterial` type parameter (through the
+// value stored in the `gMaterial` parameter block) to dispatch to
+// the correct implementation of the `getDiffuseColor()` method
+// in the `IMaterial` interface.
+//
+// The `gMaterial` parameter block declaration thus serves not only
+// to group certain shader parameters for efficient CPU-to-GPU
+// communication, but also to select the code that will execute
+// in specialized versions of the `fragmentMain` entry point.
+//
+[shader("fragment")]
+float4 fragmentMain(
+    CoarseVertex coarseVertex : CoarseVertex) : SV_Target
+{
+    float3 N = normalize(coarseVertex.worldNormal);
+    float3 L = normalize(gViewParams.lightDir);
+
+    float4 color;
+    color.xyz = gMaterial.getDiffuseColor() * max(0, dot(N, L));
+    color.w = 1.0f;
+
+    return color;
+}