plate_reverb.hpp

Go to the documentation of this file.

// sbl/widgets/proc/plate_reverb.hpp — Dattorro plate reverb (Audio Stack — Widgets)
//
// Classic Dattorro plate topology:
//   Input → Pre-delay → Bandwidth LP → 4x Input Diffusion (allpass)
//   → Cross-fed Tank (2 halves, each: AP → long delay → damp → AP → long delay)
//   → Multi-tap stereo output
//
// Based on Jon Dattorro, "Effect Design Part 1" (JAES, 1997).
// Uses the full Dattorro delay topology with proper long tank delays
// (4453, 3720, 4217, 3163 samples at 29.76kHz) and short allpass delays
// (672, 1800, 908, 2656). Total tank ~110KB at 48kHz.
//
// Tank modulation uses a 4-phase quadrature oscillator (zero-cost, no LUT)
// to modulate all 4 tank delay lines with 90° offsets. This ensures
// matching-length delays never have aligned comb teeth, eliminating the
// metallic resonances common in simple plate algorithms.
//
// Float-domain processing — STM32H7 (Cortex-M7) has hardware FPU.
//
// Usage:
//   float pool[PLATE_REVERB_BUFFER_SIZE] = {};
//   sbl::widgets::proc::PlateReverb reverb;
//   reverb.init(pool, PLATE_REVERB_BUFFER_SIZE);
//   reverb.set_sample_rate(48000);
//   reverb.set_decay(0.7f);
//   reverb.set_damping(0.3f);
//   reverb.process(left, right, frames);
 
#pragma once
 
#include <cstdint>
#include <cstring>
 
#include <sbl/dsp/allpass.hpp>
#include <sbl/dsp/modulated_delay_line.hpp>
#include <sbl/dsp/one_pole.hpp>
 
namespace sbl::widgets::proc {
 
// ============================================================================
// Dattorro delay values (at 29.76kHz reference rate)
// ============================================================================
 
namespace plate {
 
// Input diffusion allpass delays
constexpr uint32_t INPUT_AP1 = 142;
constexpr uint32_t INPUT_AP2 = 107;
constexpr uint32_t INPUT_AP3 = 379;
constexpr uint32_t INPUT_AP4 = 277;
 
// Tank left: AP1 → Delay1 → (damp) → AP2 → Delay2
// APs use the short Dattorro allpass delays; standalone DLs use the long delays.
// 4453 and 3720 are coprime (GCD=1) — no shared comb harmonics.
constexpr uint32_t TANK_L_AP1    = 672;
constexpr uint32_t TANK_L_DELAY1 = 4453;
constexpr uint32_t TANK_L_AP2    = 1800;
constexpr uint32_t TANK_L_DELAY2 = 3720;
 
// Tank right: AP1 → Delay1 → (damp) → AP2 → Delay2
// 4217 is prime, 3163 is prime — maximum comb decorrelation.
constexpr uint32_t TANK_R_AP1    = 908;
constexpr uint32_t TANK_R_DELAY1 = 4217;
constexpr uint32_t TANK_R_AP2    = 2656;
constexpr uint32_t TANK_R_DELAY2 = 3163;
 
// Pre-delay (max 100ms @ 48kHz)
constexpr uint32_t PREDELAY_MAX = 4800;
 
// LFO modulation parameters
constexpr float MOD_RATE_HZ = 1.0f;
constexpr float MOD_DEPTH   = 8.0f;
 
// Extra buffer headroom for modulation excursion + interpolation margin
constexpr uint32_t MOD_MARGIN = static_cast<uint32_t>(MOD_DEPTH) + 2;
 
// Total buffer size needed (tank delay buffers include modulation margin)
constexpr uint32_t BUFFER_SIZE =
    INPUT_AP1 + INPUT_AP2 + INPUT_AP3 + INPUT_AP4 +
    TANK_L_AP1 + (TANK_L_DELAY1 + MOD_MARGIN) +
    TANK_L_AP2 + (TANK_L_DELAY2 + MOD_MARGIN) +
    TANK_R_AP1 + (TANK_R_DELAY1 + MOD_MARGIN) +
    TANK_R_AP2 + (TANK_R_DELAY2 + MOD_MARGIN) +
    PREDELAY_MAX;
 
// Input diffusion feedback coefficients (Dattorro standard)
constexpr float INPUT_DIFFUSION1 = 0.75f;   // AP1, AP2
constexpr float INPUT_DIFFUSION2 = 0.625f;  // AP3, AP4
 
// Tank diffusion
constexpr float DECAY_DIFFUSION1 = 0.7f;    // First AP in each half
constexpr float DECAY_DIFFUSION2 = 0.5f;    // Second AP in each half
 
// --- Output tap positions (relative to start of each delay/AP buffer) ---
// Taps from Dattorro paper, placed to maximize echo density across the
// stereo field. Deep taps reach into the long delay lines for diffuse tails.
constexpr uint32_t TAP_L_AP1_A   = 266;
constexpr uint32_t TAP_L_DL1_A   = 353;
constexpr uint32_t TAP_L_DL1_B   = 3627;
constexpr uint32_t TAP_L_AP2_A   = 1340;
constexpr uint32_t TAP_L_DL2_A   = 1400;
constexpr uint32_t TAP_L_DL2_B   = 2667;
 
constexpr uint32_t TAP_R_AP1_A   = 266;
constexpr uint32_t TAP_R_DL1_A   = 353;
constexpr uint32_t TAP_R_DL1_B   = 3467;
constexpr uint32_t TAP_R_AP2_A   = 700;
constexpr uint32_t TAP_R_DL2_A   = 1228;
constexpr uint32_t TAP_R_DL2_B   = 2545;
 
} // namespace plate
 
// ============================================================================
// PlateReverb widget
// ============================================================================
 
/// Total float buffer size required for PlateReverb::init()
constexpr uint32_t PLATE_REVERB_BUFFER_SIZE = plate::BUFFER_SIZE;
 
class PlateReverb {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    PlateReverb() = default;
 
