From 12816810855883472ecab454f9c0d08d66f0ae52 Mon Sep 17 00:00:00 2001 From: skal Date: Thu, 5 Feb 2026 20:18:28 +0100 Subject: feat(audio): Complete Task #56 - Audio Lifecycle Refactor (All Phases) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- src/tests/test_3d.cc | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) (limited to 'src/tests/test_3d.cc') diff --git a/src/tests/test_3d.cc b/src/tests/test_3d.cc index 90869bf..e0fb2e0 100644 --- a/src/tests/test_3d.cc +++ b/src/tests/test_3d.cc @@ -23,14 +23,14 @@ void test_camera() { assert(near(view.m[14], -10.0f)); // Test Camera::set_look_at - cam.set_look_at({5, 0, 0}, {0, 0, 0}, {0, 1, 0}); // Look at origin from (5,0,0) + cam.set_look_at({5, 0, 0}, {0, 0, 0}, + {0, 1, 0}); // Look at origin from (5,0,0) mat4 view_shifted = cam.get_view_matrix(); - // The camera's forward vector (0,0,-1) should now point towards (-1,0,0) in world space. - // The translation part of the view matrix should be based on -dot(s, eye), -dot(u, eye), dot(f, eye) - // s = (0,0,-1), u = (0,1,0), f = (-1,0,0) - // m[12] = -dot({0,0,-1}, {5,0,0}) = 0 - // m[13] = -dot({0,1,0}, {5,0,0}) = 0 - // m[14] = dot({-1,0,0}, {5,0,0}) = -5 + // The camera's forward vector (0,0,-1) should now point towards (-1,0,0) in + // world space. The translation part of the view matrix should be based on + // -dot(s, eye), -dot(u, eye), dot(f, eye) s = (0,0,-1), u = (0,1,0), f = + // (-1,0,0) m[12] = -dot({0,0,-1}, {5,0,0}) = 0 m[13] = -dot({0,1,0}, {5,0,0}) + // = 0 m[14] = dot({-1,0,0}, {5,0,0}) = -5 assert(near(view_shifted.m[12], 0.0f)); assert(near(view_shifted.m[13], 0.0f)); assert(near(view_shifted.m[14], -5.0f)); @@ -76,22 +76,27 @@ void test_object_transform() { mat4 inv_model_t = model_t.inverse(); // Applying inv_model to a translated point should undo the translation. // Point (5,0,0) should go to (0,0,0) - vec4 translated_point(5,0,0,1); - vec4 original_space_t = inv_model_t * vec4(translated_point.x, translated_point.y, translated_point.z, 1.0); - assert(near(original_space_t.x, 0.0f) && near(original_space_t.y, 0.0f) && near(original_space_t.z, 0.0f)); + vec4 translated_point(5, 0, 0, 1); + vec4 original_space_t = + inv_model_t * + vec4(translated_point.x, translated_point.y, translated_point.z, 1.0); + assert(near(original_space_t.x, 0.0f) && near(original_space_t.y, 0.0f) && + near(original_space_t.z, 0.0f)); // Model matrix with rotation (90 deg Y) and translation (5,0,0) obj.position = vec3(5, 0, 0); obj.rotation = quat::from_axis({0, 1, 0}, 1.570796f); mat4 model_trs = obj.get_model_matrix(); mat4 inv_model_trs = model_trs.inverse(); - // Transform point (1,0,0) (local right) via TRS: Rotates to (0,0,-1), Translates to (5,0,-1) - vec4 p_trs(1,0,0,1); + // Transform point (1,0,0) (local right) via TRS: Rotates to (0,0,-1), + // Translates to (5,0,-1) + vec4 p_trs(1, 0, 0, 1); vec4 transformed_p = model_trs * p_trs; assert(near(transformed_p.x, 5.0f) && near(transformed_p.z, -1.0f)); // Apply inverse to transformed point to get back original point vec4 original_space_trs = inv_model_trs * transformed_p; - assert(near(original_space_trs.x, 1.0f) && near(original_space_trs.y, 0.0f) && near(original_space_trs.z, 0.0f)); + assert(near(original_space_trs.x, 1.0f) && near(original_space_trs.y, 0.0f) && + near(original_space_trs.z, 0.0f)); } void test_scene() { -- cgit v1.2.3