@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.1

package/docs/resource/formats/webgl/memory-structured.md

@@ -154,101 +154,35 @@ own `SVT_INT`/`SVT_INT16`/`SVT_INT12` type forces `TO_FLAG_INTEGER`
 
 ### GLSL lowering — B. Historical WebGL2 `cb3` joint-matrix rewrite contract
 
-**Superseded 2026-08-02.** The original two-stage `BoneTransforms` vertex-skinning
-pipeline follows. Its steps, citations, failures and proposed diagnostics are
-historical evidence, not open requirements. Step 2 records its replacement:
-
-1. Emit HLSLcc's reference SSBO GLSL exactly as in section A (this project's
-   HLSLcc fork already tolerates missing `RDEF` bindings for
-   `dcl_resource_structured` by falling back to the DXBC declaration's encoded
-   stride — see `CARBONENGINEJS-FORK.md:41-44` and
-   `TRANSPILING-GAPS.md:51-54`), producing text of the exact shape:
-   ```glsl
-   struct t0_type { uint[1] value; };
-   layout(std430, binding = 0) readonly buffer t0 { t0_type t0_buf[]; };
-   ...
-   dest = vec4(uintBitsToFloat(t0_buf[idx].value[(0 >> 2) + 0]),
-               uintBitsToFloat(t0_buf[idx].value[(0 >> 2) + 1]),
-               uintBitsToFloat(t0_buf[idx].value[(0 >> 2) + 2]),
-               uintBitsToFloat(t0_buf[idx].value[(0 >> 2) + 3]));
-   ```
-   Verified against an actual generated fixture
-   (`../shaderdiscovery/artifacts/ab-shader-set/work/skinned_fxdirectionalv5/skinned_fxdirectionalv5.sm_hi.dxbc_29291f5662ed6781.vertex.es300.glsl:60-64`):
-   all four components of one row share the **same** byte offset (row 0 uses
-   `0`, row 1 uses `16`, row 2 uses `32` — i.e. the row's base byte offset, not
-   a per-component offset of `0/4/8/12`), differing only in the trailing
-   `+ 0/1/2/3` dword index, and **without** a `u` suffix on either the shift or
-   the addend. The missing `u` is not a formatting nit: in this corpus the
-   byte-offset operand is declared `SVT_INT` (not `SVT_UINT`), so
-   `srcOffFlag` resolves to `TO_FLAG_INTEGER`
-   (`toGLSLInstruction.cpp:1618-1621`), which suppresses the `u` suffix
-   entirely (see `printImmediate32`, `toGLSLOperand.cpp:371-387` vs. `388-395`).
-   This also matters functionally: `lowerStructuredBoneLoad`'s regex
-   (`packageTr2WebglEffect.js:875`) matches literal `(\d+)\s*>>\s*2\s*\)` with
-   no `u` tolerance, and its 4-component agreement check requires all four
-   loads to share one `byteOffset` — a per-component-varying offset of
-   `0/4/8/12` would both fail to match the regex *and* fail the "same
-   byteOffset" agreement check, silently no-opping the rewrite. The previous
-   worked example here was internally inconsistent with the very rewrite
-   contract it was illustrating.
-2. A package-time rewrite pass over the generated GLSL text, performing the
-   steps below **in this exact order**.
-
-   > **Superseded (2026-08-02).** This pass no longer exists. The emitter now
-   > declares vertex-stage structured buffers as `std140` UBOs when it emits the
-   > shader, with real bindings, rather than rewriting text afterwards — see
-   > `DxbcGlslEmitter.js`, the `dcl_resource_structured` vertex branch. The
-   > regex functions it describes were deleted from
-   > `scripts/packageTr2WebglEffect.js`, so the line citations below point at
-   > nothing. The section is kept because it records *why* each rewrite was
-   > needed, which the ccpwgl runtime ABI still constrains; read it as history,
-   > not as a description of the code.
-   1. Strip the `#ifdef GL_ARB_shader_storage_buffer_object` /
-      `GL_ARB_shader_image_load_store` extension guard blocks (regexes at
-      `packageTr2WebglEffect.js:832-833`).
-   2. Strip the `struct t0_type { uint[1] value; };` declaration (regex at
-      `packageTr2WebglEffect.js:834`, matches only the 1-word/4-byte stride
-      shape).
-   3. Strip the `layout(std430, binding = 0) readonly buffer t0 { t0_type
-      t0_buf[]; };` declaration (regex at `packageTr2WebglEffect.js:835`).
-   4. Grow the vertex stage's `ConstantBuffer3` (`cb3`) declaration to
-      `vec4 data[max(existingSize, 200)]` (`packageTr2WebglEffect.js:836-839`) —
-      this is where `JointMat` lives at `cb3.data[26..199]` per the ccpwgl runtime
-      ABI (`cb3[26..199]`, 58 joints × 12 floats = 696 floats,
-      `AGENT-FINDINGS/decisions/016-carbonwebgl-skinning-abi-lowering-for-ccpwgl-2026-06-30.md`
-      and `015-joint-matrix-jointmat-findings-ccpwgl-runtime-truth.md`).
-   5. Convert `uvec4`/`ivec4` (or `uvec2/3`, `ivec2/3`) `in_BLENDINDICES<n>` vertex
-      inputs to plain `vec<N>` (regex at `packageTr2WebglEffect.js:840-843`) —
-      ccpwgl binds GR2 mesh blend indices as float attributes via
-      `vertexAttribPointer`, not `vertexAttribIPointer`
-      (`AGENT-FINDINGS/decisions/028-carbonwebgl-skinned-blend-index-abi-lowering.md`).
-   6. Strip the DX11 global bone-offset add HLSLcc emits when combining
-      `in_BLENDINDICES0` with a `cb3.data[26]` offset uniform (two regex forms at
-      `packageTr2WebglEffect.js:845-852`, covering both the scalar `int(...)  +
-      floatBitsToInt(cb3.data[26].x)` shape and the vector `(i)uvec/ivec(...) +
-      floatBitsToInt(cb3.data[26].<swz>)` shape) — ccpwgl's `cb3.data[26]` slot is
-      reused for `JointMat`, not the native bone-ring-buffer offset, so this add
-      must be removed entirely rather than merely rewired.
-   7. Rewrite each 4-component `t0_buf[...]` row-load expression
-      (`vec4(t0_buf[idx].value[(byteOff>>2)+0], ...)`, all 4 components required,
-      `lowerStructuredBoneLoad`) into:
-      ```glsl
-      cb3.data[26 + (<idx>) * 3 + <row>]
-      ```
-      where `<row> = floor(byteOff / 16)` and must be in `{0,1,2}` (a `Float4x3`
-      bone matrix is 3 `vec4` rows); if any of the 4 component sub-expressions
-      disagree on `idx`/`byteOff`, or `row` falls outside `0..2`, or the swizzle
-      is anything but the identity `xyzw`/`.xyzw` is stripped when default,
-      **the rewrite silently no-ops and leaves the un-lowered `t0_buf` text in
-      place** (`packageTr2WebglEffect.js:886,890,895,898` all `return match`) —
-      this is a silent-failure edge case the implementing engineer must guard
-      against (add a diagnostic) rather than trust to fail loudly.
-   8. If any rewrite happened, inject a `// Carbon WebGL: BoneTransforms lowered to cb3
-      JointMat rows.` marker comment after `#version 300 es`
-      (`packageTr2WebglEffect.js:859-861`).
-
-### GLSL lowering — C. `ld_structured` in pixel stage / non-skinning resources
-The corpus also uses `ld_structured` on `t#` "packed tbuffer" resources unrelated
+**Superseded 2026-08-02.** Vertex-stage structured buffers are emitted as
+`std140` UBOs with real bindings by `DxbcGlslEmitter.js`'s
+`dcl_resource_structured` vertex branch. The package-time regex pass was
+deleted from `scripts/packageTr2WebglEffect.js`.
+
+The [pinned original recipe](https://github.com/carbonenginejs/runtime/blob/917c644807fa7d4802dbba572af50cb98fff0bef/docs/resource/formats/webgl/memory-structured.md#glsl-lowering--b-webgl2-cb3-joint-matrix-rewrite-contract-the-shipping-path)
+preserves all eight ordered rewrites, source/fixture citations, worked example,
+failure cases and proposed diagnostics. It preserves the historical document,
+not the missing cited source or artifacts. The legacy ccpwgl ABI constraints
+that motivated it remain useful:
+
+- `JointMat` occupied `cb3[26..199]`: 58 joints × 3 `vec4` rows
+  (696 floats), requiring at least 200 rows in the buffer declaration.
+- Blend-index inputs became float `vec<N>` attributes for
+  `vertexAttribPointer`, not `vertexAttribIPointer`.
+- The native bone-offset addition was stripped because `cb3[26]` held
+  `JointMat`, not that offset.
+- Four loads had to agree on index and base byte offset (`0/16/32`, not
+  per-component `0/4/8/12`), with rows `0..2` and identity swizzle.
+  Signed offsets explained the fixture's missing `u`; the regex did not
+  tolerate that suffix. Partial masks, mismatched indices/offsets/rows or
+  incompatible swizzles silently left the SSBO load unreplaced.
+
+Those failed matches and diagnostic proposals are historical, not renewed
+implementation requirements. The retained helper inventory below has the same
+historical scope.
+
+### GLSL lowering — C. `ld_structured` in pixel stage / non-skinning resources
+The corpus also uses `ld_structured` on `t#` "packed tbuffer" resources unrelated
 to skinning — e.g. `LightBuffer`/`LightIndexBuffer` reads in pixel shaders such as
 `decalcylindricv5.sm_depth` (`AGENT-FINDINGS/decisions/005-structured-resource-only-opcodes-2026-06-26.md`).
 **No `cb3`-style *functional* ABI rewrite exists for these** — they hit the same
@@ -709,53 +643,41 @@ targeting ES 3.10+/desktop: `atomicUavOrTgsmOp(func, dest, addr, src,
 shared-memory atomics) and `imageAtomicAdd` etc. (image atomics) are GLSL ES
 3.10+ compute-shader-only built-ins; none exist in ES 3.00 vertex/fragment
 shaders, regardless of which D3D11 stage the source instruction came from.
-**Fully out of scope for the WebGL2 emitter.** Detect any `atomic_*`/
-`imm_atomic_*` opcode and refuse the stage.
-
-Do **not** rely on "these only occur in compute shaders" as the reason for
-skipping this check in the pixel-stage emitter: `dx11-instruction-coverage.json`
-(`initialCandidateOpcodeExamples`) records a concrete `atomic_iadd` instance in
-`graphics\effect.dx11\managed\space\specialfx\lensflares\lensflareoccludert.sm_depth`
-tagged `stageIndex: 1` / `stageName: "pixel"` — an actual D3D11 pixel shader
-(D3D11.1 permits UAV access from pixel shaders; a lens-flare occlusion query
-written into a UAV counter from the pixel stage is a plausible, ordinary
-technique, not a mislabeled compute pass). The other four sampled corpus
-instances of this opcode group (`atomic_iadd` again in `createhistograms.sm_depth`,
-`imm_atomic_iadd` in `clear.sm_depth`, `imm_atomic_exch`/`atomic_umax`/
-`atomic_umin` in `computelightlists.sm_depth`) are all tagged `stageName:
-"geometry"` by the same tool, but those files' names (histogram building,
-particle-buffer clear, light-list culling) are classic GPGPU compute-shader
-workloads, and the coverage tool has no `"compute"` stage label at all in its
-vocabulary (only `vertex`/`pixel`/`geometry`/`hull`) — those four are much
-better explained as compute shaders whose slot the tool mislabels than as
-genuine geometry shaders (a real DX11 geometry shader cannot declare
-`dcl_thread_group`/`sync`, which the *sibling* `createhistograms.sm_depth`
-example for the `sync` opcode does, and DXBC does not permit that in a
-geometry stage). The `lensflareoccludert` pixel-stage instance is not
-explained away by that reasoning and must be treated as real: the emitter's
-**ps-stage translation path itself** needs the detect-and-refuse check, not
-just a pre-filter that assumes this opcode class never survives into a vs/ps
-compile.
-
-`TRANSPILING-GAPS.md:100-114` ("UAV and atomic path... blocked for current
-WebGL2 target... `atomic_iadd`: 6... Affects the `lensflareoccludert` path" —
-note that count was measured on a narrower earlier corpus slice than this
-family's 450k-instruction sweep, which shows 27) already names
-`lensflareoccludert` as the blocked case; it does not itself claim the
-instruction is compute-only, and the per-instruction corpus scan confirms it
-is not.
-
-### Confidence
-**High** for the DXBC/GLSL semantics (read directly from source) and for the
-WebGL2-out-of-scope conclusion (ES 3.00 has no atomics in any stage, so the
-`lensflareoccludert` pixel-shader counterexample does not change the outcome).
-**Medium** on the blanket "compute-only" framing carried over from the
-project's decision log — confirmed false for at least the `lensflareoccludert`
-`atomic_iadd` instance, which is a pixel shader; the emitter must not assume
-this opcode family is filtered out before reaching ps-stage translation.
-
----
-
+**Fully out of scope for the WebGL2 emitter.** Detect any `atomic_*`/
+`imm_atomic_*` opcode and refuse the stage.
+
+Do **not** skip the pixel-stage check by assuming compute-only use.
+`dx11-instruction-coverage.json` (`initialCandidateOpcodeExamples`) records
+`atomic_iadd` in
+`graphics\effect.dx11\managed\space\specialfx\lensflares\lensflareoccludert.sm_depth`
+with `stageIndex: 1` / `stageName: "pixel"`. D3D11.1 permits pixel-shader
+UAV access; a lens-flare occlusion counter is a plausible use, not a mislabeled
+compute pass. The **ps-stage translator itself** must detect and refuse it.
+
+The four other sampled cases are tagged `"geometry"`: `atomic_iadd` in
+`createhistograms.sm_depth`, `imm_atomic_iadd` in `clear.sm_depth`, and
+`imm_atomic_exch`/`atomic_umax`/`atomic_umin` in
+`computelightlists.sm_depth`. Their histogram, particle-clear and light-list
+workloads suggest compute. The tool's vocabulary is only
+`vertex`/`pixel`/`geometry`/`hull`, with no `"compute"` label;
+the sibling `sync` example in `createhistograms.sm_depth` also carries
+`dcl_thread_group`/`sync`, illegal in a real DX11 geometry stage. That
+mislabeling inference does not explain away the confirmed pixel example.
+
+`TRANSPILING-GAPS.md:100-114` already names `lensflareoccludert` as
+blocked ("UAV and atomic path... blocked for current WebGL2 target...
+`atomic_iadd`: 6... Affects the `lensflareoccludert` path"). Its count 6
+is from a narrower earlier slice than this 450k-instruction sweep's 27, and it
+does not claim compute-only use.
+
+### Confidence
+**High** for the source-read DXBC/GLSL semantics and WebGL2 exclusion: ES 3.00
+has no atomics in any stage. **Medium** for the decision log's blanket
+compute-only framing, disproven by the pixel-stage example. Refusal must not
+depend on a pre-filter removing this family before ps translation.
+
+---
+
 ## `ld_uav_typed` (18 instances)
 
 ### Semantics

package/docs/resource/formats/webgl/texture-sample.md

@@ -351,95 +351,78 @@ dest = textureGather(<TextureSamplerName>, <coord>[, <refZ>][, <offsetVec>][, <c
 
 **Type rules**: destination type same rule as `sample` (reflected return type,
 `SVT_FLOAT` fallback). Offset operand is read with `TO_FLAG_INTEGER` (never bitcast to
-float) since GLSL's `ivec` offset parameters require true integer values, not a
-reinterpreted float register.
-
-**Helpers needed**: `hlslcc_textureGather4Emulated` (**mandatory for this target** — see
-WebGL2 notes below). **Correction**: an earlier draft of this spec claimed "zero hits for
-`HaveGather` outside `languages.h`" — that grep claim is false. `toGLSLInstruction.cpp`/
-`toGLSLDeclaration.cpp`/`toGLSLOperand.cpp` (the instruction/declaration/operand lowering
-proper) indeed never check `HaveGather`, but `toGLSL.cpp`'s `AddVersionDependentCode`
-(`:163-172`) does: `if (!HaveGather(eLang)) { if (any gather4* opcode used)
-EnableExtension("GL_ARB_texture_gather"); }`. `EnableExtension` (`HLSLCrossCompilerContext.cpp:157-167`)
-emits a guarded pragma — `#ifdef GL_ARB_texture_gather` / `#extension GL_ARB_texture_gather
-: enable` / `#endif` — so it never hard-fails on an unrecognized extension name; it is a
-best-effort "enable it if the compiler happens to advertise it" pattern. For `LANG_ES_300`
-this is a no-op in practice: `GL_ARB_texture_gather` is a **desktop**-only ARB extension
-token with no ES/WebGL2-side branch (contrast the image-atomics case a few lines above at
-`:154-160`, which does pick `GL_OES_shader_image_atomic` on `isES`) — no WebGL2 GLSL ES
-preprocessor predefines that macro, so the `#ifdef` never fires, no `#extension` line is
-emitted, and the instruction body's hardcoded `funcName = "textureGather"`
-(`toGLSLInstruction.cpp:1253-1254`, still unconditional) is unaffected either way. So the
-end conclusion is unchanged — this target still needs the emulation helper — but the
-"HLSLcc never gates this at all" framing is wrong: it does attempt a gate, the gate is just
-built for desktop GL and silently does nothing useful on `LANG_ES_300`. The JS emitter must
-supply its own 4-tap emulation (four `textureOffset`/`texture` calls at the four
-bilinear-neighbor texel centers, computed from `textureSize`) wherever the real
-`textureGather` builtin is unavailable.
-
-**Edge cases**: `textureGather` (where available) requires the four sampled texels to be
-selected by hardware bilinear-neighbor rules that are implementation-defined at exact
+float) since GLSL's `ivec` offset parameters require true integer values, not a
+reinterpreted float register.
+
+**Helpers needed**: `hlslcc_textureGather4Emulated` (**mandatory for this
+target**). The earlier claim of "zero hits for `HaveGather` outside
+`languages.h`" was false: instruction/declaration/operand lowering does not
+check it, but `toGLSL.cpp`'s `AddVersionDependentCode` (`:163-172`) checks
+`!HaveGather(eLang)` and, for any `gather4*`, calls
+`EnableExtension("GL_ARB_texture_gather")`.
+
+`EnableExtension` (`HLSLCrossCompilerContext.cpp:157-167`) emits a guarded
+`#ifdef GL_ARB_texture_gather` / `#extension GL_ARB_texture_gather : enable` /
+`#endif`, not a hard failure on an unknown extension. This desktop-only token
+is never predefined by an ES/WebGL2 preprocessor: the guard emits no extension
+and leaves the instruction's unconditional `funcName = "textureGather"`
+(`toGLSLInstruction.cpp:1253-1254`) unchanged. Unlike the image-atomics case
+at `:154-160`, it has no `isES` branch selecting
+`GL_OES_shader_image_atomic`.
+
+Thus HLSLcc attempts a gate, but it does nothing useful on `LANG_ES_300`.
+The JS emitter must supply four-tap emulation: four `textureOffset`/`texture`
+calls at the bilinear-neighbor texel centers, computed from `textureSize`.
+
+**Edge cases**: `textureGather` (where available) requires the four sampled texels to be
+selected by hardware bilinear-neighbor rules that are implementation-defined at exact
 texel boundaries; an emulated fallback needs to replicate the "texel below-left of the
 sample point" neighbor-selection rule (typically via `floor(coord*size - 0.5)` and
 `+ivec2(0/1,0/1)` taps) to match D3D `Gather4` semantics closely enough for typical
 consumers (contact-hardening shadows, procedural blending). This emulation is
-**not sourced from HLSLcc** (HLSLcc assumes `textureGather` exists) and is the single
-highest-risk item in this spec.
-
-**WebGL2 notes — critical gap**: `languages.h:220-227` defines
-`HaveGather(eLang)` as true only for `eLang >= LANG_400` (desktop GL 4.0+) **or**
-`eLang == LANG_ES_310`. **`LANG_ES_300` (this project's actual target) is excluded.**
-`textureGather`/`textureGatherOffset` are GLSL ES 3.10 / desktop-GLSL-4.00 builtins; they
-do not exist in GLSL ES 3.00 core and WebGL2 (which is GLSL ES 3.00-based) exposes no
-extension that adds them. **Correction**: an earlier draft of this spec claimed "HLSLcc's
-GLSL backend never checks `HaveGather` before emitting `textureGather(...)`" — that is not
-quite right; see the "Helpers needed" correction above: `toGLSL.cpp` does check
-`!HaveGather(eLang)` and attempts to `EnableExtension("GL_ARB_texture_gather")`, it's just
-that the attempt is built for desktop GL and is a silent no-op on `LANG_ES_300`
-(the `#ifdef`-guarded extension macro is never predefined by an ES/WebGL2 preprocessor, and
-the instruction body's `funcName` is set unconditionally regardless of that check's
-outcome). Net effect is unchanged: it will happily produce GLSL that fails to compile under
-strict WebGL2/ES 3.00 validation. This spec's emitter must either (a) always emit the
-`hlslcc_textureGather4Emulated` helper instead of raw `textureGather` for this family, or
-(b) detect and reject `gather4*` shaders at translation time with an explicit diagnostic —
-but silently trusting HLSLcc's literal `textureGather(...)` output will break at WebGL2
-shader-compile time. This is the most important actionable finding in this spec for the
-`gather4` opcodes.
-
-**Confidence**: low for WebGL2 compilability, high for what HLSLcc *literally emits*
-(fully read source, zero ambiguity in the C++, including the `toGLSL.cpp` extension-attempt
-correction above) — the risk is entirely in the target capability mismatch documented
-above, not in misreading HLSLcc's intent. An earlier draft cited `TRANSPILING-GAPS.md:188`
-as corroboration for this being a known pending item; that file does not exist anywhere in
-this repository (see the authority-order correction at the top of this document), so that
-citation is withdrawn and this section's confidence rests solely on the C++ reading above.
-
----
-
+**not sourced from HLSLcc** (HLSLcc assumes `textureGather` exists) and is the single
+highest-risk item in this spec.
+
+**WebGL2 notes — critical gap**: `languages.h:220-227` makes
+`HaveGather(eLang)` true only for `eLang >= LANG_400` or `LANG_ES_310`,
+excluding `LANG_ES_300`. `textureGather`/`textureGatherOffset` require
+GLSL ES 3.10 / desktop GLSL 4.00; WebGL2 exposes no extension adding them.
+The ineffective desktop extension attempt is described above, not "no gate".
+
+This spec's emitter must either (a) always emit the
+`hlslcc_textureGather4Emulated` helper instead of raw `textureGather` for this family, or
+(b) detect and reject `gather4*` shaders at translation time with an explicit diagnostic —
+but silently trusting HLSLcc's literal `textureGather(...)` output will break at WebGL2
+shader-compile time.
+
+**Confidence**: low for WebGL2 compilability, high for HLSLcc's literal output
+(fully read C++, including the global extension attempt). The risk is target
+capability mismatch. The earlier `TRANSPILING-GAPS.md:188` corroboration is
+withdrawn: that file is absent (see the authority-order correction), so this
+assessment rests solely on the cited C++ reading.
+
+---
+
 ## 6. `sample_c` (0 occurrences in corpus, spec required for depth paths)
 
 **Semantics**: Depth-comparison ("shadow") sample: fetches from a depth-format resource
 using a comparison sampler, compares the fetched depth against a supplied reference value,
 and returns the hardware's percentage-closer-filtered (PCF) result — a **float in
 `[0.0, 1.0]`**, not a 0/1 boolean and **not** the DXBC ALU integer comparison-mask
-convention. D3D11 `SAMPLE_C`: `dest, address, resource, sampler, referenceValue`, implicit
-(derivative-based) LOD like `sample`.
-
-**Important — comparison-mask convention does NOT apply here**: DXBC's scalar/vector ALU
-comparison opcodes (`eq`/`ne`/`lt`/`ge`, `ieq`/`ige`/etc., handled by `AddComparison`,
-`toGLSLInstruction.cpp:173` and the `OPCODE_GE` comment "the result is a boolean but HLSL
-asm returns 0xFFFFFFFF/0x0 instead", `:2689-2694`) produce a full-lane
-`0xFFFFFFFF`/`0x00000000` integer mask per component. **`sample_c`/`sample_c_lz`/
-`gather4_c` are unrelated to that convention** — hardware depth comparison sampling
-returns a genuinely-filtered floating-point value (0.0, 1.0, or any PCF-blended value in
-between when the sampler uses linear filtering across multiple depth texels), matching
-standard D3D11 `SampleCmp`/`SampleCmpLevelZero` semantics that HLSLcc's GLSL backend
-forwards unchanged (it applies no extra masking logic to the depth-compare result — the
-value comes directly out of GLSL `texture(sampler2DShadow, ...)`, which itself returns a
-filtered float per the GLSL spec).
-
-**GLSL lowering**: `TranslateTextureSample(psInst, TEXSMP_FLAG_DEPTHCOMPARE)`
-(`toGLSLInstruction.cpp:3181-3190`). `psSrcRef = operands[4 + hasParamOffset]` (`:1143`).
+convention. D3D11 `SAMPLE_C`: `dest, address, resource, sampler, referenceValue`, implicit
+(derivative-based) LOD like `sample`.
+
+**Important — comparison-mask convention does NOT apply here**: ALU
+`eq`/`ne`/`lt`/`ge`, `ieq`/`ige`, etc. return per-lane
+`0xFFFFFFFF`/`0x00000000` masks (`AddComparison`,
+`toGLSLInstruction.cpp:173`; `OPCODE_GE` comment, `:2689-2694`).
+`sample_c`/`sample_c_lz`/`gather4_c` instead return filtered floats,
+including intermediate PCF values under linear filtering. HLSLcc forwards the
+GLSL shadow-sample result without extra masking, matching D3D11
+`SampleCmp`/`SampleCmpLevelZero` semantics.
+
+**GLSL lowering**: `TranslateTextureSample(psInst, TEXSMP_FLAG_DEPTHCOMPARE)`
+(`toGLSLInstruction.cpp:3181-3190`). `psSrcRef = operands[4 + hasParamOffset]` (`:1143`).
 
 - For every resource dimension **except** `TEXTURECUBEARRAY` and non-gather ops, the
   reference value is embedded as the **last component of the texture coordinate vector**
@@ -603,29 +586,23 @@ non-multisample resources.
 | `TEXTURE2DMS` (`ld_ms` only) | `texelFetch(tex, ivec2(coord.xy), int(sampleIndexOperand.x))` — 3rd instruction operand, not `.w` |
 | `TEXTURE2DMSARRAY` (`ld_ms`) | `texelFetch(tex, ivec3(coord.xyz), int(sampleIndexOperand.x))` |
 | Cube / CubeArray / BufferEx | not possible in HLSL or GLSL — `ASSERT(0)` (`:970-974`) |
-
-- `hasOffset` (`psInst->bAddressOffset`) swaps in `texelFetchOffset(...)` with a trailing
-  `ivec2`/`ivec3`/int offset literal (`:875,891-894,909-911,923-926,938-941`).
-- **Source bug — malformed offset literal for `TEXTURE2D`/`TEXTURE2DARRAY`**: the
-  `TEXTURE1D` (`:909-910`, plain `int`) and `TEXTURE3D` (`:923-924`, `ivec3(%d, %d, %d)`,
-  3 args) offset literals are well-formed, but the `TEXTURE2DARRAY` (`:925-926`) and
-  `TEXTURE2D` (`:940-941`) cases both emit the literal text `ivec3(%d, %d)` —
-  labeled `ivec3` but with only **two** `%d` substitutions
-  (`bformata(glsl, ", ivec3(%d, %d)", psInst->iUAddrOffset, psInst->iVAddrOffset)`).
-  `ivec3(3, 5)` is not a legal GLSL constructor call (an `ivec3` needs 3 components, or a
-  single scalar to splat, not 2), so this is invalid GLSL that will fail to compile — this
-  looks like a copy-paste typo in the vendor source (should read `ivec2`, matching the
-  correct 2-arg, 2D offset shape used elsewhere, e.g. `sample`'s own offset-building code at
-  `toGLSLInstruction.cpp:1398-1402` which correctly emits `ivec2(%d, %d)` for 2 offsets).
-  Any Carbon effect that uses an immediate texel offset (`sample_controls`) on a `ld`/`ld_ms`
-  against a `Texture2D` or `Texture2DArray` resource will hit this bug and get
-  non-compiling GLSL; `Texture1D`/`Texture3D`/`Texture1DArray` immediate-offset `ld` is
-  unaffected. This is a real upstream HLSLcc defect (ground truth wins per this review's
-  brief), not a misreading — the JS emitter must special-case these two dimensions to emit
-  `ivec2` instead of replicating the literal `ivec3` text.
-- Coordinates are read `TO_FLAG_INTEGER | TO_AUTO_EXPAND_TO_VEC2/VEC3` (`:903,920,935,950,961`)
-  — **integer**, not the `TO_AUTO_BITCAST_TO_FLOAT` used by filtered sampling; the mip/LOD
-  (or sample index for MS) is separately read with plain `TO_FLAG_INTEGER` on the `.w`/`.a`
+
+- `hasOffset` (`psInst->bAddressOffset`) swaps in `texelFetchOffset(...)` with a trailing
+  `ivec2`/`ivec3`/int offset literal (`:875,891-894,909-911,923-926,938-941`).
+- **Source bug — malformed offset literal for `TEXTURE2D`/`TEXTURE2DARRAY`**:
+  `TEXTURE2DARRAY` (`:925-926`) and `TEXTURE2D` (`:940-941`) emit
+  `bformata(glsl, ", ivec3(%d, %d)", psInst->iUAddrOffset, psInst->iVAddrOffset)`.
+  Two components cannot construct an `ivec3`: `ivec3(3, 5)` fails GLSL
+  compilation. The JS emitter must emit `ivec2` for these dimensions, as the
+  filtered-sample offset builder does (`toGLSLInstruction.cpp:1398-1402`),
+  rather than copy this upstream typo. Immediate-offset `ld`/`ld_ms` on
+  `Texture2D`/`Texture2DArray` hits it; `Texture1D`/`Texture3D`/
+  `Texture1DArray` is unaffected. `TEXTURE1D` (`:909-910`, plain `int`)
+  and `TEXTURE3D` (`:923-924`, three-argument `ivec3(%d, %d, %d)`) are
+  well-formed. This is the recorded vendor-source defect, not a lowering to copy.
+- Coordinates are read `TO_FLAG_INTEGER | TO_AUTO_EXPAND_TO_VEC2/VEC3` (`:903,920,935,950,961`)
+  — **integer**, not the `TO_AUTO_BITCAST_TO_FLOAT` used by filtered sampling; the mip/LOD
+  (or sample index for MS) is separately read with plain `TO_FLAG_INTEGER` on the `.w`/`.a`
   mask or the dedicated 4th operand.
 - Return-channel swizzle is applied the same way as `sample` (via the texture operand's
   own swizzle re-enabled and masked by the destination access mask, `:978`).
@@ -711,42 +688,36 @@ component on this target** — see WebGL2 notes). No helper needed for the width
 depth components (`textureSize` is fully core).
 
 **Edge cases**: `textureSize` with an out-of-range `lod` argument returns `0` per GLSL ES
-3.00 spec (well-defined). Buffer/`BUFFEX` resources are excluded from the `dim==0` default
-path implicitly by never appearing in the `resinfo`-legal dimension set.
-
-**WebGL2 notes — gap on the mip-count component**: `languages.h:247-254` defines
-`HaveQueryLevels(eLang)` true only for `eLang >= LANG_430`. `LANG_ES_300` does **not**
-qualify, and `GetResInfoData`'s `index >= 3` branch (`:1112-1127`) itself calls
-`textureQueryLevels(...)` unconditionally, with no local `HaveQueryLevels` gate. **Correction**:
-an earlier draft of this spec said this was "no gate at all" and contrasted it with `lod`'s
-`HaveQueryLod` as the supposed sole gated case in the family — that contrast overstates the
-difference. `toGLSL.cpp`'s `AddVersionDependentCode` **does** check `HaveQueryLevels`
-(`:234-241`): `if (!HaveQueryLevels(eLang)) { if (OPCODE_RESINFO used)
-{ EnableExtension("GL_ARB_texture_query_levels"); EnableExtension("GL_ARB_shader_image_size"); } }`.
-As with `gather4`'s analogous `GL_ARB_texture_gather` attempt above, both are desktop-only
-ARB extension tokens behind an `EnableExtension` `#ifdef` guard that is never true under a
-GLSL ES/WebGL2 preprocessor, so on `LANG_ES_300` this is a no-op in practice: no
-`#extension` line is emitted and `GetResInfoData`'s call site is unaffected. The practical
-conclusion is therefore unchanged — `textureQueryLevels` does not exist in GLSL ES 3.00
-core, has no WebGL2-exposed extension equivalent, and any Carbon effect that reads
-`resinfo`'s 4th (`.w`, "total mip count") component on this target will receive GLSL that
-fails to compile. Given 247 corpus occurrences of `resinfo`, this is a second actionable,
-high-value gap for this spec (alongside `gather4`'s `textureGather` gap) — the emitter must
-substitute `hlslcc_textureQueryLevels` (fallback strategy: accept the mip count as an
-out-of-band uniform per texture, since there is no in-shader WebGL2-legal way to query it;
-or hard-fail translation if this exact component is read). The first-3-components path
-(`textureSize`) has no such gap.
-
-**Confidence**: high on what HLSLcc emits (fully read, unambiguous, including the
-`toGLSL.cpp` extension-attempt correction above), but explicitly flagged as a real WebGL2
-compile-time risk for the mip-count component. The general opcode was previously described
-as "corroborated by `TRANSPILING-GAPS.md:186,337`" — that file does not exist in this
-repository (see the authority-order correction at the top of this document), so that
-corroboration claim is withdrawn; this section's confidence now rests solely on the C++
-reading above.
-
----
-
+3.00 spec (well-defined). Buffer/`BUFFEX` resources are excluded from the `dim==0` default
+path implicitly by never appearing in the `resinfo`-legal dimension set.
+
+**WebGL2 notes — gap on the mip-count component**:
+`HaveQueryLevels(eLang)` requires `eLang >= LANG_430`
+(`languages.h:247-254`), excluding `LANG_ES_300`.
+`GetResInfoData`'s `index >= 3` branch (`:1112-1127`) calls
+`textureQueryLevels` without a local gate. The earlier "no gate at all"
+claim was too broad: `toGLSL.cpp`'s `AddVersionDependentCode`
+(`:234-241`) checks `!HaveQueryLevels` plus `OPCODE_RESINFO`, then
+attempts `GL_ARB_texture_query_levels` and `GL_ARB_shader_image_size`.
+Like the gather gate, these desktop-only tokens sit behind `EnableExtension`
+`#ifdef` guards that do nothing under ES/WebGL2; the call site is unchanged.
+
+`textureQueryLevels` has neither an ES 3.00 builtin nor a WebGL2 extension
+equivalent. Reading `resinfo`'s fourth (`.w`, total-mip-count) component
+therefore produces non-compiling GLSL. The 247 corpus occurrences make this
+an actionable risk; the first three `textureSize` components have no such gap.
+The emitter must
+substitute `hlslcc_textureQueryLevels` (fallback strategy: accept the mip count as an
+out-of-band uniform per texture, since there is no in-shader WebGL2-legal way to query it;
+or hard-fail translation if this exact component is read).
+
+**Confidence**: high on HLSLcc's literal output, including the global extension
+attempt; the mip-count path remains a WebGL2 compile risk. Corroboration by
+`TRANSPILING-GAPS.md:186,337` is withdrawn because that file is absent (see
+the authority-order correction). Confidence rests on the C++ reading alone.
+
+---
+
 ## 10. `deriv_rtx_coarse` (209) and `deriv_rty_coarse` (215)
 ### (plus `deriv_rtx`/`deriv_rtx_fine`/`deriv_rty`/`deriv_rty_fine`, same lowering)