From 23d0c8910dfeab0bfa6fd8fa6c2450452bc25d3c Mon Sep 17 00:00:00 2001
From: Yong He <yonghe@outlook.com>
Date: Thu, 29 Apr 2021 14:20:20 -0700
Subject: Add gfx user's guide. (#1824)

* Add gfx user's guide.

* Add getting started chapter in gfx-guide

* Fixes

* Fix

* Polishing doc template
---
 docs/_layouts/user-guide.html             | 175 +++++++++++++--
 docs/assets/css/style.scss                |  18 +-
 docs/gfx-user-guide/01-getting-started.md | 342 ++++++++++++++++++++++++++++++
 docs/gfx-user-guide/build_toc.ps1         |   9 +
 docs/gfx-user-guide/index.md              |  25 +++
 docs/gfx-user-guide/nav.html              |   5 +
 docs/gfx-user-guide/toc.html              |  18 ++
 docs/scripts/Program.cs                   | 207 ++++++++++++++++++
 docs/user-guide/build_toc.ps1             |   2 +-
 docs/user-guide/nav.html                  |   6 +
 docs/user-guide/scripts/Program.cs        | 164 --------------
 docs/user-guide/toc.html                  |  88 ++++++++
 docs/user-guide/user-guide-toc.html       |  87 --------
 13 files changed, 874 insertions(+), 272 deletions(-)
 create mode 100644 docs/gfx-user-guide/01-getting-started.md
 create mode 100644 docs/gfx-user-guide/build_toc.ps1
 create mode 100644 docs/gfx-user-guide/index.md
 create mode 100644 docs/gfx-user-guide/nav.html
 create mode 100644 docs/gfx-user-guide/toc.html
 create mode 100644 docs/scripts/Program.cs
 create mode 100644 docs/user-guide/nav.html
 delete mode 100644 docs/user-guide/scripts/Program.cs
 create mode 100644 docs/user-guide/toc.html
 delete mode 100644 docs/user-guide/user-guide-toc.html

(limited to 'docs')

diff --git a/docs/_layouts/user-guide.html b/docs/_layouts/user-guide.html
index af48da693..c744c6462 100644
--- a/docs/_layouts/user-guide.html
+++ b/docs/_layouts/user-guide.html
@@ -13,10 +13,40 @@
   <style>
     #centeringDiv {
       margin: auto;
-      max-width: 1000px;
-      padding-left: 350px;
+      max-width: 1200px;
+    }
+    #navDiv
+    {
+      display: block;
+      box-sizing: border-box;
+      padding-top: 5px;
+      padding-bottom: 5px;
+      border-bottom-width: 3px;
+      border-bottom-style: solid;
+      border-bottom-color: #F0F0F0;
+    }
+    #navDiv nav
+    {
+      float:left;
+    }
+    #navDiv::after {
+      content: "";
+      clear: both;
+      display: table;
+    }
+    #navDiv nav li::after
+    {
+      content: "/";
+      padding-left: 10px;
+      padding-right: 0px;
+      color: #808080;
+    }
+    #navDiv nav li
+    {
+      display:inline;
+      padding-left: 10px;
+      padding-right: 0px;
     }
-
     #tocColumn {
       width: 350px;
       position: fixed;
@@ -31,12 +61,9 @@
     }
 
     #rightColumn {
-      padding-left: 40px;
+      padding-left: 390px;
       padding-right: 40px;
       padding-top: 20px;
-      border-left-width: 1.5px;
-      border-left-style: solid;
-      border-left-color: #C8C8C8;
     }
 
     .toc_root_list {
@@ -73,7 +100,22 @@
     }
     .toc_span:hover
     {
-      color: #303080
+      color: #3030BE
+    }
+    .tocIcon
+    {
+      vertical-align: -2.5px;
+    }
+    .editButton
+    {
+      float: right;
+      margin-right: 10px;
+      color:#808080;
+    }
+    .editIcon
+    {
+      fill: currentColor;
+      vertical-align: text-top;
     }
     #btnToggleTOC {
       display: none;
@@ -84,14 +126,22 @@
       border-style: solid;
       border-color: #808080;
       border-width: 1px;
+      background-color: #E8E8E8;
     }
-    @media screen and (max-width: 850px) {
+    #btnToggleTOC:hover {
+      background-color: #F0F0E8;
+    }
+    #btnToggleTOC:active {
+      background-color: #D4D4D4;
+    }
+    @media screen and (max-width: 900px) {
       #tocColumn {
         width: 300px;
         display: block;
       }
-      #centeringDiv {
-         padding-left: 300px;
+      #rightColumn {
+        padding-left: 320px;
+        padding-right: 20px;
       }
     }
 
@@ -100,6 +150,7 @@
         width: 100%;
         position: static;
         display: none;
+        border-right-style: none;
       }
       #tocInner {
         padding: 10px;
@@ -120,18 +171,34 @@
 </head>
 
 <body>
-    <button id="btnToggleTOC" onclick="toggleTOC()">Table of Contents</button>
+  <div id="centeringDiv">
+    <div id="navDiv">
+    {% include_relative nav.html %}
+    <a class="editButton" title="Edit this page" href="https://github.com/{{ site.github.repository_nwo }}/edit/{{ site.branch }}/docs/{{ page.path }}">
+      <svg class="editIcon" height="16" viewBox="0 0 16 16" version="1.1" width="16" aria-hidden="true">
+        <path fill-rule="evenodd"
+          d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z">
+        </path>
+      </svg>
+    </a>
+    </div>
+    <button id="btnToggleTOC" onclick="toggleTOC()">
+      <svg height="16" class="tocIcon" viewBox="0 0 16 16" version="1.1" width="16" aria-hidden="true">
+        <path fill-rule="evenodd"
+          d="M2 4a1 1 0 100-2 1 1 0 000 2zm3.75-1.5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zm0 5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zm0 5a.75.75 0 000 1.5h8.5a.75.75 0 000-1.5h-8.5zM3 8a1 1 0 11-2 0 1 1 0 012 0zm-1 6a1 1 0 100-2 1 1 0 000 2z">
+        </path>
+      </svg>
+      Table of Contents</button>
     <div id="tocColumn">
       <div id="tocInner">
-        {% include_relative user-guide-toc.html %}
+        {% include_relative toc.html %}
       </div>
     </div>
-    <div id="centeringDiv">
-      <div id="rightColumn">
+    <div id="rightColumn">
         <section id="main_content">
           {% include anchor_headings.html html=content anchorBody="" %}
         </section>
-
+        <a href="javascript:;" id="_content_end_"></a>
         <footer>
           {% if site.github.is_project_page %}
           {{ site.title | default: site.github.repository_name }} is maintained by <a
@@ -142,20 +209,40 @@
       </div>
     </div>
   <script>
+    // Fix for IE. Make sure String has `startsWith` method.
+    if (!String.prototype.startsWith)
+    {
+      String.prototype.startsWith = function (searchString, position) {
+        position = position || 0;
+        return this.indexOf(searchString, position) === position;
+      };
+    }
+
     var tocColumn = document.getElementById("tocColumn");
     var rightColumn = document.getElementById("rightColumn");
