[SPIR-V] Add SPV_EXT_descriptor_heap + SPV_KHR_untyped_pointers codegen by jzakharovnv · Pull Request #8517 · microsoft/DirectXShaderCompiler

Jonathan Zakharov (jzakharovnv) · 2026-06-04T21:43:25Z

Building off of #8281, this PR adds a native lowering via SPV_EXT_descriptor_heap and SPV_KHR_untyped_pointers and is part 1/3 in a series.

ResourceDescriptorHeap and SamplerDescriptorHeap are lowered to untyped variables decorated with ResourceHeapEXT and SamplerHeapEXT. Each heap access emits OpUntypedAccessChainKHR into a runtime array of the appropriate descriptor type. Buffer-like resources (StructuredBuffer, ByteAddressBuffer, ConstantBuffer, TextureBuffer) use OpTypeBufferEXT and OpBufferPointerEXT; image and sampler resources use OpLoad. Interlocked operations on RWTexture use OpUntypedImageTexelPointerEXT.

Requires -fspv-target-env=vulkan1.3.

Assisted by an AI agent.

Diego Novillo (@dnovillo)

github-actions · 2026-06-04T21:45:20Z

✅ With the latest revision this PR passed the C/C++ code formatter.

Jonathan Zakharov (jzakharovnv) · 2026-06-04T23:02:24Z

@microsoft-github-policy-service agree company="NVIDIA"

Diego Novillo (dnovillo)

Thanks for this! I just started looking at it and have a couple of questions. I'll add more as I read the PRs.

Tobski · 2026-07-07T16:09:15Z

Jonathan Zakharov (@jzakharovnv) I think the OpConstantSizeOfEXT usage in this MR isn't quite right - it looks like you're just taking the stride of the descriptor type being loaded and using that? This works for the sampler heap where there's only one type (samplers), but not for the resource heap.

The stride of all resource descriptors must be the same for all descriptors, and has to be based on the biggest of the buffer/image sizes. This is illustrated in the VK extension doc here: https://docs.vulkan.org/features/latest/features/proposals/VK_EXT_descriptor_heap.html#_shader_model_6_6_samplerheap_and_resourceheap

I might be misunderstanding the code, but I don't see anything for finding the largest of the two sizes? They're both POT, so it is a simple "which is max" calculation, but I don't see it being done in this PR.

Jonathan Zakharov (jzakharovnv) · 2026-07-07T17:43:11Z

Tobski You are right, this is my blunder. Will fix shortly.

Jonathan Zakharov (jzakharovnv) · 2026-07-10T22:35:26Z

Tobski Shared max(image,buffer) stride for descriptor heap resource arrays ought to be closer to the original intent. Please take a look when you can. Thanks!

Tobski · 2026-07-13T11:15:43Z

Tobski Shared max(image,buffer) stride for descriptor heap resource arrays ought to be closer to the original intent. Please take a look when you can. Thanks!

Looks right to me now! Thanks!

Diego Novillo (dnovillo)

A question on changes that have gone in #8519 that we may to reflect here. Not sure how you want to handle it.

Jonathan Zakharov (jzakharovnv) · 2026-07-20T21:48:54Z

Diego Novillo (@dnovillo) In response to your last comment on this PR, yes I think it's more correct to have the TODO commit a part of this initial branch rather than one down the line. Cherrypicked and rebased to reflect this.

Diego Novillo (dnovillo)

Just one minor change and it's good to from my side.

Diego Novillo (dnovillo)

LGTM. Just one final nit. Thanks for doing this!

Damyan Pepper (damyanp) · 2026-07-30T16:48:15Z

[Auto-generated note from Damyan Pepper (@damyanp)]

This looks like a user-visible bug fix/feature change. Please add (or point to) the corresponding entry in docs/ReleaseNotes.md.

If release-note coverage is planned in a related PR (including one that hasn’t been submitted yet), please mention that plan/link so we can avoid duplicate notes.

Copilot

Pull request overview

Adds native SPIR-V descriptor-heap lowering using SPV_EXT_descriptor_heap and SPV_KHR_untyped_pointers.

Changes:

