RPS Tutorial Part 1 – Hello Triangle

Introduction to RPSL

For a deeper documentation of RPSL, please see rpsl.h.

To begin, let’s recap what we know about RPSL:

• RPSL is an HLSL derivative language.

• An RPSL “shader” is executed on the CPU and is invoked by the RPS runtime.

• Execution of an RPSL shader builds a render graph.

• Execution of a render graph invokes its graph node implementations, each of which constitute a part of a componentized renderer.

For this tutorial, our application will use the following .rpsl file,

graphics node Triangle([readwrite(rendertarget)] texture renderTarget : SV_Target0);

export void main([readonly(present)] texture backbuffer)
{
    // clear and then render geometry to backbuffer
    clear(backbuffer, float4(0.0, 0.2, 0.4, 1.0));
    Triangle(backbuffer);
}

The component renderer that the above RPSL source defines is quite simple; it clears the backbuffer, then executes the Triangle node, which as the application programmer, we understand will render a triangle to the backbuffer.

While the above example demonstrates just a single RPSL program, an RPSL shader can contain many different programs, each of which if executed would build a separate graph. These programs are identified by their entry nodes, which are declared with the keyword export. For the snippet above, the entry point is main.

But, once the program above is executed, what render graph does it build? And, in general, what is the structure of a render graph?

The execution model of RPSL is akin to executing a program on the CPU – during its execution it will make “calls” to the nodes. These aren’t actual “calls” but instead a “touch” – the nodes are noted to be executed and the execution data that was passed into them is saved. Once the RPSL program has completed execution, all touched nodes define the nodes that make up the render graph, which takes the form of a linear, ordered sequence of nodes to call.

And so, when invoking the main entry point in the RPSL program above, it ends up touching two nodes: clear and Triangle. The render graph is thus made up of these two nodes. The clear node is a built-in node – its implementation is already provided by RPS. As for the Triangle node – this is a user-defined node, or, more appropriately, a node declaration. We’ll need to hook an implementation callback to this declaration before executing the render graph.

Let’s not forget one of the key functions of the RPS SDK – to optimize the execution of work on the GPU. To this end, after the render graph is built and before graph execution, the nodes in the graph are reordered by the RPS runtime scheduler. This occurs specifically during the call to rpsRenderGraphUpdate as one of the phases used to build the render graph. As such, the RPSL program author should keep this in mind when writing their RPSL shader. It can be an arbitrary reordering as long as it preserves pipeline correctness.

You may ask, then, what rules are used during scheduling and how can a developer use them to reason about the authoring of a render graph?

It’s all about resource views and access attributes. Resource views are the working flux of RPS. A resource view contains a reference to an underlying resource as well as several view attributes, such as the subresource range over which the resource is viewed. In RPSL, the types of texture and buffer are both resource views. As for access attributes, these are the decoration on-top. They specify how a node accesses resources through its resource view parameters. It is through this specification that implicit ordering dependencies are defined, to which the RPS scheduler must guarantee.

It would be a fair assumption to make that the clear node is scheduled before the Triangle node, and indeed, that would be correct. But why is that?

Let’s consider the node definitions. We’ll start with the clear node (there are many overloads, so this is just one):

node clear( [writeonly(rendertarget, clear)] texture dst, float4 clearValue );

From this definition, we can say that the first access of the backbuffer in the frame is with an access attribute of writeonly. This means that the first access can only write to the backbuffer, not read from it, and that the previous data can be discarded. The subsequent Triangle node accesses the backbuffer with the access attribute of readwrite. This means that the node can both read and write to the backbuffer. The program order access sequence thus goes as: writeonly (WO) -> readwrite (RW). Such a sequence must not be reordered. Placing the WO after the RW discards whatever the Triangle node has generated, functionally altering the specified pipeline. Since the re-ordering would be invalid, the scheduler must keep the program order.

Right, but, what is going on with the rendertarget part in the Triangle node? This is an argument to the access attribute, and it plays a special role in the specification of the pipeline as well. The rendertarget argument means that the resource view node parameter it decorates is accessible as a render target view. This has different implications depending on the runtime backend in use. For example, one of the requirements that a DX12 runtime backend fulfils is to ensure the resource is in the D3D12_RESOURCE_STATE_RENDER_TARGET state before the node callback is invoked. A render target view is very common, as are various other accesses. Thus, RPS defines a set of convenience macros; e.g., rtv is an alias for [readwrite(rendertarget)] texture.

The last part to break down in the .rpsl above is the access attribute of the entry node as this has different semantics than accesses by regular node declarations. For the entry nodes, the access attributes do not apply within the node scope, but rather outside the node scope. This establishes an enter/exit state for the resources accessed by the entry. The input parameter into main is accessed with [readonly(present)]. This is what we want – after using the render graph to render the frame, we present the backbuffer to the swapchain.