    /**
     * @brief Initialize with a pre-allocated float buffer pool
     * @param pool Float buffer pool (must outlive the PlateReverb)
     * @param pool_size Pool size in floats (must be >= PLATE_REVERB_BUFFER_SIZE)
     */
    void init(float* pool, uint32_t pool_size) {
        if (pool_size < plate::BUFFER_SIZE) return;
 
        // Zero the pool — NOLOAD sections may contain garbage from previous firmware
        memset(pool, 0, pool_size * sizeof(float));
 
        float* p = pool;
 
        predelay_buf_ = p;  p += plate::PREDELAY_MAX;
 
        input_ap_[0].init(p, plate::INPUT_AP1);  p += plate::INPUT_AP1;
        input_ap_[1].init(p, plate::INPUT_AP2);  p += plate::INPUT_AP2;
        input_ap_[2].init(p, plate::INPUT_AP3);  p += plate::INPUT_AP3;
        input_ap_[3].init(p, plate::INPUT_AP4);  p += plate::INPUT_AP4;
 
        input_ap_[0].set_feedback(plate::INPUT_DIFFUSION1);
        input_ap_[1].set_feedback(plate::INPUT_DIFFUSION1);
        input_ap_[2].set_feedback(plate::INPUT_DIFFUSION2);
        input_ap_[3].set_feedback(plate::INPUT_DIFFUSION2);
 
        tank_l_ap1_buf_ = p;
        tank_l_ap1_.init(p, plate::TANK_L_AP1);   p += plate::TANK_L_AP1;
        tank_l_dl1_buf_ = p;
        tank_l_dl1_.init(p, plate::TANK_L_DELAY1 + plate::MOD_MARGIN);
        p += plate::TANK_L_DELAY1 + plate::MOD_MARGIN;
        tank_l_ap2_buf_ = p;
        tank_l_ap2_.init(p, plate::TANK_L_AP2);   p += plate::TANK_L_AP2;
        tank_l_dl2_buf_ = p;
        tank_l_dl2_.init(p, plate::TANK_L_DELAY2 + plate::MOD_MARGIN);
        p += plate::TANK_L_DELAY2 + plate::MOD_MARGIN;
 
        tank_l_ap1_.set_feedback(plate::DECAY_DIFFUSION1);
        tank_l_ap2_.set_feedback(plate::DECAY_DIFFUSION2);
 
        tank_r_ap1_buf_ = p;
        tank_r_ap1_.init(p, plate::TANK_R_AP1);   p += plate::TANK_R_AP1;
        tank_r_dl1_buf_ = p;
        tank_r_dl1_.init(p, plate::TANK_R_DELAY1 + plate::MOD_MARGIN);
        p += plate::TANK_R_DELAY1 + plate::MOD_MARGIN;
        tank_r_ap2_buf_ = p;
        tank_r_ap2_.init(p, plate::TANK_R_AP2);   p += plate::TANK_R_AP2;
        tank_r_dl2_buf_ = p;
        tank_r_dl2_.init(p, plate::TANK_R_DELAY2 + plate::MOD_MARGIN);
        p += plate::TANK_R_DELAY2 + plate::MOD_MARGIN;
 
        tank_r_ap1_.set_feedback(plate::DECAY_DIFFUSION1);
        tank_r_ap2_.set_feedback(plate::DECAY_DIFFUSION2);
 
        pool_ = pool;
        pool_size_ = pool_size;
 
        reset();
    }
 
