delay_line.hpp

Go to the documentation of this file.

// sbl/dsp/primitives/delay_line.hpp — Circular buffer delay line
//
// Circular buffer with integer, linear, and 4-point Hermite cubic reads.
// Caller-provided storage. Supports both fixed and per-sample modulated
// read positions.
//
// Domain: Time — stores and retrieves audio across time.
// See docs/design-philosophy.md for the domain manipulation framework.
//
// Usage:
//   float buf[4096] = {};
//   sbl::dsp::primitives::DelayLine dl;
//   dl.init(buf, 4096);
//   dl.write(sample);
//   float out = dl.read(delay_samples);       // linear interpolation
//   float out = dl.read_cubic(delay_samples);  // 4-point Hermite
//
//   // Block processing (fused write+read with per-sample modulation):
//   dl.process(in, out, delay_per_sample, frames);
 
#ifndef SBL_DSP_PRIMITIVES_DELAY_LINE_HPP_
#define SBL_DSP_PRIMITIVES_DELAY_LINE_HPP_
 
#include <cstdint>
 
namespace sbl::dsp::primitives {
 
class DelayLine {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Construct with caller-provided buffer
     * @param buffer Float buffer (must outlive the DelayLine)
     * @param max_delay Maximum delay in samples (buffer size)
     */
    DelayLine(float* buffer, uint32_t max_delay)
        : buffer_(buffer), max_delay_(max_delay), write_pos_(0) {}
 
    /// Default constructor for deferred initialization (must call init() before use)
    DelayLine() = default;
 
    /**
     * @brief Initialize after default construction
     * @param buffer Float buffer (must outlive the DelayLine)
     * @param max_delay Maximum delay in samples (buffer size)
     */
    void init(float* buffer, uint32_t max_delay) {
        buffer_ = buffer;
        max_delay_ = max_delay;
        write_pos_ = 0;
    }
 
    /**
     * @brief Write a sample to the delay line
     *
     * Advances the write pointer after storing. The write pointer always
     * points to the next write location.
     */
    void write(float sample) {
        buffer_[write_pos_] = sample;
        ++write_pos_;
        if (write_pos_ >= max_delay_) {
            write_pos_ = 0;
        }
    }
 
    /**
     * @brief Read at fractional delay with linear interpolation
     *
     * @param delay_samples Delay in samples (1.0 = most recently written sample).
     *        Clamped to [1.0, max_delay - 1].
     * @return Linearly interpolated sample
     */
    float read(float delay_samples) const {
        // Clamp to valid range for linear interpolation
        if (delay_samples < 1.0f) delay_samples = 1.0f;
        float max_f = static_cast<float>(max_delay_ - 1);
        if (delay_samples > max_f) delay_samples = max_f;
 
        // Split into integer and fractional parts
        uint32_t int_delay = static_cast<uint32_t>(delay_samples);
        float frac = delay_samples - static_cast<float>(int_delay);
 
        // Read two adjacent samples
        float y0 = read_at(int_delay);
        float y1 = read_at(int_delay + 1);
 
        // Linear interpolation
        return y0 + frac * (y1 - y0);
    }
 
    /**
     * @brief Read at fractional delay with 4-point Hermite cubic interpolation
     *
     * Higher quality than linear — reduces artifacts for reverb tank modulation
     * and pitch shifting. Uses samples at [d-1, d, d+1, d+2] around the read
     * position.
     *
     * @param delay_samples Delay in samples (1.0 = most recently written sample).
     *        Clamped to [2.0, max_delay - 2].
     * @return Hermite-interpolated sample
     */
    float read_cubic(float delay_samples) const {
        // Clamp to valid range for cubic interpolation (need 1 sample before, 2 after)
        if (delay_samples < 2.0f) delay_samples = 2.0f;
        float max_f = static_cast<float>(max_delay_ - 2);
        if (delay_samples > max_f) delay_samples = max_f;
 
        uint32_t int_delay = static_cast<uint32_t>(delay_samples);
        float frac = delay_samples - static_cast<float>(int_delay);
 
        // 4 samples: y0=d-1, y1=d, y2=d+1, y3=d+2
        float y0 = read_at(int_delay - 1);
        float y1 = read_at(int_delay);
        float y2 = read_at(int_delay + 1);
        float y3 = read_at(int_delay + 2);
 
        // Hermite interpolation (4-point, 3rd-order)
        float a = -0.5f * y0 + 1.5f * y1 - 1.5f * y2 + 0.5f * y3;
        float b = y0 - 2.5f * y1 + 2.0f * y2 - 0.5f * y3;
        float c = -0.5f * y0 + 0.5f * y2;
        float d = y1;
 
        return ((a * frac + b) * frac + c) * frac + d;
    }
 
    /**
     * @brief Block processing with per-sample modulated delay
     *
     * For each frame: writes in[i], reads at delay[i], outputs to out[i].
     * The delay array provides per-sample modulation (e.g., base delay + LFO).
     * Uses linear interpolation.
     *
     * in and out may alias (in-place processing is safe since each sample
     * is read from in before write, and output is written after read).
     *
     * @param in Input audio buffer
     * @param out Output audio buffer
     * @param delay Per-sample delay values in samples
     * @param frames Number of frames to process
     */
    void process(const float* in, float* out,
                 const float* delay, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            write(in[i]);
            out[i] = read(delay[i]);
        }
    }
 
    /** @brief Zero all samples in the buffer and reset write position */
    void reset() {
        if (buffer_) {
            for (uint32_t i = 0; i < max_delay_; ++i) {
                buffer_[i] = 0.0f;
            }
        }
        write_pos_ = 0;
    }
 
    /** @brief Maximum delay in samples (buffer size) */
    uint32_t max_delay() const { return max_delay_; }
 
    /** @brief Current write position (for external tap reads) */
    uint32_t write_pos() const { return write_pos_; }
 
private:
    /**
     * @brief Read sample at integer delay from write position
     * @param delay Integer delay in samples (1 = most recently written)
     */
    float read_at(uint32_t delay) const {
        // write_pos_ points to the *next* write location.
        // delay=1 reads the most recently written sample (write_pos_ - 1).
        uint32_t pos = (write_pos_ + max_delay_ - delay) % max_delay_;
        return buffer_[pos];
    }
 
    float* buffer_ = nullptr;
    uint32_t max_delay_ = 0;
    uint32_t write_pos_ = 0;
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_DELAY_LINE_HPP_