| Age | Commit message (Collapse) | Author |
|---|
|
SUMMARY
=======
Successfully completed comprehensive 4-phase refactor of audio subsystem to
eliminate fragile initialization order dependency between synth and tracker.
This addresses long-standing architectural fragility where tracker required
synth to be initialized first or spectrograms would be cleared.
IMPLEMENTATION
==============
Phase 1: Design & Prototype
- Created AudioEngine class as unified audio subsystem manager
- Created SpectrogramResourceManager for lazy resource loading
- Manages synth, tracker, and resource lifecycle
- Comprehensive test suite (test_audio_engine.cc)
Phase 2: Test Migration
- Migrated all tracker tests to use AudioEngine
- Updated: test_tracker.cc, test_tracker_timing.cc,
test_variable_tempo.cc, test_wav_dump.cc
- Pattern: Replace synth_init() + tracker_init() with engine.init()
- All 20 tests pass (100% pass rate)
Phase 3: Production Integration
- Fixed pre-existing demo crash (procedural texture loading)
- Updated flash_cube_effect.cc and hybrid_3d_effect.cc
- Migrated main.cc to use AudioEngine
- Replaced tracker_update() calls with engine.update()
Phase 4: Cleanup & Documentation
- Removed synth_init() call from audio_init() (backwards compatibility)
- Added AudioEngine usage guide to HOWTO.md
- Added audio initialization protocols to CONTRIBUTING.md
- Binary size verification: <500 bytes overhead (acceptable)
RESULTS
=======
✅ All 20 tests pass (100% pass rate)
✅ Demo runs successfully with audio and visuals
✅ Initialization order fragility eliminated
✅ Binary size impact minimal (<500 bytes)
✅ Clear documentation for future development
✅ No backwards compatibility issues
DOCUMENTATION UPDATES
=====================
- Updated TODO.md: Moved Task #56 to "Recently Completed"
- Updated PROJECT_CONTEXT.md: Added AudioEngine milestone
- Updated HOWTO.md: Added "Audio System" section with usage examples
- Updated CONTRIBUTING.md: Added audio initialization protocols
CODE FORMATTING
===============
Applied clang-format to all source files per project standards.
FILES CREATED
=============
- src/audio/audio_engine.h (new)
- src/audio/audio_engine.cc (new)
- src/audio/spectrogram_resource_manager.h (new)
- src/audio/spectrogram_resource_manager.cc (new)
- src/tests/test_audio_engine.cc (new)
KEY FILES MODIFIED
==================
- src/main.cc (migrated to AudioEngine)
- src/audio/audio.cc (removed backwards compatibility)
- All tracker test files (migrated to AudioEngine)
- doc/HOWTO.md (added usage guide)
- doc/CONTRIBUTING.md (added protocols)
- TODO.md (marked complete)
- PROJECT_CONTEXT.md (added milestone)
TECHNICAL DETAILS
=================
AudioEngine Design Philosophy:
- Manages initialization order (synth before tracker)
- Owns SpectrogramResourceManager for lazy loading
- Does NOT wrap every synth API - direct calls remain valid
- Provides lifecycle management, not a complete facade
What to Use AudioEngine For:
- Initialization: engine.init() instead of separate init calls
- Updates: engine.update(music_time) instead of tracker_update()
- Cleanup: engine.shutdown() for proper teardown
- Seeking: engine.seek(time) for timeline navigation (debug only)
Direct Synth API Usage (Still Valid):
- synth_register_spectrogram() - Register samples
- synth_trigger_voice() - Trigger playback
- synth_get_output_peak() - Get audio levels
- synth_render() - Low-level rendering
SIZE IMPACT ANALYSIS
====================
Debug build: 6.2MB
Size-optimized build: 5.0MB
Stripped build: 5.0MB
AudioEngine overhead: <500 bytes (0.01% of total)
BACKWARD COMPATIBILITY
======================
No breaking changes. Tests that need low-level control can still call
synth_init() directly. AudioEngine is the recommended pattern for
production code and tests requiring both synth and tracker.
handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio
initialization is now robust, well-documented, and properly tested.
The fragile initialization order dependency has been eliminated.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Completed Task #49.
- Implemented CPU-side SDF library (sphere, box, torus, plane).
- Implemented Dynamic BVH construction (rebuilt every frame).
- Implemented PhysicsSystem with semi-implicit Euler integration and collision resolution.
- Added visual debugging for BVH nodes.
- Created test_3d_physics interactive test and test_physics unit tests.
- Updated project docs and triaged new tasks.
|
|
Extracted all hardcoded WGSL shaders into external assets. Updated AssetManager to handle shader snippets. Refactored Renderer3D, VisualDebug, and Effects to load shaders via the AssetManager, enabling better shader management and composition.
|
|
|
|
- Adjusted Torus proxy hull in vs_main to fit unit dimensions (1.4x0.4x1.4).
- Updated VisualDebug to support per-object local extents, improving wireframe accuracy.
- Restored procedural floor grid and SDF bump mapping in the fragment shader.
- Added varied scaling to test scene objects to verify transform robustness.
|
|
- Updated VisualDebug to accept mat4 transforms, enabling wireframes to follow rotating objects.
- Restored SDF bump mapping and floor grid texture in the fragment shader.
- Added vec4::xyz() helper to mini_math.h.
- Fixed Renderer3D to pass the full model matrix for debug visualization.
|
|
- Implemented dynamic resolution support in all shaders and effects.
- Added explicit viewport setting for all render passes to ensure correct scaling.
- Fixed 3D shadow mapping by adding PLANE support and standardizing soft shadow logic.
- Propagated resize events through the Effect hierarchy.
- Applied project-wide code formatting.
|
|
- Added 'src/3d/visual_debug.h/cc' to implement wireframe rendering.
- Integrated VisualDebug into Renderer3D with a static global toggle.
- Added '--debug' command-line option to 'demo64k' and 'test_3d_render' to enable wireframes.
- Updated 'src/gpu/effects/hybrid_3d_effect.h' to expose the debug setter (reverted later as static method used).
- Ensured full cross-platform compatibility (native and Windows) for the new debug module.
- All code guarded by STRIP_ALL for final release.
|
