summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-09 12:37:57 +0100
committerskal <pascal.massimino@gmail.com>2026-02-09 12:37:57 +0100
commit655d0a627c17b598562616a269e53bf06124d43f (patch)
tree7af4bba4fd413ec3dc2fc0c9ac55d1c010732f8a
parent9f470ce9c629b8756a3b1b8b9d30e8cf643dbcbd (diff)
docs: Archive Feb 9 completed tasks and clarify build configs
- Move completed tasks (Uniform alignment, WGSL validation, test_demo fix) to COMPLETED.md - Clean up TODO.md and PROJECT_CONTEXT.md "Recently Completed" sections - Update HOWTO.md to clarify DEMO_ALL_OPTIONS enables STRIP_ALL - Note: test_demo PeakMeterEffect requires non-STRIP build Net: -26 lines (better context hygiene) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
-rw-r--r--PROJECT_CONTEXT.md43
-rw-r--r--TODO.md30
-rw-r--r--doc/COMPLETED.md29
-rw-r--r--doc/HOWTO.md8
4 files changed, 42 insertions, 68 deletions
diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md
index 636f339..7df7587 100644
--- a/PROJECT_CONTEXT.md
+++ b/PROJECT_CONTEXT.md
@@ -44,7 +44,7 @@ Style:
---
## Next Up
-- **Task #5: Spectral Brush Editor** [IN PROGRESS - February 6, 2026]
+- **Task #5: Spectral Brush Editor** [IN PROGRESS]
- Create web-based tool for procedurally tracing audio spectrograms
- Replace large .spec assets with tiny C++ code (50-100× compression)
- Phase 1: C++ runtime (`spectral_brush.h/cc` - Bezier curves + Gaussian profiles)
@@ -52,19 +52,13 @@ Style:
- Phase 3: File I/O (load .wav/.spec, export procedural_params.txt + C++ code)
- See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete design
-- **Task #72: Audio Pipeline Streamlining** [COMPLETED - February 8, 2026]
- - ✅ Optimize data flow: Zero heap allocations per frame achieved
- - ✅ Direct additive mixing: Ring buffer two-phase write API
- - ✅ Precision: float32 internal pipeline with explicit clipping
-
- **Visuals & Content**
- - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering.
- - [ ] **Task #53: Particles Shader Polish**: Improve visual quality of particles.
- - [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection.
+ - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering
+ - [ ] **Task #53: Particles Shader Polish**: Improve visual quality of particles
+ - [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection
- **Tooling & Optimization**
- - [ ] **Task #54: Tracy Integration**: Integrate Tracy debugger for performance profiling.
- - [x] **Task #39: Visual Debugging System**: Implemented wireframe primitives (Sphere, Cone, Cross, Trajectory) for debugging.
+ - [ ] **Task #54: Tracy Integration**: Integrate Tracy debugger for performance profiling
---
## Design Docs Quick Reference
@@ -99,32 +93,11 @@ For detailed documentation, use Read tool to load specific docs:
## Recently Completed (February 2026)
-- **Uniform Buffer Alignment Fix** (February 9) - Task #74: Fixed WebGPU validation errors caused by WGSL `vec3<f32>` alignment mismatches. Changed circle_mask_compute.wgsl padding from `vec3<f32>` to three `f32` fields. Demo now runs with 0 validation errors. Test suite: 32/33 passing (97%).
-
-- **Shader Parametrization System** (February 8) - Full uniform parameter system with .seq syntax support. FlashEffect now supports dynamic color/decay parameters computed per-frame. Critical WGSL alignment bugfix (vec3 = 16-byte aligned). Size: ~400-500 bytes. See `doc/COMPLETED.md` for details.
-
-- **Extended Shader Parametrization** (February 8) - Task #73 (2/4 effects complete):
- - ChromaAberrationEffect: Added offset_scale and angle parameters (diagonal/vertical aberration modes)
- - GaussianBlurEffect: Added strength parameter (configurable blur radius)
- - Both effects follow FlashEffect pattern (UniformHelper, params struct, .seq syntax)
- - Size: ~200-300 bytes per effect
-
-- **WGSL Shader Composability** - Extracted common utilities to `math/common_utils.wgsl`:
- - `transform_normal()` - 2 call sites (renderer_3d, mesh_render)
- - `spherical_uv()` / `spherical_uv_from_dir()` - 8 call sites (renderer_3d, skybox)
- - `grid_pattern()` - 2 call sites (renderer_3d)
- - Size savings: ~200 bytes net
+- **WGSL Uniform Buffer Validation (Task #75)** (February 9) - Standardized uniform buffer layout across all effects. Created validation tool (`validate_uniforms.py`) integrated into build. All effects now use `CommonPostProcessUniforms` (binding 2) + effect-specific params (binding 3). Added `UNIFORM_BUFFER_GUIDELINES.md`.
-- **Test Suite Optimization** - JitteredAudioBackendTest: 3.5s → 0.07s (50x speedup)
- - Reduced test duration and sleep times
- - Full CI suite now <1 second
+- **Uniform Buffer Alignment (Task #74)** (February 9) - Fixed WGSL `vec3<f32>` alignment issues. Changed padding from `vec3` to three `f32` fields in multiple shaders. Demo runs with 0 validation errors. Test suite: 32/33 passing (97%).
-- **CHECK_RETURN Macro System** - Error handling for recoverable errors:
- - `CHECK_RETURN_IF()` - Simple validation with return
- - `CHECK_RETURN_BEGIN/END` - Complex validation with cleanup
- - `WARN_IF()` - Non-fatal warnings
- - Applied to 5 call sites (asset_manager, test_demo)
- - Size impact: ~500 bytes saved in STRIP_ALL builds
+- **Shader Parametrization (Task #73)** (February 8) - Full uniform parameter system with .seq syntax. FlashEffect, ChromaAberrationEffect, GaussianBlurEffect now support dynamic parameters. Size: ~400-500 bytes. See `doc/COMPLETED.md` for details.
## Architectural Overview
diff --git a/TODO.md b/TODO.md
index a61ba59..46baa06 100644
--- a/TODO.md
+++ b/TODO.md
@@ -2,35 +2,7 @@
This file tracks prioritized tasks with detailed attack plans.
-**Note:** For a history of recently completed tasks, see `COMPLETED.md`.
-
-## Recently Completed (February 9, 2026)
-
-- [x] **Fix test_demo Black Screen**:
- - **Issue**: `test_demo` showed black screen because it failed to load its timeline sequence (`assets/test_demo.seq`).
- - **Fix**: Added missing `LoadTimeline` call in `src/test_demo.cc`.
- - **Result**: `FlashEffect` and `PeakMeterEffect` should now render correctly.
-
-- [x] **WGSL Uniform Buffer Validation & Consolidation (Task #75)**:
- - **Standardization**: Refactored `DistortEffect` and others to use `CommonPostProcessUniforms` (binding 2) + `EffectParams` (binding 3).
- - **Validation Tool**: Created `tools/validate_uniforms.py` to parse C++ and WGSL (including embedded strings) and verify size/alignment.
- - **Integration**: Added validation step to CMake build system.
- - **Cleanup**: Renamed generic `EffectParams` to specific names (`FadeParams`, `CircleMaskParams`, etc.) in WGSL and C++.
- - **Documentation**: Added `doc/UNIFORM_BUFFER_GUIDELINES.md` and updated `CONTRIBUTING.md`.
-
-- [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)
-
-- [x] **Shader Parametrization System**: Full uniform parameter system with .seq syntax support. FlashEffect now supports color/decay parameters with per-frame animation. See `COMPLETED.md` for details.
-- [x] **ChromaAberrationEffect Parametrization**: Added offset_scale and angle parameters. Supports diagonal and vertical aberration modes via .seq syntax.
-- [x] **GaussianBlurEffect Parametrization**: Added strength parameter. Replaces hardcoded blur radius with configurable value.
+**Note:** For completed tasks, see `doc/COMPLETED.md`.
---
diff --git a/doc/COMPLETED.md b/doc/COMPLETED.md
index a3c173d..49cfbe9 100644
--- a/doc/COMPLETED.md
+++ b/doc/COMPLETED.md
@@ -29,7 +29,34 @@ Detailed historical documents have been moved to `doc/archive/` for reference:
Use `read @doc/archive/FILENAME.md` to access archived documents.
-## Recently Completed (February 8, 2026)
+## Recently Completed (February 9, 2026)
+
+- [x] **WGSL Uniform Buffer Validation & Consolidation (Task #75)**
+ - **Goal**: Standardize uniform buffer usage across all post-process effects and add validation tooling
+ - **Implementation**:
+ - Refactored `DistortEffect` and others to use `CommonPostProcessUniforms` (binding 2) + `EffectParams` (binding 3)
+ - Created `tools/validate_uniforms.py` to parse C++ and WGSL (including embedded strings) and verify size/alignment
+ - Added validation step to CMake build system
+ - Renamed generic `EffectParams` to specific names (`FadeParams`, `CircleMaskParams`, etc.) in WGSL and C++
+ - Added `doc/UNIFORM_BUFFER_GUIDELINES.md` and updated `CONTRIBUTING.md`
+ - **Result**: Consistent binding layout across all effects, automatic validation on build
+
+- [x] **Uniform Buffer Alignment (Task #74)**
+ - **Goal**: Fix WGSL struct alignment issues causing validation errors and crashes
+ - **Implementation**:
+ - `circle_mask_compute.wgsl`: Changed `_pad: vec3<f32>` to three `f32` fields for correct 16-byte alignment
+ - `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, 32/33 tests passing (97%), 0 WebGPU validation errors
+
+- [x] **Fix test_demo Black Screen**
+ - **Issue**: `test_demo` showed black screen because it failed to load its timeline sequence (`assets/test_demo.seq`)
+ - **Fix**: Added missing `LoadTimeline` call in `src/test_demo.cc`
+ - **Result**: `FlashEffect` and `PeakMeterEffect` now render correctly
+
+## Previously Completed (February 8, 2026)
- [x] **Shader Parametrization System (Task #73 Phase 0)** (February 8, 2026)
- **Goal**: Enable per-frame dynamic parameters for shaders and effects via uniform buffers and .seq syntax
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 967b554..2595258 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -45,12 +45,14 @@ cmake --build build_final -j4
- STRIP_ALL: Full checks, no debug (~64k target)
- FINAL_STRIP: No checks, no debug (absolute minimum)
-### Developer Build
+### Developer Build (Tests + Tools)
```bash
-cmake -S . -B build -DDEMO_ALL_OPTIONS=ON
+cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4
```
-Enables tests, tools, size optimizations.
+Enables tests and tools without stripping debug features.
+
+**Note**: `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code (e.g., `test_demo` PeakMeterEffect). Use selective flags for debugging.
## Build System