Add opt-in unified ArrayStride for SPIR-V resource descriptor heaps

[nv-slang-bot]

Motivation

Fixes #11718.

VK_EXT_descriptor_heap / spvDescriptorHeapEXT packs every resource descriptor
(images and buffers) into one runtime array — the "resource heap" — and a separate
array for samplers. The host allocator stores each heap slot at a fixed stride:
for the resource heap, the spec (§"Shader Model 6.6 - SamplerHeap and ResourceHeap")
defines that stride as the canonical maximum

max(sizeof(image descriptor), sizeof(buffer descriptor))

so that index * stride lands on the same byte offset regardless of which descriptor
category a given access happens to read.

Slang previously emitted a per-type ArrayStrideIdEXT derived only from the descriptor
types a single shader referenced. That is wrong for a shared heap: an image-only
shader and a buffer-only shader, indexing the same host-packed heap, would advertise
two different strides and mis-index each other's descriptors. The motivating case:

[shader("compute")][numthreads(1,1,1)]
void computeMain(
    DescriptorHandle<Texture2D<float4>>        tex,
    DescriptorHandle<ConstantBuffer<MyStruct>> cbuffer,
    RWStructuredBuffer<uint>                   output)
{
    float4 texel = tex.Load(int3(0, 0, 0));
    output[0] = (uint)texel.x + (*cbuffer).value;
}

Compiled with -spirv-unified-descriptor-heap-stride, both resource arrays here — and a
buffer-only shader sharing the heap — must advertise the identical image-vs-buffer max.

Proposed solution

Add an opt-in option, -spirv-unified-descriptor-heap-stride, that decorates every
image/buffer resource descriptor-heap runtime array with one shared, fixed ArrayStrideIdEXT:
the canonical max(sizeof(image descriptor), sizeof(buffer descriptor)). (Acceleration-structure
heap entries are unaffected — they keep their existing literal uint64 stride.)

The stride is not adaptive to the shader's contents. Because the host heap layout is
independent of any one shader, the emitted stride is always the full image-vs-buffer max —
even for a shader that touches only a buffer. A buffer-only shader still emits the
placeholder image descriptor type and the full Select chain, so two shaders over the same
heap can never disagree.

OpConstantSizeOfEXT is device-defined (the descriptor size is decided by the driver,
not the compiler), so the maximum cannot be a compile-time literal. It is expressed
symbolically as max(a, b) = Select(UGreaterThan(a, b), a, b) using OpSpecConstantOp,
whose result is a constant <id> — a requirement for ArrayStrideIdEXT.
(OpExtInst GLSL.std.450 UMax will not do: its result is not a constant <id>.)

The unified stride is built lazily and memoized the first time a resource array needs it
(getUnifiedResourceHeapStride()), so the constant <id> is emitted before the first
array type — ArrayStrideIdEXT requires the stride <id> to precede the array it decorates.
There is no separate finalize pass and no array reordering.

Samplers are out of scope. The spec uses two heaps — samplers are never co-located with
resources — so the unified resource-heap stride folds only image-vs-buffer. Sampler arrays
(OpTypeSampler element type) are excluded from the fold and keep their existing
-spirv-sampler-heap-stride behavior.

Mutual exclusivity. A non-zero -spirv-resource-heap-stride and the unified maximum
stride are mutually exclusive — the explicit literal and the device-defined max are different
contracts for the same array, so combining them is a hard error (E57006,
SpirvConflictingDescriptorHeapStrideOptions), not a silent "one wins." An explicit
-spirv-resource-heap-stride 0 selects the same default OpConstantSizeOfEXT path the unified
option modifies and is therefore accepted (not a conflict).

Placeholder image descriptor type — deviation from the proposal

The issue's literal proposal sketches the placeholder image descriptor as
OpTypeImage %void 2D 2 0 0 0 Unknown. That is invalid SPIR-V for Vulkan:

• VUID-StandaloneSpirv-OpTypeImage-04656 — the sampled type must be a 32-bit int,
  64-bit int, or 32-bit float scalar; %void is rejected.
• VUID-StandaloneSpirv-OpTypeImage-04657 — Sampled must be 1 or 2, never 0.

A descriptor's device-defined size is its heap-slot footprint and is independent of the
image's sampled type and Sampled flag, so we use a spec-valid placeholder
OpTypeImage %float 2D 2 0 0 1 Unknown (sampled type float, Sampled = 1; depth operand
stays Unknown = 2). Both entry points of the regression test then pass static SPIR-V
validation (see below). cc @csyonghe — flagging the placeholder deviation explicitly.

Change summary

