Update gfx getting started doc (#1832)

3 files changed, 64 insertions, 151 deletions

diff --git a/docs/gfx-user-guide/01-getting-started.md b/docs/gfx-user-guide/01-getting-started.md
index a6f6b241c..41b9738f6 100644
--- a/docs/gfx-user-guide/01-getting-started.md
+++ b/docs/gfx-user-guide/01-getting-started.md
@@ -31,7 +31,7 @@ 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++
+```cpp
 #include "slang-gfx.h"
 
 using namespace gfx;
@@ -56,7 +56,7 @@ The Slang Graphics Layer provides a debug layer that can be enabled to perform a
 
 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++
+```cpp
 struct MyDebugCallback : public IDebugCallback
 {
     virtual SLANG_NO_THROW void SLANG_MCALL handleMessage(
@@ -79,121 +79,43 @@ void initGfx()
 }
 ```
 
-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:
+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`.
+```cpp
+ICommandQueue* gQueue = nullptr;
 
-```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;
-    }
+ICommandQueue::Desc queueDesc = {ICommandQueue::QueueType::Graphics};
+device->createCommandQueue(queueDesc, &gQueue);
+```
 
-    // 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);
-    }
+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`.
 
-    // 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);
+```cpp
+ITransientResourceHeap* gTransientHeap;
 
-    // Since we no longer need to use `shaderProgram` after creating
-    // a pipeline state, we should release it to prevent memory leaks.
-    shaderProgram->release();
-}
+ITransientResourceHeap::Desc transientHeapDesc = {};
+transientHeapDesc.constantBufferSize = 4096;
+device->createTransientResourceHeap(transientHeapDesc, &gTransientHeap);
+```
+
+With a `TransientResourceHeap`, we can call `createCommandBuffer` method to allocate a command buffer:
+
+```cpp
+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.
+
 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++
+We need to create the buffer resources used our `hello-world` shader as input and output. This can be done via `IDevice::createBufferResource` method. When creating a resource, the user must specify a resource state that the resource will be in by default, as well as all allowed resource states the resource can be in. Resource states in the graphics layer follows the same model of resource states in D3D12, and the user can also assume the same automatic resource promotion/demotion behavior in D3D12.
+
+```cpp
 const int numberCount = 4;
 float initialData[] = {0.0f, 1.0f, 2.0f, 3.0f};
 IBufferResource::Desc bufferDesc = {};
@@ -210,37 +132,37 @@ SLANG_RETURN_ON_FAIL(device->createBufferResource(
     &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;
+Creating a Pipeline State
+---------------------------
 
-ITransientResourceHeap::Desc transientHeapDesc = {};
-transientHeapDesc.constantBufferSize = 4096;
-device->createTransientResourceHeap(transientHeapDesc, &gTransientHeap);
-```
+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 creates a Graphics layer `IPipelineState` object from a shader module represented by a `slang::IComponentType` object:
 
-With a `TransientResourceHeap`, we can call `createCommandBuffer` method to allocate a command buffer:
+```cpp
+void createComputePipelineFromShader(
+    IComponentType* slangProgram, 
+    IPipelineState*& outPipelineState)
+{
+    // The `IComponentType` parameter 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 = slangProgram;
+    gDevice->createShaderProgram(programDesc, &shaderProgram);
+    
+    // Create a compute pipeline state from `shaderProgram`.
+    ComputePipelineStateDesc pipelineDesc = {};
+    pipelineDesc.program = shaderProgram;
+    gDevice->createComputePipelineState(pipelineDesc, &outPipelineState);
 
-```C++
-ICommandBuffer* commandBuffer;
-gTransientHeap->createCommandBuffer(&commandBuffer);
+    // Since we no longer need to use `shaderProgram` after creating
+    // a pipeline state, we should release it to prevent memory leaks.
+    shaderProgram->release();
+}
 ```
 
-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
 ------------------------------------
 
@@ -251,19 +173,19 @@ set the compute pipeline state, bind shader parameters, and dispatch a kernel la
 
 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++
+```cpp
 IComputeCommandEncoder* encoder = commandBuffer->encodeComputeCommands();
 ```
 
 The first command is to bind the pipeline state we created earlier:
 
-```C++
+```cpp
 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++
+```cpp
 // Create a resource view for buffer0.
 IBufferView* buffer0View;
 {
@@ -303,7 +225,7 @@ rootObject->setResource(ShaderOffset{0,2,0}, resultView);
 
 After binding all shader parameters, we can now dispatch the kernel:
 
-```C++
+```cpp
 encoder->dispatchCompute(1, 1, 1);
 ```
 
@@ -313,13 +235,13 @@ encoder->dispatchCompute(1, 1, 1);
 
 When we are done recording commands, we need to close the command encoder and the command buffer.
 
-```C++
+```cpp
 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++
+```cpp
 gQueue->executeCommandBuffer(commandBuffer);
 gQueue->wait();
 ```
@@ -329,7 +251,7 @@ Cleaning Up
 
 At the end of our example, we need to make sure all created objects are released by calling the `release` method:
 
-```C++
+```cpp
 commandBuffer->release();
 gQueue->release();
 gTransientResourceHeap->release();
diff --git a/docs/gfx-user-guide/build_toc.ps1 b/docs/gfx-user-guide/build_toc.ps1
deleted file mode 100644
index 567a73988..000000000
--- a/docs/gfx-user-guide/build_toc.ps1
+++ /dev/null
@@ -1,9 +0,0 @@
-$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/toc.html b/docs/gfx-user-guide/toc.html
index 197790b93..be64cca17 100644
--- a/docs/gfx-user-guide/toc.html
+++ b/docs/gfx-user-guide/toc.html
@@ -5,10 +5,10 @@
 <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#creating-buffer-resource"><span>Creating Buffer Resource</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#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>