Skip to content

08_02 - DSP Integration Layer

Complete DSP integration system for AudioLab plugins.

🎯 Overview

This module provides the infrastructure for integrating DSP engines into plugins:

  • Engine Management - Factory, pooling, lifecycle
  • Signal Routing - Flexible audio routing with zero-copy optimization
  • Modulation - Sample-accurate parameter modulation (LFO, envelopes)
  • Optimization - SIMD, cache optimization, vectorization
  • Performance Tracking - CPU monitoring, RT-safety validation

📂 Module Structure

08_02_dsp_integration_layer/
├── 08_02_00_engine_instantiation/    # Engine factory & lifecycle
├── 08_02_01_signal_routing/          # Audio routing matrix
├── 08_02_02_modulation_system/       # LFO, envelopes, modulation
├── 08_02_03_optimization/            # SIMD & cache optimization
└── 08_02_04_performance_tracking/    # CPU monitoring & profiling

🚀 Quick Start

Engine Instantiation

#include "08_02_00_engine_instantiation/include/EngineFactory.hpp"
#include "08_02_00_engine_instantiation/include/EnginePool.hpp"

using namespace audiolab::plugins::dsp;

// Register engine type
REGISTER_ENGINE("Compressor", CompressorEngine);

// Create engine
auto factory = EngineFactory::getInstance();
auto engine = factory.createEngine("Compressor");

// Or use pool for efficiency
EnginePool pool("Compressor", 4);  // Pre-allocate 4 engines
auto pooled = pool.acquire();
// Use engine...
pool.release(std::move(pooled));

Signal Routing

#include "08_02_01_signal_routing/include/RoutingMatrix.hpp"

RoutingMatrix router(8, 8);  // 8 in, 8 out
router.prepareToPlay(44100.0);

// Route input 0 to outputs 0 and 1 (stereo split)
router.connect(0, 0, 0.707f);  // Left
router.connect(0, 1, 0.707f);  // Right

// Process
router.process(inputs, outputs, numSamples);

Modulation System

#include "08_02_02_modulation_system/include/LFO.hpp"
#include "08_02_02_modulation_system/include/Envelope.hpp"
#include "08_02_02_modulation_system/include/ModulationMatrix.hpp"

// Create LFO
LFO lfo;
lfo.prepareToPlay(44100.0);
lfo.setWaveform(LFO::Waveform::Sine);
lfo.setFrequency(5.0f);

// Create ADSR
Envelope env;
env.prepareToPlay(44100.0);
env.setAttackTime(0.01f);
env.setDecayTime(0.1f);
env.setSustainLevel(0.7f);
env.setReleaseTime(0.3f);

// Setup modulation routing
ModulationMatrix matrix;
matrix.registerSource("lfo1", &lfo);
matrix.registerSource("env1", &env);

ModulationMatrix::Routing route;
route.sourceId = "lfo1";
route.targetParamId = "cutoff";
route.depth = 0.5f;
matrix.addRouting(route);

// In audio callback
env.noteOn();
matrix.process(numSamples);
lfo.advance(numSamples);
env.advance(numSamples);

SIMD Optimization

#include "08_02_03_optimization/include/SIMDHelpers.hpp"

using namespace audiolab::plugins::dsp::simd;

// Check SIMD support
auto support = detectSIMDSupport();
if (support.avx2) {
    // Use AVX2 optimized path
}

// SIMD operations
float* result = alignedAlloc<float>(512);
vectorAdd(result, input1, input2, 512);
vectorMultiply(result, input, gain, 512);

Performance Tracking

#include "08_02_04_performance_tracking/include/CPUMonitor.hpp"
#include "08_02_04_performance_tracking/include/ProfileScope.hpp"

CPUMonitor monitor;

void processBlock(AudioBuffer& buffer) {
    ProfileScope scope("processBlock", &monitor);

    monitor.startBlock(buffer.getNumSamples(), getSampleRate());

    // Process audio...

    monitor.endBlock();

    if (monitor.isOverloaded()) {
        // Warning: CPU > 90%
    }
}

📊 Performance Characteristics

Component Overhead Notes
Engine Factory < 1 µs Per creation
Engine Pool < 0.01 µs Per acquire
Signal Routing < 1% CPU Per 512 samples
Modulation < 0.1% CPU Per source
SIMD Helpers 2-4x speedup vs scalar
CPU Monitor < 0.01% CPU Measurement overhead

🏗️ Dependencies

  • Internal:
  • 08_00_plugin_infrastructure - IAudioEngine, IModulationTarget

  • 04_CORE/04_05_buffer_management - AudioBuffer

  • External:

  • C++20 compiler
  • Platform SIMD support (SSE2/AVX/NEON)

🧪 Testing

# Build all tests
cd tests
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

# Run tests
./test_engine_instantiation
./test_signal_routing
./test_modulation
./test_optimization
./test_performance_tracking

📈 Implementation Status

  • ✅ Phase 1: Engine Instantiation (100%)
  • ✅ Phase 2: Signal Routing (100%)
  • ✅ Phase 3: Modulation System (100%)
  • ✅ Phase 4: Optimization (100%)
  • ✅ Phase 5: Performance Tracking (100%)

Overall: 100% Complete 🎉

📚 Documentation

Each subdirectory contains detailed README with: - Architecture overview - API reference - Usage examples - Performance notes

🔧 Build Configuration

CMake options: 

-DBUILD_TESTING=ON          # Enable tests
-DENABLE_SIMD=ON            # Enable SIMD optimizations (default)
-DENABLE_BENCHMARKS=ON      # Build benchmarks

🎓 Best Practices

  1. Engine Management
  2. Use EnginePool for frequently created/destroyed engines
  3. Always call prepareToPlay() before processing

  4. Respect lifecycle state machine

  5. Signal Routing

  6. Pre-allocate buffers before real-time thread
  7. Use zero-copy optimization where possible

  8. Monitor connection count (avoid excessive routing)

  9. Modulation

  10. Keep modulation sources lightweight
  11. Use sample-accurate interpolation

  12. Avoid modulation in inner loops

  13. Optimization

  14. Profile before optimizing
  15. Use SIMD for bulk operations (> 64 samples)
  16. Align data to cache lines

  17. Avoid branches in hot paths

  18. Performance

  19. Monitor CPU usage continuously
  20. Validate RT-safety in debug builds
  21. Set realistic performance budgets
  22. Use ProfileScope for bottleneck identification

📄 License

Part of AudioLab framework. See root LICENSE file.

Version: 1.0.0
Last Updated: 2025-10-09
Maintainer: AudioLab Team