Skip to content

Commit d0d33d2

Browse files
joaosaffranjoaosaffran
joaosaffran
and
joaosaffran
authored
[DirectX] Documenting Root Signature Binary representation (#131011)
Closes: #131009, #129796, #129749, #129561 --------- Co-authored-by: joaosaffran <[email protected]>
1 parent 9cab82f commit d0d33d2

File tree

1 file changed

+182
-1
lines changed

1 file changed

+182
-1
lines changed

‎llvm/docs/DirectX/DXContainer.rst

Lines changed: 182 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ FXC are marked with \*.
111111
#. `PSV0`_ - Stores Pipeline State Validation data.
112112
#. RDAT† - Stores Runtime Data.
113113
#. RDEF\* - Stores resource definitions.
114-
#. RTS0 - Stores compiled root signature.
114+
#. `RTS0`_ - Stores compiled root signature.
115115
#. `SFI0`_ - Stores shader feature flags.
116116
#. SHDR\* - Stores compiled DXBC bytecode.
117117
#. SHEX\* - Stores compiled DXBC bytecode.
@@ -393,6 +393,187 @@ bit in the mask vector identifies one column of a patch constant input and a
393393
column of an output. A value of 1 means the output is impacted by the primitive
394394
input.
395395

396+
Root Signature (RTS0) Part
397+
--------------------------
398+
.. _RTS0:
399+
400+
The Root Signature data defines the shader's resource interface with Direct3D
401+
12, specifying what resources the shader needs to access and how they're
402+
organized and bound to the pipeline.
403+
404+
The RTS0 part comprises three data structures: ``RootSignatureHeader``,
405+
``RootParameters`` and ``StaticSamplers``. The details of each will be described
406+
in the following sections. All ``RootParameters`` will be serialized following
407+
the order they were defined in the metadata representation.
408+
409+
The table below summarizes the data being serialized as well as it's size. The
410+
details of it part will be discussed in further details on the next sections
411+
of this document.
412+
413+
======================== =========================================== =============================
414+
Part Name Size In Bytes Maximum number of Instances
415+
======================== =========================================== =============================
416+
Root Signature Header 24 1
417+
Root Parameter Headers 12 Many
418+
Root Parameter ================================ === Many
419+
Root Constants 12
420+
Root Descriptor Version 1.0 8
421+
Root Descriptor Version 1.1 12
422+
Descriptors Tables Version 1.0 20
423+
Descriptors Tables Version 1.1 24
424+
================================ ===
425+
426+
Static Samplers 52 Many
427+
======================== =========================================== =============================
428+
429+
430+
Root Signature Header
431+
~~~~~~~~~~~~~~~~~~~~~
432+
433+
The root signature header is 24 bytes long, consisting of six 32 bit values
434+
representing the version, number and offset of parameters, number and offset
435+
of static samplers, and a flags field for global behaviours:
436+
437+
.. code-block:: c
438+
439+
struct RootSignatureHeader {
440+
uint32_t Version;
441+
uint32_t NumParameters;
442+
uint32_t ParametersOffset;
443+
uint32_t NumStaticSamplers;
444+
uint32_t StaticSamplerOffset;
445+
uint32_t Flags;
446+
}
447+
448+
449+
Root Parameters
450+
~~~~~~~~~~~~~~~
451+
452+
Root parameters define how resources are bound to the shader pipeline, each
453+
type having different size and fields.
454+
455+
The slot of root parameters is preceded by a variable size section containing
456+
the header information for such parameters. Such structure is 12 bytes long,
457+
composed of three 32 bit values, representing the parameter type, a flag
458+
encoding the pipeline stages where the data is visible, and an offset
459+
calculated from the start of RTS0 section.
460+
461+
.. code-block:: c
462+
463+
struct RootParameterHeader {
464+
uint32_t ParameterType;
465+
uint32_t ShaderVisibility;
466+
uint32_t ParameterOffset;
467+
};
468+
469+
After the header information has been serialized, the actual data for each of the
470+
root parameters is layout in a single continous blob. The parameters can be fetch
471+
from such using the offset information, present in the header.
472+
473+
The following sections will describe each of the root parameters types and their
474+
encodings.
475+
476+
Root Constants
477+
''''''''''''''
478+
479+
The root constants are inline 32-bit values that show up in the shader
480+
as a constant buffer. It is a 12 bytes long structure, two 32 bit values
481+
encoding the register and space the constant is assigned to, and
482+
the last 32 bits encode the number of constants being defined in the buffer.
483+
484+
.. code-block:: c
485+
486+
struct RootConstants {
487+
uint32_t Register;
488+
uint32_t Space;
489+
uint32_t NumOfConstants;
490+
};
491+
492+
Root Descriptor
493+
'''''''''''''''
494+
495+
Root descriptors provide direct GPU memory addresses to resources.
496+
497+
In version 1.0, the root descriptor is 8 bytes. It encodes the register and
498+
space as 2 32-bit values.
499+
500+
In version 1.1, the root descriptor is 12 bytes. It matches the 1.0 descriptor
501+
but adds a 32-bit access flag.
502+
503+
.. code-block:: c
504+
505+
struct RootDescriptor_V1_0 {
506+
uint32_t ShaderRegister;
507+
uint32_t RegisterSpace;
508+
};
509+
510+
struct RootDescriptor_V1_1 {
511+
uint32_t ShaderRegister;
512+
uint32_t RegisterSpace;
513+
uint32_t Flags;
514+
};
515+
516+
Root Descriptor Table
517+
'''''''''''''''''''''
518+
519+
Descriptor tables let shaders access multiple resources through a single pointer
520+
to a descriptor heap.
521+
522+
The tables are made of a collection of descriptor ranges. In Version 1.0, the
523+
descriptor range is 20 bytes, containing five 32 bit values. It encodes a range
524+
of registers, including the register type, range length, register numbers and
525+
space within range and the offset locating each range inside the table.
526+
527+
In version 1.1, the descriptor range is 24 bytes. It matches the 1.0 descriptor
528+
but adds a 32-bit access flag.
529+
530+
.. code-block:: c
531+
532+
struct DescriptorRange_V1_0 {
533+
uint32_t RangeType;
534+
uint32_t NumDescriptors;
535+
uint32_t BaseShaderRegister;
536+
uint32_t RegisterSpace;
537+
uint32_t OffsetInDescriptorsFromTableStart;
538+
};
539+
540+
struct DescriptorRange_V1_1 {
541+
dxbc::DescriptorRangeType RangeType;
542+
uint32_t NumDescriptors;
543+
uint32_t BaseShaderRegister;
544+
uint32_t RegisterSpace;
545+
uint32_t OffsetInDescriptorsFromTableStart;
546+
uint32_t Flags;
547+
};
548+
549+
Static Samplers
550+
~~~~~~~~~~~~~~~
551+
552+
Static samplers are predefined filtering settings built into the root signature,
553+
avoiding descriptor heap lookups.
554+
555+
This section also has a variable size, since it can contain multiple static
556+
samplers definitions. However, the definition is a fixed sized struct,
557+
containing 13 32-byte fields of various enum, float, and integer values.
558+
559+
.. code-block:: c
560+
561+
struct StaticSamplerDesc {
562+
FilterMode Filter;
563+
TextureAddressMode AddressU;
564+
TextureAddressMode AddressV;
565+
TextureAddressMode AddressW;
566+
float MipLODBias;
567+
uint32_t MaxAnisotropy;
568+
ComparisonFunc ComparisonFunc;
569+
StaticBorderColor BorderColor;
570+
float MinLOD;
571+
float MaxLOD;
572+
uint32_t ShaderRegister;
573+
uint32_t RegisterSpace;
574+
ShaderVisibility ShaderVisibility;
575+
};
576+
396577
SFI0 Part
397578
---------
398579
.. _SFI0:

0 commit comments

Comments
 (0)