Rendering a triangle with The Forge

After implementing my own renderer from scratch with Vulkan, I think it’s time to move on to using something a bit higher level. I decided to try out The Forge by ConfettiFX. Unfortunately, the documentation is rather lacking, and the examples are really the only resources available for learning it.

There is a guide on building The Forge by LCG, but it’s outdated and didn’t work for me. I managed to get a triangle rendered on the screen after a few hours of tinkering. In this post, I’ll share the steps I took, to help others like me get started with the framework.

This guide is mainly geared towards people with experience in Vulkan, or any of the modern graphics APIs.

Triangle

Prerequisites (Windows)

TL;DR: Download Visual Studio 2019 version 16.10 here, select and install “Desktop development with C++” package and Windows 10 SDK (10.0.17763.0).

ConfettiFX provides IDE project files for the supported platforms, and since I use Windows, that will be Visual Studio.

The Forge is only tested on Visual Studio 2019 with Windows SDK 10.0.17763.0, so that’s what we’re going to use. If we take a look at Application/Config.h, it specifically wants _MSC_VER == 1929, which is Visual Studio 2019 version 16.10.

// Whitelist of compiler versions
#if (_MSC_VER == 1929) // VS 2019 all VC++ compilers
#else
#pragma message("Bad Visual Studio version: (" QUOTE(_MSC_VER) " " QUOTE(_MSC_FULL_VER) " " QUOTE(_MSC_BUILD) ").")
#error "Bad Visual Studio version"
#endif

I used Wayback Machine to access the Visual Studio download page from June 1st, 2021, downloaded and installed it with the required Windows SDK version.

Visual Studio install page

Cloning and building The Forge

Before we try to do anything with the framework, let’s make sure we can actually run it. First clone the repository:

git clone https://github.com/ConfettiFX/The-Forge.git

To run the examples, you have to download the assets used by them by running the PRE_BUILD.bat file. Then open The-Forge\Examples_3\Unit_Tests\PC Visual Studio 2019\Unit_Tests.sln. Set 01_Transformations as the Startup Project in the Solution Explorer.

Select startup project

Then launch by clicking on Local Windows Debugger. If everything went well the following window with the solar system should open.

Solar system demo

Now we’re ready to create our triangle project.

Creating a new project

In Solution Explorer, create a new project by right clicking Examples, and select Add/New Project.

Create new project

Select the Empty Project template, name the project triangle and put it in the PC Visual Studio 2019 directory.

New project

Visual Studio will create a new directory for our project, but we want our project files to be in the same directory as the other examples (otherwise we’ll have to adjust some paths). First remove the project in Visual Studio:

Remove project

Then copy the project files to the same directory as the other examples and delete the original triangle directory

Copy project

Then add as an existing project

Add existing

Now let’s add a source file. Right click on Source Files and select Add/New Item.

New source file

Create a new directory triangle under Unit_Tests\src and put your source file there. I named mine triangle.cpp.

Source file location

Put the following code in triangle.cpp. Adjust the include path if you need to.

#include "../../../../Common_3/Application/Interfaces/IApp.h"

class Triangle : public IApp
{
    bool Init() override
    {
        return true;
    }

    void Exit() override
    {

    }

    bool Load(ReloadDesc* pReloadDesc) override
    {
        (void)pReloadDesc;
        return true;
    }

    void Unload(ReloadDesc* pReloadDesc) override
    {
        (void)pReloadDesc;
    }

    void Update(float deltaTime) override
    {
        (void)deltaTime;
    }

    void Draw() override
    {

    }

    const char* GetName() override
    {
        return "Triangle";
    }
};


DEFINE_APPLICATION_MAIN(Triangle)

We’ll need to configure our new project. Right click on the project and select Properties.

In Configuration Properties/General, set Output Directory to:

$(SolutionDir)$(Platform)\$(Configuration)\$(ProjectName)\

And set Intermediate Directory to:

$(SolutionDir)\$(Platform)\$(Configuration)\Intermediate\$(ProjectName)\

Make sure that the correct version of Visual Studio and Windows SDK are selected.

