WGSL: emit runtime-indexable static const arrays as var<private> (#11628)

## Motivation

When targeting WGSL, a module-scope `static const` array is emitted as a
WGSL `const`. But a WGSL `const` is a compile-time value (closer to C++
`constexpr` than to `const`): the WGSL spec permits a *value* of array
type to be indexed only by a const-expression. So indexing such a global
by a runtime value is rejected by the WGSL validator.

Motivating case (from the issue):

```hlsl
static const float2 positions[] = {
    float2(-1.0f, -1.0f), float2(1.0f, -1.0f), float2(1.0f, 1.0f), float2(-1.0f, 1.0f)
};

[shader("vertex")]
VertexOutput vertexMain(uint vertexID : SV_VertexID)
{
    VertexOutput o;
    o.position = float4(positions[vertexID], 0.0f, 1.0f);  // runtime index
    return o;
}
```

emits `const positions_0 : array<vec2<f32>, i32(4)> = ...;` then
`positions_0[vertexID_0]`, which naga/tint reject: *"The expression may
only be indexed by a constant."*

## Proposed solution

Emit module-scope `static const` globals of **array** type as WGSL
`var<private>` (a private module-scope variable), keeping their inline
const-expression initializer, instead of `const`. A `var<private>` holds
the same value but is addressable, so it is runtime-indexable. After the
fix the array emits `var<private> positions_0 : array<vec2<f32>, i32(4)>
= array<vec2<f32>, i32(4)>( ... );` and `positions_0[vertexID_0]` is
valid.

Only arrays are converted. A WGSL matrix *value* is itself
runtime-indexable, so a `const` matrix needs no conversion;
scalars/vectors stay `const` (a vector value is also dynamically
indexable), and function-local constants are unaffected.

Nested aggregates need one more step. A nested `static const` (e.g. `int
grid[2][3]`) lowers to nested `MakeArray` insts, each a module-scope
array constant emitted as a *separate named* declaration. Converting all
of them to `var<private>` would make the outer initializer reference
inner `var<private>`s — illegal WGSL (a `var<private>` initializer must
be a const-expression and cannot read another `var`). The fix folds the
inner constituents inline so the outermost runtime-indexed array becomes
a single `var<private>` with a self-contained initializer:

```wgsl
var<private> grid_0 : array<array<i32, i32(3)>, i32(2)> = array<array<i32, i32(3)>, i32(2)>( array<i32, i32(3)>( i32(1), i32(2), i32(3) ), array<i32, i32(3)>( i32(4), i32(5), i32(6) ) );
```

Alternatives ruled out: a `static`-only (non-`const`) global lowers its
initializer into an init function, producing the broken `const _S3 =
...;` statements seen in the issue thread; keeping the initializer
inline avoids that. A precise "is this global ever dynamically indexed"
use-analysis is unnecessary — constant-indexed reads are already
constant-folded before emit (see Process report).

## Change summary

| File | Change |
| --- | --- |
| `source/slang/slang-emit-wgsl.cpp` | `emitVarKeywordImpl`: a
module-scope **array** constant emits `var` + `<private>` instead of
`const`. `shouldFoldInstIntoUseSites`: for WGSL, fold a module-scope
`MakeArray`/`MakeStruct`/`MakeArrayFromElement` inline when it is only a
nested constituent of another aggregate, so the outermost array's
initializer stays self-contained. |
| `tests/wgsl/static-const-array-indexing.slang` | Runtime-indexed array
→ `var<private>`; `+ wgsl-spirv-asm` (Tint) validation directive. |
| `tests/wgsl/static-const-array-nested.slang` | New: nested 2D-array
regression — one inline `var<private>`, no separate inner-array decls;
`+ wgsl-spirv-asm` directive. |
| `tests/wgsl/static-const-matrix.slang` | New: a runtime-indexed
`static const` matrix stays an inline `const` value (not
`var<private>`); `+ wgsl-spirv-asm` directive validates it through Tint
on CI. |
| `tests/wgsl/static-const-array-const-index.slang` | A constant-indexed
element folds away and leaves no `const`/`var` reading another variable;
tightened anchors + negative guard. |
| `docs/user-guide/a2-03-wgsl-target-specific.md` | Document the
module-scope `const` (scalar/vector/matrix) vs `var<private>` (array)
split. |

## Concepts and vocabulary

- **WGSL `const` vs `var<private>`** — a WGSL `const` is a compile-time
value; a `const` value of array type may only be indexed by a
const-expression. A `var<private>` is an addressable module-scope
variable, indexable by a runtime value, whose initializer must still be
a const-expression.
- **`GlobalConstant` / `MakeArray`** — a `static const` array lowers to
an `IRGlobalConstant` wrapping an `IRMakeArray`; nested arrays nest
`MakeArray`s.
- **`replaceGlobalConstants` / peephole fold** —
`replaceGlobalConstants` inlines a global constant's value into its
uses; the peephole pass folds `GetElement(MakeArray, constIndex)` to the
element, leaving a runtime index intact.
- **`shouldFoldInstIntoUseSites`** — decides whether an inst is emitted
inline at its use or as its own declaration. WGSL can fold
`MakeArray`/`MakeStruct` (constructor expressions, valid in any
expression context) where the base class cannot (C/HLSL initializer
lists).

## Process report

**`emitVarKeywordImpl` (`source/slang/slang-emit-wgsl.cpp`).** The
declared inst for a module-scope `static const` array is an ordinary
module-scope instruction; `emitInstResultDecl` (`slang-emit-c-like.cpp`)
emits `<keyword> <name> : <type> = <initializer>`, with the keyword from
`emitVarKeywordImpl`. Previously the `default:` arm emitted `const` for
any module-scope constant. The predicate
`emitModuleScopeArrayConstAsPrivateVar` reuses the existing
`isStaticConst` helper and is true when the inst is a module-scope
constant (`isStaticConst(varDecl)`), is not a `GlobalParam`, and has
type `kIROp_ArrayType`; it then emits `var` and `<private>` (joining the
existing `kIROp_GlobalVar` storage-space branch, after the
array-of-ConstantBuffer/structured-buffer branches, so resource arrays
are unaffected). The `!= kIROp_GlobalParam` guard is load-bearing: the
predicate is also read in the address-space chain (which runs for all
ops), where a module-scope `GlobalParam` array — e.g. a descriptor array
like `Texture2D t[8]`, whose element type isn't
ConstantBuffer/structured so it falls through to the final branch —
would otherwise wrongly get `<private>` instead of its handle address
space. (`isStaticConst` is true for any module child, including
`GlobalParam`/`GlobalVar`, so the guard is required; a local `Var` is
not module-scope and is already excluded.)

**Why a type-based conversion is safe (no const-expression chain
breaks).** A constant index into a static-const array is constant-folded
before emit, so no `const` is left whose initializer reads the converted
`var`: `replaceGlobalConstants` inlines `GlobalConstant` values into
uses before `simplifyIR`, then the peephole `kIROp_GetElement` case
folds `GetElement(MakeArray, IRIntLit)` to the element while a
non-constant (runtime) index hits `if (!index) break;` and is left
intact. `tests/wgsl/static-const-array-const-index.slang` guards this.

**Nested aggregates — `shouldFoldInstIntoUseSites`.** The base class
never-folds `MakeArray`/`MakeStruct`/`MakeArrayFromElement` because in
C/HLSL they lower to initializer lists, invalid in a general expression
context. WGSL instead emits them as constructor expressions
(`type(args...)`, `tryEmitInstExprImpl`), valid anywhere. So a nested
`static const` otherwise emits each inner `MakeArray` as a separate
named module-scope decl, and converting them all to `var<private>`
yields an outer initializer that references inner `var<private>`s —
illegal. The override folds a module-scope constituent inline when every
use of it is an operand of another
`MakeArray`/`MakeStruct`/`MakeArrayFromElement` (checked by a small
inlined loop), so the outermost aggregate — used directly, e.g. by a
runtime `GetElement` — stays a declaration eligible for `var<private>`
while its constituents inline. Function-local aggregates are left to the
base policy; resource/global-parameter arrays keep their existing
declaration paths. `tests/wgsl/static-const-array-nested.slang` covers a
runtime-indexed 2D array.

*Known limitation:* an aggregate that is both a nested constituent and
used directly — a named `static const` array shared as an element of
another `static const` array *and* independently runtime-indexed — is
not folded, so it stays a separate `var<private>` declaration that the
enclosing converted array's initializer references by name (invalid
WGSL). This is not constructible from typical anonymous nested literals,
and is not a regression for accepted WGSL output (such a constant was a
rejected runtime-indexed `const` before this change too, though the
failure now takes a different form); fully handling it would require
inlining a duplicate copy of the constituent into the enclosing
initializer.

