246 lines · plain
1===============2Root Signatures3===============4 5.. contents::6 :local:7 8.. toctree::9 :hidden:10 11Overview12========13 14A root signature is used to describe what resources a shader needs access to15and how they're organized and bound in the pipeline. The DirectX Container16(DXContainer) contains a root signature part (RTS0), which stores this17information in a binary format. To assist with the construction of, and18interaction with, a root signature is represented as metadata19(``dx.rootsignatures`` ) in the LLVM IR. The metadata can then be converted to20its binary form, as defined in21`llvm/include/llvm/llvm/Frontend/HLSL/RootSignatureMetadata.h22<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Frontend/HLSL/RootSignatureMetadata.h>`_.23This document serves as a reference for the metadata representation of a root24signature for users to interface with.25 26Metadata Representation27=======================28 29Consider the reference root signature, then the following sections describe the30metadata representation of this root signature and the corresponding operands.31 32.. code-block:: HLSL33 34 RootFlags(ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT),35 RootConstants(b0, space = 1, num32Constants = 3),36 CBV(b1, flags = 0),37 StaticSampler(38 filter = FILTER_MIN_MAG_POINT_MIP_LINEAR,39 addressU = TEXTURE_ADDRESS_BORDER,40 ),41 DescriptorTable(42 visibility = VISIBILITY_ALL,43 SRV(t0, flags = DATA_STATIC_WHILE_SET_AT_EXECUTE),44 UAV(45 numDescriptors = 5, u1, space = 10, offset = 5,46 flags = DATA_VOLATILE47 )48 )49 50.. note::51 52 A root signature does not necessarily have a unique metadata representation.53 Futher, a malformed root signature can be represented in the metadata format,54 (eg. mixing Sampler and non-Sampler descriptor ranges), and so it is the55 user's responsibility to verify that it is a well-formed root signature.56 57Named Root Signature Table58==========================59 60.. code-block:: LLVM61 62 !dx.rootsignatures = !{!0}63 64A named metadata node, ``dx.rootsignatures``` is used to identify the root65signature table. The table itself is a list of references to function/root66signature pairs.67 68Function/Root Signature Pair69============================70 71.. code-block:: LLVM72 73 !1 = !{ptr @main, !2, i32 2 }74 75The function/root signature associates a function (the first operand) with a76reference to a root signature (the second operand). The root signature version77(the third operand) used for validation logic and binary format follows.78 79Root Signature80==============81 82.. code-block:: LLVM83 84 !2 = !{ !3, !4, !5, !6, !7 }85 86The root signature itself simply consists of a list of references to its root87signature elements.88 89Root Signature Element90======================91 92A root signature element is identified by the first operand, which is a string.93The following root signature elements are defined:94 95================= ======================96Identifier String Root Signature Element97================= ======================98"RootFlags" Root Flags99"RootConstants" Root Constants100"RootCBV" Root Descriptor101"RootSRV" Root Descriptor102"RootUAV" Root Descriptor103"StaticSampler" Static Sampler104"DescriptorTable" Descriptor Table105================= ======================106 107Below is listed the representation for each type of root signature element.108 109Root Flags110==========111 112.. code-block:: LLVM113 114 !3 = { !"RootFlags", i32 1 }115 116======================= ====117Description Type118======================= ====119`Root Signature Flags`_ i32120======================= ====121 122.. _Root Signature Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_signature_flags123 124Root Constants125==============126 127.. code-block:: LLVM128 129 !4 = { !"RootConstants", i32 0, i32 1, i32 2, i32 3 }130 131==================== ====132Description Type133==================== ====134`Shader Visibility`_ i32135Shader Register i32136Register Space i32137Number 32-bit Values i32138==================== ====139 140.. _Shader Visibility: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility141 142Root Descriptor143===============144 145As noted in the table above, the first operand will denote the type of146root descriptor.147 148.. code-block:: LLVM149 150 !5 = { !"RootCBV", i32 0, i32 1, i32 0, i32 0 }151 152======================== ====153Description Type154======================== ====155`Shader Visibility`_ i32156Shader Register i32157Register Space i32158`Root Descriptor Flags`_ i32159======================== ====160 161.. _Root Descriptor Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_root_descriptor_flags162 163Static Sampler164==============165 166.. code-block:: LLVM167 168 !6 = !{ !"StaticSampler", i32 1, i32 4, ... }; remaining operands omitted for space169 170==================== =====171Description Type172==================== =====173`Filter`_ i32174`AddressU`_ i32175`AddressV`_ i32176`AddressW`_ i32177MipLODBias float178MaxAnisotropy i32179`ComparisonFunc`_ i32180`BorderColor`_ i32181MinLOD float182MaxLOD float183ShaderRegister i32184RegisterSpace i32185`Shader Visibility`_ i32186==================== =====187 188.. _Filter: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter189.. _AddressU: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode190.. _AddressV: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode191.. _AddressW: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode192.. _ComparisonFunc: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>193.. _BorderColor: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>194 195Descriptor Table196================197 198A descriptor table consists of a visibility and the remaining operands are a199list of references to its descriptor ranges.200 201.. note::202 203 The term Descriptor Table Clause is synonymous with Descriptor Range when204 referencing the implementation details.205 206.. code-block:: LLVM207 208 !7 = { !"DescriptorTable", i32 0, !8, !9 }209 210========================= ================211Description Type212========================= ================213`Shader Visibility`_ i32214Descriptor Range Elements Descriptor Range215========================= ================216 217 218Descriptor Range219================220 221Similar to a root descriptor, the first operand will denote the type of222descriptor range. It is one of the following types:223 224- "CBV"225- "SRV"226- "UAV"227- "Sampler"228 229.. code-block:: LLVM230 231 !8 = !{ !"SRV", i32 1, i32 0, i32 0, i32 -1, i32 4 }232 !9 = !{ !"UAV", i32 5, i32 1, i32 10, i32 5, i32 2 }233 234============================== ====235Description Type236============================== ====237Number of Descriptors in Range i32238Shader Register i32239Register Space i32240`Offset`_ i32241`Descriptor Range Flags`_ i32242============================== ====243 244.. _Offset: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ns-d3d12-d3d12_descriptor_range245.. _Descriptor Range Flags: https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_descriptor_range_flags246