General

In Configuration Properties/Debugging, set Working Directory to $(OutDir)

Debugging

In Configuration Properties/VC++ Directories, set Library Directories to:

$(SolutionDir)\$(Platform)\$(Configuration);$(LibraryPath)

VCC directories

In Configuration Properties/Linker/Input, set Additional Dependencies to:

Xinput9_1_0.lib;ws2_32.lib;Renderer.lib;OS.lib;%(AdditionalDependencies)

Linker input

We also need to set the build dependencies. Right click on the project, select Build Dependencies/Project Dependencies.

Project dependencies

Select OS and Renderer

Project dependencies

Now, this error will appear if we try to build:

The examples define D3D12_AGILITY_SDK_VERSION in Examples_3\Build_Props\VS\TF_Shared.props.

<PreprocessorDefinitions>
  D3D12_AGILITY_SDK=1;
  D3D12_AGILITY_SDK_VERSION=715;
  %(PreprocessorDefinitions)
</PreprocessorDefinitions>

TF_Shared.props also imports a platform-specific .props that contains the commands to copy the required resources to the build directory, and a command that launches the shader reload server.

<ImportGroup Label="PropertySheets">
  <Import Condition="$(ProjectDir.Contains('Quest_VisualStudio2019'))" Project="$(TheForgeRoot)Examples_3\Build_Props\VS\Quest.arm64.v8a.props" />
  <Import Condition="$(ProjectDir.Contains('Android_VisualStudio2019'))" Project="$(TheForgeRoot)Examples_3\Build_Props\VS\Android.arm64.v8a.props" />
  <Import Condition="$(ProjectDir.Contains('PC Visual Studio 2019'))" Project="$(TheForgeRoot)Examples_3\Build_Props\VS\Examples.x64.props" />
  <Import Condition="$(ProjectDir.Contains('PS4 Visual Studio 2019'))" Project="$(TheForgeRoot)PS4\VSProps\PS4.props" />
  <Import Condition="$(ProjectDir.Contains('Prospero Visual Studio 2019'))" Project="$(TheForgeRoot)Prospero\VSProps\Prospero.props" />
  <Import Condition="$(ProjectDir.Contains('NX'))" Project="$(TheForgeRoot)Switch\Examples_3\Unit_Tests\NX Visual Studio 2019\ImportNintendoSdk.props" />
</ImportGroup>

On Windows, the imported .props is Examples.x64.props

<ItemDefinitionGroup Condition="'$(ConfigurationType)' == 'Application'">
  <PostBuildEvent>
    <Command>
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\VulkanSDK\bin\Win32\*.dll" "$(OutDir)" /S /Y /D
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\VulkanSDK\bin\Win32\*.json" "$(OutDir)" /S /Y /D
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\ags\ags_lib\lib\amd_ags_x64.dll" "$(OutDir)amd_ags_x64.dll"* /S /Y /D
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\DirectXShaderCompiler\bin\x64\dxcompiler.dll" "$(OutDir)dxcompiler.dll"* /S /Y /D
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\Direct3d12Agility\bin\x64\*.dll" "$(OutDir)"* /S /Y /D
      xcopy "$(TheForgeRoot)Common_3\Graphics\ThirdParty\OpenSource\winpixeventruntime\bin\WinPixEventRuntime.dll" "$(OutDir)WinPixEventRunTime.dll"* /S /Y /D
      xcopy /Y /D "$(TheForgeArtDir)PathStatement.Windows.txt" "$(OutDir)PathStatement.txt*"
      xcopy /Y /D "..\src\$(ProjectName)\GPUCfg\gpu.cfg" "$(OutDir)"

      mkdir "$(OutDir)PipelineCaches\"
      mkdir "$(OutDir)Screenshots\"
      mkdir "$(OutDir)Debug\"
      mkdir "$(OutDir)Scripts\"
      xcopy /Y /D "..\src\$(ProjectName)\Scripts\*" "$(OutDir)\Scripts\"
      xcopy "$(TheForgeRoot)Common_3\Scripts\*" "$(OutDir)\Scripts\" /Y /D

      xcopy "$(TheForgeRoot)Common_3\OS\Windows\pc_gpu.data" "$(OutDir)gpu.data*" /Y /D

      cd "$(TheForgeRoot)"
      powershell start-process ".\Common_3\Tools\ReloadServer\ReloadServer.bat" -WindowStyle Hidden
    </Command>
  </PostBuildEvent>
  <PreLinkEvent>
    <Command>
      if exist "$(OutDir)..\OS\Shaders\" xcopy /Y /S /D "$(OutDir)..\OS\Shaders\*" "$(OutDir)Shaders\"
      if exist "$(OutDir)..\OS\CompiledShaders\" xcopy /Y /S /D "$(OutDir)..\OS\CompiledShaders\*" "$(OutDir)CompiledShaders\"
    </Command>
  </PreLinkEvent>
