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/3d/bvh.cc | 3 ++- src/3d/renderer.cc | 3 ++- src/3d/sdf_cpu.h | 10 ++++++---- src/3d/visual_debug.cc | 20 +++++++++++--------- 4 files changed, 21 insertions(+), 15 deletions(-) (limited to 'src/3d') diff --git a/src/3d/bvh.cc b/src/3d/bvh.cc index 0c6bf9a..5f7abef 100644 --- a/src/3d/bvh.cc +++ b/src/3d/bvh.cc @@ -72,7 +72,8 @@ int build_recursive(std::vector& nodes, if (extent.z > (axis == 0 ? extent.x : extent.y)) axis = 2; - float split = (centroid_bounds.min[axis] + centroid_bounds.max[axis]) * 0.5f; + float split = + (centroid_bounds.min[axis] + centroid_bounds.max[axis]) * 0.5f; // Partition int mid = start; diff --git a/src/3d/renderer.cc b/src/3d/renderer.cc index 64f6fc3..684fda9 100644 --- a/src/3d/renderer.cc +++ b/src/3d/renderer.cc @@ -243,7 +243,8 @@ void Renderer3D::create_pipeline() { WGPUPipelineLayout pipeline_layout = wgpuDeviceCreatePipelineLayout(device_, &pl_desc); - const char* asset_data = (const char*)GetAsset(AssetId::ASSET_SHADER_RENDERER_3D); + const char* asset_data = + (const char*)GetAsset(AssetId::ASSET_SHADER_RENDERER_3D); std::string main_code = asset_data; std::string shader_source = ShaderComposer::Get().Compose({}, main_code); diff --git a/src/3d/sdf_cpu.h b/src/3d/sdf_cpu.h index 1e461f6..e0f1b3f 100644 --- a/src/3d/sdf_cpu.h +++ b/src/3d/sdf_cpu.h @@ -45,10 +45,12 @@ inline float sdPlane(vec3 p, vec3 n, float h) { template inline vec3 calc_normal(vec3 p, F sdf_func, float e = 0.001f) { const float d2e = 2.0f * e; - return vec3( - sdf_func(vec3(p.x + e, p.y, p.z)) - sdf_func(vec3(p.x - e, p.y, p.z)), - sdf_func(vec3(p.x, p.y + e, p.z)) - sdf_func(vec3(p.x, p.y - e, p.z)), - sdf_func(vec3(p.x, p.y, p.z + e)) - sdf_func(vec3(p.x, p.y, p.z - e))) + return vec3(sdf_func(vec3(p.x + e, p.y, p.z)) - + sdf_func(vec3(p.x - e, p.y, p.z)), + sdf_func(vec3(p.x, p.y + e, p.z)) - + sdf_func(vec3(p.x, p.y - e, p.z)), + sdf_func(vec3(p.x, p.y, p.z + e)) - + sdf_func(vec3(p.x, p.y, p.z - e))) .normalize(); } diff --git a/src/3d/visual_debug.cc b/src/3d/visual_debug.cc index ab4cb6c..86f12b4 100644 --- a/src/3d/visual_debug.cc +++ b/src/3d/visual_debug.cc @@ -182,18 +182,20 @@ void VisualDebug::add_box(const mat4& transform, const vec3& local_extent, } } -void VisualDebug::add_aabb(const vec3& min, const vec3& max, const vec3& color) { - vec3 p[] = {{min.x, min.y, min.z}, {max.x, min.y, min.z}, {max.x, max.y, min.z}, - {min.x, max.y, min.z}, {min.x, min.y, max.z}, {max.x, min.y, max.z}, +void VisualDebug::add_aabb(const vec3& min, const vec3& max, + const vec3& color) { + vec3 p[] = {{min.x, min.y, min.z}, {max.x, min.y, min.z}, + {max.x, max.y, min.z}, {min.x, max.y, min.z}, + {min.x, min.y, max.z}, {max.x, min.y, max.z}, {max.x, max.y, max.z}, {min.x, max.y, max.z}}; DebugLine edges[] = { - {p[0], p[1], color}, {p[1], p[2], color}, {p[2], p[3], color}, - {p[3], p[0], color}, // Front - {p[4], p[5], color}, {p[5], p[6], color}, {p[6], p[7], color}, - {p[7], p[4], color}, // Back - {p[0], p[4], color}, {p[1], p[5], color}, {p[2], p[6], color}, - {p[3], p[7], color} // Connections + {p[0], p[1], color}, {p[1], p[2], color}, + {p[2], p[3], color}, {p[3], p[0], color}, // Front + {p[4], p[5], color}, {p[5], p[6], color}, + {p[6], p[7], color}, {p[7], p[4], color}, // Back + {p[0], p[4], color}, {p[1], p[5], color}, + {p[2], p[6], color}, {p[3], p[7], color} // Connections }; for (const auto& l : edges) { -- cgit v1.2.3