[llvm] [DirectX] Documenting Root Signature Binary representation (PR #131011)
via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 19 11:29:41 PDT 2025
https://github.com/joaosaffran updated https://github.com/llvm/llvm-project/pull/131011
>From e26ef1838d0e3349abe1f4d14fbe62da49c0e38d Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 10:21:31 -0800
Subject: [PATCH 01/22] Adding root constant documentation
---
llvm/docs/DirectX/DXContainer.rst | 72 +++++++++++++++++++++++++++++++
1 file changed, 72 insertions(+)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 36e670a1c164d..601982d60cd8f 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -400,3 +400,75 @@ SFI0 Part
The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
This denotes which optional features the shader requires. The flag values are
defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
+
+
+Root Signature (RST0) Part
+---------
+.. _RST0:
+
+The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand.
+
+The Root Signature consists of a header followed by a collection of root parameters and static samplers. The structure uses a versioned design with offset-based references to allow for flexible serialization and deserialization.
+
+Root Signature Header
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ struct RootSignatureHeader {
+ uint32_t Version;
+ uint32_t NumParameters;
+ uint32_t ParametersOffset;
+ uint32_t NumStaticSamplers;
+ uint32_t StaticSamplerOffset;
+ uint32_t Flags;
+ }
+
+
+The `RootSignatureHeader` structure contains the top-level information about a root signature:
+
+- **Version**: Specifies the version of the root signature format. This allows for backward compatibility as the format evolves.
+- **NumParameters**: The number of root parameters contained in this root signature.
+- **ParametersOffset**: Byte offset from the beginning to the array of root parameters header.
+- **NumStaticSamplers**: The number of static samplers defined in the root signature.
+- **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers.
+- **Flags**: Bit flags that define global behaviors for the root signature, such as whether to deny vertex shader access to certain resources.
+
+This header allows readers to navigate the binary representation of the root signature by providing counts and offsets to locate each component within the serialized data.
+
+Root Parameter Header
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ struct RootParameterHeader {
+ dxbc::RootParameterType ParameterType;
+ dxbc::ShaderVisibility ShaderVisibility;
+ uint32_t ParameterOffset;
+ };
+
+
+Each root parameter in the signature is preceded by a `RootParameterHeader` that describes the parameter's basic attributes:
+
+- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor table, constants, CBV, SRV, UAV).
+- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, vertex shader only, pixel shader only).
+- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure for this entry.
+
+The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature.
+
+Root Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+ union RootParameter {
+ RootConstants Constants;
+ };
+
+The `RootParameter` union represents the various types of parameters that can be specified in a root signature. Such includes:
+
+- **Constants**: Represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource.
+
+Each specific parameter type will have its own structure with fields relevant to that parameter type. For example, `RootConstants` would include information about the register binding, count of 32-bit values, and other properties specific to constant parameters.
+
+When processing root parameters, readers should first check the `ParameterType` field in the corresponding header to determine which member of the union to access.
>From 4f3930a56d0355813a264156010aa6e6129fb3e0 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:01:27 -0800
Subject: [PATCH 02/22] Removing union, fix typos
---
llvm/docs/DirectX/DXContainer.rst | 33 +++++++++++++++++++------------
1 file changed, 20 insertions(+), 13 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 601982d60cd8f..1f46b6ccb9599 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -111,7 +111,7 @@ FXC are marked with \*.
#. `PSV0`_ - Stores Pipeline State Validation data.
#. RDAT†- Stores Runtime Data.
#. RDEF\* - Stores resource definitions.
-#. RTS0 - Stores compiled root signature.
+#. `RTS0`_ - Stores compiled root signature.
#. `SFI0`_ - Stores shader feature flags.
#. SHDR\* - Stores compiled DXBC bytecode.
#. SHEX\* - Stores compiled DXBC bytecode.
@@ -402,9 +402,9 @@ This denotes which optional features the shader requires. The flag values are
defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
-Root Signature (RST0) Part
----------
-.. _RST0:
+Root Signature (RTS0) Part
+--------------------------
+.. _RTS0:
The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand.
@@ -457,18 +457,25 @@ Each root parameter in the signature is preceded by a `RootParameterHeader` that
The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature.
Root Parameters
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
-.. code-block:: c
+The Root Parameters section contains structured definitions for each type of root parameter that can be included in a root signature. Each structure corresponds to a specific parameter type as identified by the ``ParameterType`` field in the ``RootParameterHeader``.
- union RootParameter {
- RootConstants Constants;
- };
+Root Constants
+~~~~~~~~~~~~~~
+
+.. code-block:: cpp
-The `RootParameter` union represents the various types of parameters that can be specified in a root signature. Such includes:
+ struct RootConstants {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t Num32BitValues;
+ };
-- **Constants**: Represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource.
+The ``RootConstants`` structure represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource:
-Each specific parameter type will have its own structure with fields relevant to that parameter type. For example, `RootConstants` would include information about the register binding, count of 32-bit values, and other properties specific to constant parameters.
+- **ShaderRegister**: The shader register (b#) where these constants are bound.
+- **RegisterSpace**: The register space used for the binding.
+- **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-When processing root parameters, readers should first check the `ParameterType` field in the corresponding header to determine which member of the union to access.
+Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
>From 8fae269b1543ff49ff4960cd205661ed73388653 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:06:02 -0800
Subject: [PATCH 03/22] Wrapping text
---
llvm/docs/DirectX/DXContainer.rst | 44 ++++++++++++++++++++++---------
1 file changed, 31 insertions(+), 13 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 1f46b6ccb9599..4aea201b02eb3 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -399,16 +399,23 @@ SFI0 Part
The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
This denotes which optional features the shader requires. The flag values are
-defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
+defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def
+<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
Root Signature (RTS0) Part
--------------------------
.. _RTS0:
-The Root Signature defines the interface between the shader and the pipeline, specifying which resources are bound to the shader and how they are accessed. This structure serves as a contract between the application and the GPU, establishing a layout for resource binding that both the shader compiler and the runtime can understand.
+The Root Signature defines the interface between the shader and the pipeline,
+specifying which resources are bound to the shader and how they are accessed.
+This structure serves as a contract between the application and the GPU,
+establishing a layout for resource binding that both the shader compiler and
+the runtime can understand.
-The Root Signature consists of a header followed by a collection of root parameters and static samplers. The structure uses a versioned design with offset-based references to allow for flexible serialization and deserialization.
+The Root Signature consists of a header followed by a collection of root parameters
+and static samplers. The structure uses a versioned design with offset-based references
+to allow for flexible serialization and deserialization.
Root Signature Header
~~~~~~~~~~~~~~~~~~~~~~~
@@ -427,14 +434,17 @@ Root Signature Header
The `RootSignatureHeader` structure contains the top-level information about a root signature:
-- **Version**: Specifies the version of the root signature format. This allows for backward compatibility as the format evolves.
+- **Version**: Specifies the version of the root signature format. This allows for
+backward compatibility as the format evolves.
- **NumParameters**: The number of root parameters contained in this root signature.
- **ParametersOffset**: Byte offset from the beginning to the array of root parameters header.
- **NumStaticSamplers**: The number of static samplers defined in the root signature.
- **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers.
-- **Flags**: Bit flags that define global behaviors for the root signature, such as whether to deny vertex shader access to certain resources.
+- **Flags**: Bit flags that define global behaviors for the root signature, such as whether
+to deny vertex shader access to certain resources.
-This header allows readers to navigate the binary representation of the root signature by providing counts and offsets to locate each component within the serialized data.
+This header allows readers to navigate the binary representation of the root signature by
+providing counts and offsets to locate each component within the serialized data.
Root Parameter Header
~~~~~~~~~~~~~~~~~~~~~~~
@@ -448,18 +458,25 @@ Root Parameter Header
};
-Each root parameter in the signature is preceded by a `RootParameterHeader` that describes the parameter's basic attributes:
+Each root parameter in the signature is preceded by a `RootParameterHeader` that describes
+the parameter's basic attributes:
-- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor table, constants, CBV, SRV, UAV).
-- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages, vertex shader only, pixel shader only).
-- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure for this entry.
+- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor
+table, constants, CBV, SRV, UAV).
+- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages,
+vertex shader only, pixel shader only).
+- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure
+for this entry.
-The header uses a parameter type field rather than encoding the version of the parameter through size, allowing for a more explicit representation of the parameter's nature.
+The header uses a parameter type field rather than encoding the version of the parameter through
+size, allowing for a more explicit representation of the parameter's nature.
Root Parameters
~~~~~~~~~~~~~~~
-The Root Parameters section contains structured definitions for each type of root parameter that can be included in a root signature. Each structure corresponds to a specific parameter type as identified by the ``ParameterType`` field in the ``RootParameterHeader``.
+The Root Parameters section contains structured definitions for each type of root parameter that can
+be included in a root signature. Each structure corresponds to a specific parameter type as identified
+by the ``ParameterType`` field in the ``RootParameterHeader``.
Root Constants
~~~~~~~~~~~~~~
@@ -472,7 +489,8 @@ Root Constants
uint32_t Num32BitValues;
};
-The ``RootConstants`` structure represents inline root constants that are directly embedded in the root signature and passed to the shader without requiring a constant buffer resource:
+The ``RootConstants`` structure represents inline root constants that are directly embedded in the root
+signature and passed to the shader without requiring a constant buffer resource:
- **ShaderRegister**: The shader register (b#) where these constants are bound.
- **RegisterSpace**: The register space used for the binding.
>From 7ad5d2b42cf61cc38f278630f4f9d51a9ebf9265 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:08:34 -0800
Subject: [PATCH 04/22] Removing redundant byte offset reference
---
llvm/docs/DirectX/DXContainer.rst | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 4aea201b02eb3..509d273e2c38f 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -437,9 +437,10 @@ The `RootSignatureHeader` structure contains the top-level information about a r
- **Version**: Specifies the version of the root signature format. This allows for
backward compatibility as the format evolves.
- **NumParameters**: The number of root parameters contained in this root signature.
-- **ParametersOffset**: Byte offset from the beginning to the array of root parameters header.
+- **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root
+parameters header.
- **NumStaticSamplers**: The number of static samplers defined in the root signature.
-- **StaticSamplerOffset**: Byte offset from the beginning to the array of static samplers.
+- **StaticSamplerOffset**: Byte offset to the array of static samplers.
- **Flags**: Bit flags that define global behaviors for the root signature, such as whether
to deny vertex shader access to certain resources.
@@ -465,7 +466,7 @@ the parameter's basic attributes:
table, constants, CBV, SRV, UAV).
- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages,
vertex shader only, pixel shader only).
-- **ParameterOffset**: Byte offset from the beginning to the specific parameter data structure
+- **ParameterOffset**: Byte offset to the specific parameter data structure
for this entry.
The header uses a parameter type field rather than encoding the version of the parameter through
>From 93116c0070e23ccae03d490a598621ccc54fffc4 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:22:42 -0800
Subject: [PATCH 05/22] Try fix test
---
llvm/docs/DirectX/DXContainer.rst | 36 +++++++++++++++----------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 509d273e2c38f..ffef94c1e1edd 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -434,15 +434,15 @@ Root Signature Header
The `RootSignatureHeader` structure contains the top-level information about a root signature:
-- **Version**: Specifies the version of the root signature format. This allows for
-backward compatibility as the format evolves.
-- **NumParameters**: The number of root parameters contained in this root signature.
-- **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root
-parameters header.
-- **NumStaticSamplers**: The number of static samplers defined in the root signature.
-- **StaticSamplerOffset**: Byte offset to the array of static samplers.
-- **Flags**: Bit flags that define global behaviors for the root signature, such as whether
-to deny vertex shader access to certain resources.
+#. **Version**: Specifies the version of the root signature format. This allows for backward
+ compatibility as the format evolves.
+#. **NumParameters**: The number of root parameters contained in this root signature.
+#. **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root
+ parameters header.
+#. **NumStaticSamplers**: The number of static samplers defined in the root signature.
+#. **StaticSamplerOffset**: Byte offset to the array of static samplers.
+#. **Flags**: Bit flags that define global behaviors for the root signature, such as whether
+ to deny vertex shader access to certain resources.
This header allows readers to navigate the binary representation of the root signature by
providing counts and offsets to locate each component within the serialized data.
@@ -462,12 +462,12 @@ Root Parameter Header
Each root parameter in the signature is preceded by a `RootParameterHeader` that describes
the parameter's basic attributes:
-- **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor
-table, constants, CBV, SRV, UAV).
-- **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages,
-vertex shader only, pixel shader only).
-- **ParameterOffset**: Byte offset to the specific parameter data structure
-for this entry.
+#. **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor
+ table, constants, CBV, SRV, UAV).
+#. **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages,
+ vertex shader only, pixel shader only).
+#. **ParameterOffset**: Byte offset to the specific parameter data structure
+ for this entry.
The header uses a parameter type field rather than encoding the version of the parameter through
size, allowing for a more explicit representation of the parameter's nature.
@@ -493,8 +493,8 @@ Root Constants
The ``RootConstants`` structure represents inline root constants that are directly embedded in the root
signature and passed to the shader without requiring a constant buffer resource:
-- **ShaderRegister**: The shader register (b#) where these constants are bound.
-- **RegisterSpace**: The register space used for the binding.
-- **Num32BitValues**: The number of 32-bit values included in this constant buffer.
+#. **ShaderRegister**: The shader register (b#) where these constants are bound.
+#. **RegisterSpace**: The register space used for the binding.
+#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
>From e1d385a599450e50e2af203073c88555aa6ea2a6 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:38:56 -0800
Subject: [PATCH 06/22] Fix git error
---
llvm/docs/DirectX/DXContainer.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index ffef94c1e1edd..0e7026b03a606 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -399,8 +399,7 @@ SFI0 Part
The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
This denotes which optional features the shader requires. The flag values are
-defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def
-<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
+defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
Root Signature (RTS0) Part
>From b390cd27d2b32f0e3b3d13c8ef3020cbd6af1fa9 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 4 Mar 2025 10:30:07 -0800
Subject: [PATCH 07/22] Adding root descriptor subsection
---
llvm/docs/DirectX/DXContainer.rst | 50 ++++++++++++++++++++++++++++++-
1 file changed, 49 insertions(+), 1 deletion(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 0e7026b03a606..14bc802ff6b97 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -496,4 +496,52 @@ signature and passed to the shader without requiring a constant buffer resource:
#. **RegisterSpace**: The register space used for the binding.
#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
+Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead
+of creating and binding a constant buffer resource.
+
+Root Descriptor
+~~~~~~~~~~~~~~
+
+Root descriptors provide a direct mechanism for binding individual resources to shader stages in the Direct3D 12
+rendering pipeline. They represent a critical interface for efficient resource management, allowing applications
+to specify how shader stages access specific GPU resources.
+
+.. code-block:: cpp
+
+ // Version 1.0 Root Descriptor
+ struct RootDescriptor_V1_0 {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ };
+
+ // Version 1.1 Root Descriptor
+ struct RootDescriptor_V1_1 {
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ // New flags for Version 1.1
+ enum Flags {
+ None = 0x0,
+ DATA_STATIC = 0x1,
+ DATA_STATIC_WHILE_SET_AT_EXECUTE = 0x2,
+ DATA_VOLATILE = 0x4
+ };
+
+ // Bitfield of flags from the Flags enum
+ uint32_t Flags;
+ };
+
+The Root Descriptor structure has evolved to support two versions, providing enhanced flexibility and
+performance optimization capabilities.
+
+Version 1.0 Root Descriptor
+'''''''''''''''''''''''''''
+The Version 1.0 RootDescriptor_V1_0 provides basic resource binding:
+
+#. **ShaderRegister**: The shader register where the descriptor is bound.
+#. **RegisterSpace**: The register space used for the binding.
+
+Version 1.1 Root Descriptor
+'''''''''''''''''''''''''''
+The Version 1.1 RootDescriptor_V1_1 extends the base structure with the following additional fields:
+
+#. **Flags**: Provides additional metadata about the descriptor's usage pattern.
>From 46face18e140b1313dfdc437e6f4ee03904d245a Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 4 Mar 2025 10:32:54 -0800
Subject: [PATCH 08/22] Fix git error
---
llvm/docs/DirectX/DXContainer.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 14bc802ff6b97..93ed9afe42b50 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -496,8 +496,7 @@ signature and passed to the shader without requiring a constant buffer resource:
#. **RegisterSpace**: The register space used for the binding.
#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead
-of creating and binding a constant buffer resource.
+Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
Root Descriptor
~~~~~~~~~~~~~~
>From 6a260b3fe40c05b4f159a5d26345229ae221f593 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 4 Mar 2025 10:53:11 -0800
Subject: [PATCH 09/22] Try fix test
---
llvm/docs/DirectX/DXContainer.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 93ed9afe42b50..b9a2067368e0f 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -499,7 +499,7 @@ signature and passed to the shader without requiring a constant buffer resource:
Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
Root Descriptor
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
Root descriptors provide a direct mechanism for binding individual resources to shader stages in the Direct3D 12
rendering pipeline. They represent a critical interface for efficient resource management, allowing applications
>From 82a7de3b1a22eb7f7630d5b2d6998916ede45a8c Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:32:03 -0800
Subject: [PATCH 10/22] Updating Root Descriptor documentation
---
llvm/docs/DirectX/DXContainer.rst | 70 +++++++++++++++++++++++++++++++
1 file changed, 70 insertions(+)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index b9a2067368e0f..fd1ff3f04a008 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -544,3 +544,73 @@ Version 1.1 Root Descriptor
The Version 1.1 RootDescriptor_V1_1 extends the base structure with the following additional fields:
#. **Flags**: Provides additional metadata about the descriptor's usage pattern.
+
+Root Descriptor Table
+~~~~~~~~~~~~~~~~~~~~~
+
+Descriptor tables provide a flexible mechanism for grouping and managing multiple resource descriptors within
+a single root signature parameter. They enable efficient binding of complex shader resource sets while minimizing
+root signature space consumption.
+
+.. code-block:: cpp
+
+ struct DescriptorRange_V1_0 {
+ dxbc::DescriptorRangeType RangeType;
+ uint32_t NumDescriptors;
+ uint32_t BaseShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t OffsetInDescriptorsFromTableStart;
+ };
+
+ struct DescriptorRange_V1_1 {
+ dxbc::DescriptorRangeType RangeType;
+ uint32_t NumDescriptors;
+ uint32_t BaseShaderRegister;
+ uint32_t RegisterSpace;
+ uint32_t OffsetInDescriptorsFromTableStart;
+ Copy// New flags for Version 1.1
+ enum Flags {
+ None = 0x0,
+ // Descriptors are static and known at root signature creation
+ DESCRIPTORS_STATIC = 0x1,
+ // Descriptors remain constant during command list execution
+ DESCRIPTORS_STATIC_KEEPING_BUFFER_BOUNDS_CHECKS = 0x2,
+ // Descriptors may change frequently
+ DESCRIPTORS_VOLATILE = 0x4
+ };
+
+ // Bitfield of flags from the Flags enum
+ uint32_t Flags;
+ };
+
+ struct RootDescriptorTable {
+ uint32_t NumDescriptorRanges;
+ uint32_t DescriptorRangesOffset;
+ };
+
+
+Descriptor Range Version 1.0
+''''''''''''''''''''''''''''
+
+The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
+
+#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
+#. **NumDescriptors**: Number of descriptors in the range
+#. **BaseShaderRegister**: First shader register in the range
+#. **RegisterSpace**: Register space for the range
+#. **OffsetInDescriptorsFromTableStart**: Offset from the descriptor heap start
+
+Descriptor Range Version 1.1
+''''''''''''''''''''''''''''
+The Version 1.1 DescriptorRange_V1_1 extends the base structure with performance optimization flags.
+
+#. **Flags**: Provide additional information about the descriptors and enable further driver optimizations.
+
+Root Descriptor Table
+'''''''''''''''''''''
+
+RootDescriptorTable provides basic table structure:
+
+#. **NumDescriptorRanges**: Number of descriptor ranges
+#. **DescriptorRangesOffset**: Offset to descriptor range array
+
>From b591fd86524243db44b27008a20bb02f9499303a Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 4 Mar 2025 14:50:29 -0800
Subject: [PATCH 11/22] Linking Direct X docs to details flags
---
llvm/docs/DirectX/DXContainer.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index b9a2067368e0f..4131f126b7c00 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -529,8 +529,8 @@ to specify how shader stages access specific GPU resources.
uint32_t Flags;
};
-The Root Descriptor structure has evolved to support two versions, providing enhanced flexibility and
-performance optimization capabilities.
+Version 1.1 of Root Descriptors has introduced some flags that can hint the drivers into
+performing further code optimizations. For details about it, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
Version 1.0 Root Descriptor
'''''''''''''''''''''''''''
>From 583e29c08573d3621fb13ea5279c04a02c840002 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Wed, 5 Mar 2025 12:55:27 -0800
Subject: [PATCH 12/22] Detail RootDescriptorFlags enum
---
llvm/docs/DirectX/DXContainer.rst | 17 ++++++++---------
1 file changed, 8 insertions(+), 9 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 4131f126b7c00..f469f9a64f674 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -507,6 +507,13 @@ to specify how shader stages access specific GPU resources.
.. code-block:: cpp
+ enum RootDescriptorFlags {
+ None = 0,
+ DataVolatile = 0x2,
+ DataStaticWhileSetAtExecute = 0x4,
+ DataStatic = 0x8,
+ }
+
// Version 1.0 Root Descriptor
struct RootDescriptor_V1_0 {
uint32_t ShaderRegister;
@@ -516,15 +523,7 @@ to specify how shader stages access specific GPU resources.
// Version 1.1 Root Descriptor
struct RootDescriptor_V1_1 {
uint32_t ShaderRegister;
- uint32_t RegisterSpace;
- // New flags for Version 1.1
- enum Flags {
- None = 0x0,
- DATA_STATIC = 0x1,
- DATA_STATIC_WHILE_SET_AT_EXECUTE = 0x2,
- DATA_VOLATILE = 0x4
- };
-
+ uint32_t RegisterSpace;
// Bitfield of flags from the Flags enum
uint32_t Flags;
};
>From 16e3642a23540edb2e306899999655ef0e9722f2 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Thu, 6 Mar 2025 11:10:41 -0800
Subject: [PATCH 13/22] Update DXContainer.rst
---
llvm/docs/DirectX/DXContainer.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index fd1ff3f04a008..0c652ed65c528 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -568,7 +568,7 @@ root signature space consumption.
uint32_t BaseShaderRegister;
uint32_t RegisterSpace;
uint32_t OffsetInDescriptorsFromTableStart;
- Copy// New flags for Version 1.1
+ // New flags for Version 1.1
enum Flags {
None = 0x0,
// Descriptors are static and known at root signature creation
>From 3da10bdd38df23cd582cf796f975621355f39b3a Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 11 Mar 2025 14:19:10 -0700
Subject: [PATCH 14/22] Addressing comments
---
llvm/docs/DirectX/DXContainer.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 0e7026b03a606..c4f976f5920ee 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -401,7 +401,6 @@ The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
This denotes which optional features the shader requires. The flag values are
defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
-
Root Signature (RTS0) Part
--------------------------
.. _RTS0:
@@ -417,7 +416,7 @@ and static samplers. The structure uses a versioned design with offset-based ref
to allow for flexible serialization and deserialization.
Root Signature Header
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
.. code-block:: c
@@ -447,7 +446,7 @@ This header allows readers to navigate the binary representation of the root sig
providing counts and offsets to locate each component within the serialized data.
Root Parameter Header
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
.. code-block:: c
@@ -496,4 +495,5 @@ signature and passed to the shader without requiring a constant buffer resource:
#. **RegisterSpace**: The register space used for the binding.
#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
+Root constants provide a fast way to pass small amounts of data directly to the shader without the
+overhead of creating and binding a constant buffer resource.
>From 73c645d5205b7717ccf4e99f6709318d287105b1 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 11 Mar 2025 14:23:24 -0700
Subject: [PATCH 15/22] Addressing comments
---
llvm/docs/DirectX/DXContainer.rst | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index f469f9a64f674..64c1310707db4 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -496,14 +496,14 @@ signature and passed to the shader without requiring a constant buffer resource:
#. **RegisterSpace**: The register space used for the binding.
#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-Root constants provide a fast way to pass small amounts of data directly to the shader without the overhead of creating and binding a constant buffer resource.
+Root constants provide a fast way to pass small amounts of data directly to the shader without the
+overhead of creating and binding a constant buffer resource.
Root Descriptor
~~~~~~~~~~~~~~~
-Root descriptors provide a direct mechanism for binding individual resources to shader stages in the Direct3D 12
-rendering pipeline. They represent a critical interface for efficient resource management, allowing applications
-to specify how shader stages access specific GPU resources.
+Root descriptors provide a mechanism for binding individual resources to shader stages in the Direct3D 12
+rendering pipeline. They allow applications to specify how shader stages access specific GPU resources.
.. code-block:: cpp
@@ -529,7 +529,8 @@ to specify how shader stages access specific GPU resources.
};
Version 1.1 of Root Descriptors has introduced some flags that can hint the drivers into
-performing further code optimizations. For details about it, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
+performing further code optimizations. For details, check
+`Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
Version 1.0 Root Descriptor
'''''''''''''''''''''''''''
>From fcabc0ec08da3e28d7e65bd578c7ca0fdeae7a9d Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Tue, 11 Mar 2025 14:31:23 -0700
Subject: [PATCH 16/22] Address PR Comments
---
llvm/docs/DirectX/DXContainer.rst | 8 +++-----
1 file changed, 3 insertions(+), 5 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 0c652ed65c528..40c088462a452 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -548,9 +548,8 @@ The Version 1.1 RootDescriptor_V1_1 extends the base structure with the followin
Root Descriptor Table
~~~~~~~~~~~~~~~~~~~~~
-Descriptor tables provide a flexible mechanism for grouping and managing multiple resource descriptors within
-a single root signature parameter. They enable efficient binding of complex shader resource sets while minimizing
-root signature space consumption.
+Descriptor tables function as containers that hold references to descriptors in descriptor heaps.
+They allow multiple descriptors to be bound to the pipeline through a single root signature parameter.
.. code-block:: cpp
@@ -591,7 +590,6 @@ root signature space consumption.
Descriptor Range Version 1.0
''''''''''''''''''''''''''''
-
The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
@@ -605,10 +603,10 @@ Descriptor Range Version 1.1
The Version 1.1 DescriptorRange_V1_1 extends the base structure with performance optimization flags.
#. **Flags**: Provide additional information about the descriptors and enable further driver optimizations.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
Root Descriptor Table
'''''''''''''''''''''
-
RootDescriptorTable provides basic table structure:
#. **NumDescriptorRanges**: Number of descriptor ranges
>From b13609de4e66c1b4574264b553594fab47a1b08f Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Wed, 12 Mar 2025 11:36:06 -0700
Subject: [PATCH 17/22] Adding Static Sampler Documentation
---
llvm/docs/DirectX/DXContainer.rst | 45 +++++++++++++++++++++++++++++++
1 file changed, 45 insertions(+)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 40c088462a452..8d32ad02d5e6a 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -612,3 +612,48 @@ RootDescriptorTable provides basic table structure:
#. **NumDescriptorRanges**: Number of descriptor ranges
#. **DescriptorRangesOffset**: Offset to descriptor range array
+Static Samplers
+~~~~~~~~~~~~~~~
+
+Static samplers provide a way to define fixed sampler states within the root signature itself.
+
+.. code-block:: cpp
+
+ struct StaticSamplerDesc {
+ FilterMode Filter;
+ TextureAddressMode AddressU;
+ TextureAddressMode AddressV;
+ TextureAddressMode AddressW;
+ float MipLODBias;
+ uint32_t MaxAnisotropy;
+ ComparisonFunc ComparisonFunc;
+ StaticBorderColor BorderColor;
+ float MinLOD;
+ float MaxLOD;
+ uint32_t ShaderRegister;
+ uint32_t RegisterSpace;
+ ShaderVisibility ShaderVisibility;
+ };
+
+
+The StaticSamplerDesc structure defines all properties of a static sampler:
+
+#. Filter: The filtering mode (e.g., point, linear, anisotropic) used for texture sampling.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter#syntax>`_.
+#. AddressU: The addressing mode for the U texture coordinate.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_.
+#. AddressV: The addressing mode for the V texture coordinate.
+#. AddressW: The addressing mode for the W texture coordinate.
+#. MipLODBias: Bias value applied to mipmap level of detail calculations.
+#. MaxAnisotropy: Maximum anisotropy level when using anisotropic filtering.
+#. ComparisonFunc: Comparison function used for comparison samplers.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_.
+#. BorderColor: Predefined border color used when address mode is set to border.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_.
+#. MinLOD: Minimum level of detail to use for sampling.
+#. MaxLOD: Maximum level of detail to use for sampling.
+#. ShaderRegister: The shader sampler register (s#) where this sampler is bound.
+#. RegisterSpace: The register space used for the binding.
+#. ShaderVisibility: Specifies which shader stages can access this sampler.
+ For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
+
>From 4525033d87b787d1530be8522f6bf2b5ab8aa5d4 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Wed, 12 Mar 2025 11:56:22 -0700
Subject: [PATCH 18/22] Update DXContainer.rst
---
llvm/docs/DirectX/DXContainer.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 8d32ad02d5e6a..dadb91f225bb5 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -639,21 +639,21 @@ Static samplers provide a way to define fixed sampler states within the root sig
The StaticSamplerDesc structure defines all properties of a static sampler:
#. Filter: The filtering mode (e.g., point, linear, anisotropic) used for texture sampling.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter#syntax>`_.
+ For details, check `Static Sampler Fileters definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter#syntax>`_.
#. AddressU: The addressing mode for the U texture coordinate.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_.
+ For details, check `Texture address mode definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_.
#. AddressV: The addressing mode for the V texture coordinate.
#. AddressW: The addressing mode for the W texture coordinate.
#. MipLODBias: Bias value applied to mipmap level of detail calculations.
#. MaxAnisotropy: Maximum anisotropy level when using anisotropic filtering.
#. ComparisonFunc: Comparison function used for comparison samplers.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_.
+ For details, check `Comparison Function definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_.
#. BorderColor: Predefined border color used when address mode is set to border.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_.
+ For details, check `Static border color <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_.
#. MinLOD: Minimum level of detail to use for sampling.
#. MaxLOD: Maximum level of detail to use for sampling.
#. ShaderRegister: The shader sampler register (s#) where this sampler is bound.
#. RegisterSpace: The register space used for the binding.
#. ShaderVisibility: Specifies which shader stages can access this sampler.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
+ For details, check `Sahder Visibility definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
>From 8dc983ab18f5fb6270c5f89750734c8f39cc759f Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Thu, 13 Mar 2025 14:05:10 -0700
Subject: [PATCH 19/22] Update DXContainer.rst
---
llvm/docs/DirectX/DXContainer.rst | 83 +++++++++++++++++--------------
1 file changed, 45 insertions(+), 38 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 609ab764af625..f35d60e0a97b0 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -411,9 +411,11 @@ This structure serves as a contract between the application and the GPU,
establishing a layout for resource binding that both the shader compiler and
the runtime can understand.
-The Root Signature consists of a header followed by a collection of root parameters
-and static samplers. The structure uses a versioned design with offset-based references
-to allow for flexible serialization and deserialization.
+The Root Signature consists of a header followed by an array of root parameters
+and an array of static samplers. The structure uses a versioned design with
+offset-based references to allow for flexible serialization and deserialization.
+One consequence of using an offset-based reference is that root parameters and
+static samplers don't need to follow any specific ordering logic.
Root Signature Header
~~~~~~~~~~~~~~~~~~~~~
@@ -445,8 +447,17 @@ The `RootSignatureHeader` structure contains the top-level information about a r
This header allows readers to navigate the binary representation of the root signature by
providing counts and offsets to locate each component within the serialized data.
+Root Parameters
+~~~~~~~~~~~~~~~
+
+Root signatures parameters are split into a header section containing the parameter type,
+shader visibility and its offset, and a data section. The parameters don't need to follow
+any specific order. Root parameters define the interface elements that shaders can access.
+Each parameter can be one of several types, including descriptor tables, constants, or
+descriptors for different resource types.
+
Root Parameter Header
-~~~~~~~~~~~~~~~~~~~~~
+'''''''''''''''''''''
.. code-block:: c
@@ -470,17 +481,14 @@ the parameter's basic attributes:
The header uses a parameter type field rather than encoding the version of the parameter through
size, allowing for a more explicit representation of the parameter's nature.
-Root Parameters
-~~~~~~~~~~~~~~~
-
-The Root Parameters section contains structured definitions for each type of root parameter that can
-be included in a root signature. Each structure corresponds to a specific parameter type as identified
-by the ``ParameterType`` field in the ``RootParameterHeader``.
+Root Parameter Types
+''''''''''''''''''''
+This section describes the representation of each root parameter type.
Root Constants
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
-.. code-block:: cpp
+.. code-block:: c
struct RootConstants {
uint32_t ShaderRegister;
@@ -499,12 +507,12 @@ Root constants provide a fast way to pass small amounts of data directly to the
overhead of creating and binding a constant buffer resource.
Root Descriptor
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
Root descriptors provide a mechanism for binding individual resources to shader stages in the Direct3D 12
rendering pipeline. They allow applications to specify how shader stages access specific GPU resources.
-.. code-block:: cpp
+.. code-block:: c
enum RootDescriptorFlags {
None = 0,
@@ -532,25 +540,24 @@ performing further code optimizations. For details, check
`Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
Version 1.0 Root Descriptor
-'''''''''''''''''''''''''''
+"""""""""""""""""""""""""""
The Version 1.0 RootDescriptor_V1_0 provides basic resource binding:
#. **ShaderRegister**: The shader register where the descriptor is bound.
#. **RegisterSpace**: The register space used for the binding.
Version 1.1 Root Descriptor
-'''''''''''''''''''''''''''
+"""""""""""""""""""""""""""
The Version 1.1 RootDescriptor_V1_1 extends the base structure with the following additional fields:
#. **Flags**: Provides additional metadata about the descriptor's usage pattern.
Root Descriptor Table
-~~~~~~~~~~~~~~~~~~~~~
-
+^^^^^^^^^^^^^^^^^^^^^
Descriptor tables function as containers that hold references to descriptors in descriptor heaps.
They allow multiple descriptors to be bound to the pipeline through a single root signature parameter.
-.. code-block:: cpp
+.. code-block:: c
struct DescriptorRange_V1_0 {
dxbc::DescriptorRangeType RangeType;
@@ -588,7 +595,7 @@ They allow multiple descriptors to be bound to the pipeline through a single roo
Descriptor Range Version 1.0
-''''''''''''''''''''''''''''
+""""""""""""""""""""""""""""
The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
@@ -598,14 +605,14 @@ The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definit
#. **OffsetInDescriptorsFromTableStart**: Offset from the descriptor heap start
Descriptor Range Version 1.1
-''''''''''''''''''''''''''''
+""""""""""""""""""""""""""""
The Version 1.1 DescriptorRange_V1_1 extends the base structure with performance optimization flags.
#. **Flags**: Provide additional information about the descriptors and enable further driver optimizations.
For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
-Root Descriptor Table
-'''''''''''''''''''''
+Root Descriptor Table Structure
+"""""""""""""""""""""""""""""""
RootDescriptorTable provides basic table structure:
#. **NumDescriptorRanges**: Number of descriptor ranges
@@ -616,7 +623,7 @@ Static Samplers
Static samplers provide a way to define fixed sampler states within the root signature itself.
-.. code-block:: cpp
+.. code-block:: c
struct StaticSamplerDesc {
FilterMode Filter;
@@ -637,21 +644,21 @@ Static samplers provide a way to define fixed sampler states within the root sig
The StaticSamplerDesc structure defines all properties of a static sampler:
-#. Filter: The filtering mode (e.g., point, linear, anisotropic) used for texture sampling.
+#. **Filter**: The filtering mode (e.g., point, linear, anisotropic) used for texture sampling.
For details, check `Static Sampler Fileters definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter#syntax>`_.
-#. AddressU: The addressing mode for the U texture coordinate.
+#. **AddressU**: The addressing mode for the U texture coordinate.
For details, check `Texture address mode definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_.
-#. AddressV: The addressing mode for the V texture coordinate.
-#. AddressW: The addressing mode for the W texture coordinate.
-#. MipLODBias: Bias value applied to mipmap level of detail calculations.
-#. MaxAnisotropy: Maximum anisotropy level when using anisotropic filtering.
-#. ComparisonFunc: Comparison function used for comparison samplers.
+#. **AddressV**: The addressing mode for the V texture coordinate.
+#. **AddressW**: The addressing mode for the W texture coordinate.
+#. **MipLODBias**: Bias value applied to mipmap level of detail calculations.
+#. **MaxAnisotropy**: Maximum anisotropy level when using anisotropic filtering.
+#. **ComparisonFunc**: Comparison function used for comparison samplers.
For details, check `Comparison Function definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_.
-#. BorderColor: Predefined border color used when address mode is set to border.
+#. **BorderColor**: Predefined border color used when address mode is set to border.
For details, check `Static border color <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_.
-#. MinLOD: Minimum level of detail to use for sampling.
-#. MaxLOD: Maximum level of detail to use for sampling.
-#. ShaderRegister: The shader sampler register (s#) where this sampler is bound.
-#. RegisterSpace: The register space used for the binding.
-#. ShaderVisibility: Specifies which shader stages can access this sampler.
- For details, check `Sahder Visibility definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
+#. **MinLOD**: Minimum level of detail to use for sampling.
+#. **MaxLOD**: Maximum level of detail to use for sampling.
+#. **ShaderRegister**: The shader sampler register (s#) where this sampler is bound.
+#. **RegisterSpace**: The register space used for the binding.
+#. **ShaderVisibility**: Specifies which shader stages can access this sampler.
+ For details, check `Shader Visibility definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
>From b0130802d43bc4a366e71e6a800d50fe9e4f3567 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Fri, 14 Mar 2025 11:58:46 -0700
Subject: [PATCH 20/22] Update DXContainer.rst
---
llvm/docs/DirectX/DXContainer.rst | 58 ++++++++++++++++++-------------
1 file changed, 33 insertions(+), 25 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index f35d60e0a97b0..294cebe486658 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -556,6 +556,26 @@ Root Descriptor Table
^^^^^^^^^^^^^^^^^^^^^
Descriptor tables function as containers that hold references to descriptors in descriptor heaps.
They allow multiple descriptors to be bound to the pipeline through a single root signature parameter.
+Tables are split in a Header and Data Section. The Header contains information that helps locate the data,
+which will contain a collection of descriptor ranges.
+
+Root Descriptor Table Header
+"""""""""""""""""""""""""""""""
+
+.. code-block:: c
+
+ struct RootDescriptorTable {
+ uint32_t NumDescriptorRanges;
+ uint32_t DescriptorRangesOffset;
+ };
+
+RootDescriptorTable provides basic table structure:
+
+#. **NumDescriptorRanges**: Number of descriptor ranges
+#. **DescriptorRangesOffset**: Offset to descriptor range array
+
+Descriptor Range Version 1.0
+""""""""""""""""""""""""""""
.. code-block:: c
@@ -567,6 +587,19 @@ They allow multiple descriptors to be bound to the pipeline through a single roo
uint32_t OffsetInDescriptorsFromTableStart;
};
+The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
+
+#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
+#. **NumDescriptors**: Number of descriptors in the range
+#. **BaseShaderRegister**: First shader register in the range
+#. **RegisterSpace**: Register space for the range
+#. **OffsetInDescriptorsFromTableStart**: Offset from the descriptor heap start
+
+Descriptor Range Version 1.1
+""""""""""""""""""""""""""""
+
+.. code-block:: c
+
struct DescriptorRange_V1_1 {
dxbc::DescriptorRangeType RangeType;
uint32_t NumDescriptors;
@@ -588,36 +621,11 @@ They allow multiple descriptors to be bound to the pipeline through a single roo
uint32_t Flags;
};
- struct RootDescriptorTable {
- uint32_t NumDescriptorRanges;
- uint32_t DescriptorRangesOffset;
- };
-
-
-Descriptor Range Version 1.0
-""""""""""""""""""""""""""""
-The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
-
-#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
-#. **NumDescriptors**: Number of descriptors in the range
-#. **BaseShaderRegister**: First shader register in the range
-#. **RegisterSpace**: Register space for the range
-#. **OffsetInDescriptorsFromTableStart**: Offset from the descriptor heap start
-
-Descriptor Range Version 1.1
-""""""""""""""""""""""""""""
The Version 1.1 DescriptorRange_V1_1 extends the base structure with performance optimization flags.
#. **Flags**: Provide additional information about the descriptors and enable further driver optimizations.
For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
-Root Descriptor Table Structure
-"""""""""""""""""""""""""""""""
-RootDescriptorTable provides basic table structure:
-
-#. **NumDescriptorRanges**: Number of descriptor ranges
-#. **DescriptorRangesOffset**: Offset to descriptor range array
-
Static Samplers
~~~~~~~~~~~~~~~
>From 0bcfa6b67016a30067b47db7b86edaa33a849571 Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Mon, 17 Mar 2025 12:50:25 -0700
Subject: [PATCH 21/22] Addressing comments
---
llvm/docs/DirectX/DXContainer.rst | 224 +++++++-----------------------
1 file changed, 51 insertions(+), 173 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index 294cebe486658..a766b4d399483 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -405,21 +405,22 @@ Root Signature (RTS0) Part
--------------------------
.. _RTS0:
-The Root Signature defines the interface between the shader and the pipeline,
-specifying which resources are bound to the shader and how they are accessed.
-This structure serves as a contract between the application and the GPU,
-establishing a layout for resource binding that both the shader compiler and
-the runtime can understand.
-
-The Root Signature consists of a header followed by an array of root parameters
-and an array of static samplers. The structure uses a versioned design with
-offset-based references to allow for flexible serialization and deserialization.
-One consequence of using an offset-based reference is that root parameters and
-static samplers don't need to follow any specific ordering logic.
+The Root Signature data defines the shader's resource interface with Direct3D 12,
+specifying what resources the shader needs to access and how they're organized
+and bound to the pipeline.
+
+The RTS0 part comprises three data structures: ``RootSignatureHeader``,
+``RootParameters`` and ``StaticSamplers``. The details of each will be described
+in the following sections. All ``RootParameters`` will be serialized following the
+order they were defined in the metadata representation.
Root Signature Header
~~~~~~~~~~~~~~~~~~~~~
+The root signature header is 24 bytes long, consisting of six 32 bit values
+representing the version, number and offset of parameters, number and offset
+of static samplers, and a flags field for global behaviours:
+
.. code-block:: c
struct RootSignatureHeader {
@@ -432,215 +433,113 @@ Root Signature Header
}
-The `RootSignatureHeader` structure contains the top-level information about a root signature:
-
-#. **Version**: Specifies the version of the root signature format. This allows for backward
- compatibility as the format evolves.
-#. **NumParameters**: The number of root parameters contained in this root signature.
-#. **ParametersOffset**: Byte offset from the beginning of RST0 section to the array of root
- parameters header.
-#. **NumStaticSamplers**: The number of static samplers defined in the root signature.
-#. **StaticSamplerOffset**: Byte offset to the array of static samplers.
-#. **Flags**: Bit flags that define global behaviors for the root signature, such as whether
- to deny vertex shader access to certain resources.
-
-This header allows readers to navigate the binary representation of the root signature by
-providing counts and offsets to locate each component within the serialized data.
-
Root Parameters
~~~~~~~~~~~~~~~
+Root parameters define how resources are bound to the shader pipeline, each
+type having different size and fields.
-Root signatures parameters are split into a header section containing the parameter type,
-shader visibility and its offset, and a data section. The parameters don't need to follow
-any specific order. Root parameters define the interface elements that shaders can access.
-Each parameter can be one of several types, including descriptor tables, constants, or
-descriptors for different resource types.
-
-Root Parameter Header
-'''''''''''''''''''''
+Each slot of root parameters is preceded by 12 bytes, three 32 bit values,
+representing the parameter type, a flag encoding the pipeline stages where
+the data is visible, and an offset calculated from the start of RTS0 section.
.. code-block:: c
struct RootParameterHeader {
- dxbc::RootParameterType ParameterType;
- dxbc::ShaderVisibility ShaderVisibility;
+ uint32_t ParameterType;
+ uint32_t ShaderVisibility;
uint32_t ParameterOffset;
};
-
-Each root parameter in the signature is preceded by a `RootParameterHeader` that describes
-the parameter's basic attributes:
-
-#. **ParameterType**: Enumeration indicating what type of parameter this is (e.g., descriptor
- table, constants, CBV, SRV, UAV).
-#. **ShaderVisibility**: Specifies which shader stages can access this parameter (e.g., all stages,
- vertex shader only, pixel shader only).
-#. **ParameterOffset**: Byte offset to the specific parameter data structure
- for this entry.
-
-The header uses a parameter type field rather than encoding the version of the parameter through
-size, allowing for a more explicit representation of the parameter's nature.
-
-Root Parameter Types
-''''''''''''''''''''
-This section describes the representation of each root parameter type.
+The following sections will describe each of the root parameters types and their encodings.
Root Constants
-^^^^^^^^^^^^^^
+''''''''''''''
+
+Root constants are values passed directly to shaders without needing a constant
+buffer. It is a 12 bytes long structure, two 32 bit values encoding the register
+and space the constant is assigned to, and one 32 bit value encoding the constant value.
.. code-block:: c
struct RootConstants {
- uint32_t ShaderRegister;
- uint32_t RegisterSpace;
- uint32_t Num32BitValues;
+ uint32_t Register;
+ uint32_t Space;
+ uint32_t Value;
};
-The ``RootConstants`` structure represents inline root constants that are directly embedded in the root
-signature and passed to the shader without requiring a constant buffer resource:
-
-#. **ShaderRegister**: The shader register (b#) where these constants are bound.
-#. **RegisterSpace**: The register space used for the binding.
-#. **Num32BitValues**: The number of 32-bit values included in this constant buffer.
-
-Root constants provide a fast way to pass small amounts of data directly to the shader without the
-overhead of creating and binding a constant buffer resource.
-
Root Descriptor
-^^^^^^^^^^^^^^^
+'''''''''''''''
-Root descriptors provide a mechanism for binding individual resources to shader stages in the Direct3D 12
-rendering pipeline. They allow applications to specify how shader stages access specific GPU resources.
+Root descriptors provide direct GPU memory addresses to resources. Version 1.1 of
+root descriptor is a 12 byte long, the first two 32 bit values encode the register
+and space being assigned to the descriptor, and the last 32 bit value is an access flag flag.
-.. code-block:: c
+Version 1.0 doesn't contain the flags available in version 1.1.
- enum RootDescriptorFlags {
- None = 0,
- DataVolatile = 0x2,
- DataStaticWhileSetAtExecute = 0x4,
- DataStatic = 0x8,
- }
+.. code-block:: c
- // Version 1.0 Root Descriptor
struct RootDescriptor_V1_0 {
uint32_t ShaderRegister;
uint32_t RegisterSpace;
};
- // Version 1.1 Root Descriptor
struct RootDescriptor_V1_1 {
uint32_t ShaderRegister;
uint32_t RegisterSpace;
- // Bitfield of flags from the Flags enum
uint32_t Flags;
};
-Version 1.1 of Root Descriptors has introduced some flags that can hint the drivers into
-performing further code optimizations. For details, check
-`Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
-
-Version 1.0 Root Descriptor
-"""""""""""""""""""""""""""
-The Version 1.0 RootDescriptor_V1_0 provides basic resource binding:
-
-#. **ShaderRegister**: The shader register where the descriptor is bound.
-#. **RegisterSpace**: The register space used for the binding.
-
-Version 1.1 Root Descriptor
-"""""""""""""""""""""""""""
-The Version 1.1 RootDescriptor_V1_1 extends the base structure with the following additional fields:
-
-#. **Flags**: Provides additional metadata about the descriptor's usage pattern.
-
Root Descriptor Table
-^^^^^^^^^^^^^^^^^^^^^
-Descriptor tables function as containers that hold references to descriptors in descriptor heaps.
-They allow multiple descriptors to be bound to the pipeline through a single root signature parameter.
-Tables are split in a Header and Data Section. The Header contains information that helps locate the data,
-which will contain a collection of descriptor ranges.
-
-Root Descriptor Table Header
-"""""""""""""""""""""""""""""""
-
-.. code-block:: c
-
- struct RootDescriptorTable {
- uint32_t NumDescriptorRanges;
- uint32_t DescriptorRangesOffset;
- };
-
-RootDescriptorTable provides basic table structure:
+'''''''''''''''''''''
+Descriptor tables let shaders access multiple resources through a single pointer to a descriptor heap.
-#. **NumDescriptorRanges**: Number of descriptor ranges
-#. **DescriptorRangesOffset**: Offset to descriptor range array
+The tables are made of a collection of descriptor ranges. Version 1.1 ranges are 24 bytes long, containing
+five 32 bit values: The type of register, the number of registers in the range, the starting register number,
+the register space, an offset in number of descriptors from the start of the table and finally an access flag.
-Descriptor Range Version 1.0
-""""""""""""""""""""""""""""
+Version 1.0 ranges are the 20 bytes long, following the same structure without the flags.
.. code-block:: c
struct DescriptorRange_V1_0 {
- dxbc::DescriptorRangeType RangeType;
+ uint_32t RangeType;
uint32_t NumDescriptors;
uint32_t BaseShaderRegister;
uint32_t RegisterSpace;
uint32_t OffsetInDescriptorsFromTableStart;
};
-The Version 1.0 ``DescriptorRange_V1_0`` provides basic descriptor range definition:
-
-#. **RangeType**: Type of descriptors (CBV, SRV, UAV, or Sampler)
-#. **NumDescriptors**: Number of descriptors in the range
-#. **BaseShaderRegister**: First shader register in the range
-#. **RegisterSpace**: Register space for the range
-#. **OffsetInDescriptorsFromTableStart**: Offset from the descriptor heap start
-
-Descriptor Range Version 1.1
-""""""""""""""""""""""""""""
-
-.. code-block:: c
-
struct DescriptorRange_V1_1 {
dxbc::DescriptorRangeType RangeType;
uint32_t NumDescriptors;
uint32_t BaseShaderRegister;
uint32_t RegisterSpace;
- uint32_t OffsetInDescriptorsFromTableStart;
- // New flags for Version 1.1
- enum Flags {
- None = 0x0,
- // Descriptors are static and known at root signature creation
- DESCRIPTORS_STATIC = 0x1,
- // Descriptors remain constant during command list execution
- DESCRIPTORS_STATIC_KEEPING_BUFFER_BOUNDS_CHECKS = 0x2,
- // Descriptors may change frequently
- DESCRIPTORS_VOLATILE = 0x4
- };
-
+ uint32_t OffsetInDescriptorsFromTableStart;
// Bitfield of flags from the Flags enum
uint32_t Flags;
};
-The Version 1.1 DescriptorRange_V1_1 extends the base structure with performance optimization flags.
-
-#. **Flags**: Provide additional information about the descriptors and enable further driver optimizations.
- For details, check `Direct X documentation <https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signature-version-1-1#static-and-volatile-flags>`_.
-
Static Samplers
~~~~~~~~~~~~~~~
-Static samplers provide a way to define fixed sampler states within the root signature itself.
+Static samplers are predefined filtering settings built into the root signature, avoiding descriptor heap lookups.
+
+This section also has a variable size. The size is 68 bytes long, containing the following fields: 32 bits for a
+filter mode, three 32 bit fields for texture address mode, 64 bits for the bias value of minmap level calculation,
+32 bits for maximum anisotropy level, 32 bits for the comparison function type, 32 bits for the static border colour,
+two 64 bit fields for the min and max level of detail, two 32 bit fields for the register number and space and finally
+32 bits for the shader visibility flag.
.. code-block:: c
struct StaticSamplerDesc {
- FilterMode Filter;
+ FilterMode Filter;
TextureAddressMode AddressU;
TextureAddressMode AddressV;
TextureAddressMode AddressW;
float MipLODBias;
uint32_t MaxAnisotropy;
- ComparisonFunc ComparisonFunc;
+ ComparisonFunc ComparisonFunc;
StaticBorderColor BorderColor;
float MinLOD;
float MaxLOD;
@@ -649,24 +548,3 @@ Static samplers provide a way to define fixed sampler states within the root sig
ShaderVisibility ShaderVisibility;
};
-
-The StaticSamplerDesc structure defines all properties of a static sampler:
-
-#. **Filter**: The filtering mode (e.g., point, linear, anisotropic) used for texture sampling.
- For details, check `Static Sampler Fileters definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_filter#syntax>`_.
-#. **AddressU**: The addressing mode for the U texture coordinate.
- For details, check `Texture address mode definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_texture_address_mode>`_.
-#. **AddressV**: The addressing mode for the V texture coordinate.
-#. **AddressW**: The addressing mode for the W texture coordinate.
-#. **MipLODBias**: Bias value applied to mipmap level of detail calculations.
-#. **MaxAnisotropy**: Maximum anisotropy level when using anisotropic filtering.
-#. **ComparisonFunc**: Comparison function used for comparison samplers.
- For details, check `Comparison Function definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_comparison_func>`_.
-#. **BorderColor**: Predefined border color used when address mode is set to border.
- For details, check `Static border color <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_static_border_color>`_.
-#. **MinLOD**: Minimum level of detail to use for sampling.
-#. **MaxLOD**: Maximum level of detail to use for sampling.
-#. **ShaderRegister**: The shader sampler register (s#) where this sampler is bound.
-#. **RegisterSpace**: The register space used for the binding.
-#. **ShaderVisibility**: Specifies which shader stages can access this sampler.
- For details, check `Shader Visibility definition. <https://learn.microsoft.com/en-us/windows/win32/api/d3d12/ne-d3d12-d3d12_shader_visibility>`_.
>From 787c9203ee7786b805017ea68ad85c8e300dff4a Mon Sep 17 00:00:00 2001
From: joaosaffran <126493771+joaosaffran at users.noreply.github.com>
Date: Wed, 19 Mar 2025 11:29:19 -0700
Subject: [PATCH 22/22] Addressing comments
---
llvm/docs/DirectX/DXContainer.rst | 69 +++++++++++++++++--------------
1 file changed, 38 insertions(+), 31 deletions(-)
diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst
index a766b4d399483..670f465c2b10e 100644
--- a/llvm/docs/DirectX/DXContainer.rst
+++ b/llvm/docs/DirectX/DXContainer.rst
@@ -393,26 +393,18 @@ bit in the mask vector identifies one column of a patch constant input and a
column of an output. A value of 1 means the output is impacted by the primitive
input.
-SFI0 Part
----------
-.. _SFI0:
-
-The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
-This denotes which optional features the shader requires. The flag values are
-defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
-
Root Signature (RTS0) Part
--------------------------
.. _RTS0:
-The Root Signature data defines the shader's resource interface with Direct3D 12,
-specifying what resources the shader needs to access and how they're organized
-and bound to the pipeline.
+The Root Signature data defines the shader's resource interface with Direct3D
+12, specifying what resources the shader needs to access and how they're
+organized and bound to the pipeline.
The RTS0 part comprises three data structures: ``RootSignatureHeader``,
``RootParameters`` and ``StaticSamplers``. The details of each will be described
-in the following sections. All ``RootParameters`` will be serialized following the
-order they were defined in the metadata representation.
+in the following sections. All ``RootParameters`` will be serialized following
+the order they were defined in the metadata representation.
Root Signature Header
~~~~~~~~~~~~~~~~~~~~~
@@ -450,14 +442,16 @@ the data is visible, and an offset calculated from the start of RTS0 section.
uint32_t ParameterOffset;
};
-The following sections will describe each of the root parameters types and their encodings.
+The following sections will describe each of the root parameters types and their
+encodings.
Root Constants
''''''''''''''
Root constants are values passed directly to shaders without needing a constant
buffer. It is a 12 bytes long structure, two 32 bit values encoding the register
-and space the constant is assigned to, and one 32 bit value encoding the constant value.
+and space the constant is assigned to, and one 32 bit value encoding the
+constant value.
.. code-block:: c
@@ -470,9 +464,13 @@ and space the constant is assigned to, and one 32 bit value encoding the constan
Root Descriptor
'''''''''''''''
-Root descriptors provide direct GPU memory addresses to resources. Version 1.1 of
-root descriptor is a 12 byte long, the first two 32 bit values encode the register
-and space being assigned to the descriptor, and the last 32 bit value is an access flag flag.
+Root descriptors provide direct GPU memory addresses to resources.
+
+In version 1.0, the root descriptor is 8 bytes. It encodes the register and
+space as 2 32-bit values.
+
+In version 1.1, the root descriptor is 12 bytes. It matches the 1.0 descriptor
+but adds a 32-bit access flag.
Version 1.0 doesn't contain the flags available in version 1.1.
@@ -491,18 +489,21 @@ Version 1.0 doesn't contain the flags available in version 1.1.
Root Descriptor Table
'''''''''''''''''''''
-Descriptor tables let shaders access multiple resources through a single pointer to a descriptor heap.
+Descriptor tables let shaders access multiple resources through a single pointer
+to a descriptor heap.
-The tables are made of a collection of descriptor ranges. Version 1.1 ranges are 24 bytes long, containing
-five 32 bit values: The type of register, the number of registers in the range, the starting register number,
-the register space, an offset in number of descriptors from the start of the table and finally an access flag.
+The tables are made of a collection of descriptor ranges. In Version 1.0, the
+descriptor range is 20 bytes, containing five 32 bit values. It encodes a range
+of registers, including the register type, range length, register numbers and
+space within range and the offset locating each range inside the table.
-Version 1.0 ranges are the 20 bytes long, following the same structure without the flags.
+In version 1.1, the descriptor range is 24 bytes. It matches the 1.0 descriptor
+but adds a 32-bit access flag.
.. code-block:: c
struct DescriptorRange_V1_0 {
- uint_32t RangeType;
+ uint32_t RangeType;
uint32_t NumDescriptors;
uint32_t BaseShaderRegister;
uint32_t RegisterSpace;
@@ -515,20 +516,18 @@ Version 1.0 ranges are the 20 bytes long, following the same structure without t
uint32_t BaseShaderRegister;
uint32_t RegisterSpace;
uint32_t OffsetInDescriptorsFromTableStart;
- // Bitfield of flags from the Flags enum
uint32_t Flags;
};
Static Samplers
~~~~~~~~~~~~~~~
-Static samplers are predefined filtering settings built into the root signature, avoiding descriptor heap lookups.
+Static samplers are predefined filtering settings built into the root signature,
+avoiding descriptor heap lookups.
-This section also has a variable size. The size is 68 bytes long, containing the following fields: 32 bits for a
-filter mode, three 32 bit fields for texture address mode, 64 bits for the bias value of minmap level calculation,
-32 bits for maximum anisotropy level, 32 bits for the comparison function type, 32 bits for the static border colour,
-two 64 bit fields for the min and max level of detail, two 32 bit fields for the register number and space and finally
-32 bits for the shader visibility flag.
+This section also has a variable size, since it can contain multiple static
+samplers definitions. However, the definition is a fixed sized struct,
+containing 13 32-byte fields of various enum, float, and integer values.
.. code-block:: c
@@ -548,3 +547,11 @@ two 64 bit fields for the min and max level of detail, two 32 bit fields for the
ShaderVisibility ShaderVisibility;
};
+
+SFI0 Part
+---------
+.. _SFI0:
+
+The SFI0 part encodes a 64-bit unsigned integer bitmask of the feature flags.
+This denotes which optional features the shader requires. The flag values are
+defined in `llvm/include/llvm/BinaryFormat/DXContainerConstants.def <https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/BinaryFormat/DXContainerConstants.def>`_.
More information about the llvm-commits
mailing list