diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-09 12:37:57 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-09 12:37:57 +0100 |
| commit | 655d0a627c17b598562616a269e53bf06124d43f (patch) | |
| tree | 7af4bba4fd413ec3dc2fc0c9ac55d1c010732f8a | |
| parent | 9f470ce9c629b8756a3b1b8b9d30e8cf643dbcbd (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.md | 43 | ||||
| -rw-r--r-- | TODO.md | 30 | ||||
| -rw-r--r-- | doc/COMPLETED.md | 29 | ||||
| -rw-r--r-- | doc/HOWTO.md | 8 |
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 @@ -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 |
