From 3099b546053c597fe329363660a9c92bdbb505e7 Mon Sep 17 00:00:00 2001 From: "Amar Patel (Microsoft)" Date: Tue, 15 Jul 2025 19:39:59 -0700 Subject: [PATCH 1/2] ClusterID HLSL proposal --- proposals/NNNN-hlsl-clustered-geometry.md | 204 ++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 proposals/NNNN-hlsl-clustered-geometry.md diff --git a/proposals/NNNN-hlsl-clustered-geometry.md b/proposals/NNNN-hlsl-clustered-geometry.md new file mode 100644 index 00000000..56dad972 --- /dev/null +++ b/proposals/NNNN-hlsl-clustered-geometry.md @@ -0,0 +1,204 @@ + + +# HLSL support for Clustered Geometry in Raytracing + +--- + +* Proposal: [NNNN](NNNN-hlsl-clustered-geometry.md) +* Author(s): [Author 1](https://github.com/author_username) +* Sponsor: [Amar Patel](https://github.com/amarpMSFT) +* Status: **Under Consideration** + +--- + +## Introduction + +Acceleration structure build times can become a bottleneck in raytracing +applications that require large amounts of dynamic geometry. Example scenarios +include new geometry being streamed in from disk, high numbers of animated +objects, level-of-detail systems, or dynamic tessellation. + +Clustered Geometry is a proposed future DXR feature that aims to address this +issue by enabling the application to construct bottom-level acceleration structures +from previously generated clusters of primitives, resulting in significant speedups +in acceleration structure build times. The DXR spec details for this are not available +yet, but as an example for now see [NVIDIA's blog](https://developer.nvidia.com/blog/nvidia-rtx-mega-geometry-now-available-with-new-vulkan-samples/) describing the overall concept of clustered +geometry (among other topics). + +How clustered geometry gets exposed in D3D overall is to be determined but this document is +certainly a part: a proposal for the HLSL operations needed for clustered geometry. + +Also see the complementary [DXIL](NNNN-dxil-clustered-geometry.md) proposal. + +--- + +## Motivation + +Clustered Geometry refers to a building block for Bottom Level Acceleration Structures +(BLASes). Most of the details of what a cluster is are out of scope for this spec. +What's relevant is that the application can build BLASes out of cluster building +blocks. When raytracing, hit shaders will want to know the ID of the cluster that is hit +so the shader can do things like look up cluster-specific user data. Hence the need for a `ClusterID()` intrinsic. + +This isn't an index into the clusters in a given BLAS but rather an ID assigned by +the user for each cluster in a BLAS. Different BLASs could reuse simmilar building blocks, and +thus share cluster ID. + +--- + +## HLSL + +--- + +### Enums + +```C +enum CLUSTER_ID_CONSTANTS : uint +{ + CLUSTER_ID_INVALID = 0xffffffff, +}; +``` + +ClusterID values returned by [ClusterID()](#clusterid) with predefined meaning + +Value | Definition +----- | ---- +`CLUSTER_ID_INVALID` | Returned if a BLAS was intersected that was not constructed from CLAS + +--- + +### DXR 1.0 System Value Intrinsics + +A new DXR System Value Intrinsic is added to support fetching the `ClusterID` of an intersected CLAS. + +--- + +#### ClusterID + +```C +uint ClusterID() +``` + +Returns a `uint` containing the user-defined `ClusterID` value a CLAS was +built with. If a non-clustered BLAS was intersected, `CLUSTER_ID_INVALID` +is returned. + +The following table shows which shaders can access it: +| **values \\ shaders** | ray generation | intersection | any hit | closest hit | miss | callable | +|:---------------------------------------------------------:|:--------------:|:------------:|:-------:|:-----------:|:----:|:--------:| +| *Primitive/object space system values:* | | | | | | | +| uint [ClusterID()](#clusterid) | | | \* | \* | | | + +--- + +## Extension to DXR 1.1 RayQuery API + +New intrinsics [CandidateClusterID()](#rayquery-candidateclusterid) and +[CommittedClusterID()](#rayquery-committedclusterid) are added to `RayQuery`. +Behavior of all other intrinsics is unchanged. + +--- + +### RayQuery intrinsics + +The following table lists intrinsics available when +[RayQuery::Proceed()](https://github.com/microsoft/DirectX-Specs/blob/master/d3d/Raytracing.md#rayquery-proceed) returned `TRUE`, +meaning a type of hit candidate that requires shader evaluation has been found. +Methods named `Committed*()` in this table may actually not be available +depending on the current [CommittedStatus()](https://github.com/microsoft/DirectX-Specs/blob/master/d3d/Raytracing.md#rayquery-committedstatus) +(i.e. what type of hit has been committed yet, if any) - this is further +clarified in another table further below. + +| **Intrinsic** \ **CandidateType()** | `HIT_CANDIDATE_NON_OPAQUE_TRIANGLE` | `HIT_CANDIDATE_PROCEDURAL_PRIMITIVE` +|:--------------|:-----------:|:-----------:| +| uint [CandidateClusterID()](#rayquery-candidateclusterid)| \* | | +| uint [CommittedClusterID()](#rayquery-committedclusterid)| \* | | + +The following table lists intrinsics available depending on the current +[COMMITTED_STATUS](https://github.com/microsoft/DirectX-Specs/blob/master/d3d/Raytracing.md#committed_status) (i.e. what type of +hit has been committed, if any). This applies regardless of whether +[RayQuery::Proceed()](https://github.com/microsoft/DirectX-Specs/blob/master/d3d/Raytracing.md#rayquery-proceed) has returned +`TRUE` (shader evaluation needed for traversal), or `FALSE` (traversal +complete). If `TRUE`, additional methods than those shown below are +available (see the above table). + +| **Intrinsic** \ **CommittedStatus()** | `COMMITTED_TRIANGLE_HIT` | `COMMITTED_PROCEDURAL_PRIMITIVE_HIT` | `COMMITTED_NOTHING` | +|:--------------|:-----------:|:-----------:|:-----------:| +| uint [CommittedClusterID()](#rayquery-committedclusterid)| \* | | | + +--- + +#### RayQuery CandidateClusterID + +The user-provided `ClusterID` of the intersected CLAS, if a Cluster BLAS was +intersected for the current hit candidate. +Returns `CLUSTER_ID_INVALID` if a non-Cluster BLAS was intersected. + +```C++ +uint RayQuery::CandidateClusterID(); +``` + +[RayQuery intrinsics](#rayquery-intrinsics) illustrates when this is valid to +call. +Lowers to [RayQuery_CandidateClusterID DXIL Opcode](#rayquery_candidateclusterid-dxil-opcode). + +--- + +#### RayQuery CommittedClusterID + +The user-provided `ClusterID` of the intersected CLAS, if a Cluster BLAS was +intersected for the closest hit committed so far. +Returns `CLUSTER_ID_INVALID` if a non-Cluster BLAS was intersected. + +```C++ +uint RayQuery::CommittedClusterID(); +``` + +[RayQuery intrinsics](#rayquery-intrinsics) illustrates when this is valid to +call. +Lowers to [RayQuery_CommittedClusterID DXIL Opcode](#rayquery_committedclusterid-dxil-opcode). + +--- + +### Extension to the DXR 1.2 HitObject API + +Cluster Geometries are also supported with the HitObject feature. +The following intrinsic is added to `HitObject` type. + +#### HitObject::GetClusterID + +```C +uint HitObject::GetClusterID(); +``` + +Returns the user-provided `ClusterID` of the intersected CLAS of a hit. +Returns `CLUSTER_ID_INVALID` if a non-Cluster BLAS was intersected or if +the `HitObject` does not encode a hit. +Lowers to [HitObject_ClusterID DXIL Opcode](#hitobject_clusterid-dxil-opcode). + +--- + +### Diagnostic Changes + +This proposal does not introduce or remove diagnostics or warnings. + +### Runtime Additions + +TODO: link the DXR spec propsoal when available + +## Testing + +### Unit Tests + +#### CodeGen & AST Tests + +* Expected AST for new implicit HLSL ops. +* Lowering from HLSL to HL. +* Lowering from HL to DXIL. +* Lowering from HLSL to DXIL. + +#### Diagnostics Tests + +* Expected error when ClusterID builtins called from unsupported shader kinds. + + From eef1d171e0cb5593a6a1deff8b001f9242ecc15c Mon Sep 17 00:00:00 2001 From: "Amar Patel (Microsoft)" Date: Wed, 16 Jul 2025 16:18:21 -0700 Subject: [PATCH 2/2] update authors --- proposals/NNNN-hlsl-clustered-geometry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/NNNN-hlsl-clustered-geometry.md b/proposals/NNNN-hlsl-clustered-geometry.md index 56dad972..7f0240f9 100644 --- a/proposals/NNNN-hlsl-clustered-geometry.md +++ b/proposals/NNNN-hlsl-clustered-geometry.md @@ -5,7 +5,7 @@ --- * Proposal: [NNNN](NNNN-hlsl-clustered-geometry.md) -* Author(s): [Author 1](https://github.com/author_username) +* Author(s): [Jan Schmid](https://github.com/jschmid-nvidia), [Simon Moll](https://github.com/simoll) * Sponsor: [Amar Patel](https://github.com/amarpMSFT) * Status: **Under Consideration**