</ItemDefinitionGroup>

We can define these ourself, but for this project we’re just going to use the provided TF_Shared.props file. Edit triangle.vcxproj and add these lines just before the last </Project> line. Adjust the path to TF_Shared.props if you need to.

<ImportGroup Label="PropertySheets">
  <Import Project="..\..\..\Examples_3\Build_Props\VS\TF_Shared.props" />
</ImportGroup>

If you pay close attention, you’ll notice that we’re missing the gpu.cfg file. It’s not strictly necessary, so it’s not going to be a problem for us.

Reload the project, set it as the startup project and launch. If everything went well a window should pop up.

Window

Now we can start writing the code for our triangle.

Rendering a triangle

The Forge uses FSL (Forge Shading Language). We first need to integrate FSL by right clicking the project, select Build Dependencies/Build Customizations and choose the fsl.target file.

Now we can start writing the shaders for our triangle. First create a new filter for our shaders and name it FSLShaders

Filter

Then right click on FSLShaders and select Add/New Item.

Filter item

Create a new directory Shaders under Unit_Tests\src\triangle and place your shaders there, making sure it ends with .fsl. I named mine triangle.vert.fsl and triangle.frag.fsl. Also add a new file shaders.list in the same directory.

Shader dir

Put the following code in triangle.vert.fsl. Refer to the FSL Programming Guide for more details.

STRUCT(VSInput)
{
    DATA(float4, Position, POSITION);
};

STRUCT(VSOutput)
{
    DATA(float4, Position, SV_Position);
};

ROOT_SIGNATURE(DefaultRootSignature)
VSOutput VS_MAIN(VSInput In)
{
    INIT_MAIN;
    VSOutput Out;

    Out.Position = float4(In.Position.x, In.Position.y, In.Position.z, In.Position.w);
    RETURN(Out);
}

Put this in triangle.frag.fsl

STRUCT(VSOutput)
{
    DATA(float4, Position, SV_Position);
};

ROOT_SIGNATURE(DefaultRootSignature)
float4 PS_MAIN(VSOutput In)
{
    INIT_MAIN;
    float4 Out;

    Out = float4(1.0, 0.0, 0.0, 1.0);
    RETURN(Out);
}

And put this in shaders.list. Adjust the include path if needed.

#include "../../../../../Common_3/Graphics/FSL/defaults.h"

#rootsig default.rootsig
#end

#rootsig compute.rootsig
#end

#vert triangle.vert
#include "triangle.vert.fsl"
#end

#frag triangle.frag
#include "triangle.frag.fsl"
#end

Right click on the project and select Properties. In Configuration Properties/FSLShader:

set Language to DIRECT3D12
set OutDir to $(OutDir)Shaders
set BinaryOutDir to $(OutDir)CompiledShaders
set Compile shader after generation to Yes

Shader properties

Now put this in triangle.cpp. If you’ve used Vulkan then this should look pretty familiar.

// Interfaces
#include "../../../../Common_3/Application/Interfaces/IApp.h"

#include "../../../../Common_3/Utilities/RingBuffer.h"

// Renderer
#include "../../../../Common_3/Graphics/Interfaces/IGraphics.h"
#include "../../../../Common_3/Resources/ResourceLoader/Interfaces/IResourceLoader.h"