    void set_sample_rate(uint32_t sr) {
        sample_rate_ = sr;
        // Quadrature oscillator increment: 2π × freq / sr
        constexpr float TWO_PI = 6.283185307f;
        mod_inc_ = TWO_PI * plate::MOD_RATE_HZ / static_cast<float>(sr);
        // Bandwidth limiter: ~10kHz LP at reverb input (Dattorro spec)
        bandwidth_.set_frequency(10000.0f, static_cast<float>(sr));
    }
 
    void set_decay(float decay) {
        if (decay > 0.99f) decay = 0.99f;
        if (decay < 0.0f) decay = 0.0f;
        decay_ = decay;
    }
 
    void set_damping(float damp) {
        if (damp > 1.0f) damp = 1.0f;
        if (damp < 0.0f) damp = 0.0f;
        damping_ = damp;
        // damp=0.0 (bright) → coeff=1.0 (passthrough)
        // damp=1.0 (dark)   → coeff=0.0 (hold/max filtering)
        float coeff = 1.0f - damp;
        tank_l_damp_.set_coefficient(coeff);
        tank_r_damp_.set_coefficient(coeff);
    }
 
    void set_predelay(float ms) {
        uint32_t samples = static_cast<uint32_t>(
            ms * static_cast<float>(sample_rate_) / 1000.0f);
        if (samples >= plate::PREDELAY_MAX) {
            samples = plate::PREDELAY_MAX - 1;
        }
        predelay_samples_ = samples;
    }
 
    void set_width(float width) {
        if (width > 1.0f) width = 1.0f;
        if (width < 0.0f) width = 0.0f;
        width_ = width;
    }
 
    void set_mix(float mix) {
        if (mix > 1.0f) mix = 1.0f;
        if (mix < 0.0f) mix = 0.0f;
        mix_ = mix;
    }
 
    float decay() const { return decay_; }
    float damping() const { return damping_; }
    float mix() const { return mix_; }
    float width() const { return width_; }
 
