updated method for disabling OMMs per cluster

amarpMSFT · amarpMSFT · commit 9723562873ed · 2026-04-14T21:17:03.000-07:00
diff --git a/d3d/Raytracing2.md b/d3d/Raytracing2.md
@@ -1,6 +1,6 @@
 # DirectX Raytracing (DXR) Functional Spec, Part 2 <!-- omit in toc -->
 
-v0.20 3/18/2026
+v0.21 4/14/2026
 
 ---
 
@@ -1399,7 +1399,7 @@ Specifies per-cluster flags for raytracing clusters in a [D3D12_RTAS_OPERATION_B
 Value                                                                                            | Definition
 -----                                                                                            | ----------
 `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_NONE`                                    | No options specified.
-`D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_ALLOW_DISABLE_OMMS`                      | If enabled, any instances referencing a Cluster BLAS containing this CLAS are allowed to disable the OMM test through the [D3D12_RAYTRACING_INSTANCE_FLAG_DISABLE_OMMS](raytracing.md#d3d12_raytracing_instance_flags) flag.  Since this is per-CLAS, must be set on all CLAS containing OMMs in the Cluster BLAS to allow instances to disable OMMs.
+`D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_ALLOW_DISABLE_OMMS`                      | If enabled, any instances referencing a Cluster BLAS containing this CLAS are allowed to disable the OMM test through the [D3D12_RAYTRACING_INSTANCE_FLAG_DISABLE_OMMS](raytracing.md#d3d12_raytracing_instance_flags) flag.  Since this is per-CLAS, must be set on all CLAS containing OMMs in the Cluster BLAS to allow instances to disable OMMs.  Regardless of whether this flag is set or not, OMMs can always be disabled per-cluster by setting `OpacityMicromapArray` and `OpacityMicromapIndexBuffer` to NULL in [D3D12_RTAS_OPERATION_BUILD_CLAS_FROM_TRIANGLES_ARGS](#d3d12_rtas_operation_build_clas_from_triangles_args).
 `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_DISALLOW_DATA_ACCESS` | <p>When [D3D12_RTAS_OPERATION_FLAG_ALLOW_DATA_ACCESS](#d3d12_rtas_operation_flags) is set in the operation flags, enabling [TriangleObjectPositions()](raytracing.md#triangleobjectpositions) globally for clusters built by the operation, `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_DISALLOW_DATA_ACCESS` allows selective disabling of that property for individual cluster builds in the overall operation.  Only enabling `TriangleObjectPositions` where needed can save space on some implementations.</p><p>Calling [TriangleObjectPositions()](raytracing.md#triangleobjectpositions) on a hit in a CLAS built with this flag (or without [D3D12_RTAS_OPERATION_FLAG_ALLOW_DATA_ACCESS](#d3d12_rtas_operation_flags)) produces undefined behavior.</p><p>`D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_DISALLOW_DATA_ACCESS` is ignored (as it is the default behavior) if `D3D12_RTAS_OPERATION_FLAG_ALLOW_DATA_ACCESS` is not set for the overall operation.</p>Like [D3D12_RTAS_OPERATION_FLAG_ALLOW_DATA_ACCESS](#d3d12_rtas_operation_flags), `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_DISALLOW_DATA_ACCESS` only applies to cluster builds and cluster template builds.  For cluster BLAS builds, all CLAS referenced by a given cluster BLAS must have consistently chosen to allow data access or not when they were built, otherwise behavior is undefined.  For cluster template instantiation, the allow/disallow state is inherited from the template.<p>
 
 Used by:
@@ -1486,8 +1486,8 @@ Member                                    | Definition
 `D3D12_GPU_VIRTUAL_ADDRESS IndexBuffer`   | The address of a strided array of indices sized equal to `TriangleCount` multiplied by 3, identifying the vertices to construct each triangle of the CLAS from. Address must be aligned to the index size. See [resource state for read-only arguments](#resource-state-for-read-only-arguments).
 `D3D12_GPU_VIRTUAL_ADDRESS GeometryIndexAndFlagsArray` | Either NULL or the address of a strided array of GeometryIndices combined with values from [D3D12_RTAS_CLUSTERED_GEOMETRY_FLAGS](#d3d12_rtas_clustered_geometry_flags).  If `GeometryIndexAndFlagsBuffer` is used, the number of entries is sufficient for what the index buffer will point to, otherwise equal to the number of triangles. For general geometry index discussion see [The role of geometry index in a cluster](#the-role-of-geometry-index-in-a-cluster).  Address must be 4 byte aligned. See [resource state for read-only arguments](#resource-state-for-read-only-arguments).
 `D3D12_GPU_VIRTUAL_ADDRESS GeometryIndexAndFlagsIndexBuffer` | Either NULL or the address of an array with size equal to the number of triangles for indexing into the `GeometryIndexAndFlagsArray`.  Stride is the size of the index format selected by `GeometryIndexAndFlagsIndexFormat`, and address must be aligned to this size. For general geometry index discussion see [The role of geometry index in a cluster](#the-role-of-geometry-index-in-a-cluster). See [resource state for read-only arguments](#resource-state-for-read-only-arguments).
-`D3D12_GPU_VIRTUAL_ADDRESS OpacityMicromapArray` | Either NULL or the address of a valid Opacity Micromap Array to reference from the CLAS. If NULL, [Opacity Micromaps](raytracing.md#opacity-micromaps) will be disabled for this CLAS. If non-NULL, [D3D12_RTAS_OPERATION_FLAG_ALLOW_OMM](#d3d12_rtas_operation_flags) must be set with this call and all calls to [ExecuteIndirectRTASOperations()](#executeindirectrtasoperations) interacting with the resulting object of this call, otherwise behavior is undefined.  Address must be aligned to [D3D12_RAYTRACING_OPACITY_MICROMAP_ARRAY_BYTE_ALIGNMENT](raytracing.md#constants) (`128`). See [resource state for read-only arguments](#resource-state-for-read-only-arguments).
-`D3D12_GPU_VIRTUAL_ADDRESS OpacityMicromapIndexBuffer` | <p>Either NULL or the address of a strided array with size equal to the number of triangles for indexing into the `OpacityMicromapArray`. Special reserved index values can be used to mark uniform OMMs.</p><p>There is an additional special index value that is specific to clusters to allow individual triangles to skip OMMs and revert to geometry supplies opaque/non-opaque state: `D3D12_RAYTRACING_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_SKIP_OMM`.  See this flag documented in [D3D12_RAYTRACING_OPACITY_MICROMAP_SPECIAL_INDEX](raytracing.md#d3d12_raytracing_opacity_micromap_special_index), where the motivation for the flag appears.</p><p>Address must be aligned to the index size. See [resource state for read-only arguments](#resource-state-for-read-only-arguments).</p>
+`D3D12_GPU_VIRTUAL_ADDRESS OpacityMicromapArray` | Either NULL or the address of a valid Opacity Micromap Array to reference from the CLAS. If NULL, and `OpacityMicromapIndexBuffer` is also NULL, [Opacity Micromaps](raytracing.md#opacity-micromaps) will be disabled for this CLAS. If either is non-NULL, [D3D12_RTAS_OPERATION_FLAG_ALLOW_OMM](#d3d12_rtas_operation_flags) must be set with this call and all calls to [ExecuteIndirectRTASOperations()](#executeindirectrtasoperations) interacting with the resulting object of this call, otherwise behavior is undefined.  Address must be aligned to [D3D12_RAYTRACING_OPACITY_MICROMAP_ARRAY_BYTE_ALIGNMENT](raytracing.md#constants) (`128`). See [resource state for read-only arguments](#resource-state-for-read-only-arguments).
+`D3D12_GPU_VIRTUAL_ADDRESS OpacityMicromapIndexBuffer` | <p>Either NULL or the address of a strided array with size equal to the number of triangles for indexing into the `OpacityMicromapArray`. If NULL, and `OpacityMicromapArray` is also NULL, [Opacity Micromaps](raytracing.md#opacity-micromaps) will be disabled for this CLAS. Special reserved index values can be used to mark uniform OMMs.</p><p>There is an additional special index value that is specific to clusters to allow individual triangles to skip OMMs and revert to geometry supplied opaque/non-opaque state: `D3D12_RAYTRACING_OPACITY_MICROMAP_SPECIAL_INDEX_CLUSTER_SKIP_OMM`.  See this flag documented in [D3D12_RAYTRACING_OPACITY_MICROMAP_SPECIAL_INDEX](raytracing.md#d3d12_raytracing_opacity_micromap_special_index), where the motivation for the flag appears.  If the entire index buffer will be populated with only special index values, `OpacityMicromapArray` can be null since it won't be referenced.</p><p>Address must be aligned to the index size. See [resource state for read-only arguments](#resource-state-for-read-only-arguments).</p>
 
 Used by:
 - GPU-side operation arguments for [D3D12_RTAS_OPERATION_TYPE_BUILD_CLAS_FROM_TRIANGLES](#d3d12_rtas_operation_type)
@@ -2235,4 +2235,5 @@ v0.16|3/11/2026|<li>In [D3D12_RTAS_CLUSTER_TRIANGLES_INPUTS_DESC](#d3d12_rtas_cl
 v0.17|3/12/2026|<li>Added [Why compaction doesn't apply to clustered geometry](#why-compaction-doesnt-apply-to-clustered-geometry) section</li>
 v0.18|3/16/2026|<li>Replaced C++ bitfields with plain `UINT` members (to be manually packed by user) in [D3D12_VERTEX_FORMAT_COMPRESSED1_HEADER](#compressed1-position-encoding) and [D3D12_VERTEX_FORMAT_COMPRESSED1_TEMPLATE_HEADER](#d3d12_vertex_format_compressed1_template_header) for portable layout across C++ compilers, architectures, and HLSL. Added [Compressed1 bitfield helper macros](#compressed1-bitfield-helper-macros) section with encode/decode macros from `d3d12.h` that work in both C++ and HLSL (with `UINT`/`INT` typedefs). For the same reason, in [D3D12_RTAS_OPERATION_BUILD_CLAS_FROM_TRIANGLES_ARGS](#d3d12_rtas_operation_build_clas_from_triangles_args) replaced bitfield members with vanilla typed members.</li><li>In [D3D12_RTAS_OPERATION_BUILD_CLAS_FROM_TRIANGLES_ARGS](#d3d12_rtas_operation_build_clas_from_triangles_args), for `IndexBufferStride` limited the maximum stride value to 4 bytes. The purpose of this stride is just for cases where an application may have index values of a larger size (e.g. 4 bytes) but knows the values would happen to fit in a smaller size like 1 byte, which implementations might process more efficiently.  The intent isn't for interleaving arbitrary data between indices (something more reasonable to do with the other stride values in this struct).</li>
 v0.19|3/17/2026|<li>Moved `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_ALLOW_DATA_ACCESS` from [D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAGS](#d3d12_rtas_cluster_operation_clas_flags) to [D3D12_RTAS_OPERATION_FLAGS](#d3d12_rtas_operation_flags) as `D3D12_RTAS_OPERATION_FLAG_ALLOW_DATA_ACCESS`.  This flag applies to CLAS builds and CLAS template builds; it is ignored for CLAS template instantiation, which inherits the allow/disallow state from the template.  It not allowed for cluster BLAS builds; instead, all CLAS referenced by a given cluster BLAS must have consistently chosen to allow data access or not when they were built.</li><li>Added `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_DISALLOW_DATA_ACCESS` to [D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAGS](#d3d12_rtas_cluster_operation_clas_flags) to selectively disable data access for individual cluster builds within an operation that has `ALLOW_DATA_ACCESS` globally set.</li>
-v0.20|3/18/2026|<li>In [Compressed1 bitfield helper macros](#compressed1-bitfield-helper-macros), macro cleanup and bugfixes: removed unnecessary mask after left shifting; `UINT(val)` instead of `(UINT)(val)` (less verbose); use sign extend on right shift - support is ubiquitous enough (old macro also incorrectly masked result)</li>
+v0.20|3/18/2026|<li>In [Compressed1 bitfield helper macros](#compressed1-bitfield-helper-macros), macro cleanup and bugfixes: removed unnecessary mask after left shifting; `UINT(val)` instead of `(UINT)(val)` (less verbose); use sign extend on right shift - support is ubiquitous enough (old macro also incorrectly masked result)</li>
+v0.21|4/14/2026|<li>In [D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAGS](#d3d12_rtas_cluster_operation_clas_flags), for `D3D12_RTAS_CLUSTER_OPERATION_CLAS_FLAG_ALLOW_DISABLE_OMMS`, clarified that regardless of whether this flag is set, OMMs can always be disabled per-cluster by setting `OpacityMicromapArray` and `OpacityMicromapIndexBuffer` to NULL in [D3D12_RTAS_OPERATION_BUILD_CLAS_FROM_TRIANGLES_ARGS](#d3d12_rtas_operation_build_clas_from_triangles_args).</li><li>In [D3D12_RTAS_OPERATION_BUILD_CLAS_FROM_TRIANGLES_ARGS](#d3d12_rtas_operation_build_clas_from_triangles_args), updated `OpacityMicromapArray` and `OpacityMicromapIndexBuffer` so that OMMs are disabled only when both are NULL (previously only `OpacityMicromapArray` being NULL was required).  Similarly, [D3D12_RTAS_OPERATION_FLAG_ALLOW_OMM](#d3d12_rtas_operation_flags) is required when either is non-NULL.  For `OpacityMicromapIndexBuffer`, clarified that if the entire index buffer uses only special index values, `OpacityMicromapArray` can be null since it won't be referenced.</li>
