From 6d64674f7e3d00a9d18ec61eaf968ed37c8e849b Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Wed, 11 Feb 2026 07:48:56 +0100
Subject: fix: CNN test tool GPU readback with wgpuDevicePoll

Fixed buffer mapping callback mode mismatch causing Unknown status.
Changed from WaitAnyOnly+ProcessEvents to AllowProcessEvents+DevicePoll.

Readback now functional but CNN output incorrect (all white).
Issue isolated to tool-specific binding/uniform setup - CNNEffect
in demo works correctly.

Technical details:
- WGPUCallbackMode_WaitAnyOnly requires wgpuInstanceWaitAny
- Using wgpuInstanceProcessEvents with WaitAnyOnly never fires callback
- Fixed by using AllowProcessEvents mode + wgpuDevicePoll
- Removed debug output and platform warnings

Status: 36/36 tests pass, readback works, CNN shader issue remains.

handoff(Claude): CNN test tool readback fixed, output debugging needed
---
 doc/CNN_TEST_TOOL.md | 37 +++++++++++++++++++++++++++++++------
 doc/HOWTO.md         |  3 +++
 2 files changed, 34 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/CNN_TEST_TOOL.md b/doc/CNN_TEST_TOOL.md
index 09c55d4..e7d679e 100644
--- a/doc/CNN_TEST_TOOL.md
+++ b/doc/CNN_TEST_TOOL.md
@@ -178,12 +178,37 @@ assert mse < 10.0, f'MSE too high: {mse}'
 
 ## Known Issues
 
-**BUG: Black output (unknown cause)**
-- Tool produces all-black output despite correct architecture
-- Fixed ping-pong logic, RGBA16Float intermediates, proper pipelines
-- Shader compiles, GPU commands execute without errors
-- Possible causes: shader execution issue, synchronization, binding problem
-- Status: Under investigation
+**BUG: CNN produces incorrect output (all white)**
+- Readback works correctly (see Technical Notes below)
+- Shader compiles and executes without errors
+- Output is all white (255) regardless of input or blend setting
+- **Likely causes:**
+  - Uniform buffer layout mismatch between C++ and WGSL
+  - Texture binding issue (input not sampled correctly)
+  - Weight matrix initialization problem
+- CNNEffect works correctly in demo (visual validation confirms)
+- **Status:** Under investigation - rendering pipeline differs from demo's CNNEffect
+- **Workaround:** Use CNNEffect visual validation in demo until tool fixed
+
+---
+
+## Technical Notes (Readback Fix)
+
+**Original Bug:** Buffer mapping returned `WGPUMapAsyncStatus_Unknown` (status=5)
+
+**Root Cause:** Callback mode mismatch
+- Used `WGPUCallbackMode_WaitAnyOnly` (fires only during `wgpuInstanceWaitAny`)
+- Called `wgpuInstanceProcessEvents` in wait loop (wrong API for this mode)
+- Callback never fired → timeout → empty buffer
+
+**Fix Applied:**
+1. Changed callback mode to `WGPUCallbackMode_AllowProcessEvents`
+2. Replaced `wgpuInstanceProcessEvents` with `wgpuDevicePoll(device, true, nullptr)`
+3. Added pre-mapping device poll to ensure copy completes
+
+**Relevant Code:** `src/gpu/texture_readback.cc` lines 97-110
+
+**Reference:** WebGPU spec - Asynchronous Operations, Callback Modes
 
 ---
 
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index c0e9363..140c09f 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -165,6 +165,9 @@ See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
 ## CNN Testing
 
 ### Offline Shader Validation
+
+**Note:** Tool builds and runs but produces incorrect output. Use CNNEffect visual validation in demo. See `doc/CNN_TEST_TOOL.md`.
+
 ```bash
 # Test trained CNN on PNG input
 ./build/cnn_test input.png output.png
-- 
cgit v1.2.3