From 139059e1fdbcace3e233c6109a61446b14b774e4 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Tue, 10 Feb 2026 15:58:46 +0100
Subject: fix: Resolve CNN effect black screen bug (framebuffer capture +
 uniforms)

Two bugs causing black screen when CNN post-processing activated:

1. Framebuffer capture timing: Capture ran inside post-effect loop after
   ping-pong swaps, causing layers 1+ to capture wrong buffer. Moved
   capture before loop to copy framebuffer_a once before post-chain starts.

2. Missing uniforms update: CNNEffect never updated uniforms_ buffer,
   leaving uniforms.resolution uninitialized (0,0). UV calculation
   p.xy/uniforms.resolution produced NaN, causing all texture samples
   to return black. Added uniforms update in update_bind_group().

Files modified:
- src/gpu/effect.cc: Capture before post-chain (lines 308-346)
- src/gpu/effects/cnn_effect.cc: Add uniforms update (lines 132-142)
- workspaces/main/shaders/cnn/cnn_layer.wgsl: Remove obsolete comment
- doc/CNN_DEBUG.md: Historical debugging doc
- CLAUDE.md: Reference CNN_DEBUG.md in historical section

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/CNN_DEBUG.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 doc/CNN_DEBUG.md

(limited to 'doc/CNN_DEBUG.md')

diff --git a/doc/CNN_DEBUG.md b/doc/CNN_DEBUG.md
new file mode 100644
index 0000000..dba0b60
--- /dev/null
+++ b/doc/CNN_DEBUG.md
@@ -0,0 +1,43 @@
+# CNN Effect Black Screen Bug - Resolution (2026-02)
+
+## Problem
+CNN post-processing effect showed black screen when activated at 11.50s, despite scene rendering correctly before CNN started.
+
+## Root Causes
+
+### Bug 1: Framebuffer Capture Timing
+**Location**: `src/gpu/effect.cc`
+**Issue**: Capture ran INSIDE post-effect loop after ping-pong buffer swaps. CNN layers 1+ captured wrong buffer (output being written to, not scene).
+**Fix**: Moved capture before loop starts (lines 308-346). Capture now copies `framebuffer_a` to `captured_frame` auxiliary texture ONCE before any post-effects run.
+
+### Bug 2: Missing Uniforms Update ⚠️ CRITICAL
+**Location**: `src/gpu/effects/cnn_effect.cc`
+**Issue**: `CNNEffect::update_bind_group()` never updated `uniforms_` buffer. `uniforms.resolution` uninitialized (0,0 or garbage) → UV calculation `p.xy / uniforms.resolution` produced NaN → all texture samples black.
+**Fix**: Added uniforms update before bind group creation (lines 132-142):
+```cpp
+const CommonPostProcessUniforms u = {
+    .resolution = {(float)width_, (float)height_},
+    .aspect_ratio = (float)width_ / (float)height_,
+    .time = 0.0f,
+    .beat = 0.0f,
+    .audio_intensity = 0.0f,
+};
+uniforms_.update(ctx_.queue, u);
+```
+
+## Key Lessons
+
+1. **All post-process effects MUST update `uniforms_` buffer** - Required for UV calculations and shader parameters
+2. **Framebuffer capture timing is critical** - Must happen before post-chain ping-pong starts
+3. **Uninitialized uniforms cause silent failures** - Produces black output without validation errors
+4. **Post-effects must render or chain breaks** - `loadOp=Load` preserves previous (black) content if no draw call executes
+
+## Files Modified
+- `src/gpu/effect.cc`: Lines 308-346 (capture timing)
+- `src/gpu/effects/cnn_effect.cc`: Lines 132-142 (uniforms update)
+
+## Verification
+Test: `demo64k --seek 11.5`
+- ✅ Scene visible with RotatingCube
+- ✅ CNN stylization applied
+- ✅ All 3 layers process with correct original texture reference
-- 
cgit v1.2.3