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/gpu/effects/fade_effect.cc | 7 ++++--- src/gpu/effects/flash_effect.cc | 9 +++++---- src/gpu/effects/shaders.cc | 6 ++++-- src/gpu/effects/theme_modulation_effect.cc | 17 ++++++++++------- src/gpu/effects/theme_modulation_effect.h | 5 +++-- 5 files changed, 26 insertions(+), 18 deletions(-) (limited to 'src/gpu/effects') diff --git a/src/gpu/effects/fade_effect.cc b/src/gpu/effects/fade_effect.cc index 3b942c0..4d7633c 100644 --- a/src/gpu/effects/fade_effect.cc +++ b/src/gpu/effects/fade_effect.cc @@ -47,15 +47,16 @@ FadeEffect::FadeEffect(WGPUDevice device, WGPUQueue queue, )"; pipeline_ = create_post_process_pipeline(device, format, shader_code); - uniforms_ = gpu_create_buffer(device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); + uniforms_ = gpu_create_buffer( + device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); } void FadeEffect::update_bind_group(WGPUTextureView input_view) { pp_update_bind_group(device_, pipeline_, &bind_group_, input_view, uniforms_); } -void FadeEffect::render(WGPURenderPassEncoder pass, float time, - float beat, float intensity, float aspect_ratio) { +void FadeEffect::render(WGPURenderPassEncoder pass, float time, float beat, + float intensity, float aspect_ratio) { (void)beat; (void)intensity; (void)aspect_ratio; diff --git a/src/gpu/effects/flash_effect.cc b/src/gpu/effects/flash_effect.cc index de7be62..176c60c 100644 --- a/src/gpu/effects/flash_effect.cc +++ b/src/gpu/effects/flash_effect.cc @@ -49,22 +49,23 @@ FlashEffect::FlashEffect(WGPUDevice device, WGPUQueue queue, )"; pipeline_ = create_post_process_pipeline(device, format, shader_code); - uniforms_ = gpu_create_buffer(device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); + uniforms_ = gpu_create_buffer( + device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); } void FlashEffect::update_bind_group(WGPUTextureView input_view) { pp_update_bind_group(device_, pipeline_, &bind_group_, input_view, uniforms_); } -void FlashEffect::render(WGPURenderPassEncoder pass, float time, - float beat, float intensity, float aspect_ratio) { +void FlashEffect::render(WGPURenderPassEncoder pass, float time, float beat, + float intensity, float aspect_ratio) { (void)time; (void)beat; (void)aspect_ratio; // Trigger flash on strong beat hits if (intensity > 0.7f && flash_intensity_ < 0.2f) { - flash_intensity_ = 0.8f; // Trigger flash + flash_intensity_ = 0.8f; // Trigger flash } // Exponential decay diff --git a/src/gpu/effects/shaders.cc b/src/gpu/effects/shaders.cc index 7255cf5..7b543e1 100644 --- a/src/gpu/effects/shaders.cc +++ b/src/gpu/effects/shaders.cc @@ -34,8 +34,10 @@ void InitShaderComposer() { register_if_exists("math/sdf_shapes", AssetId::ASSET_SHADER_MATH_SDF_SHAPES); register_if_exists("math/sdf_utils", AssetId::ASSET_SHADER_MATH_SDF_UTILS); register_if_exists("render/shadows", AssetId::ASSET_SHADER_RENDER_SHADOWS); - register_if_exists("render/scene_query", AssetId::ASSET_SHADER_RENDER_SCENE_QUERY); - register_if_exists("render/lighting_utils", AssetId::ASSET_SHADER_RENDER_LIGHTING_UTILS); + register_if_exists("render/scene_query", + AssetId::ASSET_SHADER_RENDER_SCENE_QUERY); + register_if_exists("render/lighting_utils", + AssetId::ASSET_SHADER_RENDER_LIGHTING_UTILS); register_if_exists("sdf_primitives", AssetId::ASSET_SHADER_SDF_PRIMITIVES); diff --git a/src/gpu/effects/theme_modulation_effect.cc b/src/gpu/effects/theme_modulation_effect.cc index 4ddb1f4..d2705d5 100644 --- a/src/gpu/effects/theme_modulation_effect.cc +++ b/src/gpu/effects/theme_modulation_effect.cc @@ -51,7 +51,8 @@ ThemeModulationEffect::ThemeModulationEffect(WGPUDevice device, WGPUQueue queue, pipeline_ = create_post_process_pipeline(device, format, shader_code); // Create uniform buffer (4 floats: brightness + padding) - uniforms_ = gpu_create_buffer(device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); + uniforms_ = gpu_create_buffer( + device, 16, WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst); } void ThemeModulationEffect::update_bind_group(WGPUTextureView input_view) { @@ -59,22 +60,24 @@ void ThemeModulationEffect::update_bind_group(WGPUTextureView input_view) { } void ThemeModulationEffect::render(WGPURenderPassEncoder pass, float time, - float beat, float intensity, - float aspect_ratio) { + float beat, float intensity, + float aspect_ratio) { (void)beat; (void)intensity; (void)aspect_ratio; // Alternate between bright and dark every 4 seconds (2 pattern changes) // Music patterns change every 2 seconds at 120 BPM - float cycle_time = fmodf(time, 8.0f); // 8 second cycle (4 patterns) - bool is_dark_section = (cycle_time >= 4.0f); // Dark for second half + float cycle_time = fmodf(time, 8.0f); // 8 second cycle (4 patterns) + bool is_dark_section = (cycle_time >= 4.0f); // Dark for second half // Smooth transition between themes using a sine wave - float transition = (std::sin(time * 3.14159f / 4.0f) + 1.0f) * 0.5f; // 0.0 to 1.0 + float transition = + (std::sin(time * 3.14159f / 4.0f) + 1.0f) * 0.5f; // 0.0 to 1.0 float bright_value = 1.0f; float dark_value = 0.35f; - float theme_brightness = bright_value + (dark_value - bright_value) * transition; + float theme_brightness = + bright_value + (dark_value - bright_value) * transition; // Update uniform buffer float uniforms[4] = {theme_brightness, 0.0f, 0.0f, 0.0f}; diff --git a/src/gpu/effects/theme_modulation_effect.h b/src/gpu/effects/theme_modulation_effect.h index 6f76695..ac584e2 100644 --- a/src/gpu/effects/theme_modulation_effect.h +++ b/src/gpu/effects/theme_modulation_effect.h @@ -1,6 +1,7 @@ // This file is part of the 64k demo project. -// It implements a theme modulation effect that alternates between bright and dark. -// Pattern changes every 2 seconds, so we alternate every 4 seconds (2 patterns). +// It implements a theme modulation effect that alternates between bright and +// dark. Pattern changes every 2 seconds, so we alternate every 4 seconds (2 +// patterns). #pragma once #include "gpu/effect.h" -- cgit v1.2.3