To bring it all together, we’ll reflect on what we’ve just built. We’ve built a component renderer that clears the backbuffer via the built-in clear node, and then executes the Triangle node implementation (user-defined), ultimately making a draw call with whatever graphics API that happens to be in use. Finally, at the frame end, the backbuffer is transitioned into the D3D12_RESOURCE_STATE_PRESENT state.

Compiling and linking the RPSL module

Referring once again back to our brief RPS introduction, the .rpsl shader document must be compiled. This is achieved via the bundled RPSL compiler, rps-hlslc.

To compile an RPSL file, simply execute,

rps-hlslc.exe rps_tutorial_p1.rpsl -O0

The result of this compilation, as priorly stated, is a .c file. However, it is also possible to compile our module into a DLL, or even load it via the RPSL-JIT compiler. For now, we will do the simplest possible thing – statically link with some .c file.

To do so, it begins with a call to a function-like macro – no .h is required, nor is it generated by the RPSL compiler. For our case, that looks like this:

// ...
RPS_DECLARE_RPSL_ENTRY(rps_tutorial_p1, main);
// ...

With this macro, we can forward declare some entry found in a .c RPSL module and later specify in RpsRenderGraphCreateInfo that this function is the main entry point. The macro is here to deal with the implementation details of the RPSL .c backend output and the RPS runtime linkage to that, which is permitted to be different than the conceptual model of “linking with a function”. It’s important to make sure that you have the correct module and entry name in your macro, as incorrect information may lead to a complicated debugging process.

Alright, we’re finally ready to make the call to rpsRenderGraphCreate,

virtual void OnInit(ID3D12GraphicsCommandList*         pInitCmdList,
                    std::vector<ComPtr<ID3D12Object>>& tempResources) override
{
    // ...
    // Create RPS render graph.
    RpsRenderGraphCreateInfo renderGraphInfo = {};
    RpsQueueFlags            queueFlags[]  = {RPS_QUEUE_FLAG_GRAPHICS, RPS_QUEUE_FLAG_COMPUTE, RPS_QUEUE_FLAG_COPY};
    renderGraphInfo.scheduleInfo.numQueues = 3;
    renderGraphInfo.scheduleInfo.pQueueInfos            = queueFlags;
    renderGraphInfo.mainEntryCreateInfo.hRpslEntryPoint = RPS_ENTRY_REF(hello_triangle, main);
    AssertIfRpsFailed(rpsRenderGraphCreate(m_rpsDevice, &renderGraphInfo, &m_rpsRenderGraph));
    // ...
}

Calling rpsRenderGraphCreate does not execute the main RPSL module; it merely sets up the RenderGraph object.

If this call returns with RPS_OK, you’re good to go! Otherwise, one thing to note about this call is the scheduleInfo structure member.

Here, we specify to RPS the available queues and their index layout. This mapping of indices to queues becomes relevant later, when RPS will communicate a piece of work to be scheduled on some queue index. In the snippet above, we associate queue indices 0, 1, and 2 to the application managed Graphics, Compute, and Copy queues. These managed queues and their index ordering are particular to our app framework. The queue indices are used in our hello triangle example to index into an array storing the queue pointers. In general, an application should communicate to RPS the correct queue indices given the application defined index layout of the available queues.

Temporal resources

Temporal resources are comprised of slices. For any given frame, a temporal resource will resolve to one of its slices (which is itself a resource). The selected slice to resolve to is computed via the frameIndex member within RpsRenderGraphUpdateInfo as well as the TemporalLayer member of the resource view.

The computation for resolving temporal slices is as follows,

uint32_t temporalSliceIdx = (frameIndex - std::min(TemporalLayer, frameIndex)) % numTemporalLayers;

By default, resource views have TemporalLayer set to zero, which causes the resolved slice to be that for the current frame.

While the temporal resource construct is useful for the specific problem of resolving to the correct render target for the frame, the power of this construct is of course much more – most generically, temporal resources allow for easy historical data access. Setting TemporalLayer can be used to access historical temporal slices. To set the temporal layer on the resource view, a derived view must be created. In RPSL, this can be achieved via something like resA.temporal(1). This is a view that would access the slice of some resA that a default view of resA last frame would have accessed.

Providing input arguments to the render graph

In the snippet below, we update the render graph and provide our swapchain images / temporal slices as an array of ID3D12Resource handles to the RPSL program via ppArgResources.