// FSL
#include "../../../../Common_3/Graphics/FSL/defaults.h"

Renderer*  pRenderer = NULL;
Queue*     pGraphicsQueue = NULL;
GpuCmdRing gGraphicsCmdRing = {};

SwapChain* pSwapChain = NULL;
Semaphore* pImageAcquiredSemaphore = NULL;

Shader* pTriangleShader = NULL;
Buffer* pTriangleVertexBuffer = NULL;
Pipeline* pTrianglePipeline = NULL;

const uint32_t gFramesInFlight = 2;

const float gTrianglePoints[] = {
    -0.5f, -0.5f, 0.0f, 1.0f,
    0.5f, -0.5f, 0.0f, 1.0f,
    0.0f, 0.5f, 0.0f, 1.0f,
};

class Triangle : public IApp
{
    bool Init() override
    {
        RendererDesc settings;
        memset(&settings, 0, sizeof(settings));
        initGPUConfiguration(settings.pExtendedSettings);
        initRenderer(GetName(), &settings, &pRenderer);

        if (!pRenderer)
        {
            ShowUnsupportedMessage("Failed to Initialize renderer!");
            return false;
        }
        setupGPUConfigurationPlatformParameters(pRenderer, settings.pExtendedSettings);

        QueueDesc queueDesc = {};
        queueDesc.mType = QUEUE_TYPE_GRAPHICS;
        queueDesc.mFlag = QUEUE_FLAG_INIT_MICROPROFILE;
        initQueue(pRenderer, &queueDesc, &pGraphicsQueue);

        GpuCmdRingDesc cmdRingDesc = {};
        cmdRingDesc.pQueue = pGraphicsQueue;
        cmdRingDesc.mPoolCount = gFramesInFlight;
        cmdRingDesc.mCmdPerPoolCount = 1;
        cmdRingDesc.mAddSyncPrimitives = true;
        initGpuCmdRing(pRenderer, &cmdRingDesc, &gGraphicsCmdRing);

        initSemaphore(pRenderer, &pImageAcquiredSemaphore);

        initResourceLoaderInterface(pRenderer);

        RootSignatureDesc rootDesc = {};
        INIT_RS_DESC(rootDesc, "default.rootsig", "compute.rootsig");
        initRootSignature(pRenderer, &rootDesc);

        uint64_t triangleDataSize = 4 * 3 * sizeof(float);
        BufferLoadDesc triangleVbDesc = {};
        triangleVbDesc.mDesc.mDescriptors = DESCRIPTOR_TYPE_VERTEX_BUFFER;
        triangleVbDesc.mDesc.mMemoryUsage = RESOURCE_MEMORY_USAGE_GPU_ONLY;
        triangleVbDesc.mDesc.mSize = triangleDataSize;
        triangleVbDesc.pData = gTrianglePoints;
        triangleVbDesc.ppBuffer = &pTriangleVertexBuffer;
        addResource(&triangleVbDesc, NULL);

        waitForAllResourceLoads();

        return true;
    }

    void Exit() override
    {
        removeResource(pTriangleVertexBuffer);

        exitGpuCmdRing(pRenderer, &gGraphicsCmdRing);
        exitSemaphore(pRenderer, pImageAcquiredSemaphore);

        exitRootSignature(pRenderer);
        exitResourceLoaderInterface(pRenderer);

        exitQueue(pRenderer, pGraphicsQueue);

        exitRenderer(pRenderer);
        exitGPUConfiguration();
        pRenderer = NULL;
    }

    bool Load(ReloadDesc* pReloadDesc) override
    {
        if (pReloadDesc->mType & RELOAD_TYPE_SHADER)
        {
            addShaders();
        }

        if (pReloadDesc->mType & (RELOAD_TYPE_RESIZE | RELOAD_TYPE_RENDERTARGET))
        {
            if (!addSwapChain())
            {
                return false;
            }
        }

        if (pReloadDesc->mType & (RELOAD_TYPE_SHADER | RELOAD_TYPE_RENDERTARGET))
        {
            addPipelines();
        }

        return true;
    }

