Add Hello world example. (#1797)

3 files changed, 476 insertions, 0 deletions

diff --git a/examples/triangle/README.md b/examples/triangle/README.md
new file mode 100644
index 000000000..ba377b8cb
--- /dev/null
+++ b/examples/triangle/README.md
@@ -0,0 +1,12 @@
+Slang "Hello World" Example
+===========================
+
+The goal of this example is to demonstrate an almost minimal application that uses Slang for shading.
+
+The `shaders.slang` file contains simple vertex and fragment shader entry points. The shader code should compile as either Slang or HLSL code (that is, this example does not show off any new Slang language features).
+
+The `main.cpp` file contains the C++ application code, showing how to use the Slang API to load and compile the shader code to DirectX shader bytecode (DXBC).
+The application perform rendering using the D3D11 API, through a platform and graphics API abstraction layer that is implemented in `tools/gfx`.
+Note that this abstraction layer is *not* required in order to work with Slang, and it is just there to help us write example and test applications more conveniently.
+
+This example is not necessarily representative of best practices for integrating Slang into a production engine; the goal is merely to use the minimum amount of code possible to demonstrate a complete applicaiton that uses Slang.
diff --git a/examples/triangle/main.cpp b/examples/triangle/main.cpp
new file mode 100644
index 000000000..6b9104072
--- /dev/null
+++ b/examples/triangle/main.cpp
@@ -0,0 +1,398 @@
+// main.cpp
+
+// This file implements an extremely simple example of loading and
+// executing a Slang shader program. This is primarily an example
+// of how to use Slang as a "drop-in" replacement for an existing
+// HLSL compiler like the `D3DCompile` API. More advanced usage
+// of advanced Slang language and API features is left to the
+// next example.
+//
+// The comments in the file will attempt to explain concepts as
+// they are introduced.
+//
+// Of course, in order to use the Slang API, we need to include
+// its header. We have set up the build options for this project
+// so that it is as simple as:
+//
+#include <slang.h>
+//
+// Other build setups are possible, and Slang doesn't assume that
+// its include directory must be added to your global include
+// path.
+
+// For the purposes of keeping the demo code as simple as possible,
+// while still retaining some level of portability, our examples
+// make use of a small platform and graphics API abstraction layer,
+// which is included in the Slang source distribution under the
+// `tools/` directory.
+//
+// Applications can of course use Slang without ever touching this
+// abstraction layer, so we will not focus on it when explaining
+// examples, except in places where best practices for interacting
+// with Slang may depend on an application/engine making certain
+// design choices in their abstraction layer.
+//
+#include "slang-gfx.h"
+#include "gfx-util/shader-cursor.h"
+#include "tools/platform/window.h"
+#include "slang-com-ptr.h"
+#include "source/core/slang-basic.h"
+#include "examples/example-base/example-base.h"
+
+using namespace gfx;
+using namespace Slang;
+
+// For the purposes of a small example, we will define the vertex data for a
+// single triangle directly in the source file. It should be easy to extend
+// this example to load data from an external source, if desired.
+//
+struct Vertex
+{
+    float position[3];
+    float color[3];
+};
+
+static const int kVertexCount = 3;
+static const Vertex kVertexData[kVertexCount] =
+{
+    { { 0,  0, 0.5 }, { 1, 0, 0 } },
+    { { 0,  1, 0.5 }, { 0, 0, 1 } },
+    { { 1,  0, 0.5 }, { 0, 1, 0 } },
+};
+
+// The example application will be implemented as a `struct`, so that
+// we can scope the resources it allocates without using global variables.
+//
+struct HelloWorld : public WindowedAppBase
+{
+
+// Many Slang API functions return detailed diagnostic information
+// (error messages, warnings, etc.) as a "blob" of data, or return
+// a null blob pointer instead if there were no issues.
+//
+// For convenience, we define a subroutine that will dump the information
+// in a diagnostic blob if one is produced, and skip it otherwise.
+//
+void diagnoseIfNeeded(slang::IBlob* diagnosticsBlob)
+{
+    if( diagnosticsBlob != nullptr )
+    {
+        printf("%s", (const char*) diagnosticsBlob->getBufferPointer());
+    }
+}
+
+// The main task an application cares about is compiling shader code
+// from souce (if needed) and loading it through the chosen graphics API.
+//
+// In addition, an application may want to receive reflection information
+// about the program, which is what a `slang::ProgramLayout` provides.
+//
+gfx::Result loadShaderProgram(
+    gfx::IDevice*         device,
+    gfx::IShaderProgram**   outProgram)
+{
+    // We need to obatin a compilation session (`slang::ISession`) that will provide
+    // a scope to all the compilation and loading of code we do.
+    //
+    // Our example application uses the `gfx` graphics API abstraction layer, which already
+    // creates a Slang compilation session for us, so we just grab and use it here.
+    ComPtr<slang::ISession> slangSession;
+    slangSession = device->getSlangSession();
+
+    // We can now start loading code into the slang session.
+    //
+    // The simplest way to load code is by calling `loadModule` with the name of a Slang
+    // module. A call to `loadModule("MyStuff")` will behave more or less as if you
+    // wrote:
+    //
+    //      import MyStuff;
+    //
+    // In a Slang shader file. The compiler will use its search paths to try to locate
+    // `MyModule.slang`, then compile and load that file. If a matching module had
+    // already been loaded previously, that would be used directly.
+    //
+    ComPtr<slang::IBlob> diagnosticsBlob;
+    slang::IModule* module = slangSession->loadModule("shaders", diagnosticsBlob.writeRef());
+    diagnoseIfNeeded(diagnosticsBlob);
+    if(!module)
+        return SLANG_FAIL;
+
+    // Loading the `shaders` 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("vertex")] void vertexMain(...)`). 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> vertexEntryPoint;
+    SLANG_RETURN_ON_FAIL(module->findEntryPointByName("vertexMain", vertexEntryPoint.writeRef()));
+    //
+    ComPtr<slang::IEntryPoint> fragmentEntryPoint;
+    SLANG_RETURN_ON_FAIL(module->findEntryPointByName("fragmentMain", fragmentEntryPoint.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(module);
+
+    // Later on when we go to extract compiled kernel code for our vertex
+    // and fragment shaders, we will need to make use of their order within
+    // the composition, so we will record the relative ordering of the entry
+    // points here as we add them.
+    int entryPointCount = 0;
+    int vertexEntryPointIndex = entryPointCount++;
+    componentTypes.add(vertexEntryPoint);
+
+    int fragmentEntryPointIndex = entryPointCount++;
+    componentTypes.add(fragmentEntryPoint);
+
+    // 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> linkedProgram;
+    SlangResult result = slangSession->createCompositeComponentType(
+        componentTypes.getBuffer(),
+        componentTypes.getCount(),
+        linkedProgram.writeRef(),
+        diagnosticsBlob.writeRef());
+    diagnoseIfNeeded(diagnosticsBlob);
+    SLANG_RETURN_ON_FAIL(result);
+
+    // Once we've described the particular composition of entry points
+    // that we want to compile, we defer to the graphics API layer
+    // to extract compiled kernel code and load it into the API-specific
+    // program representation.
+    //
+    gfx::IShaderProgram::Desc programDesc = {};
+    programDesc.pipelineType = gfx::PipelineType::Graphics;
+    programDesc.slangProgram = linkedProgram;
+    SLANG_RETURN_ON_FAIL(device->createProgram(programDesc, outProgram));
+
+    return SLANG_OK;
+}
+
+//
+// The above function shows the core of what is required to use the
+// Slang API as a simple compiler (e.g., a drop-in replacement for
+// fxc or dxc).
+//
+// The rest of this file implements an extremely simple rendering application
+// that will execute the vertex/fragment shaders loaded with the function
+// we have just defined.
+//
+
+// We will define global variables for the various platform and
+// graphics API objects that our application needs:
+//
+// As a reminder, *none* of these are Slang API objects. All
+// of them come from the utility library we are using to simplify
+// building an example program.
+//
+ComPtr<gfx::IPipelineState> gPipelineState;
+ComPtr<gfx::IBufferResource> gVertexBuffer;
+
+// Now that we've covered the function that actually loads and
+// compiles our Slang shade code, we can go through the rest
+// of the application code without as much commentary.
+//
+Slang::Result initialize()
+{
+    // Create a window for our application to render into.
+    //
+    initializeBase("hello-world", 1024, 768);
+
+    // We will create objects needed to configur the "input assembler"
+    // (IA) stage of the D3D pipeline.
+    //
+    // First, we create an input layout:
+    //
+    InputElementDesc inputElements[] = {
+        { "POSITION", 0, Format::RGB_Float32, offsetof(Vertex, position) },
+        { "COLOR",    0, Format::RGB_Float32, offsetof(Vertex, color) },
+    };
+    auto inputLayout = gDevice->createInputLayout(
+        &inputElements[0],
+        2);
+    if(!inputLayout) return SLANG_FAIL;
+
+    // Next we allocate a vertex buffer for our pre-initialized
+    // vertex data.
+    //
+    IBufferResource::Desc vertexBufferDesc;
+    vertexBufferDesc.init(kVertexCount * sizeof(Vertex));
+    vertexBufferDesc.setDefaults(IResource::Usage::VertexBuffer);
+    gVertexBuffer = gDevice->createBufferResource(
+        IResource::Usage::VertexBuffer,
+        vertexBufferDesc,
+        &kVertexData[0]);
+    if(!gVertexBuffer) return SLANG_FAIL;
+
+    // Now we will use our `loadShaderProgram` function to load
+    // the code from `shaders.slang` into the graphics API.
+    //
+    ComPtr<IShaderProgram> shaderProgram;
+    SLANG_RETURN_ON_FAIL(loadShaderProgram(gDevice, shaderProgram.writeRef()));
+
+    // Following the D3D12/Vulkan style of API, we need a pipeline state object
+    // (PSO) to encapsulate the configuration of the overall graphics pipeline.
+    //
+    GraphicsPipelineStateDesc desc;
+    desc.inputLayout = inputLayout;
+    desc.program = shaderProgram;
+    desc.framebufferLayout = gFramebufferLayout;
+    auto pipelineState = gDevice->createGraphicsPipelineState(desc);
+    if (!pipelineState)
+        return SLANG_FAIL;
+
+    gPipelineState = pipelineState;
+
+    return SLANG_OK;
+}
+
+// With the initialization out of the way, we can now turn our attention
+// to the per-frame rendering logic. As with the initialization, there is
+// nothing really Slang-specific here, so the commentary doesn't need
+// to be very detailed.
+//
+virtual void renderFrame(int frameBufferIndex) override
+{
+    ComPtr<ICommandBuffer> commandBuffer = gTransientHeaps[frameBufferIndex]->createCommandBuffer();
+    auto renderEncoder = commandBuffer->encodeRenderCommands(gRenderPass, gFramebuffers[frameBufferIndex]);
+
+    gfx::Viewport viewport = {};
+    viewport.maxZ = 1.0f;
+    viewport.extentX = (float)windowWidth;
+    viewport.extentY = (float)windowHeight;
+    renderEncoder->setViewportAndScissor(viewport);
+
+    // In order to bind shader parameters to the pipeline, we need
+    // to know how those parameters were assigned to locations/bindings/registers
+    // for the target graphics API.
+    //
+    // The Slang compiler assigns locations to parameters in a deterministic
+    // fashion, so it is possible for a programmer to hard-code locations
+    // into their application code that will match up with their shaders.
+    //
+    // Hard-coding of locations can become intractable as an application needs
+    // to support more different target platforms and graphics APIs, as well
+    // as more shaders with different specialized variants.
+    //
+    // Rather than rely on hard-coded locations, our examples will make use of
+    // reflection information provided by the Slang compiler (see `programLayout`
+    // above), and our example graphics API layer will translate that reflection
+    // information into a layout for a "root shader object."
+    //
+    // The root object will store values/bindings for all of the parameters in
+    // the `IShaderProgram` used to create the pipeline state. At a conceptual
+    // level we can think of `rootObject` as representing the "global scope" of
+    // the shader program that was loaded; it has entries for each global shader
+    // parameter that was declared.
+    //
+    // Readers who are familiar with D3D12 or Vulkan might think of this root
+    // layout as being similar in spirit to a "root signature" or "pipeline layout."
+    //
+    // We start parameter binding by binding the pipeline state in command encoder.
+    // This method will return a transient root shader object for us to write our
+    // shader parameters into.
+    //
+    auto rootObject = renderEncoder->bindPipeline(gPipelineState);
+
+    // We will update the model-view-projection matrix that is passed
+    // into the shader code via the `Uniforms` buffer on a per-frame
+    // basis, even though the data that is loaded does not change
+    // per-frame (we always use an identity matrix).
+    //
+    auto deviceInfo = gDevice->getDeviceInfo();
+
+    // We know that `rootObject` is a root shader object created
+    // from our program, and that it is set up to hold values for
+    // all the parameter of that program. In order to actually
+    // set values, we need to be able to look up the location
+    // of speciic parameter that we want to set.
+    //
+    // Our example graphics API layer supports this operation
+    // with the idea of a *shader cursor* which can be thought
+    // of as pointing "into" a particular shader object at
+    // some location/offset. This design choice abstracts over
+    // the many ways that different platforms and APIs represent
+    // the necessary offset information.
+    //
+    // We construct an initial shader cursor that points at the
+    // entire shader program. You can think of this as akin to
+    // a diretory path of `/` for the root directory in a file
+    // system.
+    //
+    ShaderCursor rootCursor(rootObject);
+    //
+    // Next, we use a convenience overload of `operator[]` to
+    // navigate from the root cursor down to the parameter we
+    // want to set.
+    //
+    // The operation `rootCursor["Uniforms"]` looks up the
+    // offset/location of the global shader parameter `Uniforms`
+    // (which is a uniform/constant buffer), and the subsequent
+    // `["modelViewProjection"]` step navigates from there down
+    // to the member named `modelViewProjection` in that buffer.
+    //
+    // Once we have formed a cursor that "points" at the
+    // model-view projection matrix, we can set its data directly.
+    //
+    rootCursor["Uniforms"]["modelViewProjection"].setData(
+        deviceInfo.identityProjectionMatrix, sizeof(float) * 16);
+    //
+    // Some readers might be concerned about the performance o
+    // the above operations because of the use of strings. For
+    // those readers, here are two things to note:
+    //
+    // * While these `operator[]` steps do need to perform string
+    //   comparisons, they do *not* make copies of the strings or
+    //   perform any heap allocation.
+    //
+    // * There are other overloads of `operator[]` that use the
+    //   *index* of a parameter/field instead of its name, and those
+    //   operations have fixed/constant overhead and perform no
+    //   string comparisons. The indices used are independent of
+    //   the target platform and graphics API, and can thus be
+    //   hard-coded even in cross-platform code.
+    //
+
+    // We also need to set up a few pieces of fixed-function pipeline
+    // state that are not bound by the pipeline state above.
+    //
+    renderEncoder->setVertexBuffer(0, gVertexBuffer, sizeof(Vertex));
+    renderEncoder->setPrimitiveTopology(PrimitiveTopology::TriangleList);
+
+    // Finally, we are ready to issue a draw call for a single triangle.
+    //
+    renderEncoder->draw(3);
+    renderEncoder->endEncoding();
+    commandBuffer->close();
+    gQueue->executeCommandBuffer(commandBuffer);
+
+    // With that, we are done drawing for one frame, and ready for the next.
+    //
+    gSwapchain->present();
+}
+
+};
+
+// This macro instantiates an appropriate main function to
+// run the application defined above.
+PLATFORM_UI_MAIN(innerMain<HelloWorld>)
diff --git a/examples/triangle/shaders.slang b/examples/triangle/shaders.slang
new file mode 100644
index 000000000..fe35db9c8
--- /dev/null
+++ b/examples/triangle/shaders.slang
@@ -0,0 +1,66 @@
+// shaders.slang
+
+//
+// This file provides a simple vertex and fragment shader that can be compiled
+// using Slang. This code should also be valid as HLSL, and thus it does not
+// use any of the new language features supported by Slang.
+//
+
+// Uniform data to be passed from application -> shader.
+cbuffer Uniforms
+{
+    float4x4 modelViewProjection;
+}
+
+// Per-vertex attributes to be assembled from bound vertex buffers.
+struct AssembledVertex
+{
+    float3	position : POSITION;
+    float3	color    : COLOR;
+};
+
+// Output of the vertex shader, and input to the fragment shader.
+struct CoarseVertex
+{
+    float3 color;
+};
+
+// Output of the fragment shader
+struct Fragment
+{
+    float4 color;
+};
+
+// Vertex  Shader
+
+struct VertexStageOutput
+{
+    CoarseVertex    coarseVertex    : CoarseVertex;
+    float4          sv_position     : SV_Position;
+};
+
+[shader("vertex")]
+VertexStageOutput vertexMain(
+    AssembledVertex assembledVertex)
+{
+    VertexStageOutput output;
+
+    float3 position = assembledVertex.position;
+    float3 color    = assembledVertex.color;
+
+    output.coarseVertex.color = color;
+    output.sv_position = mul(modelViewProjection, float4(position, 1.0));
+
+    return output;
+}
+
+// Fragment Shader
+
+[shader("fragment")]
+float4 fragmentMain(
+    CoarseVertex coarseVertex : CoarseVertex) : SV_Target
+{
+    float3 color = coarseVertex.color;
+
+    return float4(color, 1.0);
+}