diff options
Diffstat (limited to 'PROJECT_CONTEXT.md')
| -rw-r--r-- | PROJECT_CONTEXT.md | 20 |
1 files changed, 19 insertions, 1 deletions
diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 4d1fa35..7fcef97 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -58,6 +58,24 @@ Style: #### Milestone: Build System Optimization (February 6, 2026) - **Task C: CMake Dependency Graph Optimization**: Resolved critical build correctness bugs and improved developer iteration speed. **Header Split**: Refactored monolithic `asset_manager.h` (61 lines) into three focused headers: `asset_manager_dcl.h` (forward declarations for AssetId), `asset_manager.h` (core GetAsset/DropAsset API), and `asset_manager_utils.h` (typed helpers for TextureAsset/MeshAsset). Updated 17 source files to use appropriate headers. **Asset Dependency Tracking**: Implemented file-level dependency tracking for all 42 demo assets and 17 test assets. CMake now correctly tracks individual `.wgsl` shaders, `.spec` audio files, and `.obj` mesh files. **Critical Bug Fixed**: Changing shader files was NOT triggering asset regeneration, resulting in stale code in binaries. Developers had to manually `touch demo_assets.txt` as workaround. Now works correctly. **Performance**: Editing TextureAsset/MeshAsset helpers improved from 4.82s to 2.01s (58% faster). Shader edits now trigger correct 3.5s rebuild (was 0.28s with no rebuild - incorrect). **Implementation**: Added `parse_asset_list()` CMake function that parses `demo_assets.txt` format (`ASSET_NAME, COMPRESSION, FILENAME, DESC`) and extracts individual file paths for dependency tracking. All 20 tests pass. Zero functionality regressions. +#### Milestone: Critical Shader Stability & Test Infrastructure (February 6, 2026) ✅ +- **Shader Crash Resolution**: Fixed three critical WGSL validation errors causing demo64k and test_3d_render to crash on startup. **Bug 1 (renderer_3d.wgsl)**: Removed dead code using non-existent `inverse()` function - WGSL doesn't provide matrix inverse, and validator checks all code paths even unreachable ones. Also removed reference to undefined `in.normal` vertex input. **Bug 2 (sdf_utils.wgsl, lighting.wgsl)**: Fixed `get_normal_basic()` function signature mismatch - changed from `obj_type: f32` to `obj_params: vec4<f32>` to match `get_dist()` calls. **Bug 3 (scene_query_linear.wgsl - ROOT CAUSE)**: Fixed linear scene query mode incorrectly declaring binding 2 (BVH storage buffer). Linear version was identical to BVH version due to copy-paste error. Replaced BVH traversal with proper linear object iteration loop. **Impact**: When `use_bvh=false`, pipeline created without binding 2, but shader expected it → validation error → crash. + +- **Comprehensive Shader Compilation Tests**: Created `test_shader_compilation.cc` to prevent regression. Test compiles all production shaders through WebGPU (`wgpuDeviceCreateShaderModule`), validates both BVH and Linear composition modes using `ShaderComposer`, catches WGSL syntax errors, binding mismatches, type errors, and function signature issues. **Test Gap Analysis**: Existing `test_shader_assets.cc` only checked for keywords (`@vertex`, `fn`, etc.) without actual compilation - would NOT have caught any of the three bugs. New test fills this gap with real GPU validation. **Graceful Degradation**: Test handles platforms where WebGPU device unavailable by skipping GPU tests but still validating shader composition. + +- **Results**: demo64k runs cleanly without WebGPU errors, test_3d_render no longer crashes, 22/23 tests pass (FftTest unrelated to this work), comprehensive regression prevention infrastructure in place. All shader composition modes (BVH/Linear) now validated in CI. Files modified: renderer_3d.wgsl, sdf_utils.wgsl, lighting.wgsl, scene_query_linear.wgsl, test_shader_compilation.cc (new), CMakeLists.txt. + +#### Milestone: FFT-based DCT/IDCT Complete (February 6, 2026) ✅ +- **Core FFT Implementation**: Replaced failing double-and-mirror method with Numerical Recipes reordering method for DCT via FFT. Fixed reference IDCT to use DCT-III (inverse of DCT-II, not IDCT-II). All transforms now use orthonormal normalization: sqrt(1/N) for DC term, sqrt(2/N) for AC terms. Result: Perfect round-trip accuracy for impulse signals, <5e-3 error for sinusoidals (acceptable for FFT). + +- **Audio Pipeline Integration**: Integrated FFT-based DCT/IDCT into audio engine (`src/audio/idct.cc`, `fdct.cc`) and both web editors (`tools/spectral_editor/dct.js`, `tools/editor/dct.js`). All synthesis paths now use fast O(N log N) FFT instead of O(N²) naive DCT. Regenerated all 14 spectrogram assets with orthonormal DCT to match new synthesis engine. + +- **Critical Fixes**: **(1) Normalization Mismatch**: Old non-orthonormal DCT produced 16× larger values. Solution: Regenerated all `.spec` assets with orthonormal DCT. **(2) Procedural Notes**: NOTE_* generation inaudible after normalization change. Solution: Added sqrt(DCT_SIZE/2) = 16× scaling compensation in `gen.cc`. **(3) Windowing Error**: Hamming window incorrectly applied to spectrum before IDCT (should only be used for analysis, not synthesis). Solution: Removed windowing from `synth.cc` and both editors. Result: Correct volume, no distortion, clean frequency spectrum. + +- **Testing & Verification**: All 23 tests pass (100% success rate). Round-trip accuracy verified (impulse at index 0: perfect). Audio playback: correct volume, no distortion. Procedural notes: audible at correct levels. Web editors: clean spectrum, no comb artifacts. WAV dumps match expected output. + +- **Key Technical Insights**: (1) DCT-III is the inverse of DCT-II, not IDCT-II. (2) Hamming window is ONLY for analysis (before DCT), NOT synthesis (before IDCT). (3) Orthonormal DCT produces sqrt(N/2) smaller values than non-orthonormal. (4) Reordering method is more accurate than double-and-mirror for DCT via FFT. (5) Round-trip accuracy is more important than absolute DCT accuracy. + #### Milestone: Interactive Timeline Editor (February 5, 2026) 🎉 - **Task #57 Phase 1: Production-Ready Timeline Editor**: Created fully functional web-based editor for `demo.seq` timeline files. **Core Features**: Load/save demo.seq with BPM parsing, Gantt-style visual timeline, drag & drop sequences/effects with snap-to-beat, resize handles (left/right) allowing negative relative times, stack-order based priority system (Up/Down buttons + "Same as Above" toggle), floating auto-apply properties panel, diagonal mouse wheel scroll with 10% viewport slack, dynamic sequence bounds calculation, delete/add sequences, re-order by time. **Audio Visualization**: WAV waveform display above timeline using Web Audio API, scales with zoom (pixels per second), documented integration with `--dump_wav` flag for aligning sequences with actual demo audio output. **UI Polish**: Hoverable sequence names (large centered, fades on hover), hidden scrollbars, crosshair cursor on waveform, flash animation on active sequence change, clean minimal interface. **Bug Fixes**: Resolved critical e.target vs e.currentTarget drag offset bug, fixed sequence overlap with cumulative Y positioning, corrected effect relative time calculations. **Files**: `tools/timeline_editor/index.html` (~1200 lines pure HTML/CSS/JS, no dependencies), `README.md` (usage guide, wav_dump integration docs), `ROADMAP.md` (3 phases, 117-161 hour estimate). **Next**: Phase 1.2 (Add Effect button), Phase 2.5 (music.track visualization overlay). **Impact**: Visual timeline editing now production-ready, eliminates manual text editing for sequence placement and timing adjustments. @@ -143,7 +161,7 @@ Style: - **Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation. ### Audio Engine -- **Synthesis**: Real-time additive synthesis from spectrograms via IDCT. Stereo output (32kHz, 16-bit, interleaved L/R). +- **Synthesis**: Real-time additive synthesis from spectrograms via FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method. - **Variable Tempo**: Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch. - **Event-Based Tracker**: Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling. - **Backend Abstraction**: `AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering). |