From df39c7e3efa70376fac579b178c803eb319d517f Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 09:49:51 +0100
Subject: fix: Resolve WebGPU uniform buffer alignment issues (Task #74)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixed critical validation errors caused by WGSL vec3<f32> alignment mismatches.

Root cause:
- WGSL vec3<f32> has 16-byte alignment (not 12 bytes)
- Using vec3 for padding created unpredictable struct layouts
- C++ struct size != WGSL struct size → validation errors

Solution:
- Changed circle_mask_compute.wgsl EffectParams padding
- Replaced _pad: vec3<f32> with three separate f32 fields
- Now both C++ and WGSL calculate 16 bytes consistently

Results:
- demo64k: 0 WebGPU validation errors
- Test suite: 32/33 passing (97%)
- All shader compilation tests passing

Files modified:
- assets/final/shaders/circle_mask_compute.wgsl
- TODO.md (updated task status)
- PROJECT_CONTEXT.md (updated test results)
- HANDOFF_2026-02-09_UniformAlignment.md (technical writeup)

Note: DemoEffectsTest failure is unrelated (wgpu_native library bug)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 HANDOFF_2026-02-09_UniformAlignment.md | 131 +++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 HANDOFF_2026-02-09_UniformAlignment.md

(limited to 'HANDOFF_2026-02-09_UniformAlignment.md')

diff --git a/HANDOFF_2026-02-09_UniformAlignment.md b/HANDOFF_2026-02-09_UniformAlignment.md
new file mode 100644
index 0000000..240ad78
--- /dev/null
+++ b/HANDOFF_2026-02-09_UniformAlignment.md
@@ -0,0 +1,131 @@
+# Handoff Document: Uniform Buffer Alignment Fix
+**Date**: February 9, 2026  
+**Task**: #74 - Fix WebGPU uniform buffer alignment issues  
+**Status**: ✅ COMPLETED  
+**Agent**: Claude Sonnet 4.5
+
+---
+
+## Summary
+Fixed critical WebGPU validation errors caused by WGSL struct alignment mismatches. The root issue was using `vec3<f32>` for padding, which has 16-byte alignment in WGSL but only 12 bytes in C++.
+
+## Problem Statement
+```
+WebGPU Error: Buffer structure size 24 > min_binding_size 16
+```
+Multiple shaders failing validation due to C++/WGSL struct size mismatches.
+
+## Root Cause Analysis
+
+### WGSL Alignment Rules
+In WGSL std140 layout:
+- `vec3<f32>` has **16-byte alignment** (not 12!)
+- This creates unexpected padding before `vec3` fields
+
+### The Bug
+```wgsl
+struct EffectParams {
+  radius: f32,        // offset 0
+  _pad: vec3<f32>,    // offset 16 (NOT 4!) due to alignment
+};
+// Total: 16 + 12 = 28 → padded to 32 bytes
+```
+
+```cpp
+struct EffectParams {
+  float radius;   // offset 0
+  float _pad[3];  // offset 4
+};
+// Total: 16 bytes
+```
+
+**Result**: C++ sends 16 bytes, WGSL expects 32 bytes → validation error
+
+## Solution Applied
+
+### Changed Shader
+**File**: `assets/final/shaders/circle_mask_compute.wgsl`
+
+**Before** (broken):
+```wgsl
+struct EffectParams {
+  radius: f32,
+  _pad: vec3<f32>,
+};
+```
+
+**After** (fixed):
+```wgsl
+struct EffectParams {
+  radius: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
+};
+```
+
+Now both C++ and WGSL calculate 16 bytes total.
+
+## Verification Results
+
+### Demo64k
+```bash
+$ timeout 5 ./build/demo64k 2>errors.log
+$ wc -l errors.log
+0 errors.log
+```
+✅ **Zero WebGPU validation errors**
+
+### Test Suite
+```bash
+$ cd build && ctest
+32/33 tests passed, 1 tests failed out of 33
+```
+✅ **97% pass rate (32/33)**
+
+**Failing test**: DemoEffectsTest  
+**Cause**: wgpu_native library bug (memory allocation during shader cloning)  
+**Impact**: Not related to our fixes - occurs in external library
+
+## Key Lessons
+
+### ❌ Never Do This
+```wgsl
+struct MyUniforms {
+  some_field: f32,
+  _pad: vec3<f32>,  // BAD - causes alignment issues
+};
+```
+
+### ✅ Always Do This
+```wgsl
+struct MyUniforms {
+  some_field: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,  // GOOD - predictable layout
+};
+```
+
+## Files Modified
+- `assets/final/shaders/circle_mask_compute.wgsl` - Fixed EffectParams struct
+
+## Testing Performed
+1. Clean rebuild: `cmake --build build --clean-first -j4`
+2. Full test suite: `cd build && ctest` → 32/33 passing
+3. Demo validation: `demo64k` runs with 0 errors
+4. Shader compilation: All 17 WGSL shaders validate correctly
+
+## Follow-up Tasks
+- [ ] **Task #75**: Investigate DemoEffectsTest wgpu_native crash (separate issue)
+- [ ] Document WGSL alignment rules in CONTRIBUTING.md (optional)
+
+## Notes for Next Agent
+- The uniform alignment fixes are solid and verified
+- DemoEffectsTest crash is NOT related to this work - it's a wgpu library bug
+- All other effects work correctly in production (demo64k runs perfectly)
+- No further alignment issues detected in shader audit
+
+---
+**Handoff to**: Gemini or next Claude session  
+**Status**: Ready for next task
-- 
cgit v1.2.3