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.

1 files changed, 21 insertions, 10 deletions

diff --git a/README.md b/README.md
index a9e01340d..01d88eae1 100644
--- a/README.md
+++ b/README.md
@@ -3,18 +3,22 @@
 [![AppVeyor build status](https://ci.appveyor.com/api/projects/status/3jptgsry13k6wdwp/branch/master?svg=true)](https://ci.appveyor.com/project/shader-slang/slang/branch/master) [![Travis build status](https://travis-ci.org/shader-slang/slang.svg?branch=master)](https://travis-ci.org/shader-slang/slang)
 
 Slang is a shading language that extends HLSL with new capabilities for building modular, extensible, and high-performance real-time shading systems.
-This repository provides a command-line compiler and a plain C API for loading, compiling, and reflecting shader code in Slang or plain HLSL.
+This repository provides a command-line compiler and a C/C++ API for loading, compiling, and reflecting shader code in Slang or plain HLSL.
 
-Using Slang you can:
+The extensions provided by the Slang language make it easier for you to write high-performance shader codebases with a maintainable and modular structure. For example:
 
-* Compile your HLSL or Slang code to DX bytecode, SPIR-V, or plain source code in HLSL or GLSL (DXIL support is planned).
+* Parameter blocks (exposed as `ParameterBlock<T>`) let you group together related shader parameters -- both simple uniform values and resources like samplers/textures - in ordinary `struct` types, and then specify that they should be passed to the GPU as a single coherent block. Your application code can easily map a parameter block to abstractions like descriptor tables/sets on D3D12/Vulkan, or to the facilities provided by other APIs.
+
+* Generics and interfaces can be used to perform static specialization of your shader code without resort to preprocessor techniques or string-pasting. Unlike C++ templates, Slang's generics can be checked ahead of time and don't produce cascading error messages that are difficult to diagnose. The same generic shader can be specialized for a variety of different types to produce specialized code ahead of time, or on the fly, completely under application control.
+
+The Slang implementation in this repository provides a library and a stand-alone compiler for Slang that can be used to:
+
+* Compile your HLSL or Slang code to DX bytecode, DXIL, SPIR-V, or plain source code in HLSL or GLSL.
 
 * Get full reflection information about the parameters of your shader code, with a consistent interface no matter the target graphics API. Slang doesn't silently drop unused or "dead" shader parameters from the reflection data, so you can always see the full picture.
 
 * Take ordinary HLSL code that neglects to include all those tedious `register` and `layout` bindings, and transform it into code that includes explicit bindings on every shader parameter. This frees you to write simple and clean code, while still getting completely deterministic binding locations.
 
-* Write shading code that uses first-class support for modules, interfaces, and generics to build clean and reusable shader libraries.
-
 ## Getting Started
 
 The fastest way to get started with Slang is to use a pre-built binary package, available through GitHub [releases](https://github.com/shader-slang/slang/releases).
@@ -25,6 +29,14 @@ If you would like to build Slang from source, please consult the instructions [h
 
 ## Documentation
 
+For users getting started with Slang, it may help to start by looking at our example programs:
+
+* The [`hello-world`](examples/hello-world/) example shows the basics for integrating the Slang API into an application as a more-or-less drop-in replacement for `D3DCompile`.
+
+* The [`model-viewer`](examples/model-viewer/) example shows a more involved rendering application that uses Slang's new language features to perform efficient shader specialization and parameter binding while maintaining clear and modular shader code.
+
+A [paper](http://graphics.cs.cmu.edu/projects/slang/) on the Slang system was accepted into SIGGRAPH 2018, and it provides an overview of the language and the design of the impelemtnation.
+
 The Slang [language guide](docs/language-guide.md) provides information on extended language features that Slang provides for user code.
 
 The [API user's guide](docs/api-users-guide.md) gives information on how to drive Slang programmatically from an application.
@@ -34,15 +46,15 @@ Be warned, however, that the command-line tool is primarily intended for experim
 
 ## Limitations
 
-The Slang project is in a very early state, so there are many rough edges to be aware of.
+The Slang project is in an early state, so there are many rough edges to be aware of.
 Slang is *not* currently recommended for production use.
 The project is intentionally on a pre-`1.0.0` version to reflect the fact that interfaces and features may change at any time (though we try not to break user code without good reason).
 
 Major limitations to be aware of (beyond everything files in the issue tracker):
 
-* Slang only supports outputting GLSL/SPIR-V for Vulkan, not OpenGL
+* Slang only officially supports outputting GLSL/SPIR-V for Vulkan, not OpenGL
 
-* Slang's current approach to automatically assigning registers is appropriate to D3D12, but not D3D11
+* Slang's current approach to automatically assigning registers is appropriate to D3D12, and is not ideal for D3D11
 
 * Slang-to-GLSL cross-compilation only supports vertex, fragment, and compute shaders. Geometry and tessellation shader cross-compilation is not yet implemented.
 
@@ -66,7 +78,6 @@ The Slang code itself is under the MIT license (see [LICENSE](LICENSE)).
 
 The Slang projet can be compiled to use the [`glslang`](https://github.com/KhronosGroup/glslang) project as a submodule (under `external/glslang`), and `glslang` is under a BSD license.
 
-The Slang tests (which are not distributed with source/binary releases) include example shaders extracted from:
-* Sample HLSL shaders from the Microsoft DirectX SDK, which has its own license
+The Slang tests (which are not distributed with source/binary releases) include example HLSL shaders extracted from the Microsoft DirectX SDK, which has its own license
 
 Some of the Slang examples and tests use the `stb_image` and `stb_image_write` libraries (under `external/stb`) which have been placed in the public domain by their author(s).