**Input-shape check (right layer?).** Yes. The IR for a `static const`
array is correct (`IRGlobalConstant` wrapping `IRMakeArray`); the
defects are WGSL keyword selection and WGSL fold policy, both
target-specific. The fix belongs in the WGSL emitter.

**Verification.** Built a debug `slangc`: the flat and nested cases emit
single self-contained `var<private>` declarations indexed by name; a
`static const` matrix is emitted as an inline matrix value indexed in
place (`mat2x2<…>(…)[i]`), not promoted to `var<private>`. The full
`tests/wgsl/` suite passes (49/49). Note: `slangc` emitting WGSL is not
the same as a validator accepting it — Tint is not available in the
build environment, so the `wgsl-spirv-asm` directives (which round-trip
the emitted WGSL through Tint) are ignored locally and run on CI. The
matrix test's directive is what would confirm or refute that a
runtime-indexed `const` matrix is valid WGSL.

**Known limitation — arrays nested inside a `static const` struct.** A
`static const` struct with an array field, runtime-indexed via
`g.arr[i]`, is *not* addressed: the struct is not `ArrayType`, so it
stays `const`, and it lowers through a constructor function (`g.arr[i]`
→ `Foo_init(...).arr[i]`) whose result is an array value runtime-indexed
— the same #6747 rejection. This is a realistic lookup-table shape but a
distinct (struct-valued) problem from the top-level arrays #6747
reports, and is left as a follow-up.