Implements native image, sampler, and buffer descriptor access.
Adds descriptor-size-based runtime-array strides and image atomic support.
Expands tests and documents Vulkan 1.3 requirements and limitations.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`tools/clang/unittests/SPIRV/SpirvContextTest.cpp`	Tests runtime-array type uniqueness.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.typed-formats.hlsl`	Tests typed image formats.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.texturecube.hlsl`	Tests cube textures and samplers.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.texture.hlsl`	Tests texel buffers.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.texture-sampler-assignment.hlsl`	Tests resource reassignment.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.texture-ms.hlsl`	Tests multisampled textures.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.texture-dims.hlsl`	Tests sampled texture dimensions.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.structured-buffer-atomic.hlsl`	Tests structured-buffer atomics.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.static-global.hlsl`	Tests static global resources.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.sampler-comparison.hlsl`	Tests comparison samplers.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.sample-grad-bias.hlsl`	Tests sampling operands.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.rwtexture-dims.hlsl`	Tests RW texture dimensions.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.rwtexture-atomics.hlsl`	Tests untyped image atomics.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.rwbyteaddressbuffer.hlsl`	Tests writable byte buffers.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.nonuniform.hlsl`	Tests divergent heap indexing.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.mixed-bound.hlsl`	Tests bound/native resource coexistence.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.mixed-alias.error.hlsl`	Tests mixed-alias diagnostics.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.load-offset.hlsl`	Tests texture load offsets.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.groupshared.hlsl`	Tests groupshared coexistence.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.gather.hlsl`	Tests gather operations.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.function-params.hlsl`	Tests resource function parameters.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.discarded.error.hlsl`	Tests discarded-index diagnostics.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.counter-ops.error.hlsl`	Tests unsupported counter diagnostics.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.constant-texture-buffer.hlsl`	Tests constant and texture buffers.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.constant-buffer-assignment.hlsl`	Tests constant-buffer reassignment.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.buffer.hlsl`	Tests native buffer lowering.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.array-stride.hlsl`	Tests descriptor-array strides.
`tools/clang/test/CodeGenSPIRV/sm6_6.descriptorheap.ext.append-consume.error.hlsl`	Tests append/consume diagnostics.
`tools/clang/test/CodeGenSPIRV/resource-heap-ext-texture.hlsl`	Removes superseded coverage.
`tools/clang/lib/SPIRV/SpirvType.cpp`	Extends runtime-array equality.
`tools/clang/lib/SPIRV/SpirvInstruction.cpp`	Implements new SPIR-V instructions.
`tools/clang/lib/SPIRV/SpirvEmitter.h`	Declares heap lowering and alias state.
`tools/clang/lib/SPIRV/SpirvEmitter.cpp`	Implements native heap code generation.
`tools/clang/lib/SPIRV/SpirvContext.cpp`	Uniques buffer and stride-ID types.
`tools/clang/lib/SPIRV/SpirvBuilder.cpp`	Builds descriptor sizes and strides.
`tools/clang/lib/SPIRV/LowerTypeVisitor.cpp`	Lowers untyped image pointers.
`tools/clang/lib/SPIRV/EmitVisitor.h`	Declares new emission handlers.
`tools/clang/lib/SPIRV/EmitVisitor.cpp`	Serializes new instructions and decorations.
`tools/clang/lib/SPIRV/DeclResultIdMapper.h`	Declares function alias registration.
`tools/clang/lib/SPIRV/DeclResultIdMapper.cpp`	Implements alias registration.
`tools/clang/lib/SPIRV/CapabilityVisitor.cpp`	Requires Vulkan 1.3 and extensions.
`tools/clang/include/clang/SPIRV/SpirvVisitor.h`	Adds visitor hooks.
`tools/clang/include/clang/SPIRV/SpirvType.h`	Adds stride-ID runtime arrays.
`tools/clang/include/clang/SPIRV/SpirvInstruction.h`	Defines new instruction classes.
`tools/clang/include/clang/SPIRV/SpirvContext.h`	Adds type caches and APIs.
`tools/clang/include/clang/SPIRV/SpirvBuilder.h`	Exposes descriptor-stride builders.
`docs/SPIR-V.rst`	Documents native descriptor heaps.

Fixes #8603: MergeBinaryOpSelect produced an OpSelect with a vector result type and a scalar condition, which is only legal in SPIR-V 1.4+ (KhronosGroup/SPIRV-Tools#6827). This exposes #8740 where the resource-heap-ext-texture.hlsl test fails validation - for now this is worked around by disabling the test, since #8517 looks like it is reworking it anyway. Assisted-by: copilot --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: b04b21af-2d8b-4af5-b9ad-1b84073588f5

Copilot

Copilot review overview

🟡 Changes recommended

Heap stride computation and alias-boundary detection leave supported shader patterns capable of producing invalid SPIR-V.

Review effort: Balanced
Findings: 1

Open (1)

Track global and static RWTexture heap aliases · New

Resolved since last review (1)

Detect heap-source boundary loss before lowering shared callees

Copilot

Copilot review overview

🟡 Changes recommended

Acceleration-structure stride handling and cross-function heap-image detection have correctness gaps.

Review effort: Balanced
Findings: 1

Open (1)

Forwarded heap-image parameters bypass heap-source detection · New

Resolved since last review (1)

Track global and static RWTexture heap aliases

Copilot

Copilot review overview

🔵 Needs a closer look