    void Unload(ReloadDesc* pReloadDesc) override
    {
        waitQueueIdle(pGraphicsQueue);

        if (pReloadDesc->mType & (RELOAD_TYPE_SHADER | RELOAD_TYPE_RENDERTARGET))
        {
            removePipelines();
        }

        if (pReloadDesc->mType & RELOAD_TYPE_SHADER)
        {
            removeShaders();
        }

        if (pReloadDesc->mType & (RELOAD_TYPE_RESIZE | RELOAD_TYPE_RENDERTARGET))
        {
            removeSwapChain(pRenderer, pSwapChain);
        }
    }

    void Update(float deltaTime) override
    {
        (void)deltaTime;
    }

    void Draw() override
    {
        if ((bool)pSwapChain->mEnableVsync != mSettings.mVSyncEnabled)
        {
            waitQueueIdle(pGraphicsQueue);
            ::toggleVSync(pRenderer, &pSwapChain);
        }

        uint32_t swapchainImageIndex;
        acquireNextImage(pRenderer, pSwapChain, pImageAcquiredSemaphore, NULL, &swapchainImageIndex);

        RenderTarget*     pRenderTarget = pSwapChain->ppRenderTargets[swapchainImageIndex];
        GpuCmdRingElement elem = getNextGpuCmdRingElement(&gGraphicsCmdRing, true, 1);

        FenceStatus fenceStatus;
        getFenceStatus(pRenderer, elem.pFence, &fenceStatus);
        if (fenceStatus == FENCE_STATUS_INCOMPLETE)
        {
            waitForFences(pRenderer, 1, &elem.pFence);
        }

        resetCmdPool(pRenderer, elem.pCmdPool);

        Cmd* cmd = elem.pCmds[0];
        beginCmd(cmd);

        RenderTargetBarrier barriers[] = {
            {pRenderTarget, RESOURCE_STATE_PRESENT, RESOURCE_STATE_RENDER_TARGET},
        };
        cmdResourceBarrier(cmd, 0, NULL, 0, NULL, 1, barriers);

        BindRenderTargetsDesc bindRenderTargets = {};
        bindRenderTargets.mRenderTargetCount = 1;
        bindRenderTargets.mRenderTargets[0] = {pRenderTarget, LOAD_ACTION_CLEAR };
        cmdBindRenderTargets(cmd, &bindRenderTargets);
        cmdSetViewport(cmd, 0.0f, 0.0f, (float)pRenderTarget->mWidth, (float)pRenderTarget->mHeight, 0.0f, 1.0f);
        cmdSetScissor(cmd, 0, 0, pRenderTarget->mWidth, pRenderTarget->mHeight);

        const uint32_t triangleVbStride = sizeof(float) * 4;
        cmdBindPipeline(cmd, pTrianglePipeline);
        cmdBindVertexBuffer(cmd, 1, &pTriangleVertexBuffer, &triangleVbStride, NULL);
        cmdDraw(cmd, 3, 0);

        barriers[0] = { pRenderTarget, RESOURCE_STATE_RENDER_TARGET, RESOURCE_STATE_PRESENT };
        cmdResourceBarrier(cmd, 0, NULL, 0, NULL, 1, barriers);

        endCmd(cmd);

        Semaphore* waitSemaphores[] = { pImageAcquiredSemaphore };

        QueueSubmitDesc submitDesc = {};
        submitDesc.mCmdCount = 1;
        submitDesc.mSignalSemaphoreCount = 1;
        submitDesc.mWaitSemaphoreCount = TF_ARRAY_COUNT(waitSemaphores);
        submitDesc.ppCmds = &cmd;
        submitDesc.ppSignalSemaphores = &elem.pSemaphore;
        submitDesc.ppWaitSemaphores = waitSemaphores;
        submitDesc.pSignalFence = elem.pFence;
        queueSubmit(pGraphicsQueue, &submitDesc);

        QueuePresentDesc presentDesc = {};
        presentDesc.mIndex = (uint8_t)swapchainImageIndex;
        presentDesc.mWaitSemaphoreCount = 1;
        presentDesc.pSwapChain = pSwapChain;
        presentDesc.ppWaitSemaphores = &elem.pSemaphore;
        presentDesc.mSubmitDone = true;

        queuePresent(pGraphicsQueue, &presentDesc);
    }

