# Shapes and forms of DX12 root signatures

Tue
14
May 2024

This article is for you if you are a programmer using Direct3D 12. We will talk about a specific part of the API: root signatures. I will provide a comprehensive description of various formats in which they can be specified, stored, and ways to convert between them. The difficulty of this article is intermediate. You are expected to know at least some basics of D3D12. I think that advanced developers will can also learn something new, as some of the topics shown here are not what we typically use in a day-to-day development with D3D12.

Tools of the trade

I will use C++ as the programming language. Wherever possible, I will also try to use standalone command-line tools instead of writing a custom code. To repeat my experiments demonstrated in this article, you will need two of these:

• dxc.exe - the HLSL shader compiler from Microsoft. If you have a development environment installed (like Microsoft Visual Studio and Windows SDK), you already have it in your system, located in a path like "c:\Program Files (x86)\Windows Kits\10\bin\10.0.20348.0\x64\dxc.exe" and added to the system PATH environmental variable, so you can open Command Prompt and just type "dxc" to use it.
• rga.exe - Radeon GPU Analyzer, which is part of Radeon Developer Tool Suite. You can find the download link on page Radeon™ GPU Analyzer - AMD GPUOpen. It is an offline shader compiler that can also compile HLSL code, but on top of that it can create the full Pipeline State Object (PSO) and output the AMD GPU ISA (assembly code), among many other features. Note that you don't need an AMD graphics card to use it. It comes with the shader compiler bundled for the "offline" mode, so it works regardless of what GPU you have.

You don't need to know the command-line syntax of these tools to understand the article. I will describe everything step-by-step.

Warning about DXC: If you also have Vulkan SDK installed, very likely your PATH environmental variable points to "dxc.exe" in that SDK instead of Windows SDK, which can cause problems. To check this, type command: where dxc. If you find Vulkan SDK listed first, make sure you call "dxc.exe" from Windows SDK, e.g. by explicitly specifying full path to the executable file.

Warning about RGA: If you want to repeat command-line experiments presented here, make sure to use Radeon GPU Analyzer in the latest version, at least 2.9.1. In older versions, the commands I present wouldn't work.

Shader compilation

A side note about shader compilation: Native CPU code, like the one we create when compiling our C++ programs, is saved in .exe files. I contains instructions in a common format called x86, which is sent directly to CPU for execution. It works regardless if you have an AMD or Intel processor in your computer, because they comply to the same standard. With programs written for the GPU (which we call shaders), things are different. Every GPU vendor (AMD, Nvidia, Intel) has its own instruction set, necessitating a two-step process for shader compilation:

1. As graphics programmers, we write shaders in high-level languages like HLSL or GLSL. We then compile them using a shader compiler like "dxc.exe" to a binary format. It is actually an intermediate format common to all GPU vendors, defined by Microsoft for Direct3D (called DXIL) or by Khronos for Vulkan (called SPIR-V). We are encouraged to compile our shaders offline and only ship these compiled binaries to end users.
2. When our application uses a graphics API (like Direct3D 12, Vulkan) and creates a pipeline state object (PSO), it specifies these shaders as inputs. This intermediate code then goes to the graphics driver, which performs second stage of the compilation - translates it to instructions valid for the specific GPU (also called Instruction Set Architecture - ISA). We typically don't see this assembly code and we never write it directly, although inspecting it can be useful for optimizations. Nvidia's ISA is secret, but AMD and Intel publish documents describing theirs. RGA tool mentioned below can show the AMD ISA.

What is a root signature?

In Direct3D 12, a root signature is a data structure that describes resource bindings used by a pipeline on all the shader stages. Let's see an example. Let's work with file "Shader1.hlsl": a very simple HLSL code that contains 2 entry points: function VsMain for vertex shader and function PsMain for pixel shader:

struct VsInput
{
    float3 pos : POSITION;
    float2 tex_coord : TEXCOORD;
};
struct VsOutput
{
    float4 pos : SV_Position;
    float2 tex_coord : TEXCOORD;
};

struct VsConstants
{
    float4x4 model_view_proj;
};
ConstantBuffer<VsConstants> vs_constant_buffer : register(b4);

VsOutput VsMain(VsInput i)
{
    VsOutput o;
    o.pos = mul(float4(i.pos, 1.0), vs_constant_buffer.model_view_proj);
    o.tex_coord = i.tex_coord;
    return o;
}

Texture2D<float4> color_texture : register(t0);
SamplerState color_sampler : register(s0);

float4 PsMain(VsOutput i) : SV_Target
{
    return color_texture.Sample(color_sampler, i.tex_coord);
}

I assume you already know that a shader is a program executed on a GPU that processes a single vertex or pixel with clearly defined inputs and outputs. To perform the work, it can also reach out to video memory to access additional resources, like buffers and textures. In the code shown above:

• Vertex shader declares and uses a constant buffer, bound to slot b4. It contains a model-view-projection 4x4 matrix. Vertex position, extended to 4D (known as homogeneous coordinates) is multiplied by this matrix. Texture coordinates are passed as-is from the input to the output.
• Pixel shader declares a texture bound to slot t0 and a sampler bound to slot s0. It uses them to sample a color from this texture at given texture coordinates and returns this color, to be written to a render target.

A root signature is a data structure that describes what I said above - what resources should be bound to the pipeline at individual shader stages. In this specific example, it will be a constant buffer at register b4, a texture at t0, and a sampler at s0. It can also be shown in form of a table:

Root param index	Register	Shader stage
0	b4	VS
1	t0	PS
2	s0	PS

I am simplifying things here, because this article is not about teaching you the basics of root signatures. For more information about them, you can check:

• Root Signatures in Microsoft documentation
• D3D12 Resource Binding Functional Spec
• My old article: Direct3D 12: Long Way to Access Data

To prepare for our experiments, let's compile the shaders shown above using commands:

dxc -T vs_6_0 -E VsMain -Fo Shader1.vs.bin Shader1.hlsl
dxc -T ps_6_0 -E PsMain -Fo Shader1.ps.bin Shader1.hlsl

Note that a single HLSL source file can contain multiple functions (VsMain, PsMain). When we compile it, we need to specify one function as an entry point. For example, the first command compiles "Shader1.hlsl" file using VsMain function as the entry point (-E parameter) treated as a vertex shader in Shader Model 6.0 (-T parameter). Similarly, the second command compiles PsMain function as a pixel shader. Compiled shaders are saved in two separate files: "Shader1.vs.bin" and "Shader1.ps.bin".

Comments | #directx #rendering Share