diff options
Diffstat (limited to 'TODO.md')
| -rw-r--r-- | TODO.md | 74 |
1 files changed, 73 insertions, 1 deletions
@@ -6,7 +6,13 @@ This file tracks prioritized tasks with detailed attack plans. ## Recently Completed (February 9, 2026) -- [x] **Uniform Buffer Alignment (Task #74)**: Fixed WGSL struct alignment issues. Changed `vec3<f32>` padding to individual `f32` fields in circle_mask_compute.wgsl. Demo runs with 0 validation errors, 32/33 tests passing. +- [x] **Uniform Buffer Alignment (Task #74)**: Fixed WGSL struct alignment issues across multiple shaders: + - `circle_mask_compute.wgsl`: Changed `_pad: vec3<f32>` to three `f32` fields + - `fade_effect.cc`: Changed EffectParams padding from `vec3<f32>` to `_pad0/1/2: f32` + - `theme_modulation_effect.cc`: Same padding fix for EffectParams + - Fixed ODR violation in `demo_effects.h` (incomplete FadeEffect forward declaration) + - Renamed shadowing `uniforms_` members to `common_uniforms_`/`flash_uniforms_` + - Result: demo64k runs without crashes, 33/33 tests passing (100%) ## Previously Completed (February 8, 2026) @@ -37,6 +43,72 @@ This file tracks prioritized tasks with detailed attack plans. --- +## Priority 1: WGSL Uniform Buffer Validation & Consolidation (Task #75) + +**Goal**: Prevent alignment bugs by consolidating uniform buffer patterns and creating automated validation. + +**Background**: Recent bugs (Task #74) revealed WGSL `vec3<f32>` alignment issues causing 16-byte padding where 12 bytes expected. Need systematic approach to prevent recurrence. + +**Attack Plan**: + +### Phase 1: Audit & Document (1-2 hours) +- [ ] **1.1**: Audit all WGSL shaders for uniform struct definitions + - List all uniform structs, their sizes, and padding strategies + - Identify inconsistencies (vec3 padding vs individual f32 fields) + - Document in `doc/UNIFORM_BUFFER_GUIDELINES.md` +- [ ] **1.2**: Audit C++ struct definitions (CommonPostProcessUniforms, etc.) + - Verify static_assert size checks exist for all uniform structs + - Check for missing size validation + +### Phase 2: Consolidation (2-3 hours) +- [ ] **2.1**: Standardize on CommonUniforms pattern + - All post-process effects should use CommonPostProcessUniforms for binding 2 + - Effect-specific params at binding 3 (16 or 32 bytes, properly padded) +- [ ] **2.2**: Eliminate `vec3<f32>` in padding fields + - Replace all `_pad: vec3<f32>` with `_pad0/1/2: f32` + - Apply to: FadeEffect, ThemeModulationEffect, any other effects +- [ ] **2.3**: Add C++ wrapper structs with static_assert + - Every WGSL uniform struct should have matching C++ struct + - All structs require `static_assert(sizeof(...) == EXPECTED_SIZE)` + +### Phase 3: Validation Tool (3-4 hours) +- [ ] **3.1**: Create `tools/validate_uniforms.py` + - Parse WGSL shader files for uniform struct definitions + - Calculate expected size using WGSL alignment rules: + - `f32`: 4-byte aligned + - `vec2<f32>`: 8-byte aligned + - `vec3<f32>`: **16-byte aligned** (not 12!) + - `vec4<f32>`: 16-byte aligned + - Struct size: rounded to largest member alignment +- [ ] **3.2**: Parse C++ headers for matching structs + - Extract `sizeof()` from static_assert statements + - Match WGSL struct names to C++ struct names +- [ ] **3.3**: Report mismatches + - Exit non-zero if C++ size != WGSL size + - Print detailed alignment breakdown for debugging +- [ ] **3.4**: Integrate into CI/build system + - Add CMake custom command to run validation + - Fail build if validation fails (development builds only) + - Add to `scripts/check_all.sh` + +### Phase 4: Documentation (1 hour) +- [ ] **4.1**: Write `doc/UNIFORM_BUFFER_GUIDELINES.md` + - Explain WGSL alignment rules (with examples) + - Document standard patterns (CommonUniforms, effect params) + - Show correct padding techniques + - Add examples of common mistakes +- [ ] **4.2**: Update CONTRIBUTING.md + - Add "Uniform Buffer Checklist" section + - Require validation tool passes before commit + +**Size Impact**: Negligible (consolidation may save 50-100 bytes) + +**Priority**: High (prevents entire class of subtle bugs) + +**Dependencies**: None + +--- + ## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS] **Goal:** Create a web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` binary assets with tiny procedural C++ code (50-100× compression). |