    /**
     * @brief Process a stereo block in-place (float)
     *
     * @param left Left channel buffer (float, in-place)
     * @param right Right channel buffer (float, in-place)
     * @param frames Number of sample frames
     */
    void process(float* left, float* right, uint16_t frames) {
        const float wet = mix_;
        const float dry = 1.0f - wet;
 
        for (uint16_t i = 0; i < frames; ++i) {
            float in_l = left[i];
            float in_r = right[i];
 
            float input = (in_l + in_r) * 0.5f;
 
            // === Pre-delay ===
            float predelayed;
            if (predelay_samples_ == 0) {
                predelayed = input;
            } else {
                predelayed = predelay_read();
            }
            predelay_write(input);
 
            // === Bandwidth limiter (Dattorro input LP) ===
            float limited = bandwidth_.process(predelayed);
 
            // === Input diffusion ===
            float diffused = limited;
            for (int ap = 0; ap < 4; ++ap) {
                diffused = input_ap_[ap].process(diffused);
            }
 
            // === Quadrature LFO tick (4-phase for all tank delays) ===
            mod_sin_ += mod_inc_ * mod_cos_;
            mod_cos_ -= mod_inc_ * mod_sin_;
            // 4-phase distribution: matching delay lengths (e.g. 672 in
            // both halves) get 90° offset so their combs never align.
            float mod_dl1_l =  mod_sin_ * plate::MOD_DEPTH;  // 0°
            float mod_dl2_l =  mod_cos_ * plate::MOD_DEPTH;  // 90°
            float mod_dl1_r = -mod_sin_ * plate::MOD_DEPTH;  // 180°
            float mod_dl2_r = -mod_cos_ * plate::MOD_DEPTH;  // 270°
 
            // === Tank processing ===
            float tank_l_in = diffused + decay_ * tank_r_out_;
            float tank_r_in = diffused + decay_ * tank_l_out_;
 
            // --- Tank Left (read-before-write preserves Dattorro delays) ---
            // Cubic interpolation on all modulated reads reduces HF artifacts
            float tl = tank_l_ap1_.process(tank_l_in);
            float tl_dl1 = tank_l_dl1_.read_cubic(
                static_cast<float>(plate::TANK_L_DELAY1) + mod_dl1_l);
            tank_l_dl1_.write(tl);
            tl = tank_l_ap2_.process(tank_l_damp_.process(tl_dl1) * decay_);
            float tl_dl2 = tank_l_dl2_.read_cubic(
                static_cast<float>(plate::TANK_L_DELAY2) + mod_dl2_l);
            tank_l_dl2_.write(tl);
            tank_l_out_ = tl_dl2;
 
            // --- Tank Right (read-before-write preserves Dattorro delays) ---
            float tr = tank_r_ap1_.process(tank_r_in);
            float tr_dl1 = tank_r_dl1_.read_cubic(
                static_cast<float>(plate::TANK_R_DELAY1) + mod_dl1_r);
            tank_r_dl1_.write(tr);
            tr = tank_r_ap2_.process(tank_r_damp_.process(tr_dl1) * decay_);
            float tr_dl2 = tank_r_dl2_.read_cubic(
                static_cast<float>(plate::TANK_R_DELAY2) + mod_dl2_r);
            tank_r_dl2_.write(tr);
            tank_r_out_ = tr_dl2;
 
            // === Multi-tap stereo output ===
            // Dattorro output tapping: 7 taps per channel from the
            // opposite tank half (cross-fed), using deep taps into the
            // long delay lines for maximum echo density.
            float out_l = tap_from(tank_r_ap1_buf_, plate::TANK_R_AP1,
                                   tank_r_ap1_.write_pos(), plate::TAP_R_AP1_A)
                        + tap_from(tank_r_dl1_buf_,
                                   plate::TANK_R_DELAY1 + plate::MOD_MARGIN,
                                   tank_r_dl1_.write_pos(), plate::TAP_R_DL1_A)
                        - tap_from(tank_r_ap2_buf_, plate::TANK_R_AP2,
                                   tank_r_ap2_.write_pos(), plate::TAP_R_AP2_A)
                        + tap_from(tank_r_dl2_buf_,
                                   plate::TANK_R_DELAY2 + plate::MOD_MARGIN,
                                   tank_r_dl2_.write_pos(), plate::TAP_R_DL2_A)
                        - tap_from(tank_l_dl1_buf_,
                                   plate::TANK_L_DELAY1 + plate::MOD_MARGIN,
                                   tank_l_dl1_.write_pos(), plate::TAP_L_DL1_B)
                        - tap_from(tank_l_ap2_buf_, plate::TANK_L_AP2,
                                   tank_l_ap2_.write_pos(), plate::TAP_L_AP2_A)
                        - tap_from(tank_l_dl2_buf_,
                                   plate::TANK_L_DELAY2 + plate::MOD_MARGIN,
                                   tank_l_dl2_.write_pos(), plate::TAP_L_DL2_B);
 
            float out_r = tap_from(tank_l_ap1_buf_, plate::TANK_L_AP1,
                                   tank_l_ap1_.write_pos(), plate::TAP_L_AP1_A)
                        + tap_from(tank_l_dl1_buf_,
                                   plate::TANK_L_DELAY1 + plate::MOD_MARGIN,
                                   tank_l_dl1_.write_pos(), plate::TAP_L_DL1_B)
                        - tap_from(tank_l_ap2_buf_, plate::TANK_L_AP2,
                                   tank_l_ap2_.write_pos(), plate::TAP_L_AP2_A)
                        + tap_from(tank_l_dl2_buf_,
                                   plate::TANK_L_DELAY2 + plate::MOD_MARGIN,
                                   tank_l_dl2_.write_pos(), plate::TAP_L_DL2_A)
                        - tap_from(tank_r_dl1_buf_,
                                   plate::TANK_R_DELAY1 + plate::MOD_MARGIN,
                                   tank_r_dl1_.write_pos(), plate::TAP_R_DL1_B)
                        - tap_from(tank_r_ap2_buf_, plate::TANK_R_AP2,
                                   tank_r_ap2_.write_pos(), plate::TAP_R_AP2_A)
                        - tap_from(tank_r_dl2_buf_,
                                   plate::TANK_R_DELAY2 + plate::MOD_MARGIN,
                                   tank_r_dl2_.write_pos(), plate::TAP_R_DL2_B);
 
            out_l *= 0.15f;
            out_r *= 0.15f;
 
            float mono = (out_l + out_r) * 0.5f;
            out_l = mono + width_ * (out_l - mono);
            out_r = mono + width_ * (out_r - mono);
 
            left[i]  = dry * in_l + wet * out_l;
            right[i] = dry * in_r + wet * out_r;
        }
    }
 
