Fix path-tracing history resets

Author: proggeramlug

docs/temporal-history.md

@@ -99,8 +99,23 @@ enable epoch:
 
 Telemetry exposes `temporal_history.exposure_valid` and `exposure_index`.
 
+## Path-tracing implementation
+
+PT history validity remains the path tracer's own sample count, which the
+kernel already receives as `size.w`:
+
+- every off/progressive/realtime mode transition resets the sample count,
+  ping-pong index, deterministic sequence, and ownership;
+- a zero sample count suppresses reprojection and now also suppresses
+  disocclusion neighbor seeding, so retained buffer bytes cannot resurrect
+  history after a toggle, camera cut, seed change, or diagnostic reset;
+- buffers are retained when compatible and recreated only when trace-grid size
+  changes, preserving the established steady-state memory and pass cost.
+
+Telemetry exposes `temporal_history.pt_samples` and `pt_index`.
+
 ## Remaining #135 work
 
-The next slices should give PT and any future temporal effect the same explicit
-lifetime rules, then add camera-cut/FOV-change resets, per-pixel rejection
-diagnostics, and the sequence-based motion corpus.
+The next slice should add the common camera-cut/FOV-change reset API, then
+continue with per-pixel rejection diagnostics and the sequence-based motion
+corpus.

native/shared/src/renderer/pt_pass.rs

@@ -13,6 +13,7 @@ impl Renderer {
         let mode = mode.min(2);
         if self.pt_mode != mode {
             self.pt_mode = mode;
+            self.reset_path_tracing_history(0);
             self.ssr_history_idx = 0;
             self.ssr_history_valid = false;
             self.probe_history_idx = 0;

native/shared/src/renderer/quality_capture.rs

@@ -550,6 +550,10 @@ impl Renderer {
         });
         out.push_str(",\"exposure_index\":");
         out.push_str(&self.exposure_current_idx.to_string());
+        out.push_str(",\"pt_samples\":");
+        out.push_str(&self.pt_accum_count.to_string());
+        out.push_str(",\"pt_index\":");
+        out.push_str(&self.pt_accum_idx.to_string());
         out.push('}');
         out.push_str(",\"transparent_gi\":{");
         out.push_str("\"enabled\":");

native/shared/src/renderer/shaders/pt.rs

@@ -1508,26 +1508,31 @@ fn cs_main(@builtin(global_invocation_id) gid: vec3<u32>) {
             var seed_m2 = 0.0;
             var seed_n = 0.0;
             var seed_w = 0.0;
-            // 7x7: under TRANSLATION a whole COLUMN of texels streams in per
-            // frame (rotation only trickles a few px), so a 5x5 often found
-            // nothing but fellow newborns and the band stayed raw.
-            for (var by = -3; by <= 3; by = by + 1) {
-                for (var bx = -3; bx <= 3; bx = bx + 1) {
-                    if (bx == 0 && by == 0) { continue; }
-                    let q = vec2<i32>(i32(gid.x) + bx, i32(gid.y) + by);
-                    if (q.x < 0 || q.y < 0 || q.x >= i32(u.size.x) || q.y >= i32(u.size.y)) {
-                        continue;
+            // A global reset leaves old bytes allocated, but size.w = 0
+            // makes them invalid. Do not let neighbour seeding resurrect
+            // those moments after a mode toggle, camera cut, or seed change.
+            if (u.size.w > 0u) {
+                // 7x7: under TRANSLATION a whole COLUMN of texels streams in
+                // per frame (rotation only trickles a few px), so a 5x5 often
+                // found nothing but fellow newborns and the band stayed raw.
+                for (var by = -3; by <= 3; by = by + 1) {
+                    for (var bx = -3; bx <= 3; bx = bx + 1) {
+                        if (bx == 0 && by == 0) { continue; }
+                        let q = vec2<i32>(i32(gid.x) + bx, i32(gid.y) + by);
+                        if (q.x < 0 || q.y < 0 || q.x >= i32(u.size.x) || q.y >= i32(u.size.y)) {
+                            continue;
+                        }
+                        let qidx = u32(q.y) * u.size.x + u32(q.x);
+                        let m = moments[qidx];
+                        if (m.w >= 0.9999999 || m.z < 4.0) { continue; }
+                        if (abs(lin_depth(m.w) - zl_here) > btol) { continue; }
+                        let wt = m.z;
+                        seed_rgb += accum[qidx].rgb * wt;
+                        seed_m1 += m.x * wt;
+                        seed_m2 += m.y * wt;
+                        seed_n += m.z * wt;
+                        seed_w += wt;
                     }
-                    let qidx = u32(q.y) * u.size.x + u32(q.x);
-                    let m = moments[qidx];
-                    if (m.w >= 0.9999999 || m.z < 4.0) { continue; }
-                    if (abs(lin_depth(m.w) - zl_here) > btol) { continue; }
-                    let wt = m.z;
-                    seed_rgb += accum[qidx].rgb * wt;
-                    seed_m1 += m.x * wt;
-                    seed_m2 += m.y * wt;
-                    seed_n += m.z * wt;
-                    seed_w += wt;
                 }
             }
             if (seed_w > 0.0) {

native/shared/src/renderer/shaders/pt_tests.rs

@@ -51,3 +51,18 @@ fn base_transport_uses_bounded_reciprocal_layered_contract() {
     assert!(production.contains("return diffuse + spec;"));
     assert!(!production.contains("return alb * lit + spec;"));
 }
+
+#[test]
+fn zero_sample_count_cannot_seed_from_retained_moments() {
+    let production = pt_kernel_variant(false);
+    let gate = production
+        .find("if (u.size.w > 0u) {")
+        .expect("neighbor seeding must have a global-history gate");
+    let neighbor_read = production[gate..]
+        .find("let m = moments[qidx];")
+        .expect("gate must enclose the disocclusion neighbor read");
+    let gate_end = production[gate..]
+        .find("if (seed_w > 0.0) {")
+        .expect("seed reduction follows the gated search");
+    assert!(neighbor_read < gate_end);
+}

native/shared/tests/golden_render/temporal_history.rs

@@ -264,3 +264,31 @@ fn exposure_history_seeds_each_enable_epoch_without_advancing_while_off() {
         .quality_runtime_paths_json()
         .contains("\"exposure_valid\":true,\"exposure_index\":1"));
 }
+
+#[test]
+fn path_tracing_mode_transitions_reset_incompatible_history() {
+    let _rt_guard = lock_rt_goldens();
+    let (mut eng, _) = match try_engine_rt() {
+        Ok(Some(pair)) => pair,
+        Ok(None) => {
+            skip_rt_golden("pt_history_lifetime", "no-non-cpu-ray-query-adapter");
+            return;
+        }
+        Err(err) => panic!("{err}"),
+    };
+    build_pt_scene(&mut eng);
+
+    eng.renderer.set_path_tracing(2);
+    let _ = render(&mut eng, 1, draw_pt_static_frame);
+    assert!(eng.renderer.path_tracing_sample_count() > 0);
+
+    eng.renderer.set_path_tracing(1);
+    assert_eq!(eng.renderer.path_tracing_sample_count(), 0);
+    assert!(eng
+        .renderer
+        .quality_runtime_paths_json()
+        .contains("\"pt_samples\":0,\"pt_index\":0"));
+
+    eng.renderer.set_path_tracing(0);
+    assert_eq!(eng.renderer.path_tracing_sample_count(), 0);
+}