virtual void OnUpdate(uint32_t frameIndex) override
{
    if (m_rpsRenderGraph != RPS_NULL_HANDLE)
    {
        RpsRuntimeResource backBufferResources[DXGI_MAX_SWAP_CHAIN_BUFFERS];

        for (uint32_t i = 0; i < m_backBuffers.size(); i++)
        {
            // RpsRuntimeResource is a RPS_OPAQUE_HANDLE.
            // this type has a single elem "void* ptr".
            backBufferResources[i].ptr = m_backBuffers[i].Get();
        }

        RpsResourceDesc backBufferDesc   = {};
        backBufferDesc.type              = RPS_RESOURCE_TYPE_IMAGE_2D;
        backBufferDesc.temporalLayers    = uint32_t(m_backBuffers.size());
        backBufferDesc.image.width       = m_width;
        backBufferDesc.image.height      = m_height;
        backBufferDesc.image.arrayLayers = 1;
        backBufferDesc.image.mipLevels   = 1;
        backBufferDesc.image.format      = RPS_FORMAT_R8G8B8A8_UNORM;
        backBufferDesc.image.sampleCount = 1;

        RpsConstant               argData[]      = {&backBufferDesc};
        const RpsRuntimeResource* argResources[] = {backBufferResources};

        uint32_t argDataCount = 1;
        // ...

        // RpsAfx always waits for presentation before rendering to a swapchain image again,
        // therefore the guaranteed last completed frame by the GPU is m_backBufferCount frames ago.
        //
        // RPS_GPU_COMPLETED_FRAME_INDEX_NONE means no frames are known to have completed yet;
        // we use this during the initial frames.
        const uint64_t completedFrameIndex =
            (frameIndex > m_backBufferCount) ? frameIndex - m_backBufferCount : RPS_GPU_COMPLETED_FRAME_INDEX_NONE;

        RpsRenderGraphUpdateInfo updateInfo = {};
        updateInfo.frameIndex               = frameIndex;
        updateInfo.gpuCompletedFrameIndex   = completedFrameIndex;
        updateInfo.numArgs                  = argDataCount;
        updateInfo.ppArgs                   = argData;
        updateInfo.ppArgResources           = argResources;

        assert(_countof(argData) == _countof(argResources));

        AssertIfRpsFailed(rpsRenderGraphUpdate(m_rpsRenderGraph, &updateInfo));
    }
}

In general, arguments are provided to the main entry point of an RPSL program by setting the ppArgResources and ppArgs members of RpsRenderGraphUpdateInfo. These members are both arrays with an element type of pointer. For every pointer within ppArgs, there is a corresponding pointer to a resource handle (each of type const RpsRuntimeResource *) in ppArgResources. For temporal resources, the corresponding pointer to a resource handle points to an entire array of resource handles, and indeed, this is what is done in the OnUpdate function above.

It is also legal that a pointer in ppArgs points merely to a built-in type such as int or float, with the corresponding pointer in ppArgsResources being nullptr. In general, any C struct / POD C++ class may be passed so long as the arguments at each index match in memory size and layout between the host app and HLSL. Please note that since HLSL booleans are 32 bit, having an element in ppArgs with type bool is undefined behavior. To this end, we provide a type typedef int32_t RpsBool;.

We note further the gpuCompletedFrameIndex member. The host application should populate this to a value that communicates, at the very least, a frame index whose associated command buffers are guaranteed to have completed on the GPU. RPS uses this value to manage frame resources. If the application continually provides the value of RPS_GPU_COMPLETED_FRAME_INDEX_NONE, RPS may encounter an internal memory error, as there is a limit to the amount of frame resources that may be buffered.

Finally, we note that while a graph might be built correctly, it could be semantically invalid. Currently, at least some semantic verifications that the RPS SDK performs are done online. In such cases, the SDK errors out with RPS_ERROR_INVALID_PROGRAM.

Post-record logic

Even with the render graph commands recorded, there’s still some work to do for our OnRender function! The batch may also specify that after submission we must signal some value on the queue,

virtual void OnRender(uint32_t frameIndex) override
{
    // ...
    if (batch.signalFenceIndex != RPS_INDEX_NONE_U32)
    {
        m_fenceValue++;
        FenceSignalInfo& sInfo = m_fenceSignalInfos[batch.signalFenceIndex];
        sInfo.queueIndex       = batch.queueIndex;
        sInfo.value            = m_fenceValue;
        AssertIfFailed(m_queues[batch.queueIndex]->Signal(m_fences[sInfo.queueIndex].Get(), sInfo.value));
    }
    // ...
}

In fact, it is this exact signal scheduling moment that produces those fence signal wait calls prior to submission of the batch. While it might have been obvious already, we’ll mention that RPS elects to schedule commands like this (in batches) for the purpose of multi-queue and asynchronous compute scenarios.