    void reset() {
        if (pool_) {
            for (uint32_t i = 0; i < pool_size_; ++i) pool_[i] = 0.0f;
        }
 
        for (int i = 0; i < 4; ++i) input_ap_[i].clear();
        tank_l_ap1_.clear();
        tank_l_ap2_.clear();
        tank_r_ap1_.clear();
        tank_r_ap2_.clear();
 
        tank_l_dl1_.clear();
        tank_l_dl2_.clear();
        tank_r_dl1_.clear();
        tank_r_dl2_.clear();
 
        predelay_wp_ = 0;
 
        tank_l_out_ = 0.0f;
        tank_r_out_ = 0.0f;
        tank_l_damp_.reset();
        tank_r_damp_.reset();
        bandwidth_.reset();
 
        // Reset quadrature oscillator (sine=0, cosine=1)
        mod_sin_ = 0.0f;
        mod_cos_ = 1.0f;
    }
 
private:
    void predelay_write(float sample) {
        predelay_buf_[predelay_wp_] = sample;
        ++predelay_wp_;
        if (predelay_wp_ >= plate::PREDELAY_MAX) predelay_wp_ = 0;
    }
 
    float predelay_read() const {
        if (predelay_samples_ == 0) {
            return predelay_buf_[predelay_wp_];
        }
        uint32_t pos = (predelay_wp_ >= predelay_samples_)
            ? predelay_wp_ - predelay_samples_
            : predelay_wp_ + plate::PREDELAY_MAX - predelay_samples_;
        return predelay_buf_[pos];
    }
 
    static float tap_from(const float* buf, uint32_t buf_size,
                          uint32_t write_pos, uint32_t tap_offset) {
        if (tap_offset >= buf_size) tap_offset = buf_size - 1;
        uint32_t pos = (write_pos >= tap_offset)
            ? write_pos - tap_offset
            : write_pos + buf_size - tap_offset;
        return buf[pos];
    }
 
    float* pool_ = nullptr;
    uint32_t pool_size_ = 0;
 
    float* predelay_buf_ = nullptr;
 
    float* tank_l_ap1_buf_ = nullptr;
    float* tank_l_dl1_buf_ = nullptr;
    float* tank_l_ap2_buf_ = nullptr;
    float* tank_l_dl2_buf_ = nullptr;
 
    float* tank_r_ap1_buf_ = nullptr;
    float* tank_r_dl1_buf_ = nullptr;
    float* tank_r_ap2_buf_ = nullptr;
    float* tank_r_dl2_buf_ = nullptr;
 
    sbl::dsp::AllpassFilter input_ap_[4];
    sbl::dsp::AllpassFilter tank_l_ap1_;
    sbl::dsp::AllpassFilter tank_l_ap2_;
    sbl::dsp::AllpassFilter tank_r_ap1_;
    sbl::dsp::AllpassFilter tank_r_ap2_;
 
    sbl::dsp::ModulatedDelayLine tank_l_dl1_;
    sbl::dsp::ModulatedDelayLine tank_l_dl2_;
    sbl::dsp::ModulatedDelayLine tank_r_dl1_;
    sbl::dsp::ModulatedDelayLine tank_r_dl2_;
 
    uint32_t predelay_wp_ = 0;
 
    float tank_l_out_ = 0.0f;
    float tank_r_out_ = 0.0f;
 
    dsp::OnePole tank_l_damp_;
    dsp::OnePole tank_r_damp_;
    dsp::OnePole bandwidth_;   // Input bandwidth limiter (Dattorro input LP)
 
    // Quadrature oscillator state
    float mod_sin_ = 0.0f;
    float mod_cos_ = 1.0f;
    float mod_inc_ = 0.0f;
 
    float decay_ = 0.7f;
    float damping_ = 0.3f;
    float width_ = 1.0f;
    float mix_ = 0.3f;
    uint32_t predelay_samples_ = 0;
    uint32_t sample_rate_ = 48000;
};
 
} // namespace sbl::widgets::proc