File	Change
include/slang.h	Append SPIRVUnifiedDescriptorHeapStride = 153 before the CountOf sentinel (additive, ABI-safe); doc notes mutual exclusivity with a non-zero -spirv-resource-heap-stride.
source/slang/slang-options.cpp	Register the boolean CLI option -spirv-unified-descriptor-heap-stride and add its case to the boolean-option parse switch.
source/slang/slang-emit-spirv.cpp	getUnifiedResourceHeapStride() lazily emits the fixed image-vs-buffer Select max (memoized). getDescriptorRuntimeArrayType() decorates resource arrays with that shared ArrayStrideIdEXT when the option is on; sampler arrays are excluded. diagnoseConflictingDescriptorHeapStrideOptions() raises E57006 when the unified option and a non-zero -spirv-resource-heap-stride are both set.
source/slang/slang-diagnostics.lua	Define SpirvConflictingDescriptorHeapStrideOptions (E57006).
tests/spirv/descriptor-heap-unified-stride.slang	Four variants: UNIFIED (shared max, two arrays one stride id), DEFAULT (control — per-type size-of, no Select), CONFLICT (diagnostic — unified option + a non-zero -spirv-resource-heap-stride → E57006), SINGLE (buffer-only shader still emits the full image-vs-buffer max, proving non-adaptivity).

Concepts and vocabulary

• Resource heap vs sampler heap — spvDescriptorHeapEXT uses two separate runtime
  arrays. The unified stride applies only to the resource heap (images + buffers).
• ArrayStrideIdEXT — decorates a runtime array with a constant <id> byte stride; that
  <id> must be defined before the array type in the module.
• OpConstantSizeOfEXT — a device-defined (opaque, driver-decided) constant giving a
  descriptor type's heap-slot size. Not a compile-time literal.
• Fixed / non-adaptive stride — the emitted stride depends only on the spec's canonical
  image-vs-buffer max, never on which descriptor types the shader happens to reference.

Process report

• include/slang.h — new options need a CompilerOptionName enumerator. Appended
  SPIRVUnifiedDescriptorHeapStride = 153 immediately before CountOf with an explicit
  value (never mid-enum), so existing ABI offsets are unchanged. pr: non-breaking.

• source/slang/slang-options.cpp — the option is a pure boolean (presence = on), so it
  is registered with a nullptr value-spec and routed through the existing boolean-option
  parse case alongside TraceCoverageBoolean / SkipSPIRVValidation. No new parsing
  machinery.

• source/slang/slang-emit-spirv.cpp —

  • getUnifiedResourceHeapStride() builds, in ConstantsAndTypes, the placeholder image
    descriptor type (OpTypeImage %float 2D 2 0 0 1 Unknown), the buffer descriptor type
    (ensureDescriptorHeapBufferDescriptorType(SpvStorageClassUniform)), their two
    OpConstantSizeOfEXT, OpSpecConstantOp OpUGreaterThan, and OpSpecConstantOp OpSelect.
    It is memoized on m_unifiedResourceHeapStride and emitted lazily so the stride <id>
    precedes the first decorated array (the ArrayStrideIdEXT ordering rule).
  • getDescriptorRuntimeArrayType() gates the fold on
    arrayStride == 0 && isResourceElement && isUnifiedResourceHeapStrideEnabled(), where
    isResourceElement = descriptorElementType->opcode != SpvOpTypeSampler. When folding, it
    skips the per-type OpConstantSizeOfEXT and decorates with the shared
    emitOpDecorateArrayStrideIdEXT; otherwise it keeps the prior per-type / literal path.
    Input-shape check: the per-array descriptor element type is the correct, principled
    input — the fold is a property of the heap, not of a malformed type, so it lives at
    the array-construction site rather than masking anything upstream.
  • diagnoseConflictingDescriptorHeapStrideOptions() is called once in emitSPIRVFromIR
    (after the forward-declared-pointers loop) and raises E57006 when the unified option
    and a non-zero -spirv-resource-heap-stride are both set. It fires on the CLI
    combination even when the module declares no resource heap (the user supplied
    contradictory intent), and emits no instructions.

• source/slang/slang-diagnostics.lua — SpirvConflictingDescriptorHeapStrideOptions
  (E57006) is a location-less hard error: "an explicit resource heap stride and the unified
  maximum stride are mutually exclusive." It is only emitted when -spirv-resource-heap-stride
  is non-zero (an explicit 0 is the default path and is accepted), so the "explicit resource
  heap stride" it names is always a non-zero one.

• tests/spirv/descriptor-heap-unified-stride.slang — the SINGLE variant is the key
  guardrail: a buffer-only shader compiled with the flag still emits the placeholder
  OpTypeImage and the full Select chain, demonstrating the stride is fixed, not adaptive.

Validation

Built slang-test (Debug); descriptor-heap-unified-stride.slang passes all 4 static variants
(UNIFIED, DEFAULT, CONFLICT, SINGLE).

Static SPIR-V validation of both unified-stride entry points, under
SLANG_RUN_SPIRV_VALIDATION=1, exits 0:

$ SLANG_RUN_SPIRV_VALIDATION=1 slangc tests/spirv/descriptor-heap-unified-stride.slang \
      -target spirv -capability spvDescriptorHeapEXT -spirv-unified-descriptor-heap-stride \
      -entry computeMain   -stage compute -o main.spv      # EXIT=0
