From d594609420b3d0ca43d760ff043b3750e2be55ca Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Wed, 11 Feb 2026 07:11:59 +0100
Subject: fix: CNN test tool ping-pong bug and RGBA16Float intermediates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bugfixes:
- Fixed ping-pong logic: update current_input BEFORE flipping dst_idx
- Use RGBA16Float for intermediate layers (preserve [-1,1] range from tanh)
- Separate BGRA8Unorm final output texture for readback
- Create two pipelines: intermediate (RGBA16Float) and final (BGRA8Unorm)
- Fix all cleanup code to reference correct pipeline variables

Implementation:
- Intermediate textures use RGBA16Float to avoid clamping [-1,1] → [0,1]
- Final layer renders to separate BGRA8Unorm texture
- Correct texture view descriptors for each format
- Layer 0-1: render to RGBA16Float ping-pong textures
- Layer 2: render to BGRA8Unorm output texture

Documentation:
- Added CNN testing section to doc/HOWTO.md
- Updated CNN_TEST_TOOL.md with ground-truth comparison workflow
- Noted remaining black output bug (under investigation)

Status:
- Tool compiles and runs without GPU errors
- Architecture correct: ping-pong, format conversion, separate pipelines
- Output still all-black (unknown cause, needs debugging)
- All 36 tests still pass

handoff(Claude): CNN test tool bugfixes complete, black output remains

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/HOWTO.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

(limited to 'doc/HOWTO.md')

diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index ba550bb..c0e9363 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -162,6 +162,45 @@ See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
 
 ---
 
+## CNN Testing
+
+### Offline Shader Validation
+```bash
+# Test trained CNN on PNG input
+./build/cnn_test input.png output.png
+
+# Adjust blend amount (0.0 = original, 1.0 = full CNN)
+./build/cnn_test input.png output.png --blend 0.5
+
+# PPM output format
+./build/cnn_test input.png output.ppm --format ppm
+```
+
+### Ground Truth Comparison
+```bash
+# Generate Python ground truth
+./training/train_cnn.py --infer input.png \
+  --export-only checkpoints/checkpoint_epoch_1000.pth \
+  --output ground_truth.png
+
+# Run tool
+./build/cnn_test input.png tool_output.png
+
+# Compare (Python required)
+python3 -c "
+import numpy as np
+from PIL import Image
+gt = np.array(Image.open('ground_truth.png').convert('RGB'))
+out = np.array(Image.open('tool_output.png').convert('RGB'))
+mse = np.mean((gt.astype(float) - out.astype(float)) ** 2)
+print(f'MSE: {mse:.4f} (target: < 10.0)')
+"
+```
+
+See `doc/CNN_TEST_TOOL.md` for full documentation.
+
+---
+
 ## Additional Documentation
 
 - **Build System:** `doc/BUILD.md` - Multi-platform, size optimization
-- 
cgit v1.2.3