+    function updateScroll()
+    {
+      if (window.innerWidth < 700)
+      {
+        tocColumn.style.height = "";
+        return;
+      }
+      var top = Math.max(0, rightColumn.getBoundingClientRect().top);
+      tocColumn.style.top = top + "px";
+      tocColumn.style.height = (window.innerHeight-top) + "px";
+    }
     function updatePosition()
     {
       if (window.innerWidth > 700)
         tocColumn.style.display = "";
-      tocColumn.style.left = (rightColumn.getBoundingClientRect().x - tocColumn.getBoundingClientRect().width) + "px";
+      tocColumn.style.left = rightColumn.getBoundingClientRect().left + "px";
+      updateScroll();
     }
     window.addEventListener("resize", updatePosition);
     updatePosition();
-  </script>
 
-  <script>
     var tocItemsArray = [];
+    var subSectionItems = [];
     var selectedItem = null;
     function toggleTOC() {
       var tocColumn = document.getElementById("tocColumn");
@@ -249,6 +336,56 @@
         curItem.getAttribute("class").startsWith("toc_root_list"))
         break;
     }
+
+    var subItems = selectedItem.getElementsByTagName("li");
+    var subSectionTitles = [];
+    var subSectionTitleStrs = [];
+    for (var i = 0; i < subItems.length; i++)
+    {
+      subSectionItems.push(subItems[i]);
+      var title = subItems[i].getAttribute("data-link");
+      var pos = title.lastIndexOf("#");
+      title = title.substr(pos + 1);
+      var element = document.getElementById(title);
+      subSectionTitles.push(element);
+      subSectionTitleStrs.push(title);
+    }
+    subSectionTitles.push(document.getElementById("_content_end_"));
+    function isSectionFullyVisible(id)
+    {
+      var titleElement = subSectionTitles[id];
+      var nextTitleElement = subSectionTitles[id+1];
+      return (titleElement.getBoundingClientRect().top >= 0 && nextTitleElement.getBoundingClientRect().top <= window.innerHeight);
+    }
+    function findCurrentSubsection()
+    {
+      var currentSubsectionID = -1;
+      for (var i = 0; i < subSectionItems.length; i++) {
+        var titleElement = subSectionTitles[i];
+        if (titleElement == null)
+          continue;
+        if (titleElement.getBoundingClientRect().top < window.innerHeight * 0.12)
+          currentSubsectionID = i;
+      }
+      return currentSubsectionID;
+    }
+    function updateCurrentSubsection(currentSubsectionID)
+    {
+      for (var i = 0; i < subSectionItems.length; i++)
+      {
+        if (i == currentSubsectionID || isSectionFullyVisible(i))
+          subSectionItems[i].getElementsByTagName("span")[0].style["font-weight"] = 600;
+        else
+          subSectionItems[i].getElementsByTagName("span")[0].style["font-weight"] = 400;
+      }
+    }
+    function windowScroll(e)
+    {
+      updateCurrentSubsection(findCurrentSubsection());
+      updateScroll();
+    }
+    window.addEventListener("scroll", windowScroll);
+    updateCurrentSubsection(findCurrentSubsection());
   </script>
 
   {% if site.google_analytics %}
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
index df8ca8272..79064ce31 100644
--- a/docs/assets/css/style.scss
+++ b/docs/assets/css/style.scss
@@ -2,7 +2,23 @@
 ---
 
 @import "{{ site.theme }}";
+blockquote {
+    background-color: #f2f2f2;
+    padding-top: 10px;
+    padding-bottom: 5px;
+}
 blockquote p {
     font-size: 16px;
-    font-weight: 600;
+    font-weight: 400;
+    margin-bottom: 5px;
+    color: #202020;
+}
+body {
+    color: initial;
+    text-shadow: none;
+    background: none;
 }
