[llvm-branch-commits] [llvm] [DirectX] Updating DXContainer documentation to add Root Descriptors (PR #129759)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Wed Mar 5 12:55:38 PST 2025
https://github.com/joaosaffran updated https://github.com/llvm/llvm-project/pull/129759
>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 1/5] 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 2/5] 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 3/5] 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 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 4/5] 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 5/5] 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;
};
More information about the llvm-branch-commits
mailing list