RingBuffer.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "DspMath.h"
#include "Interpolation.h"
 
#include <algorithm>
#include <cassert>
#include <cstddef>
#include <cstdlib>
#include <cstring>
#include <memory>
 
namespace dspark {
 
enum class InterpMethod
{
    Linear,   
    Cubic,    
    Hermite,  
    Lagrange  
};
 
template <FloatType T>
class RingBuffer
{
public:
    RingBuffer() noexcept = default;
 
    void prepare(int maxSamples) noexcept
    {
        assert(maxSamples > 0);
 
        // Clamp before the round-up loop: growing the signed capacity past
        // 2^30 would overflow the shift (undefined) and never terminate.
        constexpr int kMaxCapacity = 1 << 30;
        if (maxSamples > kMaxCapacity) maxSamples = kMaxCapacity;
 
        capacity_ = 1;
        while (capacity_ < maxSamples)
            capacity_ <<= 1;
 
        mask_ = capacity_ - 1;
 
        // Ensure 32-byte alignment for SIMD operations. std::aligned_alloc
        // additionally requires the size to be an integral multiple of the
        // alignment (UB / nullptr otherwise on POSIX), so round bytes up to 32.
        size_t bytes = static_cast<size_t>(capacity_) * sizeof(T);
        bytes = (bytes + 31u) & ~static_cast<size_t>(31u);
 
        // Custom deleter for aligned allocation
        buffer_.reset(static_cast<T*>(
            #if defined(_MSC_VER)
                _aligned_malloc(bytes, 32)
            #else
                std::aligned_alloc(32, bytes)
            #endif
        ));
 
        // On allocation failure leave the buffer in a safe unprepared state.
        if (!buffer_) { capacity_ = 0; mask_ = 0; writePos_ = 0; return; }
 
        reset();
    }
 
    void reset() noexcept
    {
        if (buffer_)
            std::fill_n(buffer_.get(), capacity_, T(0));
        writePos_ = 0;
    }
 
    inline void push(T sample) noexcept
    {
        if (capacity_ == 0) [[unlikely]] return; // not prepared
        buffer_[writePos_] = sample;
        writePos_ = (writePos_ + 1) & mask_;
    }
 
    void pushBlock(const T* samples, int numSamples) noexcept
    {
        if (capacity_ == 0 || numSamples <= 0) [[unlikely]] return;
 
        if (numSamples >= capacity_)
        {
            // Only the trailing capacity_ samples survive a full overwrite.
            samples += numSamples - capacity_;
            std::memcpy(buffer_.get(), samples, static_cast<size_t>(capacity_) * sizeof(T));
            writePos_ = 0;
            return;
        }
 
        const int firstSpan = std::min(numSamples, capacity_ - writePos_);
        std::memcpy(buffer_.get() + writePos_, samples,
                    static_cast<size_t>(firstSpan) * sizeof(T));
 
        const int remaining = numSamples - firstSpan;
        if (remaining > 0)
            std::memcpy(buffer_.get(), samples + firstSpan,
                        static_cast<size_t>(remaining) * sizeof(T));
 
        writePos_ = (writePos_ + numSamples) & mask_;
    }
 
    [[nodiscard]] inline T read(int delaySamples) const noexcept
    {
        if (capacity_ == 0) [[unlikely]] return T(0); // not prepared
        assert(delaySamples >= 0 && delaySamples < capacity_
               && "RingBuffer::read: delay out of range");
 
        int idx = (writePos_ - 1 - delaySamples) & mask_;
        return buffer_[idx];
    }
 
    template <InterpMethod Method = InterpMethod::Cubic>
    [[nodiscard]] inline T readInterpolated(T delaySamples) const noexcept
    {
        if (capacity_ == 0) [[unlikely]] return T(0); // not prepared
 
        int intDelay = static_cast<int>(delaySamples);
        T frac = delaySamples - static_cast<T>(intDelay);
 
        assert(delaySamples >= T(0) && intDelay + 2 < capacity_);
 
        if constexpr (Method == InterpMethod::Linear)
        {
            T s0 = read(intDelay);
            T s1 = read(intDelay + 1);
            return s0 + frac * (s1 - s0);
        }
        else
        {
            assert(delaySamples >= T(1) && "4-point interpolators require delay >= 1.0");
 
            T s[4];
            // Optimized contiguous logical read
            s[0] = read(intDelay - 1);
            s[1] = read(intDelay);
            s[2] = read(intDelay + 1);
            s[3] = read(intDelay + 2);
 
            // Interpolate within the s[1]..s[2] interval, so an integer delay
            // (frac == 0) returns exactly read(intDelay) == s[1]. The 4-point
            // (y0,y1,y2,y3,frac) overloads do precisely that. (Calling the
            // buffer+position overloads with `frac` would misread it as an
            // absolute index and interpolate s[0]..s[1] with a wrapped neighbour,
            // i.e. a 1-sample delay error.)
            if constexpr (Method == InterpMethod::Cubic || Method == InterpMethod::Hermite)
                return interpolateHermite(s[0], s[1], s[2], s[3], frac);
            else if constexpr (Method == InterpMethod::Lagrange)
                return interpolateLagrange(s[0], s[1], s[2], s[3], frac);
        }
    }
 
    [[nodiscard]] int getCapacity() const noexcept { return capacity_; }
    [[nodiscard]] const T* data() const noexcept { return buffer_.get(); }
    [[nodiscard]] int getWritePosition() const noexcept { return writePos_; }
 
private:
    struct AlignedDeleter {
        void operator()(T* ptr) const {
            #if defined(_MSC_VER)
                _aligned_free(ptr);
            #else
                std::free(ptr);
            #endif
        }
    };
 
    std::unique_ptr<T[], AlignedDeleter> buffer_;
    int capacity_ = 0;
    int mask_ = 0;
    int writePos_ = 0;
};
 
} // namespace dspark