    const char* GetName() override {
        return "Triangle";
    }

    void addPipelines()
    {
        VertexLayout triangleVertexLayout = {};
        triangleVertexLayout.mBindingCount = 1;
        triangleVertexLayout.mBindings[0].mStride = sizeof(float4);
        triangleVertexLayout.mAttribCount = 1;
        triangleVertexLayout.mAttribs[0].mSemantic = SEMANTIC_POSITION;
        triangleVertexLayout.mAttribs[0].mFormat = TinyImageFormat_R32G32B32A32_SFLOAT;
        triangleVertexLayout.mAttribs[0].mBinding = 0;
        triangleVertexLayout.mAttribs[0].mLocation = 0;
        triangleVertexLayout.mAttribs[0].mOffset = 0;

        RasterizerStateDesc rasterizerStateDesc = {};
        rasterizerStateDesc.mCullMode = CULL_MODE_NONE;

        PipelineDesc desc = {};
        desc.mType = PIPELINE_TYPE_GRAPHICS;

        GraphicsPipelineDesc& pipelineSettings = desc.mGraphicsDesc;
        pipelineSettings.mPrimitiveTopo = PRIMITIVE_TOPO_TRI_LIST;
        pipelineSettings.mRenderTargetCount = 1;
        pipelineSettings.pDepthState = NULL;
        pipelineSettings.pColorFormats = &pSwapChain->ppRenderTargets[0]->mFormat;
        pipelineSettings.mSampleCount = pSwapChain->ppRenderTargets[0]->mSampleCount;
        pipelineSettings.mSampleQuality = pSwapChain->ppRenderTargets[0]->mSampleQuality;
        pipelineSettings.pShaderProgram = pTriangleShader;
        pipelineSettings.pVertexLayout = &triangleVertexLayout;
        pipelineSettings.pRasterizerState = &rasterizerStateDesc;
        addPipeline(pRenderer, &desc, &pTrianglePipeline);
    }

    void removePipelines()
    {
        removePipeline(pRenderer, pTrianglePipeline);
    }

    void addShaders()
    {
        ShaderLoadDesc triangleShader = {};
        triangleShader.mVert.pFileName = "triangle.vert";
        triangleShader.mFrag.pFileName = "triangle.frag";

        addShader(pRenderer, &triangleShader, &pTriangleShader);
    }

    void removeShaders()
    {
        removeShader(pRenderer, pTriangleShader);
    }

    bool addSwapChain()
    {
        SwapChainDesc swapChainDesc = {};
        swapChainDesc.mWindowHandle = pWindow->handle;
        swapChainDesc.mPresentQueueCount = 1;
        swapChainDesc.ppPresentQueues = &pGraphicsQueue;
        swapChainDesc.mWidth = mSettings.mWidth;
        swapChainDesc.mHeight = mSettings.mHeight;
        swapChainDesc.mImageCount = getRecommendedSwapchainImageCount(pRenderer, &pWindow->handle);
        swapChainDesc.mColorFormat = getSupportedSwapchainFormat(pRenderer, &swapChainDesc, COLOR_SPACE_SDR_SRGB);
        swapChainDesc.mColorSpace = COLOR_SPACE_SDR_SRGB;
        swapChainDesc.mEnableVsync = mSettings.mVSyncEnabled;
        ::addSwapChain(pRenderer, &swapChainDesc, &pSwapChain);

        return pSwapChain != NULL;
    }
};

DEFINE_APPLICATION_MAIN(Triangle)

Then launch. If everything went well a red triangle should appear.

Triangle

TITLE

DESCRIPTION

CREATED

LAST MODIFIED

POST

Prerequisites (Windows)

Cloning and building The Forge

Creating a new project

Rendering a triangle