diff options
Diffstat (limited to 'PROJECT_CONTEXT.md')
| -rw-r--r-- | PROJECT_CONTEXT.md | 22 |
1 files changed, 15 insertions, 7 deletions
diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 520e733..4d1fa35 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -33,7 +33,7 @@ Style: ### Recently Completed #### Milestone: Audio Playback Stability & Debug Infrastructure (February 4, 2026) -- **Core Audio Backend Optimization**: Resolved critical audio playback issues (stop-and-go, glitches, eventual silence) caused by timing mismatches in miniaudio's Core Audio backend. Root cause: Core Audio optimized for 44.1kHz with 10ms periods, but our 32kHz system expected uniform ~13.78ms callbacks, causing resampling jitter. Fix: Added `allowNominalSampleRateChange = TRUE` to force OS-level 32kHz native playback and `performanceProfile = conservative` for larger buffers (4096 frames = 128ms). Result: Stable ~128ms callbacks with <1ms jitter, zero underruns during variable tempo (1.0x → 2.0x). +- **Core Audio Backend Optimization**: Resolved critical audio playback issues (stop-and-go, glitches, eventual silence) caused by timing mismatches in miniaudio's Core Audio backend. Root cause: Core Audio optimized for 44.1kHz with 10ms periods, but our 32kHz system expected uniform ~13.78ms callbacks, causing resampling jitter. Fix: Added `allowNominalSampleRateChange = TRUE` to force OS-level 32kHz native and `performanceProfile = conservative` for larger buffers (4096 frames = 128ms). Result: Stable ~128ms callbacks with <1ms jitter, zero underruns during variable tempo (1.0x → 2.0x). - **Ring Buffer Capacity Tuning**: Increased ring buffer from 200ms to 400ms (25,600 samples) to handle tempo scaling headroom. Added comprehensive bounds checking with abort() on violations to catch buffer corruption early. Fixed critical bug: tempo-scaled rendering wasn't scaling dt when pre-filling buffer (`audio_render_ahead(g_music_time, dt * g_tempo_scale)`). Buffer now maintains 400ms fullness throughout playback, including 2.0x tempo acceleration. @@ -55,6 +55,9 @@ Style: #### Milestone: Audio Lifecycle Refactor (February 5, 2026) - **Task #56: AudioEngine Implementation**: Completed 4-phase refactor to eliminate fragile initialization order dependency between synth and tracker. **Phase 1 (Design & Prototype)**: Created `AudioEngine` class and `SpectrogramResourceManager` for unified lifecycle management with lazy loading. **Phase 2 (Test Migration)**: Migrated all tracker tests to use AudioEngine (test_tracker.cc, test_tracker_timing.cc, test_variable_tempo.cc, test_wav_dump.cc). **Phase 3 (Production Integration)**: Updated main.cc to use AudioEngine, fixed pre-existing procedural texture crash (flash_cube_effect.cc, hybrid_3d_effect.cc). **Phase 4 (Cleanup & Documentation)**: Removed backwards compatibility (synth_init from audio_init), updated HOWTO.md and CONTRIBUTING.md with usage patterns. Result: All 20 tests pass, binary size impact <500 bytes, initialization fragility eliminated. +#### 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: 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. @@ -78,17 +81,21 @@ Style: - **Tight Ray Bounds (Task 21.2)**: Implemented local-space ray-box intersection to optimize SDF raymarching. - **High-DPI Fix**: Resolved viewport "squishing" via dynamic resolution uniforms and explicit viewports. - **Unified 3D Shadows**: Implemented robust SDF shadows across all objects using `inv_model` transforms. +- **test_mesh tool**: Implemented a standalone `test_mesh` tool for visualizing OBJ files with debug normal display. --- ## Next Up -- **Task #49: Physics & Collision** - - [ ] **Task #49.1: CPU-Side SDF Library**: Implement `sdSphere`, `sdBox` etc. in C++ (`src/3d/sdf_cpu.h`). - - [ ] **Task #49.2: BVH Construction**: Implement BVH builder and traversal for broad-phase collision. - - [ ] **Task #49.3: Physics Loop**: Implement integration, narrow-phase SDF probing, and collision resolution. + +- **Task #5: Spectral Brush Editor** [IN PROGRESS - February 6, 2026] + - 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) + - Phase 2: Editor UI (HTML/JS canvas, dual-layer visualization, keyboard shortcuts) + - Phase 3: File I/O (load .wav/.spec, export procedural_params.txt + C++ code) + - See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete design - **Task #18: 3D System Enhancements** - [ ] **Task #18.0: Basic OBJ Asset Pipeline**: Implement `ASSET_MESH` type, `asset_packer` OBJ support, and `Renderer3D` mesh rendering. - - [ ] **Task #36: Blender Exporter**: Create script to export scenes to internal binary format. - [ ] **Task #37: Asset Ingestion**: Update `asset_packer` to handle the new 3D binary format. - [ ] **Task #38: Runtime Loader**: Implement a minimal C++ parser to load the scene data into the ECS/Renderer. @@ -102,12 +109,13 @@ Style: --- ## Future Goals +- **Task #36: Blender Exporter**: Create script to export scenes to internal binary format. (Deprioritized) - **Task #5: Implement Spectrogram Editor** - [ ] Develop a web-based tool (`tools/editor`) for creating and editing `.spec` files visually. - **Task #21: Shader Optimization** - [ ] Use macros or code generation to factorize common WGSL code (normals, bump, lighting). - [ ] Implement Tri-planar mapping for better procedural textures. -- **Task #18-B: GPU BVH & Shadows**: Optimize scene queries with a GPU-based BVH. +- [ ] **Task #18-B: GPU BVH & Shadows**: Optimize scene queries with a GPU-based BVH. - **Phase 2: Advanced Size Optimization** - [ ] **Task #22: Windows Native Platform**: Replace GLFW with minimal native Windows API. - [ ] **Task #28: Spectrogram Quantization**: Quantize spectrograms to logarithmic frequency and uint16_t. |