$ SLANG_RUN_SPIRV_VALIDATION=1 slangc tests/spirv/descriptor-heap-unified-stride.slang \
      -target spirv -capability spvDescriptorHeapEXT -spirv-unified-descriptor-heap-stride \
      -entry computeSingle -stage compute -o single.spv    # EXIT=0

Caveat: static spirv-val confirms the module is well-formed, but the device driver is the
final arbiter of the device-defined descriptor sizes and the resulting stride — this opt-in path
has not been exercised end-to-end on hardware. The runtime stack (slang-rhi) does not yet support
VK_EXT_descriptor_heap, so a runtime COMPARE_COMPUTE is not meaningful for this path today.
The two-heap assumption was confirmed by @chaoticbob on this PR.

_{🤖 Generated by an automated Slang coworker — may be inaccurate. A human maintainer should verify.}

[jkwak-work]

@nv-slang-bot , Fix the format workflow problem.

[nv-slang-bot]

Thanks for the review @jkwak-work — addressed in c2dc734:

• getUnifiedResourceHeapStride comment too verbose / error cases (r3469658009): trimmed to the what/why and dropped the spirv-val VUID and %void→%float detail; that rationale now lives only in the PR description (flagged there for @csyonghe).
• Conflict-diagnose comment too verbose (r3469632834): cut to three lines.
• Redundant call-site comment (r3469637449): removed — the function's own comment covers it.
• Runtime COMPARE_COMPUTE test (r3469644313): added tests/spirv/descriptor-heap-unified-stride-runtime.slang, a -vk bindless COMPARE_COMPUTE. It's a separate file because COMPARE_COMPUTE(compute) runs the entry named computeMain by convention, and in the static-stride file computeMain is the texture+cbuffer entry. The spvDescriptorHeapEXT unified-stride path itself needs VK_EXT_descriptor_heap driver support, so it stays statically verified; this runtime test exercises the descriptor-handle path through the bindless render feature.
• Format workflow: the shorter comments resolve the Check Formatting failure (verified locally; CI is re-running on the new commit).

_{🤖 Generated by an automated Slang coworker — may be inaccurate. A human maintainer should verify.}

[jkwak-work]

It looks good to me.
And I think the code properly addressed what Yong concerned about.

[jkwak-work]

@nv-slang-bot , don't we need to update the documents for the new option?

[nv-slang-bot]

@jkwak-work Done — documented -spirv-unified-descriptor-heap-stride across all three user-facing surfaces (commit 14f5d62):

• docs/user-guide/03-convenience-features.md — prose in the spvDescriptorHeapEXT section (shared image-vs-buffer-max stride, default-OpConstantSizeOfEXT-path-only scope, sampler heap + acceleration-structure entries unaffected).
• docs/user-guide/08-compiling.md — a SPIRVUnifiedDescriptorHeapStride row in the compilation-API options table.
• docs/command-line-slangc-reference.md — regenerated via slangc -help-style markdown -h, adding the option's block.

While writing the docs I also tightened the conflict wording everywhere (option help text, slang.h doc, both internal comments, and the test comment): the conflict is specifically with a non-zero -spirv-resource-heap-stride — diagnoseConflictingDescriptorHeapStrideOptions() gates on SPIRVResourceHeapStride != 0, so an explicit -spirv-resource-heap-stride 0 selects the same default path the unified option modifies and is accepted. CI re-dispatched on the latest commit.

_{🤖 Generated by an automated Slang coworker — may be inaccurate. A human maintainer should verify.}

[nv-slang-bot]

Rebased onto current master and renumbered to clear a merge-time enum collision.

This PR's head CI was green on its own, but it was evicted from the merge queue by a duplicate case value build break that only appears in the merge group: the concurrently-queued #11556 (getDownstreamCompilerVersion) appends CompilerOptionName::CompilerVersion = 153, and this PR independently took the next free value 153 for SPIRVUnifiedDescriptorHeapStride — so the two OptionKind switch cases collide once batched together.

Fix: yield 153 to #11556 and append SPIRVUnifiedDescriptorHeapStride at 154 instead. Append-only, so no existing enumerator value shifts (ABI-safe); the two now hold distinct values in any merge order. Rebased onto master @ 838d6b40e1; slangc builds clean locally with no duplicate case value.

_{🤖 Generated by an automated Slang coworker — may be inaccurate. A human maintainer should verify.}

[nv-slang-bot]

@jkwak-work — courtesy heads-up: the force-push for the rebase auto-dismissed your prior approval, so this PR is back at REVIEW_REQUIRED and can't re-enter the merge queue without a fresh approval.

The only change since you approved is the verified SPIRVUnifiedDescriptorHeapStride 153 → 154 deconfliction (append-only, so no existing enumerator value shifts — ABI-safe), which resolves the merge-time duplicate case value collision with #11556's CompilerOptionName::CompilerVersion = 153. Head CI is green — no duplicate case value. Re-approval would let it re-enter the queue whenever convenient; no rush.

_{🤖 Generated by an automated Slang coworker — may be inaccurate. A human maintainer should verify.}

[jkwak-work]

Looks good to me