Fixes #6747.

---------

Co-authored-by: nv-slang-bot[bot] <274397474+nv-slang-bot[bot]@users.noreply.github.com>
Co-authored-by: Harsh Aggarwal <haaggarwal@nvidia.com>

Author: 2 people

docs/user-guide/a2-03-wgsl-target-specific.md

@@ -158,6 +158,9 @@ WGSL requires explicit address space qualifiers. Slang automatically assigns app
 | Group Shared          | `workgroup`         |
 | Parameter Blocks      | `uniform`           |
 
+Module-scope `static const` globals are emitted as a WGSL `const` (a compile-time value) when their type is a scalar, vector, or matrix.
+A `static const` global of **array** type is instead emitted as a `var<private>` (with the same initializer), because a WGSL `const` is a compile-time value that may only be indexed by a const-expression, whereas a `var<private>` is addressable and so can be indexed by a runtime value (for example `positions[vertexID]`).
+
 
 Matrix type translation
 -----------------------

source/slang/slang-emit-wgsl.cpp

@@ -808,6 +808,20 @@ static bool isStaticConst(IRInst* inst)
 
 void WGSLSourceEmitter::emitVarKeywordImpl(IRType* type, IRInst* varDecl)
 {
+    // A module-scope `static const` array is emitted as `var<private>`, not `const`: a WGSL
+    // `const` value of array type may only be indexed by a const-expression, so a constant array
+    // indexed by a runtime value (e.g. `positions[SV_VertexID]`) is rejected by the validator. A
+    // `var<private>` takes the same const-expression initializer but, being addressable, is
+    // runtime-indexable. Only arrays are converted -- a scalar/vector/matrix *value* is already
+    // runtime-indexable in WGSL. The type-based conversion is safe because constant-indexed reads
+    // fold away before emit (see the PR description). The `!= kIROp_GlobalParam` guard is
+    // load-bearing: this predicate is reused in the address-space chain below, where a
+    // `GlobalParam` array (e.g. a descriptor array) must keep its own address space, not
+    // `<private>`.
+    const bool emitModuleScopeArrayConstAsPrivateVar = isStaticConst(varDecl) &&
+                                                       varDecl->getOp() != kIROp_GlobalParam &&
+                                                       type->getOp() == kIROp_ArrayType;
+
     switch (varDecl->getOp())
     {
     case kIROp_GlobalParam:
@@ -824,7 +838,12 @@ void WGSLSourceEmitter::emitVarKeywordImpl(IRType* type, IRInst* varDecl)
         }
         break;
     default:
-        if (isStaticConst(varDecl))
+        // When this emits `var`, the matching `<private>` address space is emitted by the
+        // storage-space chain below (the two must stay in lockstep — a module-scope `var`
+        // without an address space is invalid WGSL).
+        if (emitModuleScopeArrayConstAsPrivateVar)
+            m_writer->emit("var");
+        else if (isStaticConst(varDecl))
             m_writer->emit("const");
         else
             m_writer->emit("var");
@@ -872,9 +891,11 @@ void WGSLSourceEmitter::emitVarKeywordImpl(IRType* type, IRInst* varDecl)
         m_writer->emit("storage, read");
         m_writer->emit(">");
     }