+#container 
+{
+    background:none;
+}
\ No newline at end of file
diff --git a/docs/gfx-user-guide/01-getting-started.md b/docs/gfx-user-guide/01-getting-started.md
new file mode 100644
index 000000000..a6f6b241c
--- /dev/null
+++ b/docs/gfx-user-guide/01-getting-started.md
@@ -0,0 +1,342 @@
+---
+layout: user-guide
+---
+
+Getting Started with Slang Graphics Layer
+============================================
+
+[//]: # (ShortTitle: Getting Started)
+
+In this article, we provide instructions on installing the graphics layer into your application, and demonstrate the basic use of the graphics layer via a simple compute shader example. We will use the same [hello-world.slang](https://github.com/shader-slang/slang/blob/master/examples/hello-world/hello-world.slang) shader from the `hello-world` example in the [Slang getting started tutorial](../user-guide/01-get-started.html).
+
+Installation
+------------------
+
+### Obtain Release Package
+
+The Slang graphics library is implemented in `gfx.dll` (`libgfx.so` in unix systems). Since Slang is tightly integrated into the graphics layer, you need to include both `slang.dll` and `gfx.dll` in your application. Official Slang releases provide prebuilt binaries for both libraries as well as the header files to use them. If you prefer to build the libraries yourself, please follow [build instructions](../building).
+
+### Install Header Files
+Once you have built or obtained a Slang release, make the following header files from the release package accessible to your application:
+- `slang-gfx.h`
+- `slang.h`
+- `slang-com-ptr.h`
+- `slang-com-helper.h`
+
+### Linking the Library
+On Windows (with `msvc`), make sure that `gfx.lib` is provided as linker input via the `Linker->Input->Additional Dependencies` project configuration. On Unix systems, make sure to pass `-lgfx` when compiling your application.
+
+Creating a GPU Device
+---------------------------
+
+To start using the graphics layer, create an `IDevice` object by calling `gfxCreateDevice`. The `IDevice` interface is the main entry-point to interact with the graphics layer. It represent GPU device context where all interactions with the GPU take place.
+
+```C++
+#include "slang-gfx.h"
+
+using namespace gfx;
+
+IDevice* gDevice = nullptr;
+
+void initGfx()
+{
+    IDevice::Desc deviceDesc = {};
+    gfxCreateDevice(deviceDesc, &gDevice);
+}
+```
+
+The `IDevice::Desc` struct passed to `gfxCreateDevice` defines many configurations on how a device shall be created. Most notably, the `deviceType` field specifies what underlying graphics API to use. By default, `gfxCreateDevice` will attempt to use the best API available on current platform. On Windows, the layer will prefer to use `D3D12` but will also try to use `Vulkan`, `D3D11`, `OpenGL` in order, in case the former API isn't available. On Unix systems, it will always default to `Vulkan` since this is the only API that supports full Graphics capabilities. A user can always specify the `deviceType` field to force the layer to use a specific API. If the device creation succeeds, `gfxCreateDevice` will return `SLANG_OK(0)`.
+
+Similar to the Slang API, objects created by the graphics layer also conforms to the COM standard. The user to responsible for calling `release` method on every object returned to the user by the layer to prevent memory leaks.
+
+Enabling the Debug Layer
+--------------------------
+
+The Slang Graphics Layer provides a debug layer that can be enabled to perform additional validations to ensure correctness. To enable the debug layer, simply call `gfxEnableDebugLayer` before calling `gfxCreateDevice`.
+
+To receive diagnostic messages, you need to create a class that implements the `IDebugCallback` interface, and call `gfxSetDebugCallback` to provide the callback instance to the graphics layer. For example:
+
+```C++
+struct MyDebugCallback : public IDebugCallback
+{
+    virtual SLANG_NO_THROW void SLANG_MCALL handleMessage(
+        DebugMessageType type,
+        DebugMessageSource source,
+        const char* message) override
+    {
+        printf("%s\n", message);
+    }
+};
+
+MyDebugCallback gCallback;
+void initGfx()
+{
+    gfxEnableDebugLayer();
+    gfxSetDebugCallback(&gCallback);
+
+    IDevice::Desc deviceDesc = {};
+    gfxCreateDevice(&deviceDesc, &gDevice);
+}
+```
+
+Creating a Pipeline State
+---------------------------
+
+A pipeline state object encapsulates the shader program to execute on the GPU device, as well as other fix function states for graphics rendering. In this example, we will be compiling and runing a simple compute shader written in Slang. To do that we need to create a compute pipeline state from a Slang `IComponentType`. We refer the reader to the (Slang getting started tutorial)[../user-guide/01-getting-started.html] on how to create a Slang `IComponentType` from a shader file. The following source loads a shader from `hello-world.slang` and create a compute pipeline state from it:
+
+```C++
+void createComputePipelineFromShader(IPipelineState*& outPipelineState)
+{
+    // First we need to create slang global session with work with the Slang API.
+    ComPtr<slang::IGlobalSession> slangGlobalSession;
+    RETURN_ON_FAIL(slang::createGlobalSession(slangGlobalSession.writeRef()));
+
+    // Next we create a compilation session to generate SPIRV code from Slang source.
+    slang::SessionDesc sessionDesc = {};
+    slang::TargetDesc targetDesc = {};
+    targetDesc.format = SLANG_SPIRV;
+    targetDesc.profile = slangGlobalSession->findProfile("glsl440");
+    sessionDesc.targetCount = 1;
+    sessionDesc.targets = &targetDesc;
+
+    ComPtr<slang::ISession> session;
+    RETURN_ON_FAIL(slangGlobalSession->createSession(sessionDesc, session.writeRef()));
+
+    // Once the session has been obtained, we can start loading code into it.
+    //
+    // The simplest way to load code is by calling `loadModule` with the name of a Slang
+    // module. A call to `loadModule("hello-world")` will behave more or less as if you
+    // wrote:
+    //
+    //      import hello_world;
+    //
+    // In a Slang shader file. The compiler will use its search paths to try to locate
+    // `hello-world.slang`, then compile and load that file. If a matching module had
+    // already been loaded previously, that would be used directly.
+    slang::IModule* slangModule = nullptr;
+    {
+        ComPtr<slang::IBlob> diagnosticBlob;
+        slangModule = session->loadModule("hello-world", diagnosticBlob.writeRef());
+        diagnoseIfNeeded(diagnosticBlob);
+        if (!slangModule)
+            return -1;
+    }
+
+    // Loading the `hello-world` module will compile and check all the shader code in it,
+    // including the shader entry points we want to use. Now that the module is loaded
+    // we can look up those entry points by name.
+    //
+    // Note: If you are using this `loadModule` approach to load your shader code it is
+    // important to tag your entry point functions with the `[shader("...")]` attribute
+    // (e.g., `[shader("compute")] void computeMain(...)`). Without that information there
+    // is no umambiguous way for the compiler to know which functions represent entry
+    // points when it parses your code via `loadModule()`.
+    //
+    ComPtr<slang::IEntryPoint> entryPoint;
+    slangModule->findEntryPointByName("computeMain", entryPoint.writeRef());
+
+    // At this point we have a few different Slang API objects that represent
+    // pieces of our code: `module`, `vertexEntryPoint`, and `fragmentEntryPoint`.
+    //
+    // A single Slang module could contain many different entry points (e.g.,
+    // four vertex entry points, three fragment entry points, and two compute
+    // shaders), and before we try to generate output code for our target API
+    // we need to identify which entry points we plan to use together.
+    //
+    // Modules and entry points are both examples of *component types* in the
+    // Slang API. The API also provides a way to build a *composite* out of
+    // other pieces, and that is what we are going to do with our module
+    // and entry points.
+    //
+    Slang::List<slang::IComponentType*> componentTypes;
+    componentTypes.add(slangModule);
+    componentTypes.add(entryPoint);
+
+    // Actually creating the composite component type is a single operation
+    // on the Slang session, but the operation could potentially fail if
+    // something about the composite was invalid (e.g., you are trying to
+    // combine multiple copies of the same module), so we need to deal
+    // with the possibility of diagnostic output.
+    //
+    ComPtr<slang::IComponentType> composedProgram;
+    {
+        ComPtr<slang::IBlob> diagnosticsBlob;
+        SlangResult result = session->createCompositeComponentType(
+            componentTypes.getBuffer(),
+            componentTypes.getCount(),
+            composedProgram.writeRef(),
+            diagnosticsBlob.writeRef());
+        diagnoseIfNeeded(diagnosticsBlob);
+        RETURN_ON_FAIL(result);
+    }
+
+    // Now we have obtained the `IComponentType` that represents the compute
+    // kernel, we can use it to create a `IShaderProgram` object in the graphics
+    // layer.
+    IShaderProgram* shaderProgram = nullptr;
+    IShaderProgram::Desc programDesc = {};
+    programDesc.pipelineType = PipelineType::Compute;
+    programDesc.slangProgram = componentType;
+    gDevice->createShaderProgram(programDesc, &shaderProgram);
+    
+    // Create a compute pipeline state from `shaderProgram`.
+    ComputePipelineStateDesc pipelineDesc = {};
+    pipelineDesc.program = shaderProgram;
+    gDevice->createComputePipelineState(pipelineDesc, &outPipelineState);
+
+    // Since we no longer need to use `shaderProgram` after creating
+    // a pipeline state, we should release it to prevent memory leaks.
+    shaderProgram->release();
+}
+```
+
+Creating Buffer Resource
+------------------------------
+We need to create the buffer resources used our `hello-world` shader as input and output. This can be done via `IDevice::createBufferResource` method.
+```C++
+const int numberCount = 4;
+float initialData[] = {0.0f, 1.0f, 2.0f, 3.0f};
+IBufferResource::Desc bufferDesc = {};
+bufferDesc.sizeInBytes = numberCount * sizeof(float);
+bufferDesc.format = Format::Unknown;
+bufferDesc.elementSize = sizeof(float);
+bufferDesc.defaultState = ResourceState::UnorderedAccess;
+bufferDesc.allowedStates = ResourceStateSet(ResourceState::UnorderedAccess,
+                                            ResourceState::ShaderResource);
+IBufferResource* inputBuffer0;
+SLANG_RETURN_ON_FAIL(device->createBufferResource(
+    bufferDesc,
+    (void*)initialData,
+    &inputBuffer0));
+```
+
+Creating a Command Queue
+------------------------------
+A command queue is where the GPU device takes commands from the application to execute. To create a command queue, call `IDevice::createCommandQueue`.
+```C++
+ICommandQueue* gQueue = nullptr;
+
+ICommandQueue::Desc queueDesc = {ICommandQueue::QueueType::Graphics};
+device->createCommandQueue(queueDesc, &gQueue);
+```
+
+Allocating a Command Buffer
+------------------------------
+A command buffer is treated as a _transient_ resource by the graphics layer. A transient resource is required by the GPU during execution of a task, and are no longer needed when the execution has completed. Slang graphics layer provides an `ITransientResourceHeap` object to efficiently manage the life cycle of transient resources. In order to allocate a command buffer, we need to create an `ITransientResourceHeap` object first by calling `IDevice::createTransientResourceHeap`.
+
+```C++
+ITransientResourceHeap* gTransientHeap;
+
+ITransientResourceHeap::Desc transientHeapDesc = {};
+transientHeapDesc.constantBufferSize = 4096;
+device->createTransientResourceHeap(transientHeapDesc, &gTransientHeap);
+```
+
+With a `TransientResourceHeap`, we can call `createCommandBuffer` method to allocate a command buffer:
+
+```C++
+ICommandBuffer* commandBuffer;
+gTransientHeap->createCommandBuffer(&commandBuffer);
+```
+
+A user should regularly call `ITransientResourceHeap::synchronizeAndReset` to recycle all previously allocated transient resources. A standard practice is to create two `TransientResourceHeap`s in a double-buffered renderer, and alternate the transient heap on each frame to allocate command buffers and other transient resources. With this setup, the application can call `synchronizeAndReset` at start of each frame on the corresponding transient resource heap to make sure all transient resources are timely recycled.
+
+Recording Commands to Run a Compute Shader
+------------------------------------
+
+[//]: # (ShortTitle: Recording Commands)
+
+Now that we have created all the resources and allocated a command buffer, we can start recording commands to
+set the compute pipeline state, bind shader parameters, and dispatch a kernel launch.
+
+Since we are only using compute commands, we begin the recording by calling `ICommandBuffer::encodeComputeCommands`. This methods returns a transient `IComputeCommandEncoder` object for accepting actual compute commands.
+
+```C++
+IComputeCommandEncoder* encoder = commandBuffer->encodeComputeCommands();
+```
+
+The first command is to bind the pipeline state we created earlier:
+
+```C++
+IShaderObject* rootObject = encoder->bindPipeline(pipelineState);
+```
+
+Binding a pipeline state yields a transient `IShaderObject` object. We can use the `IShaderObject` instance to bind shader parameters. For the `hello-world` shader, we need to bind three parameters: `buffer0`, `buffer1` and `result`.
+
+```C++
+// Create a resource view for buffer0.
+IBufferView* buffer0View;
+{
+    IResourceView::Desc viewDesc = {};
+    viewDesc.type = IResourceView::Type::ShaderResource;
+    viewDesc.format = Format::Unknown;
+    SLANG_RETURN_ON_FAIL(device->createBufferView(inputBuffer0, viewDesc, &buffer0View));
+}
+// Bind the resource view to shader.
+rootObject->setResource(ShaderOffset{0,0,0}, buffer0View);
+
+// Create a resource view for buffer1.
+IBufferView* buffer1View;
+{
+    IResourceView::Desc viewDesc = {};
+    viewDesc.type = IResourceView::Type::ShaderResource;
+    viewDesc.format = Format::Unknown;
+    SLANG_RETURN_ON_FAIL(device->createBufferView(inputBuffer1, viewDesc, &buffer1View));
+}
+// Bind the resource view to shader.
+rootObject->setResource(ShaderOffset{0,1,0}, buffer1View);
+
+// Create a resource view for resultBuffer.
+IBufferView* resultView;
+{
+    IResourceView::Desc viewDesc = {};
+    viewDesc.type = IResourceView::Type::UnorderedAccess;
+    viewDesc.format = Format::Unknown;
+    SLANG_RETURN_ON_FAIL(device->createBufferView(resultBuffer, viewDesc, &resultView));
+}
+rootObject->setResource(ShaderOffset{0,2,0}, resultView);
+```
+
+> #### Note
+> Since `rootObject` is a transient object returned by the command encoder, it is automatically released
+> with the command encoder. Calling `release` on `rootObject` is OK but not needed.
+
+After binding all shader parameters, we can now dispatch the kernel:
+
+```C++
+encoder->dispatchCompute(1, 1, 1);
+```
+
+> #### Note
+> Command encoders are transient objects managed by a command buffer, it is automatically released
+> with the command buffer. Calling `release` on `rootObject` is OK but not needed.
+
+When we are done recording commands, we need to close the command encoder and the command buffer.
+
+```C++
+encoder->endEncoding();
+commandBuffer->close();
+```
+
+Now we are ready to submit the command buffer to the command queue, and wait for the GPU execution to finish.
+```C++
+gQueue->executeCommandBuffer(commandBuffer);
+gQueue->wait();
+```
+
+Cleaning Up
+----------------
+
+At the end of our example, we need to make sure all created objects are released by calling the `release` method:
+
+```C++
+commandBuffer->release();
+gQueue->release();
+gTransientResourceHeap->release();
+inputBuffer0->release();
+buffer0View->release();
+...
+gDevice->release();
+```
+
+The order of calls to `release` does not matter, as long as all objects are released from the user.
\ No newline at end of file
diff --git a/docs/gfx-user-guide/build_toc.ps1 b/docs/gfx-user-guide/build_toc.ps1
new file mode 100644
index 000000000..567a73988
--- /dev/null
+++ b/docs/gfx-user-guide/build_toc.ps1
@@ -0,0 +1,9 @@
+$job = Start-Job -ArgumentList $PSScriptRoot -ScriptBlock {
+    Set-Location $args[0]
+    $code = (Get-Content -Raw -Path "../scripts/Program.cs").ToString()
+    $assemblies = ("System.Core", "System.IO", "System.Collections")
+    Add-Type -ReferencedAssemblies $assemblies -TypeDefinition $code -Language CSharp	
+    [toc.Builder]::Run($args[0])
+}
+Wait-Job $job
+Receive-Job -Job $job
diff --git a/docs/gfx-user-guide/index.md b/docs/gfx-user-guide/index.md
new file mode 100644
index 000000000..4671a1a30
--- /dev/null
+++ b/docs/gfx-user-guide/index.md
@@ -0,0 +1,25 @@
+---
+layout: user-guide
+---
+
+Slang Graphics Layer
+=============
+
+The Slang Graphics Layer is an abstraction library of graphics APIs to support cross-platform applications that utilize GPU graphics/compute capabilities. The Slang Graphics Layer tightly integrates the Slang shading language to provide the most complete cross-platform GPU application development experience. The Slang language and compilation API is designed to work best when the application assumes several best practices in terms of shader specialization and parameter binding. The Slang Graphics Layer is following exactly the same best practices supported by Slang's compilation model. Outside of shader-related areas, the graphics layer's interface is designed to closely follow the modern graphics API models in Direct3D 12, Vulkan and Metal, such that the layer is only purposed to abstracting the differences between these underlying APIs instead of providing a higher level abstract that simplifies the interface. This design philosophy allows users to benefit from the ideas in the Slang shading language without giving up precise control on other aspects of the graphics API.
+
+The current support status of operating system and graphics APIs is shown in the following matrix.
+
+|               | Windows            | Linux              |
+| :------------ | :----------------: | :----------------: |
+| Direct3D 12   | Yes                | No                 |
+| Direct3D 11   | Yes                | No                 |
+| Vulkan        | Yes                | Yes                |
+| OpenGL        | Yes                | No                 |
+| CPU emulation | Yes (Compute Only) | Yes (Compute Only) |
+| CUDA          | Yes (Compute Only) | Yes (Compute Only) |
+
+
+> #### Note
+> The graphics layer is still under active development and we intend to add more platforms and APIs in the future.
+
+In this documentation, we will walk through various parts of the library and demonstrate how it can be used in your application.
\ No newline at end of file
diff --git a/docs/gfx-user-guide/nav.html b/docs/gfx-user-guide/nav.html
new file mode 100644
index 000000000..97757326e
--- /dev/null
+++ b/docs/gfx-user-guide/nav.html
@@ -0,0 +1,5 @@
+<nav>
+    <li><a href="../../">Docs</a></li>
+    <li><a href="index.html">Slang Graphics Layer</a></li>
+
+</nav>
\ No newline at end of file
diff --git a/docs/gfx-user-guide/toc.html b/docs/gfx-user-guide/toc.html
new file mode 100644
index 000000000..197790b93
--- /dev/null
+++ b/docs/gfx-user-guide/toc.html
@@ -0,0 +1,18 @@
+<ul class="toc_root_list"><li data-link="index"><span>Slang Graphics Layer</span>
+<ul class="toc_list">
+<li data-link="01-getting-started"><span>Getting Started</span>
+<ul class="toc_list">
+<li data-link="01-getting-started#installation"><span>Installation</span></li>
+<li data-link="01-getting-started#creating-a-gpu-device"><span>Creating a GPU Device</span></li>
+<li data-link="01-getting-started#enabling-the-debug-layer"><span>Enabling the Debug Layer</span></li>
+<li data-link="01-getting-started#creating-a-pipeline-state"><span>Creating a Pipeline State</span></li>
+<li data-link="01-getting-started#creating-buffer-resource"><span>Creating Buffer Resource</span></li>
+<li data-link="01-getting-started#creating-a-command-queue"><span>Creating a Command Queue</span></li>
+<li data-link="01-getting-started#allocating-a-command-buffer"><span>Allocating a Command Buffer</span></li>
+<li data-link="01-getting-started#recording-commands-to-run-a-compute-shader"><span>Recording Commands</span></li>
+<li data-link="01-getting-started#cleaning-up"><span>Cleaning Up</span></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
\ No newline at end of file
diff --git a/docs/scripts/Program.cs b/docs/scripts/Program.cs
new file mode 100644
index 000000000..8a7b6c1b6
--- /dev/null
+++ b/docs/scripts/Program.cs
@@ -0,0 +1,207 @@
+using System;
+using System.IO;
+using System.Text;
+using System.Collections.Generic;
+namespace toc
+{
+    public class Builder
+    {
+        public static string getAnchorId(string title)
+        {
+            StringBuilder sb = new StringBuilder();
+            title = title.Trim().ToLower();
+            foreach (var ch in title)
+            {
+                if (ch >= 'a' && ch <= 'z' || ch >= '0' && ch <= '9'
+                    || ch == '-')
+                    sb.Append(ch);
+                else if (ch==' ' || ch =='_')
+                    sb.Append('-');
+            }
+            return sb.ToString();
+        }
+
+        public class Node
+        {
+            public List<string> fileNamePrefix = new List<string>();
+            public string title;
+            public string shortTitle;
+            public string fileID;
+            public List<string> sections = new List<string>();
+            public List<string> sectionShortTitles = new List<string>();
+            public List<Node> children = new List<Node>();
+        }
+
+        public static void buildTOC(StringBuilder sb, Node n)
+        {
+            sb.AppendFormat("<li data-link=\"{0}\"><span>{1}</span>\n", n.fileID, n.shortTitle);
+            if (n.children.Count != 0)
+            {
+                sb.AppendLine("<ul class=\"toc_list\">");
+                foreach(var c in n.children)
+                    buildTOC(sb, c);
+                sb.AppendLine("</ul>");
+            }
+            else if (n.sections.Count != 0)
+            {
+                sb.AppendLine("<ul class=\"toc_list\">");
+                for (int i = 0; i < n.sections.Count; i++)
+                {
+                    var s = n.sections[i];
+                    var shortTitle = n.sectionShortTitles[i];
+                    sb.AppendFormat("<li data-link=\"{0}#{1}\"><span>{2}</span></li>\n", n.fileID, getAnchorId(s), shortTitle);
+                }
+                sb.AppendLine("</ul>");
+            }
+            sb.AppendLine("</li>");
+        }
+        public static string buildTOC(Node n)
+        {
+            StringBuilder sb = new StringBuilder();
+            sb.Append(@"<ul class=""toc_root_list"">");
+            buildTOC(sb, n);
+            sb.Append(@"</ul>");
+            return sb.ToString();
+        }
+
+        public static bool isChild(Node parent, Node child)
+        {
+            if (parent.fileNamePrefix.Count < child.fileNamePrefix.Count)
+            {
+                bool equal = true;
+                for (int k = 0; k < parent.fileNamePrefix.Count; k++)
+                {
+                    if (parent.fileNamePrefix[k] != child.fileNamePrefix[k])
+                    {
+                        equal = false;
+                        break;
+                    }
+                }
+                return equal;
+            }
+            return false;
+        }
+
+        public static string getNextNonEmptyLine(string[] lines, int i)
+        {
+            i++;
+            while (i < lines.Length)
+            {
+                if (lines[i].Trim().Length != 0)
+                    return lines[i];
+                i++;
+            }
+            return "";
+        }
+        const string shortTitlePrefix = "[//]: # (ShortTitle: ";
+
+        public static string maybeGetShortTitle(string originalTitle, string[] lines, int line)
+        {
+            string nextLine = getNextNonEmptyLine(lines, line);
+            if (nextLine.StartsWith(shortTitlePrefix))
+            {
+                return nextLine.Substring(shortTitlePrefix.Length, nextLine.Length - shortTitlePrefix.Length - 1).Trim();
+            }
+            return originalTitle;
+        }
+        public static string Run(string path)
+        {
+            StringBuilder outputSB = new StringBuilder();
+            outputSB.AppendFormat("Building table of contents from {0}...\n", path);
+            var files = System.IO.Directory.EnumerateFiles(path, "*.md");
+            List<Node> nodes = new List<Node>();
+            foreach (var f in files)
+            {
+                var content = File.ReadAllLines(f);
+                Node node = new Node();
+                node.fileID = Path.GetFileNameWithoutExtension(f);
+                outputSB.AppendFormat("  {0}.md\n", node.fileID);
+                bool mainTitleFound = false;
+                for (int i = 1; i < content.Length; i++)
+                {
+                    if (content[i].StartsWith("==="))
+                    {
+                        mainTitleFound = true;
+                        node.title = content[i-1];
+                        node.shortTitle = maybeGetShortTitle(node.title, content, i);
+                    }
+                    if (content[i].StartsWith("---"))
+                    {
+                        if (!mainTitleFound) continue;
+                        node.sections.Add(content[i-1]);
+                        node.sectionShortTitles.Add(maybeGetShortTitle(content[i - 1], content, i));
+                    }
+                    if (content[i].StartsWith("#") && !content[i].StartsWith("##") && node.title == null)
+                    {
+                        mainTitleFound = true;
+                        node.title = content[i].Substring(1, content[i].Length - 1).Trim();
+                        node.shortTitle = maybeGetShortTitle(node.title, content, i);
+                    }
+                    if (content[i].StartsWith("##") && !content[i].StartsWith("###"))
+                    {
+                        if (!mainTitleFound) continue;
+                        var sectionStr = content[i].Substring(2, content[i].Length - 2).Trim();
+                        node.sections.Add(sectionStr);
+                        node.sectionShortTitles.Add(maybeGetShortTitle(sectionStr, content, i));
+                    }
+                }
+                if (node.title == null)
+                {
+                    outputSB.AppendFormat("Error: {0} does not define a title.", f);
+                    node.title = "Untitiled";
+                }
+                var titleSecs = Path.GetFileName(f).Split('-');
+                foreach (var s in titleSecs)
+                {
+                    if (s.Length == 2 && s[1]>='0' && s[1] <= '9')
+                    {
+                        node.fileNamePrefix.Add(s);
+                    }
+                    else
+                    {
+                        break;
+                    }
+                }
+                // Find parent node.
+                Node parent=null;
+                for (int l = nodes.Count-1; l>=0; l--)
+                {
+                    var n = nodes[l];
+                    if (isChild(n, node))
+                    {
+                       parent = n;
+                       break;
+                    }
+                }
+                if (parent != null)
+                    parent.children.Add(node);
+                else
+                {
+                    // find child
+                    foreach (var other in nodes)
+                    {
+                        if (isChild(node, other))
+                        {
+                            node.children.Add(other);
+                        }
+                    }
+                    foreach (var c in node.children)
+                    {
+                        nodes.Remove(c);
+
+                    }
+                    nodes.Add(node);
+                }
+            }
+            var root = nodes.Find(x=>x.fileID=="index");
+            if (root != null)
+            {
+                var html = buildTOC(root);
+                var outPath = Path.Combine(path, "toc.html");
+                File.WriteAllText(outPath, html);
+                outputSB.AppendFormat("Output written to: {0}\n", outPath);
+            }
+            return outputSB.ToString();
+        }
+    }
+}
\ No newline at end of file
diff --git a/docs/user-guide/build_toc.ps1 b/docs/user-guide/build_toc.ps1
index 15603c8cb..567a73988 100644
--- a/docs/user-guide/build_toc.ps1
+++ b/docs/user-guide/build_toc.ps1
@@ -1,6 +1,6 @@
 $job = Start-Job -ArgumentList $PSScriptRoot -ScriptBlock {
     Set-Location $args[0]
-    $code = (Get-Content -Raw -Path "scripts/Program.cs").ToString()
+    $code = (Get-Content -Raw -Path "../scripts/Program.cs").ToString()
     $assemblies = ("System.Core", "System.IO", "System.Collections")
     Add-Type -ReferencedAssemblies $assemblies -TypeDefinition $code -Language CSharp	
     [toc.Builder]::Run($args[0])
diff --git a/docs/user-guide/nav.html b/docs/user-guide/nav.html
new file mode 100644
index 000000000..9a29f99f7
--- /dev/null
+++ b/docs/user-guide/nav.html
@@ -0,0 +1,6 @@
+<nav>
+    <li><a href="../../">Docs</a></li>
+    <li><a href="../slang/">Slang</a></li>
+    <li><a href="index.html">User's Guide</a></li>
+
+</nav>
\ No newline at end of file
diff --git a/docs/user-guide/scripts/Program.cs b/docs/user-guide/scripts/Program.cs
deleted file mode 100644
index 4ed2d18a6..000000000
--- a/docs/user-guide/scripts/Program.cs
+++ /dev/null
@@ -1,164 +0,0 @@
-using System;
-using System.IO;
-using System.Text;
-using System.Collections.Generic;
-namespace toc
-{
-    public class Builder
-    {
-        public static string getAnchorId(string title)
-        {
-            StringBuilder sb = new StringBuilder();
-            title = title.Trim().ToLower();
-            foreach (var ch in title)
-            {
-                if (ch >= 'a' && ch <= 'z' || ch >= '0' && ch <= '9'
-                    || ch == '-')
-                    sb.Append(ch);
-                else if (ch==' ' || ch =='_')
-                    sb.Append('-');
-            }
-            return sb.ToString();
-        }
-
-        public class Node
-        {
-            public List<string> fileNamePrefix = new List<string>();
-            public string title;
-            public string fileID;
-            public List<string> sections = new List<string>();
-            public List<Node> children = new List<Node>();
-        }
-
-        public static void buildTOC(StringBuilder sb, Node n)
-        {
-            sb.AppendFormat("<li data-link=\"{0}\"><span>{1}</span>\n", n.fileID, n.title);
-            if (n.children.Count != 0)
-            {
-                sb.AppendLine("<ul class=\"toc_list\">");
-                foreach(var c in n.children)
-                    buildTOC(sb, c);
-                sb.AppendLine("</ul>");
-            }
-            else if (n.sections.Count != 0)
-            {
-                sb.AppendLine("<ul class=\"toc_list\">");
-                foreach (var s in n.sections)
-                {
-                    sb.AppendFormat("<li data-link=\"{0}#{1}\"><span>{2}</span></li>\n", n.fileID, getAnchorId(s), s);
-                }
-                sb.AppendLine("</ul>");
-            }
-            sb.AppendLine("</li>");
-        }
-        public static string buildTOC(Node n)
-        {
-            StringBuilder sb = new StringBuilder();
-            sb.Append(@"<ul class=""toc_root_list"">");
-            buildTOC(sb, n);
-            sb.Append(@"</ul>");
-            return sb.ToString();
-        }
-
-        public static bool isChild(Node parent, Node child)
-        {
-            if (parent.fileNamePrefix.Count < child.fileNamePrefix.Count)
-            {
-                bool equal = true;
-                for (int k = 0; k < parent.fileNamePrefix.Count; k++)
-                {
-                    if (parent.fileNamePrefix[k] != child.fileNamePrefix[k])
-                    {
-                        equal = false;
-                        break;
-                    }
-                }
-                return equal;
-            }
-            return false;
-        }
-        public static string Run(string path)
-        {
-            StringBuilder outputSB = new StringBuilder();
-            outputSB.AppendFormat("Building table of contents from {0}...\n", path);
-            var files = System.IO.Directory.EnumerateFiles(path, "*.md");
-            List<Node> nodes = new List<Node>();
-            foreach (var f in files)
-            {
-                var content = File.ReadAllLines(f);
-                Node node = new Node();
-                node.fileID = Path.GetFileNameWithoutExtension(f);
-                outputSB.AppendFormat("  {0}.md\n", node.fileID);
-                for (int i = 1; i < content.Length; i++)
-                {
-                    if (content[i-1].StartsWith("layout: "))
-                        continue;
-                    if (content[i].StartsWith("==="))
-                        node.title = content[i-1];
-                    if (content[i].StartsWith("---"))
-                        node.sections.Add(content[i-1]);
-                    if (content[i].StartsWith("#") && !content[i].StartsWith("##") && node.title == null)
-                        node.title = content[i].Substring(1, content[i].Length - 1).Trim();
-                    if (content[i].StartsWith("##") && !content[i].StartsWith("###"))
-                        node.sections.Add(content[i].Substring(2, content[i].Length - 2).Trim());
-                }
-                if (node.title == null)
-                {
-                    outputSB.AppendFormat("Error: {0} does not define a title.", f);
-                    node.title = "Untitiled";
-                }
-                var titleSecs = Path.GetFileName(f).Split('-');
-                foreach (var s in titleSecs)
-                {
-                    if (s.Length == 2 && s[1]>='0' && s[1] <= '9')
-                    {
-                        node.fileNamePrefix.Add(s);
-                    }
-                    else
-                    {
-                        break;
-                    }
-                }
-                // Find parent node.
-                Node parent=null;
-                for (int l = nodes.Count-1; l>=0; l--)
-                {
-                    var n = nodes[l];
-                    if (isChild(n, node))
-                    {
-                       parent = n;
-                       break;
-                    }
-                }
-                if (parent != null)
-                    parent.children.Add(node);
-                else
-                {
-                    // find child
-                    foreach (var other in nodes)
-                    {
-                        if (isChild(node, other))
-                        {
-                            node.children.Add(other);
-                        }
-                    }
-                    foreach (var c in node.children)
-                    {
-                        nodes.Remove(c);
-
-                    }
-                    nodes.Add(node);
-                }
-            }
-            var root = nodes.Find(x=>x.fileID=="index");
-            if (root != null)
-            {
-                var html = buildTOC(root);
-                var outPath = Path.Combine(path, "user-guide-toc.html");
-                File.WriteAllText(outPath, html);
-                outputSB.AppendFormat("Output written to: {0}\n", outPath);
-            }
-            return outputSB.ToString();
-        }
-    }
-}
\ No newline at end of file
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
new file mode 100644
index 000000000..314c786aa
--- /dev/null
+++ b/docs/user-guide/toc.html
@@ -0,0 +1,88 @@
+<ul class="toc_root_list"><li data-link="index"><span>Slang User's Guide</span>
+<ul class="toc_list">
+<li data-link="00-introduction"><span>Introduction</span>
+<ul class="toc_list">
+<li data-link="00-introduction#why-use-slang"><span>Why use Slang?</span></li>
+<li data-link="00-introduction#who-is-slang-for"><span>Who is Slang for?</span></li>
+<li data-link="00-introduction#who-is-this-guide-for"><span>Who is this guide for?</span></li>
+<li data-link="00-introduction#goals-and-non-goals"><span>Goals and Non-Goals</span></li>
+</ul>
+</li>
+<li data-link="01-get-started"><span>Getting Started with Slang</span>
+<ul class="toc_list">
+<li data-link="01-get-started#installation"><span>Installation</span></li>
+<li data-link="01-get-started#your-first-slang-shader"><span>Your first Slang shader</span></li>
+<li data-link="01-get-started#the-full-example"><span>The full example</span></li>
+</ul>
+</li>
+<li data-link="02-conventional-features"><span>Conventional Language Features</span>
+<ul class="toc_list">
+<li data-link="02-conventional-features#types"><span>Types</span></li>
+<li data-link="02-conventional-features#expressions"><span>Expressions</span></li>
+<li data-link="02-conventional-features#statements"><span>Statements</span></li>
+<li data-link="02-conventional-features#functions"><span>Functions</span></li>
+<li data-link="02-conventional-features#preprocessor"><span>Preprocessor</span></li>
+<li data-link="02-conventional-features#attributes"><span>Attributes</span></li>
+<li data-link="02-conventional-features#global-variables-and-shader-parameters"><span>Global Variables and Shader Parameters</span></li>
+<li data-link="02-conventional-features#shader-entry-points"><span>Shader Entry Points</span></li>
+</ul>
+</li>
+<li data-link="03-convenience-features"><span>Basic Convenience Features</span>
+<ul class="toc_list">
+<li data-link="03-convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
+<li data-link="03-convenience-features#immutable-values"><span>Immutable Values</span></li>
+<li data-link="03-convenience-features#member-functions"><span>Member functions</span></li>
+<li data-link="03-convenience-features#properties"><span>Properties</span></li>
+<li data-link="03-convenience-features#initializers"><span>Initializers</span></li>
+<li data-link="03-convenience-features#operator-overloading"><span>Operator Overloading</span></li>
+<li data-link="03-convenience-features#struct-inheritance-limited"><span>`struct` inheritance (limited)</span></li>
+<li data-link="03-convenience-features#extensions"><span>Extensions</span></li>
+<li data-link="03-convenience-features#modules"><span>Modules</span></li>
+</ul>
+</li>
+<li data-link="04-interfaces-generics"><span>Interfaces and Generics</span>
+<ul class="toc_list">
+<li data-link="04-interfaces-generics#interfaces"><span>Interfaces</span></li>
+<li data-link="04-interfaces-generics#generics"><span>Generics</span></li>
+<li data-link="04-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
+<li data-link="04-interfaces-generics#associated-types"><span>Associated Types</span></li>
+<li data-link="04-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
+<li data-link="04-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
+<li data-link="04-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
+<li data-link="04-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
+</ul>
+</li>
+<li data-link="05-compiling"><span>Compiling Code with Slang</span>
+<ul class="toc_list">
+<li data-link="05-compiling#concepts"><span>Concepts</span></li>
+<li data-link="05-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
+<li data-link="05-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
+</ul>
+</li>
+<li data-link="06-targets"><span>Suported Compilation Targets</span>
+<ul class="toc_list">
+<li data-link="06-targets#background-and-terminology"><span>Background and Terminology</span></li>
+<li data-link="06-targets#direct3d-11"><span>Direct3D 11</span></li>
+<li data-link="06-targets#direct3d-12"><span>Direct3D 12</span></li>
+<li data-link="06-targets#vulkan"><span>Vulkan</span></li>
+<li data-link="06-targets#opengl"><span>OpenGL</span></li>
+<li data-link="06-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
+<li data-link="06-targets#cpu-compute"><span>CPU Compute</span></li>
+<li data-link="06-targets#summary"><span>Summary</span></li>
+</ul>
+</li>
+<li data-link="a1-special-topics"><span>Special Topics</span>
+<ul class="toc_list">
+<li data-link="a1-01-matrix-layout"><span>Handling Matrix Layout Differences on Different Platforms</span>
+<ul class="toc_list">
+<li data-link="a1-01-matrix-layout#two-conventions-of-matrix-transform-math"><span>Two conventions of matrix transform math</span></li>
+<li data-link="a1-01-matrix-layout#discussion"><span>Discussion</span></li>
+<li data-link="a1-01-matrix-layout#matrix-layout"><span>Matrix Layout</span></li>
+<li data-link="a1-01-matrix-layout#overriding-default-matrix-layout"><span>Overriding default matrix layout</span></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
\ No newline at end of file
diff --git a/docs/user-guide/user-guide-toc.html b/docs/user-guide/user-guide-toc.html
deleted file mode 100644
index 0847fcc3e..000000000
--- a/docs/user-guide/user-guide-toc.html
+++ /dev/null
@@ -1,87 +0,0 @@
-<ul class="toc_root_list"><li data-link="index"><span>Slang User's Guide</span>
-<ul class="toc_list">
-<li data-link="00-introduction"><span>Introduction</span>
-<ul class="toc_list">
-<li data-link="00-introduction#why-use-slang"><span>Why use Slang?</span></li>
-<li data-link="00-introduction#who-is-slang-for"><span>Who is Slang for?</span></li>
-<li data-link="00-introduction#who-is-this-guide-for"><span>Who is this guide for?</span></li>
-<li data-link="00-introduction#goals-and-non-goals"><span>Goals and Non-Goals</span></li>
-</ul>
-</li>
-<li data-link="01-get-started"><span>Getting Started with Slang</span>
-<ul class="toc_list">
-<li data-link="01-get-started#installation"><span>Installation</span></li>
-<li data-link="01-get-started#your-first-slang-shader"><span>Your first Slang shader</span></li>
-<li data-link="01-get-started#the-full-example"><span>The full example</span></li>
-</ul>
-</li>
-<li data-link="02-conventional-features"><span>Conventional Language Features</span>
-<ul class="toc_list">
-<li data-link="02-conventional-features#types"><span>Types</span></li>
-<li data-link="02-conventional-features#expressions"><span>Expressions</span></li>
-<li data-link="02-conventional-features#statements"><span>Statements</span></li>
-<li data-link="02-conventional-features#functions"><span>Functions</span></li>
-<li data-link="02-conventional-features#preprocessor"><span>Preprocessor</span></li>
-<li data-link="02-conventional-features#attributes"><span>Attributes</span></li>
-<li data-link="02-conventional-features#global-variables-and-shader-parameters"><span>Global Variables and Shader Parameters</span></li>
-<li data-link="02-conventional-features#shader-entry-points"><span>Shader Entry Points</span></li>
-</ul>
-</li>
-<li data-link="03-convenience-features"><span>Basic Convenience Features</span>
-<ul class="toc_list">
-<li data-link="03-convenience-features#type-inference-in-variable-definitions"><span>Type Inference in Variable Definitions</span></li>
-<li data-link="03-convenience-features#immutable-values"><span>Immutable Values</span></li>
-<li data-link="03-convenience-features#member-functions"><span>Member functions</span></li>
-<li data-link="03-convenience-features#properties"><span>Properties</span></li>
-<li data-link="03-convenience-features#initializers"><span>Initializers</span></li>
-<li data-link="03-convenience-features#operator-overloading"><span>Operator Overloading</span></li>
-<li data-link="03-convenience-features#struct-inheritance-limited"><span>`struct` inheritance (limited)</span></li>
-<li data-link="03-convenience-features#extensions"><span>Extensions</span></li>
-<li data-link="03-convenience-features#modules"><span>Modules</span></li>
-</ul>
-</li>
-<li data-link="04-interfaces-generics"><span>Interfaces and Generics</span>
-<ul class="toc_list">
-<li data-link="04-interfaces-generics#interfaces"><span>Interfaces</span></li>
-<li data-link="04-interfaces-generics#generics"><span>Generics</span></li>
-<li data-link="04-interfaces-generics#supported-constructs-in-interface-definitions"><span>Supported Constructs in Interface Definitions</span></li>
-<li data-link="04-interfaces-generics#associated-types"><span>Associated Types</span></li>
-<li data-link="04-interfaces-generics#generic-value-parameters"><span>Generic Value Parameters</span></li>
-<li data-link="04-interfaces-generics#interface-typed-values"><span>Interface-typed Values</span></li>
-<li data-link="04-interfaces-generics#extending-a-type-with-additional-interface-conformances"><span>Extending a Type with Additional Interface Conformances</span></li>
-<li data-link="04-interfaces-generics#extensions-to-interfaces"><span>Extensions to Interfaces</span></li>
-</ul>
-</li>
-<li data-link="05-compiling"><span>Compiling Code with Slang</span>
-<ul class="toc_list">
-<li data-link="05-compiling#concepts"><span>Concepts</span></li>
-<li data-link="05-compiling#command-line-compilation-with-slangc"><span>Command-Line Compilation with `slangc`</span></li>
-<li data-link="05-compiling#using-the-compilation-api"><span>Using the Compilation API</span></li>
-</ul>
-</li>
-<li data-link="06-targets"><span>Suported Compilation Targets</span>
-<ul class="toc_list">
-<li data-link="06-targets#background-and-terminology"><span>Background and Terminology</span></li>
-<li data-link="06-targets#direct3d-11"><span>Direct3D 11</span></li>
-<li data-link="06-targets#direct3d-12"><span>Direct3D 12</span></li>
-<li data-link="06-targets#vulkan"><span>Vulkan</span></li>
-<li data-link="06-targets#opengl"><span>OpenGL</span></li>
-<li data-link="06-targets#cuda-and-optix"><span>CUDA and OptiX</span></li>
-<li data-link="06-targets#cpu-compute"><span>CPU Compute</span></li>
-<li data-link="06-targets#summary"><span>Summary</span></li>
-</ul>
-</li>
-<li data-link="a1-special-topics"><span>Special Topics</span>
-<ul class="toc_list">
-<li data-link="a1-01-matrix-layout"><span>Handling Matrix Layout Differences on Different Platforms</span>
-<ul class="toc_list">
-<li data-link="a1-01-matrix-layout#two-conventions-of-matrix-transform-math"><span>Two conventions of matrix transform math</span></li>
-<li data-link="a1-01-matrix-layout#overriding-default-matrix-layout"><span>Overriding default matrix layout</span></li>
-<li data-link="a1-01-matrix-layout#summary"><span>Summary</span></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
\ No newline at end of file
-- 
cgit v1.2.3