Descriptor stride and alias-provenance gaps can produce incorrect lowering or invalid SPIR-V for supported HLSL patterns.

Review effort: Balanced
Findings: 1

Open (1)

Forwarded heap-image parameters bypass heap-source detection

Previously missed (3)

In code that hasn't changed since last review

Track heap-sourced images returned from function calls

tools/clang/lib/SPIRV/SpirvEmitter.cpp:5307

isHeapSourcedValue does not recognize a call that returns a heap-sourced image. Consequently, RWTexture2D x = makeHeapImage(); records x as Bound, and a later x = ResourceDescriptorHeap[i] is rejected as bound/heap mixing even though both sources are heap-backed. Function-returned image handles are explicitly supported for ordinary reads/writes, so this rejects an otherwise supported reassignment; classify heap-returning calls (and their forwarded locals) separately from genuinely bound resources here.

Preserve heap provenance through conditional image selection

tools/clang/lib/SPIRV/SpirvEmitter.cpp:8598

Valid HLSL heap provenance is not limited to a direct subscript or DeclRefExpr; conditional selection is commonly used (for example, RWTexture2D t = cond ? ResourceDescriptorHeap[a] : ResourceDescriptorHeap[b]). This returns false for that expression, so buffer resources fall back to storing OpBufferPointerEXT values through an ordinary function variable, while an image atomic later has no descriptor index and falls back to invalid OpImageTexelPointer. Track/merge both heap indices through conditionals, or diagnose this form before lowering it.

Scan nested declaration contexts for heap image callers

tools/clang/lib/SPIRV/SpirvEmitter.cpp:8715

This caller search skips function bodies nested in record/namespace declaration contexts. HLSL supports member functions, so a member can load an RWTexture from ResourceDescriptorHeap and pass it to a free function whose parameter is used by an interlocked operation; that call site is never found here, and the callee falls back to the invalid OpImageTexelPointer path this check is intended to prevent. Traverse nested declaration contexts (or a TU-wide call graph) so every user-function body is scanned.

Copilot

Copilot review overview

🟡 Changes recommended

Acceleration-structure stride handling and nested call-site analysis can produce invalid descriptor accesses.

Review effort: Balanced
Findings: 1

Open (1)

Recursively scan nested methods and declarations for heap call sites · New

Resolved since last review (1)

Forwarded heap-image parameters bypass heap-source detection

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Chris B (llvm-beanz) · 2026-10-07T23:19:24Z

/azp run

azure-pipelines · 2026-10-07T23:19:36Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Chris B (llvm-beanz)

LGTM

Jonathan Zakharov (jzakharovnv) · 2026-10-07T23:23:47Z

So, a recap of recent work:

I spent some time just iterating on Copilot's review comments and think I was able to fix most of the critical bugs it found. After a while it seemed like it was finding less significant issues and more so just requesting diagnostics for descriptor heap use cases that DXIL backend generically rejects, but would otherwise get silently compiled by SPIR-V backend- just to get rejected by spirv-val.

I think implementing a bunch of diagnostics for cases people will likely never see is less productive than going and fixing the issue at its source, but that is what I have actually done.

I have a local branch that just about gets SPIRV native descriptor heaps 1-1 with DXIL backend functionally (hopefully means less future work), but it feels morally wrong to make that apart of this branch since it is a decently large change and I've learned from my mistake of making monolithic PRs.

Thus, I'm in favor of leaving Copilot's diagnostic requests and functional gap complaints unfulfilled on this PR so we can aim to proceed with merging this branch, then layering many small PRs to follow.

I know the big dogs are at KH F2F this week, so I'll do a self-review pass again this week, but that's what I got

Jonathan Zakharov (jzakharovnv) · 2026-10-13T18:00:33Z

Chris B (@llvm-beanz) Gregory Roth (@pow2clk) Is there anything left that I can do before we merge? Thanks!

@dnovillo

…8518) Building off of #8517, this PR extends the SPV_EXT_descriptor_heap native heap lowering to cover RaytracingAccelerationStructure resources loaded from ResourceDescriptorHeap. It is part 2/4 in a series. Acceleration structure descriptors are accessed via OpUntypedAccessChainKHR into a runtime array of OpTypeAccelerationStructureKHR, consistent with the image and sampler paths added in the previous commit. Assisted by an AI agent @dnovillo

github-project-automation Bot added this to HLSL Roadmap Jun 4, 2026

github-project-automation Bot moved this to New in HLSL Roadmap Jun 4, 2026

Jonathan Zakharov (jzakharovnv) mentioned this pull request Jun 4, 2026

[SPIR-V] Add descriptor heap RaytracingAccelerationStructure support #8518

Merged

Jonathan Zakharov (jzakharovnv) force-pushed the pr1-descriptor-heap-core branch 2 times, most recently from f640327 to cbcae38 Compare June 4, 2026 22:42