-    else if (varDecl->getOp() == kIROp_GlobalVar)
+    else if (varDecl->getOp() == kIROp_GlobalVar || emitModuleScopeArrayConstAsPrivateVar)
     {
-        // Global ("module-scope") non-handle variables need to specify storage space
+        // Global ("module-scope") non-handle variables need to specify storage space. This also
+        // covers an array constant converted to `var<private>` above (which is not a GlobalVar
+        // but is likewise emitted as a module-scope private variable).
 
         // https://www.w3.org/TR/WGSL/#var-decls
         // "
@@ -1386,6 +1407,34 @@ void WGSLSourceEmitter::emitCallArg(IRInst* inst)
 
 bool WGSLSourceEmitter::shouldFoldInstIntoUseSites(IRInst* inst)
 {
+    // WGSL emits MakeArray/MakeStruct as constructor expressions, valid in any expression context
+    // (the base class never folds them because C/HLSL initializer lists are not). Fold a
+    // module-scope aggregate constant inline when it is used only as a constituent of another
+    // aggregate, so a nested `static const` (e.g. `int g[2][3]`) does not emit its inner arrays as
+    // separate named decls that the outermost array's `var<private>` initializer would illegally
+    // reference; the outermost (used directly, e.g. runtime-indexed) one stays a declaration.
+    switch (inst->getOp())
+    {
+    case kIROp_MakeArray:
+    case kIROp_MakeStruct:
+    case kIROp_MakeArrayFromElement:
+        if (inst->getParent() && inst->getParent()->getOp() == kIROp_ModuleInst)
+        {
+            bool onlyConstituent = inst->firstUse != nullptr;
+            for (auto use = inst->firstUse; onlyConstituent && use; use = use->nextUse)
+            {
+                auto userOp = use->getUser()->getOp();
+                onlyConstituent = userOp == kIROp_MakeArray || userOp == kIROp_MakeStruct ||
+                                  userOp == kIROp_MakeArrayFromElement;
+            }
+            if (onlyConstituent)
+                return true;
+        }
+        break;
+    default:
+        break;
+    }
+
     bool result = CLikeSourceEmitter::shouldFoldInstIntoUseSites(inst);
     if (result)
     {

tests/wgsl/static-const-array-const-index.slang

@@ -0,0 +1,38 @@
+//TEST:SIMPLE(filecheck=WGSL): -stage vertex -entry vertexMain -target wgsl
+
+// Regression guard for issue #6747.
+//
+// Companion to static-const-array-indexing.slang. That test verifies a runtime-indexed
+// `static const` array is emitted as `var<private>`. This test verifies the opposite case
+// is not broken by that change: an element of a `static const` array, read at a *constant*
+// index, must constant-fold (the peephole pass folds `GetElement(MakeArray, constIndex)` to
+// the element) and therefore must NOT leave behind a module-scope `const` whose initializer
+// indexes a runtime variable, which would be illegal WGSL (a `const` initializer must be a
+// const-expression and cannot read a `var`). The array, being only constant-indexed, folds
+// away entirely.
+
+static const float weights[3] = {0.25f, 0.5f, 0.25f};
+
+// `weights[1]` is a constant index, so it folds to the literal `0.5` and `weights` is
+// dead-code-eliminated; it must not survive as a variable that `midWeight` indexes.
+static const float midWeight = weights[1];
+
+struct VertexOutput
+{
+    float4 position : SV_POSITION;
+};
+
+VertexOutput vertexMain(uint vertexID : SV_VertexID)
+{
+    VertexOutput output;
+    output.position = float4(float(vertexID) * midWeight, 0.0f, 0.0f, 1.0f);
+    return output;
+}
+
+// The constant-indexed array must fold away; the identifier `weights` (a unique substring here)
+// must not survive. If it had instead become a `var<private>` that `midWeight` indexes, both
+// `weights` and a `var<private>` declaration would appear -- so the bare `weights` negative also
+// covers the spurious-promotion case (a promoted decl would carry the array's name).
+// WGSL-NOT: weights
+// ...and the dependent constant must survive as the folded element value (weights[1] == 0.5f).
+// WGSL: 0.5f

tests/wgsl/static-const-array-indexing.slang

@@ -0,0 +1,41 @@
+//TEST:SIMPLE(filecheck=WGSL): -stage vertex -entry vertexMain -target wgsl
+// This second directive hands the emitted WGSL to Tint (via wgsl-spirv-asm) so we validate that
+// the output actually compiles, not just that the keyword flipped. It is exercised on CI where
+// Tint is available, and is ignored where the downstream compiler is absent.
+//TEST:SIMPLE(filecheck=SPV): -stage vertex -entry vertexMain -target wgsl-spirv-asm
+
+// Regression test for issue #6747.
+//
+// A `static const` array that is indexed by a runtime value must be emitted as a WGSL
+// `var<private>`, not as a WGSL `const`. A WGSL `const` is a compile-time value (closer to
+// C++ `constexpr`); the WGSL spec only allows a value of array type to be indexed by a
+// const-expression, so `const positions[vertexID]` (a runtime index) is rejected by the
+// WGSL validator with "The expression may only be indexed by a constant". `var<private>`
+// keeps the same inline initializer but is addressable and therefore runtime-indexable.
+
+static const float2 positions[] = {
+    float2(-1.0f, -1.0f),
+    float2( 1.0f, -1.0f),
+    float2( 1.0f,  1.0f),
+    float2(-1.0f,  1.0f)
+};
+
+// The constant array must not be emitted as a WGSL `const`...
+// WGSL-NOT: const positions
+// ...but as a private module-scope variable that keeps its inline initializer.
+// WGSL: var<private> positions{{.*}} : array<vec2<f32>, i32(4)> = array<vec2<f32>, i32(4)>(
+
+struct VertexOutput
+{
+    float4 position : SV_POSITION;
+};
+
+VertexOutput vertexMain(uint vertexID : SV_VertexID)
+{
+    VertexOutput output;
+    // Indexing the global with a runtime value is exactly what a WGSL `const` forbids.
+    // WGSL: positions{{.*}}[vertexID
+    // SPV: OpEntryPoint
+    output.position = float4(positions[vertexID], 0.0f, 1.0f);
+    return output;
+}

tests/wgsl/static-const-array-nested.slang

@@ -0,0 +1,37 @@
+//TEST:SIMPLE(filecheck=WGSL): -stage vertex -entry vertexMain -target wgsl
+// Validate the emitted WGSL through Tint on CI (ignored where the downstream compiler is absent).
+//TEST:SIMPLE(filecheck=SPV): -stage vertex -entry vertexMain -target wgsl-spirv-asm
+
+// Regression test for issue #6747 — nested aggregates.
+//
+// A *nested* `static const` array (here a 2D array) lowers to nested `MakeArray` insts, each of
+// which is a module-scope array constant. Naively emitting each as its own module-scope decl and
+// converting all of them to `var<private>` would make the outer `var<private>` initializer
+// reference the inner `var<private>`s — which is illegal WGSL (a `var<private>` initializer must
+// be a const-expression and cannot read another `var`). The fix folds the inner constituents
+// inline (shouldFoldInstIntoUseSites) so only the outermost runtime-indexed array becomes a
+// `var<private>`, with a self-contained inline initializer.
+
+static const int grid[2][3] = {
+    {1, 2, 3},
+    {4, 5, 6}
+};
+
+// Exactly one module-scope private variable, whose initializer inlines the inner arrays as
+// constructor expressions (NOT as references to separately-declared variables).
+// WGSL: var<private> grid{{.*}} : array<array<i32, i32(3)>, i32(2)> = array<array<i32, i32(3)>, i32(2)>( array<i32, i32(3)>( i32(1), i32(2), i32(3) ), array<i32, i32(3)>( i32(4), i32(5), i32(6) ) );
+
+struct VertexOutput
+{
+    float4 position : SV_POSITION;
+};
+
+VertexOutput vertexMain(uint vertexID : SV_VertexID)
+{
+    VertexOutput output;
+    // Runtime index of the outer array — the construct that requires `grid` to be `var<private>`.
+    // WGSL: grid{{.*}}[vertexID
+    // SPV: OpEntryPoint
+    output.position = float4(float(grid[vertexID][1]), 0.0f, 0.0f, 1.0f);
+    return output;
+}

tests/wgsl/static-const-matrix.slang

@@ -0,0 +1,37 @@
+//TEST:SIMPLE(filecheck=WGSL): -stage vertex -entry vertexMain -target wgsl
+// Validate the emitted WGSL through Tint on CI (ignored where the downstream compiler is absent).
+//TEST:SIMPLE(filecheck=SPV): -stage vertex -entry vertexMain -target wgsl-spirv-asm
+
+// Regression test for issue #6747 — a `static const` MATRIX is NOT converted to `var<private>`.
+//
+// Only `static const` array globals are converted: a WGSL `const` value of array type may only
+// be indexed by a const-expression. A matrix value, like a vector value, IS runtime-indexable in
+// WGSL, so a `static const` matrix stays a `const` and is emitted as an inline value — it must
+// NOT be promoted to `var<private>`. The `wgsl-spirv-asm` directive confirms Tint accepts the
+// runtime row-index on CI; if it ever rejected it, matrices would be an instance of the same bug
+// to convert too.
+
+static const float2x2 M = {
+    {1.0f, 2.0f},
+    {3.0f, 4.0f}
+};
+
+// The matrix must NOT be promoted to a module-scope private variable. Placed before the positive
+// check so the negative covers the whole globals region (where a promoted decl would appear).
+// WGSL-NOT: var<private>{{.*}}mat2x2
+
+struct VertexOutput
+{
+    float4 position : SV_POSITION;
+};
+
+VertexOutput vertexMain(uint i : SV_VertexID)
+{
+    VertexOutput output;
+    // Runtime row-index of the matrix: it emits as an inline `mat2x2<...>(...)[i]`, not as a
+    // `var<private>` referenced by name.
+    // WGSL: mat2x2{{.*}}[i
+    // SPV: OpEntryPoint
+    output.position = float4(M[i % 2], 0.0f, 0.0f);
+    return output;
+}