Skip to content

Commit 4da1556

Browse files
python3kgaepython3kgae
committed
[Doc][HLSL] Add documentation for root signature
This patch adds documentation for the root signature in HLSL. For issue #55116
1 parent b5e4d32 commit 4da1556

File tree

1 file changed

+291
-0
lines changed

1 file changed

+291
-0
lines changed

‎clang/docs/HLSL/RootSignature.rst

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
====================
2+
HLSL Root Signatures
3+
====================
4+
5+
.. contents::
6+
:local:
7+
8+
Usage
9+
=====
10+
11+
In HLSL, the `root signature
12+
<https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signatures>`_
13+
defines what types of resources are bound to the graphics pipeline.
14+
15+
A root signature can be specified in HLSL as a `string
16+
<https://learn.microsoft.com/en-us/windows/win32/direct3d12/specifying-root-signatures-in-hlsl#an-example-hlsl-root-signature>`_.
17+
The string contains a collection of comma-separated clauses that describe root
18+
signature constituent components.
19+
20+
There are two mechanisms to compile an HLSL root signature. First, it is
21+
possible to attach a root signature string to a particular shader via the
22+
RootSignature attribute (in the following example, using the main entry
23+
point):
24+
25+
.. code-block::
26+
27+
#define RS "RootFlags( ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT | " \
28+
"DENY_VERTEX_SHADER_ROOT_ACCESS), " \
29+
"CBV(b0, space = 1, flags = DATA_STATIC), " \
30+
"SRV(t0), " \
31+
"UAV(u0), " \
32+
"DescriptorTable( CBV(b1), " \
33+
" SRV(t1, numDescriptors = 8, " \
34+
" flags = DESCRIPTORS_VOLATILE), " \
35+
" UAV(u1, numDescriptors = unbounded, " \
36+
" flags = DESCRIPTORS_VOLATILE)), " \
37+
"DescriptorTable(Sampler(s0, space=1, numDescriptors = 4)), " \
38+
"RootConstants(num32BitConstants=3, b10), " \
39+
"StaticSampler(s1)," \
40+
"StaticSampler(s2, " \
41+
" addressU = TEXTURE_ADDRESS_CLAMP, " \
42+
" filter = FILTER_MIN_MAG_MIP_LINEAR )"
43+
44+
[RootSignature(MyRS)]
45+
float4 main(float4 coord : COORD) : SV_Target
46+
{
47+
…
48+
}
49+
50+
The compiler will create and verify the root signature blob for the shader and
51+
embed it alongside the shader byte code into the shader blob.
52+
53+
The other mechanism is to create a standalone root signature blob, perhaps to
54+
reuse it with a large set of shaders, saving space. The name of the define
55+
string is specified via the usual -E argument. For example:
56+
57+
.. code-block:: sh
58+
59+
dxc.exe -T rootsig_1_1 MyRS1.hlsl -E MyRS1 -Fo MyRS1.fxo
60+
61+
Note that the root signature string define can also be passed on the command
62+
line, e.g, -D MyRS1=”…”.
63+
64+
Root signature could also used in form of StateObject like this:
65+
66+
.. code-block::
67+
68+
GlobalRootSignature MyGlobalRootSignature =
69+
{
70+
"DescriptorTable(UAV(u0))," // Output texture
71+
"SRV(t0)," // Acceleration structure
72+
"CBV(b0)," // Scene constants
73+
"DescriptorTable(SRV(t1, numDescriptors = 2))" // Static index and vertex buffers.
74+
};
75+
76+
LocalRootSignature MyLocalRootSignature =
77+
{
78+
"RootConstants(num32BitConstants = 4, b1)" // Cube constants
79+
};
80+
81+
82+
Root Signature Grammar
83+
======================
84+
85+
.. code-block:: peg
86+
87+
RootSignature : (RootElement(,RootElement)?)?
88+
89+
RootElement : RootFlags | RootConstants | RootCBV | RootSRV | RootUAV |
90+
DescriptorTable | StaticSampler
91+
92+
RootFlags : 'RootFlags' '(' (RootFlag(|RootFlag)?)? ')'
93+
94+
RootFlag : 'ALLOW_INPUT_ASSEMBLER_INPUT_LAYOUT' |
95+
'DENY_VERTEX_SHADER_ROOT_ACCESS'
96+
97+
RootConstants : 'RootConstants' '(' 'num32BitConstants' '=' NUMBER ','
98+
bReg (',' 'space' '=' NUMBER)?
99+
(',' 'visibility' '=' SHADER_VISIBILITY)? ')'
100+
101+
RootCBV : 'CBV' '(' bReg (',' 'space' '=' NUMBER)?
102+
(',' 'visibility' '=' SHADER_VISIBILITY)?
103+
(',' 'flags' '=' DATA_FLAGS)? ')'
104+
105+
RootSRV : 'SRV' '(' tReg (',' 'space' '=' NUMBER)?
106+
(',' 'visibility' '=' SHADER_VISIBILITY)?
107+
(',' 'flags' '=' DATA_FLAGS)? ')'
108+
109+
RootUAV : 'UAV' '(' uReg (',' 'space' '=' NUMBER)?
110+
(',' 'visibility' '=' SHADER_VISIBILITY)?
111+
(',' 'flags' '=' DATA_FLAGS)? ')'
112+
113+
DescriptorTable : 'DescriptorTable' '(' (DTClause(|DTClause)?)?
114+
(',' 'visibility' '=' SHADER_VISIBILITY)? ')'
115+
116+
DTClause : CBV | SRV | UAV | Sampler
117+
118+
CBV : 'CBV' '(' bReg (',' 'numDescriptors' '=' NUMBER)?
119+
(',' 'space' '=' NUMBER)?
120+
(',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
121+
(',' 'flags' '=' DATA_FLAGS)? ')'
122+
123+
SRV : 'SRV' '(' tReg (',' 'numDescriptors' '=' NUMBER)?
124+
(',' 'space' '=' NUMBER)?
125+
(',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
126+
(',' 'flags' '=' DATA_FLAGS)? ')'
127+
128+
UAV : 'UAV' '(' uReg (',' 'numDescriptors' '=' NUMBER)?
129+
(',' 'space' '=' NUMBER)?
130+
(',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)?
131+
(',' 'flags' '=' DATA_FLAGS)? ')'
132+
133+
Sampler : 'Sampler' '(' sReg (',' 'numDescriptors' '=' NUMBER)?
134+
(',' 'space' '=' NUMBER)?
135+
(',' 'offset' '=' DESCRIPTOR_RANGE_OFFSET)? (',' 'flags' '=' NUMBER)? ')'
136+
137+
138+
SHADER_VISIBILITY : 'SHADER_VISIBILITY_ALL' | 'SHADER_VISIBILITY_VERTEX' |
139+
'SHADER_VISIBILITY_HULL' |
140+
'SHADER_VISIBILITY_DOMAIN' |
141+
'SHADER_VISIBILITY_GEOMETRY' |
142+
'SHADER_VISIBILITY_PIXEL' |
143+
'SHADER_VISIBILITY_AMPLIFICATION' |
144+
'SHADER_VISIBILITY_MESH'
145+
146+
DATA_FLAGS : 'DATA_STATIC_WHILE_SET_AT_EXECUTE' | 'DATA_VOLATILE'
147+
148+
DESCRIPTOR_RANGE_OFFSET : 'DESCRIPTOR_RANGE_OFFSET_APPEND' | NUMBER
149+
150+
StaticSampler : 'StaticSampler' '(' sReg (',' 'filter' '=' FILTER)?
151+
(',' 'addressU' '=' TEXTURE_ADDRESS)?
152+
(',' 'addressV' '=' TEXTURE_ADDRESS)?
153+
(',' 'addressW' '=' TEXTURE_ADDRESS)?
154+
(',' 'mipLODBias' '=' NUMBER)?
155+
(',' 'maxAnisotropy' '=' NUMBER)?
156+
(',' 'comparisonFunc' '=' COMPARISON_FUNC)?
157+
(',' 'borderColor' '=' STATIC_BORDER_COLOR)?
158+
(',' 'minLOD' '=' NUMBER)?
159+
(',' 'maxLOD' '=' NUMBER)? (',' 'space' '=' NUMBER)?
160+
(',' 'visibility' '=' SHADER_VISIBILITY)? ')'
161+
162+
bReg : 'b' NUMBER
163+
164+
tReg : 't' NUMBER
165+
166+
uReg : 'u' NUMBER
167+
168+
sReg : 's' NUMBER
169+
170+
FILTER : 'FILTER_MIN_MAG_MIP_POINT' |
171+
'FILTER_MIN_MAG_POINT_MIP_LINEAR' |
172+
'FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT' |
173+
'FILTER_MIN_POINT_MAG_MIP_LINEAR' |
174+
'FILTER_MIN_LINEAR_MAG_MIP_POINT' |
175+
'FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
176+
'FILTER_MIN_MAG_LINEAR_MIP_POINT' |
177+
'FILTER_MIN_MAG_MIP_LINEAR' |
178+
'FILTER_ANISOTROPIC' |
179+
'FILTER_COMPARISON_MIN_MAG_MIP_POINT' |
180+
'FILTER_COMPARISON_MIN_MAG_POINT_MIP_LINEAR' |
181+
'FILTER_COMPARISON_MIN_POINT_MAG_LINEAR_MIP_POINT' |
182+
'FILTER_COMPARISON_MIN_POINT_MAG_MIP_LINEAR' |
183+
'FILTER_COMPARISON_MIN_LINEAR_MAG_MIP_POINT' |
184+
'FILTER_COMPARISON_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
185+
'FILTER_COMPARISON_MIN_MAG_LINEAR_MIP_POINT' |
186+
'FILTER_COMPARISON_MIN_MAG_MIP_LINEAR' |
187+
'FILTER_COMPARISON_ANISOTROPIC' |
188+
'FILTER_MINIMUM_MIN_MAG_MIP_POINT' |
189+
'FILTER_MINIMUM_MIN_MAG_POINT_MIP_LINEAR' |
190+
'FILTER_MINIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' |
191+
'FILTER_MINIMUM_MIN_POINT_MAG_MIP_LINEAR' |
192+
'FILTER_MINIMUM_MIN_LINEAR_MAG_MIP_POINT' |
193+
'FILTER_MINIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
194+
'FILTER_MINIMUM_MIN_MAG_LINEAR_MIP_POINT' |
195+
'FILTER_MINIMUM_MIN_MAG_MIP_LINEAR' |
196+
'FILTER_MINIMUM_ANISOTROPIC' |
197+
'FILTER_MAXIMUM_MIN_MAG_MIP_POINT' |
198+
'FILTER_MAXIMUM_MIN_MAG_POINT_MIP_LINEAR' |
199+
'FILTER_MAXIMUM_MIN_POINT_MAG_LINEAR_MIP_POINT' |
200+
'FILTER_MAXIMUM_MIN_POINT_MAG_MIP_LINEAR' |
201+
'FILTER_MAXIMUM_MIN_LINEAR_MAG_MIP_POINT' |
202+
'FILTER_MAXIMUM_MIN_LINEAR_MAG_POINT_MIP_LINEAR' |
203+
'FILTER_MAXIMUM_MIN_MAG_LINEAR_MIP_POINT' |
204+
'FILTER_MAXIMUM_MIN_MAG_MIP_LINEAR' |
205+
'FILTER_MAXIMUM_ANISOTROPIC'
206+
207+
TEXTURE_ADDRESS : 'TEXTURE_ADDRESS_WRAP' |
208+
'TEXTURE_ADDRESS_MIRROR' | 'TEXTURE_ADDRESS_CLAMP' |
209+
'TEXTURE_ADDRESS_BORDER' | 'TEXTURE_ADDRESS_MIRROR_ONCE'
210+
211+
COMPARISON_FUNC : 'COMPARISON_NEVER' | 'COMPARISON_LESS' |
212+
'COMPARISON_EQUAL' | 'COMPARISON_LESS_EQUAL' |
213+
'COMPARISON_GREATER' | 'COMPARISON_NOT_EQUAL' |
214+
'COMPARISON_GREATER_EQUAL' | 'COMPARISON_ALWAYS'
215+
216+
STATIC_BORDER_COLOR : 'STATIC_BORDER_COLOR_TRANSPARENT_BLACK' |
217+
'STATIC_BORDER_COLOR_OPAQUE_BLACK' |
218+
'STATIC_BORDER_COLOR_OPAQUE_WHITE'
219+
220+
GlobalRootSignature
221+
===================
222+
223+
A GlobalRootSignature corresponds to a D3D12_GLOBAL_ROOT_SIGNATURE structure.
224+
225+
The fields consist of some number of strings describing the parts of the root signature.
226+
The string should follow Root Signature Grammar.
227+
228+
.. code-block::
229+
230+
GlobalRootSignature MyGlobalRootSignature =
231+
{
232+
"DescriptorTable(UAV(u0))," // Output texture
233+
"SRV(t0)," // Acceleration structure
234+
"CBV(b0)," // Scene constants
235+
"DescriptorTable(SRV(t1, numDescriptors = 2))" // Static index and vertex buffers
236+
};
237+
238+
239+
LocalRootSignature
240+
==================
241+
242+
A LocalRootSignature corresponds to a D3D12_LOCAL_ROOT_SIGNATURE structure.
243+
244+
Just like the global root signature subobject, the fields consist of some
245+
number of strings describing the parts of the root signature.
246+
The string should follow Root Signature Grammar.
247+
248+
.. code-block::
249+
250+
LocalRootSignature MyLocalRootSignature =
251+
{
252+
"RootConstants(num32BitConstants = 4, b1)" // Cube constants
253+
};
254+
255+
256+
SubobjectToExportsAssociation
257+
=============================
258+
259+
By default, a subobject merely declared in the same library as an export is
260+
able to apply to that export.
261+
However, applications have the ability to override that and get specific about
262+
what subobject goes with which export. In HLSL, this "explicit association" is
263+
done using SubobjectToExportsAssociation.
264+
265+
A SubobjectToExportsAssociation corresponds to a
266+
D3D12_DXIL_SUBOBJECT_TO_EXPORTS_ASSOCIATION structure.
267+
268+
This subobject is declared with the syntax
269+
.. code-block::
270+
271+
SubobjectToExportsAssociation Name =
272+
{
273+
SubobjectName,
274+
Exports
275+
};
276+
277+
The local/global root siganture in above example could be used like this:
278+
279+
.. code-block::
280+
281+
SubobjectToExportsAssociation MyLocalRootSignatureAssociation =
282+
{
283+
"MyLocalRootSignature", // Subobject name
284+
"MyHitGroup;MyMissShader" // Exports association
285+
};
286+
SubobjectToExportsAssociation MyGlobalRootSignatureAssociation =
287+
{
288+
"MyGlobalRootSignature", // Subobject name
289+
"MyHitGroup;MyMissShader" // Exports association
290+
};
291+

0 commit comments

Comments
 (0)