Skip to content

[NFC] Update Shader Flags section of DXIL.rst #7295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Icohedron merged 11 commits into from
Jun 10, 2026
+46 −27
Merged

[NFC] Update Shader Flags section of DXIL.rst #7295

Changes from 8 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
03d8c6a
Update Shader Flags documentation
Icohedron Apr 1, 2025
42ca0a3
Match feature info names in dxcdisassembler.cpp where it makes sense
Icohedron Apr 2, 2025
3421eb2
Correct Raster Ordered UAVs criteria. Correct Disable shader optimiza…
Icohedron Apr 2, 2025
aeca9eb
Fix wording for ROV flag criteria
Icohedron Apr 2, 2025
6fb8317
Update criteria for setting the m_bResMayNotAlias flag
Icohedron Apr 22, 2025
8030ce8
Correct the criteria used to set shader flag 16 (UAVs at every shader…
Icohedron Apr 22, 2025
cfe435b
Correct criteria used to set shader flag 15 (64 UAV slots)
Icohedron Apr 22, 2025
17ecebc
Update flag descriptions to match DXContainerConstants.def in LLVM
Icohedron Jun 10, 2025
297da7e
Merge remote-tracking branch 'origin/main' into dxil-rst-shader-flags
Icohedron Jun 10, 2026
5222f53
Revise shader flag descriptions based on PR feedback
Icohedron Jun 10, 2026
1ee2290
Double back-quote the characters for `~D3D10_SB_GLOBAL_FLAG_REFACTORI…
Icohedron Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 46 additions & 27 deletions docs/DXIL.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,33 +515,52 @@ Additional shader properties are specified via tag-value pair list, which is the
Shader Flags
------------

Shaders have additional flags that covey their capabilities via tag-value pair with tag kDxilShaderFlagsTag (0), followed by an i64 bitmask integer. The bits have the following meaning:

=== =====================================================================
Bit Description
=== =====================================================================
0 Disable shader optimizations
1 Disable math refactoring
2 Shader uses doubles
3 Force early depth stencil
4 Enable raw and structured buffers
5 Shader uses min-precision, expressed as half and i16
6 Shader uses double extension intrinsics
7 Shader uses MSAD
8 All resources must be bound for the duration of shader execution
9 Enable view port and RT array index from any stage feeding rasterizer
10 Shader uses inner coverage
11 Shader uses stencil
12 Shader uses intrinsics that access tiled resources
13 Shader uses relaxed typed UAV load formats
14 Shader uses Level9 comparison filtering
15 Shader uses up to 64 UAVs
16 Shader uses UAVs
17 Shader uses CS4 raw and structured buffers
18 Shader uses Rasterizer Ordered Views
19 Shader uses wave intrinsics
20 Shader uses int64 instructions
=== =====================================================================
Shaders have additional flags that convey their capabilities via a tag-value pair with tag kDxilShaderFlagsTag (0), followed by an i64 bitmask integer. The bits have the following meaning, Shader Model requirements, and criteria for being set:

=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================
Bit SM Description Criteria to set shader flag
=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================
0 Disable shader optimizations Command-line flag ``/Od`` is provided to DXC
1 Disable math refactoring Not set

@inbelic inbelic Apr 2, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is not immediately clear what 'Not set' means in this context? Same for the others with the same criteria.

Is it that there is no set criteria, or, just if the flag is not set?

@Icohedron Icohedron Apr 2, 2025

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just means the flag is not set

@llvm-beanz llvm-beanz Apr 2, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is an older shader model flag. Maybe something more like: "Removed in Shader Model 6.0" is appropriate. @tex3d any thoughts?

@Icohedron Icohedron Apr 2, 2025 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Though I suppose the wording is a bit awkward because I think the intention for some of these flags is that you can set it if you wish to have its effects? Like if you want to disable math refactoring, you can set the bit for it?

The criteria is more like describing the conditions under which the flag is required to be set and the validator will complain if you use a capability without setting its corresponding bit, or set a capability bit without actually utilizing it in the shader. Though, again, this isn't entirely the case because the shader flags enabled by a command-line flag don't fall into this category.

@tex3d tex3d Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This flag is used in the DXBC shader converter to capture the inverse of the global flag D3D10_SB_GLOBAL_FLAG_REFACTORING_ALLOWED, which may be present in the DXBC.
The closest equivalent would be -Gis, which is partly what would have driven this flag in FXC (the other part depends on the shader profile).

DXC doesn't set this flag for shaders compiled from HLSL to DXIL, since using -Gis will control this property at the operation level through fast math flags and the precise metadata.

So perhaps the more appropriate wording would be:
"Only used by DxilConv; corresponds to ~D3D10_SB_GLOBAL_FLAG_REFACTORING_ALLOWED in DXBC"

2 Double-precision floating point Use of the double data type
3 Force early depth-stencil test Shader is a pixel shader, and the ``[earlydepthstencil]`` attribute is present in the HLSL source
4 Raw and Structured buffers Use of RawBuffer or StructuredBuffer resource types
5 Low-precision data types present Use of half or i16 data types
6 Double-precision extensions for 11.1 Use of FDiv, UIToFP, SIToFP, FPToUI, FPToSI, or Fma instructions with a double type
7 Shader extensions for 11.1 Use of the Msad instruction
8 All resources bound for the duration of shader execution Command-line flag ``/all_resources_bound`` provided to DXC
9 SV_RenderTargetArrayIndex or SV_ViewportArrayIndex from any shader feeding rasterizer ViewPortArrayIndex or RenderTargetArrayIndex semantics are present in the input signature of a geometry shader, or the output signature of a vertex, domain, or hull shader. If DXIL validator version < 1.4, this flag is also required if the ViewPortArrayIndex or RenderTargetArrayIndex semantics are present in the input signature of domain and hull shaders
10 PS Inner Coverage Use of the InnerCoverage instruction, or the InnerCoverage semantic is present in the output signature of a pixel shader
11 PS Output Stencil Ref The StencilRef semantic is present in the output signature of a pixel shader
12 Tiled resources Use of the CheckAccessFullyMapped instruction or, if DXIL validator version >= 1.8, the use of LodClamp in instructions SampleGrad, SampleCmpGrad, Sample, SampleBias, SampleCmp, or SampleCmpBias
13 Typed UAV load additional formats Use of TextureLoad or BufferLoad on a UAV with a multi-component data type. If DXIL validator version == 1.0 then this flag is set when a TextureLoad or BufferLoad is used on any UAV, regardless of its data type
14 Comparison filtering for feature level 9 Not set

@llvm-beanz llvm-beanz Apr 2, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to know the context in which this was valid, but I suspect this was also removed in SM 6.0.

@tex3d tex3d Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This maps a feature flag that is not used for DXIL shaders. We could have gotten away with omitting the flag entirely here originally, but it's here now.

I might say "Not set; Unused legacy feature requirement flag" if you wanted more context here.

15 64 UAV slots The presence of more than 8 UAVs. If DXIL validator version >= 1.6, then UAV ranges count as multiple UAVs
16 UAVs at every shader stage The shader has UAVs and: if DXIL validator version >= 1.8, the shader is a vertex, hull, domain, or geometry shader; else (DXIL validator version < 1.8) the shader is not a compute or pixel shader
17 CS4 raw and structured buffers Use of RawBuffer or StructuedBuffer in a Shader Model 4.x compute shader
18 Raster Ordered UAVs Global presence of a rasterizer ordered view (ROV)
19 Wave level operations Use of any wave or quad intrinsic: WaveIsFirstLane, WaveGetLaneIndex, WaveGetLaneCount, WaveAnyTrue, WaveAllTrue, WaveActiveAllEqual, WaveActiveBallot, WaveReadLaneAt, WaveReadLaneFirst, WaveActiveOp, WaveActiveBit, WavePrefixOp, QuadReadLaneAt, QuadOp, WaveAllBitCount, WavePrefixBitCount, WaveMatch, WaveMultiPrefixOp, WaveMultiPrefixBitCount, QuadVote
20 64-Bit integers Use of i64 data types
21 6.1+ View Instancing Use of the ViewID instruction
22 6.1+ Barycentrics Use of the AttributeAtVertex instruction, or the Barcentrics semantic is present in the shader input signature. If DXIL validator version < 1.6 then this flag must not be set at all
23 6.2+ Enable native low-precision data types Command-line flag ``-enable-16bit-types`` is provided to DXC
24 6.4+ ShadingRate The ShadingRate semantic is present in the shader input or output signature
25 6.5+ Raytracing tier 1.1 features Use of the AllocateRayQuery, AllocateRayQuery2, or GeometryIndex instruction

26 6.5+ Sampler feedback Not set
Comment thread
tex3d marked this conversation as resolved.
Outdated
27 6.6+ 64-bit Atomics on Typed Resources Use of i64 AtomicBinOp or AtomicCompareExchange instructions on a typed resource
28 6.6+ 64-bit Atomics on Group Shared Use of i64 AtomicBinOp or AtomicCompareExchange instructions on group shared memory
29 6.6+ Derivatives in mesh and amplification shaders Use of instructions DerivFineX, DerivFineY, DerivCoarseX, DerivCoarseY, CalculateLOD, Sample, SampleBias, SampleCmp, or SampleCmpBias in a mesh or amplification shader
30 6.6+ Resource descriptor heap indexing Use of the CreateHandleFromHeap instruction on a resource descriptor heap
31 6.6+ Sampler descriptor heap indexing Use of the CreateHandleFromHeap instruction on a sampler descriptor heap
32 6.6+ 64-bit Atomics on Heap Resources Use of i64 AtomicBinOp or AtomicCompareExchange instructions on a descriptor heap resource
33 6.7+ Any UAV may not alias any other UAV If DXIL validator version >= 1.8: use of a UAV in any function. If DXIL validator version < 1.8: global presence of a UAV. This flag is not set if the ``-res-may-alias`` command-line flag is provided to DXC or if DXIL version < 1.7
Comment thread
tex3d marked this conversation as resolved.
Outdated
34 6.7+ Advanced Texture Ops Use of SampleCmpLevel or TextureGatherRaw instructions, or the use of TextureLoad, SampleLevel, SampleCmpLevelZero, Sample Grad, SampleCmpGrad, Sample, SampleBias, SampleCamp, or SampleCmpBias with non-constant offsets
35 6.7+ Writeable MSAA Textures Use of the TextureStoreSample instruction. Or if DXIL validator version < 1.8: the presence of Texture2DMS or Texture2DMSArray resources. Or if DXIL validator version >= 1.8: use of Texture2DMS or Texture2DMSArray resources in CreateHandle, CreateHandleForLib, or AnnotateHandle instructions
36 6.9+ Reserved Unused
37 6.8+ SampleCmp with gradient or bias Use of the instructions SampleCmpGrad or SampleCmpBias
38 6.8+ Extended command info Use of the instructions StartVertexLocation or StartInstanceLocation
=== ==== ======================================================================================== ==========================================================================================================================================================================================================================================================================================================================================================

Geometry Shader
---------------
Expand Down