@woosh/meep-engine 3.60.3 → 3.60.4

package/src/shade/renderer/postprocess/nss/shader_nss_preprocess.js

@@ -1,246 +1,246 @@
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { F16_MAX_DEFINITION } from "../../shader/chunk/math/F16_MAX_DEFINITION.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { chunk_nss_find_nearest_depth } from "./chunk_nss_find_nearest_depth.js";
-import { chunk_nss_luma_derivative } from "./chunk_nss_luma_derivative.js";
-import { NSS_WORKGROUP_SIZE } from "./NSS_CONSTANTS.js";
-import { NSS_SETTINGS_STRUCT } from "./NSS_SETTINGS_STRUCT.js";
-
-/**
- * NSS preprocess pass. Runs at render-resolution (one thread per render-res
- * pixel) and produces:
- *  1. The 12-channel network input tensor, packed into a single rgba16f
- *     3D storage texture with depth=3 (channels 0..3, 4..7, 8..11).
- *  2. The encoded "nearest depth offset" used by postprocess to dilate
- *     velocity at output-res (`tNearestOffset` — components in [0, 1]
- *     decode to {-1, 0, 1}² via `(x*2 - 1)`).
- *
- * Per-pixel logic (matches the algorithm in ARM's `Preprocess()`):
- *   1. Dilate depth over a 3×3 neighbourhood, remember the offset of the
- *      nearest sample.
- *   2. Sample velocity at the dilated coord.
- *   3. Project to the previous frame, sample warped history (bilinear).
- *   4. Read the FSR2 depth-clip confidence from the upstream pass and
- *      invert it into the network's "high = disocclusion" convention.
- *   5. Sample the warped feedback tensor (bilinear).
- *   6. Compute the luma derivative between current and warped history.
- *   7. Pack everything into the output tensor — colours
- *      tonemapped via `Tonemap(EXPOSURE * raw)` to match ARM's training
- *      distribution.
- *
- * @see ARM NSS reference: `Preprocess` in
- *      `Source/NG-SDK/sdk/include/FidelityFX/gpu/nss/ffx_nss_preprocess.h`
- */
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
-    // ── inputs at render-res ──
-    .addTexture("tColour", "float")                          // jittered scene colour, render-res
-    // depth32float can't be bound as 'float' (filterable) — WebGPU only
-    // accepts depth textures via 'unfilterable-float' in this context.
-    // We only ever read this via textureLoad inside the depth dilation.
-    .addTexture("tDepthCurrent", "unfilterable-float")
-    .addTexture("tVelocity", "float")                        // pixel-space motion vectors, render-res
-    // FSR2 depth-clip confidence (1 = trust history, 0 = disocclusion)
-    // produced by the engine's shared shader_depth_occlusion_clip pass.
-    // We invert it into ARM's "high = disocclusion" network input.
-    .addTexture("tDisocclusionConfidence", "float")
-    // ── inputs at output-res / feedback at render-res ──
-    .addTexture("tHistory", "float")       // previous frame upscaled colour, output-res
-    .addTexture("tFeedbackIn", "float")    // 4-ch feedback tensor from previous frame, render-res
-    // ── settings ──
-    .addUniform("settings", NSS_SETTINGS_STRUCT)
-    // ── outputs ──
-    // Single rgba16f 3D storage texture holds the 12-channel input tensor
-    // packed across depth=3 layers (4 channels each). rgba16f gives the
-    // network ~10 bits of mantissa per channel, which is plenty for
-    // normalized [0, 1] inputs after the network's first BN/scale.
-    .addStorageTexture("tTensor", "rgba16float", "3d", "write-only")
-    // Nearest-depth offset packed as (dx+1, dy+1) / 2 -> [0, 1]. Postprocess
-    // uses this to fetch the velocity at the dilated coordinate when warping
-    // the history at output-resolution.
-    .addStorageTexture("tNearestOffset", "rg8unorm", "2d", "write-only")
-;
-
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const NSS_EXPOSURE: f32 = 7.38905609893; // e^2 — matches ARM's NSSCommon.ush
-
-// Karis tonemap (max-of-channels), applied to EXPOSURE-scaled colour.
-// ARM's training distribution: Tonemap(EXPOSURE * raw) -> network input.
-fn nss_tonemap_exposure(rgb: vec3<f32>) -> vec3<f32> {
-    let finite = select(vec3<f32>(0.0), clamp(rgb, vec3<f32>(0.0), vec3<f32>(F16_MAX)), rgb == rgb);
-    let scaled = finite * NSS_EXPOSURE;
-    let m = max(max(scaled.r, scaled.g), scaled.b);
-    return scaled / (1.0 + m);
-}
-
-// ARM's network was trained against inputs that go through their Quantize
-// formula: int8 = round(fp * 255 - 128). The conv then sees (uint8 - 128)
-// = signed int8 in [-128, 127] - i.e. fp 0 -> -128, fp 0.5 -> 0, fp 1 -> 127.
-// Our pipeline naively feeds fp [0, 1] which has DC offset +0.5 vs ARM's
-// expected DC of 0. The trained head biases were calibrated against that
-// near-zero DC, so feeding +0.5 puts every conv accumulator off by
-// (sum_of_weights * 0.5 * 255) - way outside the trained operating range.
-//
-// We use the SMOOTH (no-round) version of ARM's transform: a linear
-// remap [0, 1] -> approx [-1.008, 1.008] clamped to [-1, 1]. Matches
-// ARM's DC shift but without the round() discontinuities that caused
-// feature-dependent flickering when small jitter-driven input changes
-// pushed pixels across quantization boundaries. Network sensitivity to
-// near-boundary inputs would otherwise flip int8 outputs by 1/127 per
-// frame and propagate through every layer.
-//
-// Per-multiply lands at ~(ARM signed * int8_w) / 127^2, so our acc is
-// approx (ARM int32_acc / 127^2). Our rescale_factor (= 127 * mult /
-// 2^shift) then produces value_fp ~ int8_in / 127 going into the LUT -
-// the shape ARM's network was trained to produce.
-fn nss_arm_quantize(fp: f32) -> f32 {
-    return clamp(fp * (255.0 / 127.0) - (128.0 / 127.0), -1.0, 1.0);
-}
-
-fn nss_arm_quantize_v3(rgb: vec3<f32>) -> vec3<f32> {
-    return vec3<f32>(nss_arm_quantize(rgb.r), nss_arm_quantize(rgb.g), nss_arm_quantize(rgb.b));
-}
-
-fn nss_arm_quantize_v4(v: vec4<f32>) -> vec4<f32> {
-    return vec4<f32>(nss_arm_quantize(v.x), nss_arm_quantize(v.y), nss_arm_quantize(v.z), nss_arm_quantize(v.w));
-}
-
-fn nss_warp_history_sample(prev_uv: vec2<f32>) -> vec3<f32> {
-    let on_screen = all(prev_uv >= vec2<f32>(0.0)) && all(prev_uv <= vec2<f32>(1.0));
-    if (!on_screen) {
-        return vec3<f32>(0.0);
-    }
-    // ARM uses bilinear (LoadHistory in ffx_nss_callbacks_glsl.h:471);
-    // Catmull-Rom is opt-in via HISTORY_CATMULL define.
-    return max(vec3<f32>(0.0), textureSampleLevel(tHistory, sLinear, prev_uv, 0.0).rgb);
-}
-
-fn nss_warp_feedback_sample(prev_uv_render: vec2<f32>) -> vec4<f32> {
-    let on_screen = all(prev_uv_render >= vec2<f32>(0.0)) && all(prev_uv_render <= vec2<f32>(1.0));
-    if (!on_screen) {
-        return vec4<f32>(0.0);
-    }
-    return textureSampleLevel(tFeedbackIn, sLinear, prev_uv_render, 0.0);
-}
-
-@compute @workgroup_size(${NSS_WORKGROUP_SIZE}, ${NSS_WORKGROUP_SIZE}, 1)
-fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
-    let render_res_u = settings.render_resolution;
-    let render_res = vec2<i32>(render_res_u);
-
-    if (any(gid.xy >= render_res_u)) {
-        return;
-    }
-
-    let st = vec2<i32>(gid.xy);
-
-    // 1. Depth dilation
-    var nearest_off = vec2<i32>(0, 0);
-    let _dilated_depth = nss_find_nearest_depth(tDepthCurrent, st, render_res, &nearest_off);
-
-    // 2. Velocity at the depth-nearest tap (FSR2 strategy — sharpens
-    //    silhouettes at disocclusion vs picking velocity at the centre).
-    let velocity = textureLoad(tVelocity, st + nearest_off, 0).rg;
-
-    // 3. Reproject to previous frame
-    let st_centre = vec2<f32>(st) + 0.5;
-    let prev_st_render = st_centre - velocity;
-    let prev_uv_render = prev_st_render / vec2<f32>(render_res);
-
-    // History lives at output resolution but the UV is the same in [0, 1].
-    let history_rgb = nss_warp_history_sample(prev_uv_render);
-
-    // 4. Disocclusion mask. The shared depth-clip pass returns FSR2
-    //    confidence (1 = trust history, 0 = disocclusion); ARM's network
-    //    input expects the inverse (high = disocclusion). Multiply by
-    //    history_validity so a hard reset zeros the mask too.
-    let confidence = textureLoad(tDisocclusionConfidence, st, 0).r;
-    let disocclusion_mask = (1.0 - saturate(confidence)) * saturate(settings.history_validity);
-
-    // 5. Warped feedback. Multiplied by history_validity so the very first
-    //    frame (or any reset) feeds neutral (0.5 raw -> 0 post-quant)
-    //    feedback to the network instead of garbage from an uninitialised
-    //    texture.
-    //
-    //    feedback_scale (debug knob, default 1.0) blends between actual FB
-    //    and the neutral value 0.5. At 0 the network sees raw 0.5 across
-    //    all FB channels, which post-quantize is ≈0 — the trained
-    //    "no signal" point, NOT a strong negative signal.
-    let feedback_actual = nss_warp_feedback_sample(prev_uv_render);
-    let feedback_neutral = vec4<f32>(0.5);
-    let feedback = mix(
-        feedback_neutral,
-        feedback_actual,
-        saturate(settings.history_validity) * saturate(settings.feedback_scale),
-    );
-
-    // 6. Current colour (load, no filtering — already at render-res)
-    let current_rgb = max(vec3<f32>(0.0), textureLoad(tColour, st, 0).rgb);
-
-    // 7. Luma derivative — uses raw colours; the chunk handles its own scaling.
-    let luma_deriv = nss_luma_derivative(current_rgb, history_rgb);
-
-    // Tonemap with EXPOSURE applied first — matches ARM's
-    // Tonemap(EXPOSURE * raw) training distribution. Raw [0, 1] tonemap
-    // (without exposure) lands values 2-5x below the network's trained
-    // operating point.
-    let history_t = nss_tonemap_exposure(history_rgb);
-    let current_t = nss_tonemap_exposure(current_rgb);
-
-    // Apply ARM's Quantize transformation in fp — converts our [0, 1] inputs
-    // into the [-1, 1] signed-int8 / 127 distribution the trained network
-    // expects (DC at 0, not +0.5). See nss_arm_quantize header for derivation.
-    // settings.quantize_inputs (default 1.0) blends between this transform
-    // and the raw [0, 1] tonemap (0.0). Useful as an A/B test knob.
-    let q = saturate(settings.quantize_inputs);
-    let history_q = mix(history_t, nss_arm_quantize_v3(history_t), q);
-    let current_q = mix(current_t, nss_arm_quantize_v3(current_t), q);
-    let disocclusion_q = mix(disocclusion_mask, nss_arm_quantize(disocclusion_mask), q);
-    let feedback_q = mix(feedback, nss_arm_quantize_v4(feedback), q);
-    let luma_deriv_q = mix(luma_deriv, nss_arm_quantize(luma_deriv), q);
-
-    // ── Pack into 12-channel tensor ──
-    // Layout (4ch × depth=3):
-    //   z=0 : history.rgb, current.r
-    //   z=1 : current.gb, disocclusion_mask, feedback.r
-    //   z=2 : feedback.gba, luma_derivative
-    textureStore(tTensor, vec3<i32>(st, 0), vec4<f32>(history_q, current_q.r));
-    textureStore(tTensor, vec3<i32>(st, 1), vec4<f32>(current_q.g, current_q.b, disocclusion_q, feedback_q.r));
-    textureStore(tTensor, vec3<i32>(st, 2), vec4<f32>(feedback_q.gba, luma_deriv_q));
-
-    // Pack nearest offset for postprocess: (-1, 0, 1) in each axis -> [0, 1]
-    //
-    // NOTE there are two offset codecs in flight per frame under NSS. This packs (offset + 1) * 0.5
-    // into the rg of its own rg8unorm texture and shader_nss_postprocess decodes it inline; the TAA
-    // depth-clip pass, which runs unconditionally and whose confidence output NSS consumes, packs
-    // index/8 into one channel of its own output through chunk_depth_clip_offset_codec, which has a
-    // round-trip spec. The 9-tap search itself is now shared (chunk_find_nearest_depth), so the two
-    // agree on what they are encoding — but the search still runs twice over the same depth buffer and
-    // a reader has to check which convention a given rg8unorm offset texture uses.
-    //
-    // Collapsing them means this pass reading the depth-clip g channel instead of writing
-    // tNearestOffset, which changes what NSS is bound to and what its postprocess pair decodes. That is
-    // a pipeline change with a visual outcome rather than a de-duplication, so it wants a measured
-    // before/after on hardware; left as is deliberately. See DUP-039.
-    let nearest_packed = (vec2<f32>(nearest_off) + 1.0) * 0.5;
-    textureStore(tNearestOffset, st, vec4<f32>(nearest_packed, 0.0, 0.0));
-}
-    `, [
-        F16_MAX_DEFINITION,
-        chunk_nss_find_nearest_depth,
-        chunk_nss_luma_derivative,
-        NSS_SETTINGS_STRUCT.declaration_chunk,
-    ]
-);
-
-export const shader_nss_preprocess = ComputeShader.from({
-    label: "NSS / preprocess",
-    body,
-    resources,
-});
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { F16_MAX_DEFINITION } from "../../shader/chunk/math/F16_MAX_DEFINITION.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { chunk_nss_find_nearest_depth } from "./chunk_nss_find_nearest_depth.js";
+import { chunk_nss_luma_derivative } from "./chunk_nss_luma_derivative.js";
+import { NSS_WORKGROUP_SIZE } from "./NSS_CONSTANTS.js";
+import { NSS_SETTINGS_STRUCT } from "./NSS_SETTINGS_STRUCT.js";
+
+/**
+ * NSS preprocess pass. Runs at render-resolution (one thread per render-res
+ * pixel) and produces:
+ *  1. The 12-channel network input tensor, packed into a single rgba16f
+ *     3D storage texture with depth=3 (channels 0..3, 4..7, 8..11).
+ *  2. The encoded "nearest depth offset" used by postprocess to dilate
+ *     velocity at output-res (`tNearestOffset` — components in [0, 1]
+ *     decode to {-1, 0, 1}² via `(x*2 - 1)`).
+ *
+ * Per-pixel logic (matches the algorithm in ARM's `Preprocess()`):
+ *   1. Dilate depth over a 3×3 neighbourhood, remember the offset of the
+ *      nearest sample.
+ *   2. Sample velocity at the dilated coord.
+ *   3. Project to the previous frame, sample warped history (bilinear).
+ *   4. Read the FSR2 depth-clip confidence from the upstream pass and
+ *      invert it into the network's "high = disocclusion" convention.
+ *   5. Sample the warped feedback tensor (bilinear).
+ *   6. Compute the luma derivative between current and warped history.
+ *   7. Pack everything into the output tensor — colours
+ *      tonemapped via `Tonemap(EXPOSURE * raw)` to match ARM's training
+ *      distribution.
+ *
+ * @see ARM NSS reference: `Preprocess` in
+ *      `Source/NG-SDK/sdk/include/FidelityFX/gpu/nss/ffx_nss_preprocess.h`
+ */
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    // ── inputs at render-res ──
+    .addTexture("tColour", "float")                          // jittered scene colour, render-res
+    // depth32float can't be bound as 'float' (filterable) — WebGPU only
+    // accepts depth textures via 'unfilterable-float' in this context.
+    // We only ever read this via textureLoad inside the depth dilation.
+    .addTexture("tDepthCurrent", "unfilterable-float")
+    .addTexture("tVelocity", "float")                        // pixel-space motion vectors, render-res
+    // FSR2 depth-clip confidence (1 = trust history, 0 = disocclusion)
+    // produced by the engine's shared shader_depth_occlusion_clip pass.
+    // We invert it into ARM's "high = disocclusion" network input.
+    .addTexture("tDisocclusionConfidence", "float")
+    // ── inputs at output-res / feedback at render-res ──
+    .addTexture("tHistory", "float")       // previous frame upscaled colour, output-res
+    .addTexture("tFeedbackIn", "float")    // 4-ch feedback tensor from previous frame, render-res
+    // ── settings ──
+    .addUniform("settings", NSS_SETTINGS_STRUCT)
+    // ── outputs ──
+    // Single rgba16f 3D storage texture holds the 12-channel input tensor
+    // packed across depth=3 layers (4 channels each). rgba16f gives the
+    // network ~10 bits of mantissa per channel, which is plenty for
+    // normalized [0, 1] inputs after the network's first BN/scale.
+    .addStorageTexture("tTensor", "rgba16float", "3d", "write-only")
+    // Nearest-depth offset packed as (dx+1, dy+1) / 2 -> [0, 1]. Postprocess
+    // uses this to fetch the velocity at the dilated coordinate when warping
+    // the history at output-resolution.
+    .addStorageTexture("tNearestOffset", "rg8unorm", "2d", "write-only")
+;
+
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NSS_EXPOSURE: f32 = 7.38905609893; // e^2
+
+// Karis tonemap (max-of-channels), applied to EXPOSURE-scaled colour.
+// ARM's training distribution: Tonemap(EXPOSURE * raw) -> network input.
+fn nss_tonemap_exposure(rgb: vec3<f32>) -> vec3<f32> {
+    let finite = select(vec3<f32>(0.0), clamp(rgb, vec3<f32>(0.0), vec3<f32>(F16_MAX)), rgb == rgb);
+    let scaled = finite * NSS_EXPOSURE;
+    let m = max(max(scaled.r, scaled.g), scaled.b);
+    return scaled / (1.0 + m);
+}
+
+// ARM's network was trained against inputs that go through their Quantize
+// formula: int8 = round(fp * 255 - 128). The conv then sees (uint8 - 128)
+// = signed int8 in [-128, 127] - i.e. fp 0 -> -128, fp 0.5 -> 0, fp 1 -> 127.
+// Our pipeline naively feeds fp [0, 1] which has DC offset +0.5 vs ARM's
+// expected DC of 0. The trained head biases were calibrated against that
+// near-zero DC, so feeding +0.5 puts every conv accumulator off by
+// (sum_of_weights * 0.5 * 255) - way outside the trained operating range.
+//
+// We use the SMOOTH (no-round) version of ARM's transform: a linear
+// remap [0, 1] -> approx [-1.008, 1.008] clamped to [-1, 1]. Matches
+// ARM's DC shift but without the round() discontinuities that caused
+// feature-dependent flickering when small jitter-driven input changes
+// pushed pixels across quantization boundaries. Network sensitivity to
+// near-boundary inputs would otherwise flip int8 outputs by 1/127 per
+// frame and propagate through every layer.
+//
+// Per-multiply lands at ~(ARM signed * int8_w) / 127^2, so our acc is
+// approx (ARM int32_acc / 127^2). Our rescale_factor (= 127 * mult /
+// 2^shift) then produces value_fp ~ int8_in / 127 going into the LUT -
+// the shape ARM's network was trained to produce.
+fn nss_arm_quantize(fp: f32) -> f32 {
+    return clamp(fp * (255.0 / 127.0) - (128.0 / 127.0), -1.0, 1.0);
+}
+
+fn nss_arm_quantize_v3(rgb: vec3<f32>) -> vec3<f32> {
+    return vec3<f32>(nss_arm_quantize(rgb.r), nss_arm_quantize(rgb.g), nss_arm_quantize(rgb.b));
+}
+
+fn nss_arm_quantize_v4(v: vec4<f32>) -> vec4<f32> {
+    return vec4<f32>(nss_arm_quantize(v.x), nss_arm_quantize(v.y), nss_arm_quantize(v.z), nss_arm_quantize(v.w));
+}
+
+fn nss_warp_history_sample(prev_uv: vec2<f32>) -> vec3<f32> {
+    let on_screen = all(prev_uv >= vec2<f32>(0.0)) && all(prev_uv <= vec2<f32>(1.0));
+    if (!on_screen) {
+        return vec3<f32>(0.0);
+    }
+    // ARM uses bilinear (LoadHistory in ffx_nss_callbacks_glsl.h:471);
+    // Catmull-Rom is opt-in via HISTORY_CATMULL define.
+    return max(vec3<f32>(0.0), textureSampleLevel(tHistory, sLinear, prev_uv, 0.0).rgb);
+}
+
+fn nss_warp_feedback_sample(prev_uv_render: vec2<f32>) -> vec4<f32> {
+    let on_screen = all(prev_uv_render >= vec2<f32>(0.0)) && all(prev_uv_render <= vec2<f32>(1.0));
+    if (!on_screen) {
+        return vec4<f32>(0.0);
+    }
+    return textureSampleLevel(tFeedbackIn, sLinear, prev_uv_render, 0.0);
+}
+
+@compute @workgroup_size(${NSS_WORKGROUP_SIZE}, ${NSS_WORKGROUP_SIZE}, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let render_res_u = settings.render_resolution;
+    let render_res = vec2<i32>(render_res_u);
+
+    if (any(gid.xy >= render_res_u)) {
+        return;
+    }
+
+    let st = vec2<i32>(gid.xy);
+
+    // 1. Depth dilation
+    var nearest_off = vec2<i32>(0, 0);
+    let _dilated_depth = nss_find_nearest_depth(tDepthCurrent, st, render_res, &nearest_off);
+
+    // 2. Velocity at the depth-nearest tap (FSR2 strategy — sharpens
+    //    silhouettes at disocclusion vs picking velocity at the centre).
+    let velocity = textureLoad(tVelocity, st + nearest_off, 0).rg;
+
+    // 3. Reproject to previous frame
+    let st_centre = vec2<f32>(st) + 0.5;
+    let prev_st_render = st_centre - velocity;
+    let prev_uv_render = prev_st_render / vec2<f32>(render_res);
+
+    // History lives at output resolution but the UV is the same in [0, 1].
+    let history_rgb = nss_warp_history_sample(prev_uv_render);
+
+    // 4. Disocclusion mask. The shared depth-clip pass returns FSR2
+    //    confidence (1 = trust history, 0 = disocclusion); ARM's network
+    //    input expects the inverse (high = disocclusion). Multiply by
+    //    history_validity so a hard reset zeros the mask too.
+    let confidence = textureLoad(tDisocclusionConfidence, st, 0).r;
+    let disocclusion_mask = (1.0 - saturate(confidence)) * saturate(settings.history_validity);
+
+    // 5. Warped feedback. Multiplied by history_validity so the very first
+    //    frame (or any reset) feeds neutral (0.5 raw -> 0 post-quant)
+    //    feedback to the network instead of garbage from an uninitialised
+    //    texture.
+    //
+    //    feedback_scale (debug knob, default 1.0) blends between actual FB
+    //    and the neutral value 0.5. At 0 the network sees raw 0.5 across
+    //    all FB channels, which post-quantize is ≈0 — the trained
+    //    "no signal" point, NOT a strong negative signal.
+    let feedback_actual = nss_warp_feedback_sample(prev_uv_render);
+    let feedback_neutral = vec4<f32>(0.5);
+    let feedback = mix(
+        feedback_neutral,
+        feedback_actual,
+        saturate(settings.history_validity) * saturate(settings.feedback_scale),
+    );
+
+    // 6. Current colour (load, no filtering — already at render-res)
+    let current_rgb = max(vec3<f32>(0.0), textureLoad(tColour, st, 0).rgb);
+
+    // 7. Luma derivative — uses raw colours; the chunk handles its own scaling.
+    let luma_deriv = nss_luma_derivative(current_rgb, history_rgb);
+
+    // Tonemap with EXPOSURE applied first — matches ARM's
+    // Tonemap(EXPOSURE * raw) training distribution. Raw [0, 1] tonemap
+    // (without exposure) lands values 2-5x below the network's trained
+    // operating point.
+    let history_t = nss_tonemap_exposure(history_rgb);
+    let current_t = nss_tonemap_exposure(current_rgb);
+
+    // Apply ARM's Quantize transformation in fp — converts our [0, 1] inputs
+    // into the [-1, 1] signed-int8 / 127 distribution the trained network
+    // expects (DC at 0, not +0.5). See nss_arm_quantize header for derivation.
+    // settings.quantize_inputs (default 1.0) blends between this transform
+    // and the raw [0, 1] tonemap (0.0). Useful as an A/B test knob.
+    let q = saturate(settings.quantize_inputs);
+    let history_q = mix(history_t, nss_arm_quantize_v3(history_t), q);
+    let current_q = mix(current_t, nss_arm_quantize_v3(current_t), q);
+    let disocclusion_q = mix(disocclusion_mask, nss_arm_quantize(disocclusion_mask), q);
+    let feedback_q = mix(feedback, nss_arm_quantize_v4(feedback), q);
+    let luma_deriv_q = mix(luma_deriv, nss_arm_quantize(luma_deriv), q);
+
+    // ── Pack into 12-channel tensor ──
+    // Layout (4ch × depth=3):
+    //   z=0 : history.rgb, current.r
+    //   z=1 : current.gb, disocclusion_mask, feedback.r
+    //   z=2 : feedback.gba, luma_derivative
+    textureStore(tTensor, vec3<i32>(st, 0), vec4<f32>(history_q, current_q.r));
+    textureStore(tTensor, vec3<i32>(st, 1), vec4<f32>(current_q.g, current_q.b, disocclusion_q, feedback_q.r));
+    textureStore(tTensor, vec3<i32>(st, 2), vec4<f32>(feedback_q.gba, luma_deriv_q));
+
+    // Pack nearest offset for postprocess: (-1, 0, 1) in each axis -> [0, 1]
+    //
+    // NOTE there are two offset codecs in flight per frame under NSS. This packs (offset + 1) * 0.5
+    // into the rg of its own rg8unorm texture and shader_nss_postprocess decodes it inline; the TAA
+    // depth-clip pass, which runs unconditionally and whose confidence output NSS consumes, packs
+    // index/8 into one channel of its own output through chunk_depth_clip_offset_codec, which has a
+    // round-trip spec. The 9-tap search itself is now shared (chunk_find_nearest_depth), so the two
+    // agree on what they are encoding — but the search still runs twice over the same depth buffer and
+    // a reader has to check which convention a given rg8unorm offset texture uses.
+    //
+    // Collapsing them means this pass reading the depth-clip g channel instead of writing
+    // tNearestOffset, which changes what NSS is bound to and what its postprocess pair decodes. That is
+    // a pipeline change with a visual outcome rather than a de-duplication, so it wants a measured
+    // before/after on hardware; left as is deliberately. See DUP-039.
+    let nearest_packed = (vec2<f32>(nearest_off) + 1.0) * 0.5;
+    textureStore(tNearestOffset, st, vec4<f32>(nearest_packed, 0.0, 0.0));
+}
+    `, [
+        F16_MAX_DEFINITION,
+        chunk_nss_find_nearest_depth,
+        chunk_nss_luma_derivative,
+        NSS_SETTINGS_STRUCT.declaration_chunk,
+    ]
+);
+
+export const shader_nss_preprocess = ComputeShader.from({
+    label: "NSS / preprocess",
+    body,
+    resources,
+});