Diego Novillo (dnovillo) suggested changes Jun 8, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

github-project-automation Bot moved this from New to In progress in HLSL Roadmap Jun 8, 2026

Chris B (llvm-beanz) reviewed Jun 23, 2026

View reviewed changes

Jonathan Zakharov (jzakharovnv) mentioned this pull request Jun 26, 2026

[SPIR-V] Add descriptor heap stride specialization constant attribute #8520

Closed

Diego Novillo (dnovillo) suggested changes Jul 17, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Diego Novillo (dnovillo) added the spirv Work related to SPIR-V label Jul 17, 2026

Jonathan Zakharov (jzakharovnv) force-pushed the pr1-descriptor-heap-core branch from bd79339 to cbcae38 Compare July 17, 2026 20:35

Diego Novillo (dnovillo) suggested changes Jul 21, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Diego Novillo (dnovillo) approved these changes Jul 24, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Jonathan Zakharov (jzakharovnv) force-pushed the pr1-descriptor-heap-core branch from d0835c8 to 88bd33c Compare July 28, 2026 21:00

Copilot AI balanced review requested due to automatic review settings August 4, 2026 00:41

Copilot started reviewing on behalf of Jonathan Zakharov (jzakharovnv) August 4, 2026 00:41

View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

Jonathan Zakharov (jzakharovnv) mentioned this pull request Aug 4, 2026

[SPIR-V] SPV_EXT_descriptor_heap mixed bound/heap aliasing causes silent miscompilation or ICE #8732

Open

This was referenced Aug 6, 2026

Update SPIRV-Tools to 1c336172 #8738

Merged

[SPIR-V] DXC SPIR-V test fail with the latest spir-v tools #8740

Open

fix param heap boundry loss detection order dependence

ab9f2fd

Copilot AI balanced review requested due to automatic review settings September 29, 2026 18:40

Copilot started reviewing on behalf of Jonathan Zakharov (jzakharovnv) September 29, 2026 18:40

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

diagnose interlocked ops on globals and static locals

3061e45

Copilot AI balanced review requested due to automatic review settings September 29, 2026 20:12

Copilot started reviewing on behalf of Jonathan Zakharov (jzakharovnv) September 29, 2026 20:12

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Chris B (llvm-beanz) reviewed Sep 29, 2026

View reviewed changes

drop implementation details from API documentation

5261c0b

Copilot AI balanced review requested due to automatic review settings September 29, 2026 21:55

Copilot started reviewing on behalf of Jonathan Zakharov (jzakharovnv) September 29, 2026 21:56

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

fix heap image detection for chained func params

fc9380c

Copilot AI balanced review requested due to automatic review settings September 29, 2026 23:11

Copilot started reviewing on behalf of Jonathan Zakharov (jzakharovnv) September 29, 2026 23:12

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread tools/clang/lib/SPIRV/SpirvEmitter.cpp Resolved

Jonathan Zakharov (jzakharovnv) added 2 commits October 5, 2026 13:01

fix some autos

96cdb4e

clean up comments

bef4d20

Copilot AI balanced review requested due to automatic review settings October 5, 2026 20:01

Copilot AI reviewed Oct 5, 2026

Chris B (llvm-beanz) approved these changes Oct 7, 2026

View reviewed changes

Jonathan Zakharov (jzakharovnv) mentioned this pull request Oct 8, 2026

[SPIR-V] SPV_EXT_descriptor_heap crashes, or miscompiles shaders that work in emulated mode (images, buffers, ConstantBuffer, counters) #9019

Open

Gregory Roth (pow2clk) merged commit a2b66fb into microsoft:main Oct 15, 2026
12 of 13 checks passed

github-project-automation Bot moved this from In progress to Done in HLSL Roadmap Oct 15, 2026

Conversation

Jonathan Zakharov (jzakharovnv) commented Jun 4, 2026 • edited by pow2clk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jonathan Zakharov (jzakharovnv) commented Jun 4, 2026

Uh oh!

Diego Novillo (dnovillo) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Tobski commented Jul 7, 2026

Uh oh!

Jonathan Zakharov (jzakharovnv) commented Jul 7, 2026

Uh oh!

Jonathan Zakharov (jzakharovnv) commented Jul 10, 2026

Uh oh!

Tobski commented Jul 13, 2026

Uh oh!

Diego Novillo (dnovillo) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jonathan Zakharov (jzakharovnv) commented Jul 20, 2026

Uh oh!

Diego Novillo (dnovillo) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Diego Novillo (dnovillo) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Damyan Pepper (damyanp) commented Jul 30, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Jonathan Zakharov (jzakharovnv) commented Jun 4, 2026 •

edited by pow2clk

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading