WaveshapeTable.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 "AudioSpec.h"
#include "AudioBuffer.h"
#include "Oversampling.h"
#include "Interpolation.h"
 
#include <algorithm>
#include <cassert>
#include <cmath>
#include <functional>
#include <memory>
#include <vector>
 
namespace dspark {
 
template <FloatType T>
class WaveshapeTable
{
public:
    WaveshapeTable() 
    {
        buildFromFunction([](T x) { return x; }, 4);
    }
 
    void buildFromFunction(std::function<T(T)> func, int tableSize = 4096, T xMax = T(8))
    {
        assert(tableSize >= 4);
        assert(xMax > T(0));
 
        // Release-safe clamps: a tableSize below 4 makes process() compute
        // negative table positions (out-of-bounds reads), and a huge one
        // overflows the 32-bit size_t arithmetic on WASM. Invalid xMax
        // (non-positive or NaN) falls back to the default half-range.
        tableSize = std::clamp(tableSize, 4, 1 << 20);
        if (!(xMax > T(0))) xMax = T(8);
 
        tableSize_ = tableSize;
        xMax_ = std::max(xMax, T(0.001));
        invRange_ = T(1) / (T(2) * xMax_);
 
        // Allocate tableSize + 3 to accommodate Hermite interpolation padding.
        // This eliminates conditional branch bounds-checking in the DSP hot-path.
        table_.resize(static_cast<size_t>(tableSize) + 3);
 
        for (int i = 0; i < tableSize; ++i)
        {
            T x = -xMax_ + T(2) * xMax_ * static_cast<T>(i) / static_cast<T>(tableSize - 1);
            table_[static_cast<size_t>(i + 1)] = func(x); // Offset by 1
        }
 
        // Pad boundaries for Hermite (mirroring endpoints)
        table_[0] = table_[1];
        table_[static_cast<size_t>(tableSize + 1)] = table_[static_cast<size_t>(tableSize)];
        table_[static_cast<size_t>(tableSize + 2)] = table_[static_cast<size_t>(tableSize)];
    }
 
    void buildTanh(int tableSize = 4096)
    {
        buildFromFunction([](T x) -> T { return std::tanh(x); }, tableSize);
    }
 
    void buildHardClip(T threshold = T(0.8), int tableSize = 4096)
    {
        buildFromFunction([threshold](T x) -> T {
            return std::clamp(x, -threshold, threshold);
        }, tableSize);
    }
 
    void buildSoftClip(int tableSize = 4096)
    {
        buildFromFunction([](T x) -> T {
            if (x > T(1)) return T(2.0 / 3.0);
            if (x < T(-1)) return T(-2.0 / 3.0);
            return x - (x * x * x) / T(3);
        }, tableSize);
    }
 
    void buildAsymmetric(int tableSize = 4096)
    {
        buildFromFunction([](T x) -> T {
            return x >= T(0) ? std::tanh(x * T(1.2)) : std::tanh(x * T(0.8));
        }, tableSize);
    }
 
    [[nodiscard]] inline T process(T input, T preGain = T(1), T postGain = T(1)) const noexcept
    {
        // The table spans [-xMax, xMax] (default 8), so realistic drive values
        // keep tracing the curve instead of flattening at the old +-1 boundary.
        // min/max are ordered so that a NaN (input or preGain) resolves to the
        // upper table edge instead of reaching the int cast below (undefined)
        // and indexing out of bounds: the output stays finite.
        T driven = std::max(-xMax_, std::min(xMax_, input * preGain));
 
        // Map to index range [0, tableSize - 1]
        T pos = (driven + xMax_) * invRange_ * static_cast<T>(tableSize_ - 1);
 
        int idx = static_cast<int>(pos);
        T frac = pos - static_cast<T>(idx);
 
        // Base index offset by +1 due to left-side padding
        const T* t = table_.data() + idx + 1;
 
        // Catmull-Rom smoothing via the shared Hermite kernel (Interpolation.h)
        return interpolateHermite(t[-1], t[0], t[1], t[2], frac) * postGain;
    }
 
    void process(T* __restrict data, int numSamples, T preGain = T(1), T postGain = T(1)) const noexcept
    {
        for (int i = 0; i < numSamples; ++i)
            data[i] = process(data[i], preGain, postGain);
    }
 
    // -- Lifecycle & Oversampling ---------------------------------------------
 
    void prepare(const AudioSpec& spec)
    {
        spec_ = spec;
        if (oversampler_)
            oversampler_->prepare(spec);
    }
 
    void setOversampling(int factor)
    {
        assert(factor >= 1 && (factor & (factor - 1)) == 0);
 
        if (factor > 1)
        {
            oversampler_ = std::make_unique<Oversampling<T>>(factor);
            // Oversampling normalises invalid factors release-safe (rounds
            // down to a power of two); mirror the value it actually adopted
            // so getOversamplingFactor() never lies about the running rate.
            oversamplingFactor_ = oversampler_->getFactor();
            if (spec_.sampleRate > 0)
                oversampler_->prepare(spec_);
        }
        else
        {
            oversamplingFactor_ = 1;
            oversampler_.reset();
        }
    }
 
    [[nodiscard]] int getOversamplingFactor() const noexcept { return oversamplingFactor_; }
 
    void processBlock(AudioBufferView<T> buffer, T preGain = T(1), T postGain = T(1)) noexcept
    {
        if (oversamplingFactor_ > 1 && oversampler_)
        {
            auto upView = oversampler_->upsample(buffer);
            for (int ch = 0; ch < upView.getNumChannels(); ++ch)
            {
                process(upView.getChannel(ch), upView.getNumSamples(), preGain, postGain);
            }
            oversampler_->downsample(buffer);
        }
        else
        {
            for (int ch = 0; ch < buffer.getNumChannels(); ++ch)
            {
                process(buffer.getChannel(ch), buffer.getNumSamples(), preGain, postGain);
            }
        }
    }
 
    void reset() noexcept
    {
        if (oversampler_) oversampler_->reset();
    }
 
    [[nodiscard]] int getTableSize() const noexcept { return tableSize_; }
    [[nodiscard]] bool isReady() const noexcept { return tableSize_ > 0; }
 
    [[nodiscard]] T getInputRange() const noexcept { return xMax_; }
 
    [[nodiscard]] int getLatency() const noexcept
    {
        return (oversampler_ && oversamplingFactor_ > 1) ? oversampler_->getLatency() : 0;
    }
 
private:
    std::vector<T> table_;
    int tableSize_ = 0;
    T xMax_ = T(8);                 
    T invRange_ = T(1) / T(16);     
 
    AudioSpec spec_ {};
    std::unique_ptr<Oversampling<T>> oversampler_;
    int oversamplingFactor_ = 1;
};
 
} // namespace dspark