package/src/shade/renderer/rasterize/chunk_triangle_winding_is_reversed.d.ts

@@ -3,8 +3,7 @@
  * place — because there is more than one reason to reverse and they are not independent of each
  * other.
  *
- * Feed the answer to `triangle_list_reverse_winding`. Nanite's `ReverseWindingOrder` is the same
- * function for the same reason: a GPU-driven draw mixes instances that disagree about this, so it
+ * Feed the answer to `triangle_list_reverse_winding`: a GPU-driven draw mixes instances that disagree about this, so it
  * cannot be pipeline state, and every reason has to be combined before the corner is chosen.
  *
  * @see chunk_triangle_list_reverse_winding

package/src/shade/renderer/rasterize/chunk_triangle_winding_is_reversed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_triangle_winding_is_reversed.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/chunk_triangle_winding_is_reversed.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,iDAFU,SAAS,CAmBb;0BA/BoB,iCAAiC"}
+{"version":3,"file":"chunk_triangle_winding_is_reversed.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/rasterize/chunk_triangle_winding_is_reversed.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,iDAFU,SAAS,CAmBb;0BA9BoB,iCAAiC"}

package/src/shade/renderer/rasterize/chunk_triangle_winding_is_reversed.js

@@ -1,35 +1,34 @@
-import { chunk_material_draw_side } from "../material/chunk_material_draw_side.js";
-import { chunk_node3d_flags } from "../scene/chunk_node3d_flags.js";
-import { NODE3D_STRUCT } from "../scene/NODE3D_STRUCT.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-
-/**
- * The whole of what a vertex shader needs to know to emit a triangle the right way round, in one
- * place — because there is more than one reason to reverse and they are not independent of each
- * other.
- *
- * Feed the answer to `triangle_list_reverse_winding`. Nanite's `ReverseWindingOrder` is the same
- * function for the same reason: a GPU-driven draw mixes instances that disagree about this, so it
- * cannot be pipeline state, and every reason has to be combined before the corner is chosen.
- *
- * @see chunk_triangle_list_reverse_winding
- * @type {CodeChunk}
- */
-export const chunk_triangle_winding_is_reversed = CodeChunk.from(
-    //language=WGSL
-    `
-/**
- * Whether this instance's triangles must be emitted back to front.
- *
- * Two reasons, and they cancel: the instance's transform reflects, or the material asks for the
- * back face. A back-sided material on a mirrored instance is wound like a front-sided one on an
- * ordinary instance, and draws with the same pipeline state as both.
- */
-fn triangle_winding_is_reversed( node: ${NODE3D_STRUCT.wgsl_ref}, draw_side: u32 ) -> bool{
-    return node3d_global_is_mirrored(node) != material_draws_back_side(draw_side);
-}
-`, [
-        NODE3D_STRUCT.declaration_chunk,
-        chunk_node3d_flags,
-        chunk_material_draw_side,
-    ])
+import { chunk_material_draw_side } from "../material/chunk_material_draw_side.js";
+import { chunk_node3d_flags } from "../scene/chunk_node3d_flags.js";
+import { NODE3D_STRUCT } from "../scene/NODE3D_STRUCT.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+
+/**
+ * The whole of what a vertex shader needs to know to emit a triangle the right way round, in one
+ * place — because there is more than one reason to reverse and they are not independent of each
+ * other.
+ *
+ * Feed the answer to `triangle_list_reverse_winding`: a GPU-driven draw mixes instances that disagree about this, so it
+ * cannot be pipeline state, and every reason has to be combined before the corner is chosen.
+ *
+ * @see chunk_triangle_list_reverse_winding
+ * @type {CodeChunk}
+ */
+export const chunk_triangle_winding_is_reversed = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * Whether this instance's triangles must be emitted back to front.
+ *
+ * Two reasons, and they cancel: the instance's transform reflects, or the material asks for the
+ * back face. A back-sided material on a mirrored instance is wound like a front-sided one on an
+ * ordinary instance, and draws with the same pipeline state as both.
+ */
+fn triangle_winding_is_reversed( node: ${NODE3D_STRUCT.wgsl_ref}, draw_side: u32 ) -> bool{
+    return node3d_global_is_mirrored(node) != material_draws_back_side(draw_side);
+}
+`, [
+        NODE3D_STRUCT.declaration_chunk,
+        chunk_node3d_flags,
+        chunk_material_draw_side,
+    ])

package/src/shade/renderer/shader/chunk/atmosphere/C_MIE_SCATTERING_DECLARATION.d.ts

@@ -7,7 +7,7 @@ export const C_MIE_SCATTERING_DECLARATION: CodeChunk;
  * Mie extinction: scattering plus absorption. Hillaire's Earth authors this and the scattering,
  * not the absorption -- 0.004440 and 0.003996 per km.
  *
- * @see https://github.com/sebh/UnrealEngineSkyAtmosphere/blob/183ead5bdacc701b3b626347a680a2f3cd3d4fbd/Application/SkyAtmosphereCommon.cpp#L40
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
  */
 export const C_MIE_EXTINCTION_DECLARATION: CodeChunk;
 /**
@@ -15,7 +15,7 @@ export const C_MIE_EXTINCTION_DECLARATION: CodeChunk;
  * a tenth of the extinction. The shadertoy port wrote the 4.4 extinction here as the absorption,
  * which put the extinction at 8.396e-6.
  *
- * @see https://github.com/sebh/UnrealEngineSkyAtmosphere/blob/183ead5bdacc701b3b626347a680a2f3cd3d4fbd/Application/Game.cpp#L707
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
  */
 export const C_MIE_ABSORPTION_DECLARATION: CodeChunk;
 import { CodeChunk } from "../../compiler/CodeChunk.js";

package/src/shade/renderer/shader/chunk/atmosphere/C_MIE_SCATTERING_DECLARATION.js

@@ -13,7 +13,7 @@ export const C_MIE_SCATTERING_DECLARATION = CodeChunk.from(
  * Mie extinction: scattering plus absorption. Hillaire's Earth authors this and the scattering,
  * not the absorption -- 0.004440 and 0.003996 per km.
  *
- * @see https://github.com/sebh/UnrealEngineSkyAtmosphere/blob/183ead5bdacc701b3b626347a680a2f3cd3d4fbd/Application/SkyAtmosphereCommon.cpp#L40
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
  */
 export const C_MIE_EXTINCTION_DECLARATION = CodeChunk.from(
     //language=WGSL
@@ -25,7 +25,7 @@ export const C_MIE_EXTINCTION_DECLARATION = CodeChunk.from(
  * a tenth of the extinction. The shadertoy port wrote the 4.4 extinction here as the absorption,
  * which put the extinction at 8.396e-6.
  *
- * @see https://github.com/sebh/UnrealEngineSkyAtmosphere/blob/183ead5bdacc701b3b626347a680a2f3cd3d4fbd/Application/Game.cpp#L707
+ * @see "A Scalable and Production Ready Sky and Atmosphere Rendering Technique", Hillaire (2020)
  */
 export const C_MIE_ABSORPTION_DECLARATION = CodeChunk.from(
     //language=WGSL

package/src/shade/renderer/shader/chunk/atmosphere/NOTES.md

@@ -1,5 +1,5 @@
 # references:
-https://github.com/sebh/UnrealEngineSkyAtmosphere
+https://sebh.github.io/publications/egsr2020.pdf
 https://www.shadertoy.com/view/slSXRW
 https://www.reddit.com/r/GraphicsProgramming/comments/osbbhg/shadertoy_implementation_of_a_scalable_and/
 https://github1s.com/Fewes/MinimalAtmosphere/blob/master/Assets/Atmosphere/Shaders/Atmosphere.cginc#L146