From 1e3813355e37f903314ec2069ff788c6f69becfd Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 23 Mar 2026 07:31:14 +0100
Subject: feat(cnn_v3): GBufferEffect temporal feedback via post_render()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add Effect::post_render() virtual hook, called after all effects in
  the sequence have rendered each frame. Default is no-op.
- Sequence::render_effects() runs a second pass invoking post_render()
  on all DAG nodes after the render pass completes.
- GBufferEffect: declare internal node_prev_tex_ (U8X4_NORM) for
  persistent prev-frame CNN output. post_render() copies cnn_output_node_
  → node_prev_tex_ via CopyTextureToTexture. render() binds node_prev_tex_
  as prev_cnn (binding 6) — zero on frame 0 (matches training convention).
- Expose set_cnn_output_node(name) API; call once at setup.
- Drop brittle ping-pong / input_nodes_[0] fallback.
- Update doc/SEQUENCE.md: post_render() semantics, frame execution order,
  temporal feedback canonical pattern, node types table with G-buffer types.
- Update cnn_v3/docs/HOWTO.md: temporal feedback wiring section.

36/36 tests passing.

handoff(Gemini): prev.rgb temporal feedback now correct and generic.
Set set_cnn_output_node("sink") (or CNN output node name) once at setup.
---
 cnn_v3/docs/HOWTO.md | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

(limited to 'cnn_v3/docs')

diff --git a/cnn_v3/docs/HOWTO.md b/cnn_v3/docs/HOWTO.md
index a1a5707..48b5d68 100644
--- a/cnn_v3/docs/HOWTO.md
+++ b/cnn_v3/docs/HOWTO.md
@@ -79,7 +79,7 @@ Each frame, `GBufferEffect::render()` executes:
 3. **Pass 3 — Transparency** — TODO (deferred; transp=0 for opaque scenes)
 
 4. **Pass 4 — Pack compute** (`gbuf_pack.wgsl`) ✅
-   - Reads all G-buffer textures + `prev_cnn` input
+   - Reads all G-buffer textures + persistent `prev_cnn` texture
    - Writes `feat_tex0` + `feat_tex1` (rgba32uint, 20 channels, 32 bytes/pixel)
    - Shadow / transp nodes cleared to 1.0 / 0.0 via zero-draw render passes
      until Pass 2/3 are implemented.
@@ -93,6 +93,23 @@ outputs[0]  → feat_tex0   (rgba32uint: albedo.rgb, normal.xy, depth, depth_gra
 outputs[1]  → feat_tex1   (rgba32uint: mat_id, prev.rgb, mip1.rgb, mip2.rgb, dif, transp)
 ```
 
+### Temporal feedback (prev.rgb)
+
+`GBufferEffect` owns a persistent internal node `<prefix>_prev` (rgba8unorm, `U8X4_NORM`).
+Each frame it is GPU-copied from the CNN effect's output before Pass 1 runs, then bound as
+`prev_cnn` in the pack shader (binding 6).
+
+**To wire temporal feedback**, call once after constructing the effects:
+```cpp
+gbuf->set_cnn_output_node("cnn_v3_out");  // name of CNNv3Effect's output node
+```
+
+Frame 0 behaviour: `_prev` is zeroed on allocation → `prev.rgb = 0`, matching the training
+convention (static frames use zero history).
+
+The copy uses `wgpuCommandEncoderCopyTextureToTexture` (no extra render pass overhead).
+Both textures must be `rgba8unorm` — the CNN output sink (`U8X4_NORM`) satisfies this.
+
 ---
 
 ## 1b. GBufferEffect — Implementation Plan (Pass 2: SDF Shadow)
@@ -299,8 +316,13 @@ This ensures the network works for both full G-buffer and photo-only inputs.
 ```seq
 # BPM 120
 SEQUENCE 0 0 "Scene with CNN v3"
-  EFFECT + GBufferEffect prev_cnn -> gbuf_feat0 gbuf_feat1  0 60
-  EFFECT + CNNv3Effect   gbuf_feat0 gbuf_feat1 -> sink       0 60
+  EFFECT + GBufferEffect source -> gbuf_feat0 gbuf_feat1  0 60
+  EFFECT + CNNv3Effect   gbuf_feat0 gbuf_feat1 -> sink    0 60
+```
+
+After constructing the effects, wire temporal feedback:
+```cpp
+gbuf_effect->set_cnn_output_node("sink");  // or whichever node receives CNN output
 ```
 
 FiLM parameters uploaded each frame:
@@ -459,8 +481,9 @@ GBufViewEffect(const GpuContext& ctx,
 
 ```cpp
 auto gbuf  = std::make_shared<GBufferEffect>(ctx,
-    std::vector<std::string>{"prev_cnn"},
+    std::vector<std::string>{},                            // no external inputs
     std::vector<std::string>{"gbuf_feat0", "gbuf_feat1"}, 0.0f, 60.0f);
+gbuf->set_cnn_output_node("cnn_out");  // wire temporal feedback after CNN is constructed
 auto gview = std::make_shared<GBufViewEffect>(ctx,
     std::vector<std::string>{"gbuf_feat0", "gbuf_feat1"},
     std::vector<std::string>{"gbuf_view_out"}, 0.0f, 60.0f);
-- 
cgit v1.2.3