Clipper.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/AudioBuffer.h"
#include "../Core/AudioSpec.h"
#include "../Core/DspMath.h"
#include "../Core/DryWetMixer.h"
#include "../Core/Oversampling.h"
#include "../Core/SmoothedValue.h"
#include "../Core/StateBlob.h"
#include "../Core/detail/ClipperShape.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <bit>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <numbers>
#include <vector>
 
namespace dspark {
 
template <FloatType T>
class Clipper
{
public:
    enum class Mode
    {
        Hard,         
        Soft,         
        Analog,       
        GoldenRatio   
    };
 
    // -- Lifecycle --------------------------------------------------------------
 
    void prepare(const AudioSpec& spec)
    {
        if (!spec.isValid()) return;
 
        prepared_.store(false, std::memory_order_relaxed);
        spec_ = spec;
        mixer_.prepare(spec);
 
        const int osFactor = osFactor_.load(std::memory_order_relaxed);
 
        if (osFactor > 1) {
            oversampler_ = std::make_unique<Oversampling<T>>(
                osFactor, Oversampling<T>::Quality::High);
            oversampler_->prepare(spec);
        } else {
            oversampler_.reset();
        }
 
        // Align the dry copy with the latent (oversampled) wet path so that a
        // dry/wet blend below 100% does not comb-filter.
        mixer_.setLatencyCompensation(oversampler_ ? oversampler_->getLatency() : 0);
 
        // Parameter glides run at the processing (possibly oversampled) rate.
        const double procRate = spec.sampleRate * (oversampler_ ? oversampler_->getFactor() : 1);
        for (auto* sm : { &stageGainSm_, &ceilingSm_ })
        {
            sm->prepare(procRate, kParamRampMs);
            sm->setSmoothingType(SmoothedValue<T>::SmoothingType::Linear);
        }
        snapParameters();
 
        for (int ch = 0; ch < kMaxChannels; ++ch)
            slewPrev_[ch] = T(0);
 
        prepared_.store(true, std::memory_order_relaxed);
    }
 
    void reset() noexcept
    {
        mixer_.reset();
        if (oversampler_) oversampler_->reset();
        for (int ch = 0; ch < kMaxChannels; ++ch)
            slewPrev_[ch] = T(0);
        snapParameters();
        gainReductionDb_.store(T(0), std::memory_order_relaxed);
    }
 
    // -- Processing -------------------------------------------------------------
 
    void processBlock(AudioBufferView<T> buffer) noexcept
    {
        if (!prepared_.load(std::memory_order_relaxed)) return;
        if (buffer.getNumSamples() == 0 || buffer.getNumChannels() == 0) return;
 
        T mixVal = mix_.load(std::memory_order_relaxed);
        mixer_.pushDry(buffer);
 
        if (oversampler_ && oversampler_->getFactor() > 1)
        {
            auto upView = oversampler_->upsample(buffer);
            processInternal(upView, spec_.sampleRate * oversampler_->getFactor());
            oversampler_->downsample(buffer);
        }
        else
        {
            processInternal(buffer, spec_.sampleRate);
        }
 
        mixer_.mixWet(buffer, mixVal);
    }
 
    // -- Parameters (Thread-Safe Setters/Getters) -------------------------------
 
    void setMode(Mode mode) noexcept
    {
        const int m = std::clamp(static_cast<int>(mode), 0,
                                 static_cast<int>(Mode::GoldenRatio));
        mode_.store(static_cast<Mode>(m), std::memory_order_relaxed);
    }
 
    void setCeiling(T dB) noexcept
    {
        if (!std::isfinite(dB)) return;
        ceilingDb_.store(std::clamp(dB, T(-60), T(0)), std::memory_order_relaxed);
    }
 
    void setInputGain(T dB) noexcept
    {
        if (!std::isfinite(dB)) return;
        inputGainDb_.store(std::clamp(dB, T(0), T(48)), std::memory_order_relaxed);
    }
 
    void setStages(int count) noexcept
    {
        stages_.store(std::clamp(count, 1, kMaxStages), std::memory_order_relaxed);
    }
 
    void setMix(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        mix_.store(std::clamp(amount, T(0), T(1)), std::memory_order_relaxed);
    }
 
    void setSlewLimit(T ms) noexcept
    {
        if (!std::isfinite(ms)) return;
        slewLimitMs_.store(std::max(ms, T(0)), std::memory_order_relaxed);
    }
 
    void setOversampling(int factor) noexcept
    {
        factor = std::bit_ceil(static_cast<unsigned int>(std::max(1, factor)));
        osFactor_.store(std::min(factor, 16), std::memory_order_relaxed);
    }
 
    [[nodiscard]] Mode getMode() const noexcept { return mode_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getCeiling() const noexcept { return ceilingDb_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getInputGain() const noexcept { return inputGainDb_.load(std::memory_order_relaxed); }
    [[nodiscard]] int getStages() const noexcept { return stages_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getMix() const noexcept { return mix_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getSlewLimit() const noexcept { return slewLimitMs_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] int getOversampling() const noexcept { return osFactor_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] int getLatency() const noexcept { return oversampler_ ? oversampler_->getLatency() : 0; }
 
    [[nodiscard]] T getGainReductionDb() const noexcept { return gainReductionDb_.load(std::memory_order_relaxed); }
 
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        StateWriter w(stateId("CLIP"), 1);
        w.write("mode", static_cast<int32_t>(mode_.load(std::memory_order_relaxed)));
        w.write("ceiling", static_cast<float>(ceilingDb_.load(std::memory_order_relaxed)));
        w.write("inputGain", static_cast<float>(inputGainDb_.load(std::memory_order_relaxed)));
        w.write("stages", stages_.load(std::memory_order_relaxed));
        w.write("mix", static_cast<float>(mix_.load(std::memory_order_relaxed)));
        w.write("slewLimit", static_cast<float>(slewLimitMs_.load(std::memory_order_relaxed)));
        w.write("oversampling", osFactor_.load(std::memory_order_relaxed));
        return w.blob();
    }
 
    bool setState(const uint8_t* data, size_t size)
    {
        StateReader r(data, size);
        if (!r.isValid() || r.processorId() != stateId("CLIP")) return false;
        setMode(static_cast<Mode>(r.read("mode", 0)));
        setCeiling(static_cast<T>(r.read("ceiling", 0.0f)));
        setInputGain(static_cast<T>(r.read("inputGain", 0.0f)));
        setStages(r.read("stages", 1));
        setMix(static_cast<T>(r.read("mix", 1.0f)));
        setSlewLimit(static_cast<T>(r.read("slewLimit", 0.0f)));
        setOversampling(r.read("oversampling", 1));
        return true;
    }
 
protected:
    static constexpr int kMaxStages = 4;
    static constexpr int kMaxChannels = 16;
 
    static constexpr T kPhi = static_cast<T>(1.6180339887498948482);
 
    void processInternal(AudioBufferView<T>& buffer, double currentSampleRate) noexcept
    {
        Mode modeVal   = mode_.load(std::memory_order_relaxed);
        T ceilDb       = ceilingDb_.load(std::memory_order_relaxed);
        T gainDb       = inputGainDb_.load(std::memory_order_relaxed);
        int numStages  = stages_.load(std::memory_order_relaxed);
        T slewMs       = slewLimitMs_.load(std::memory_order_relaxed);
 
        ceilingSm_.setTargetValue(dbToLinear(ceilDb));
        stageGainSm_.setTargetValue(stageGainFor(dbToLinear(gainDb), numStages));
 
        // Maximum slew per sample is ceiling * slewScale (time-aware).
        const T slewScale = (slewMs > T(0))
            ? T(1) / (slewMs * T(0.001)) / static_cast<T>(currentSampleRate)
            : T(0);
 
        // The mode switch is resolved once per block, outside the sample loop.
        switch (modeVal)
        {
            case Mode::Hard:        dispatchClipping<Mode::Hard>(buffer, numStages, slewScale); break;
            case Mode::Soft:        dispatchClipping<Mode::Soft>(buffer, numStages, slewScale); break;
            case Mode::Analog:      dispatchClipping<Mode::Analog>(buffer, numStages, slewScale); break;
            case Mode::GoldenRatio: dispatchClipping<Mode::GoldenRatio>(buffer, numStages, slewScale); break;
            default:                dispatchClipping<Mode::Hard>(buffer, numStages, slewScale); break;
        }
    }
 
    [[nodiscard]] static T stageGainFor(T totalGainLin, int numStages) noexcept
    {
        return (numStages > 1) ? std::pow(totalGainLin, T(1) / static_cast<T>(numStages))
                               : totalGainLin;
    }
 
    void snapParameters() noexcept
    {
        ceilingSm_.reset(dbToLinear(ceilingDb_.load(std::memory_order_relaxed)));
        stageGainSm_.reset(stageGainFor(dbToLinear(inputGainDb_.load(std::memory_order_relaxed)),
                                        stages_.load(std::memory_order_relaxed)));
    }
 
    template <Mode M>
    void dispatchClipping(AudioBufferView<T>& buffer, int numStages, T slewScale) noexcept
    {
        const int nCh = std::min(buffer.getNumChannels(), kMaxChannels);
        const int nS  = buffer.getNumSamples();
 
        T peakIn  = T(0);
        T peakOut = T(0);
 
        // Chunks: the parameter glides are computed once per sample and shared
        // by every channel; settled, both are plain constants.
        for (int start = 0; start < nS; start += kChunk)
        {
            const int n = std::min(kChunk, nS - start);
            const bool gliding = stageGainSm_.isSmoothing() || ceilingSm_.isSmoothing();
            if (gliding)
                for (int j = 0; j < n; ++j)
                {
                    gainRamp_[static_cast<size_t>(j)] = stageGainSm_.getNextValue();
                    ceilRamp_[static_cast<size_t>(j)] = ceilingSm_.getNextValue();
                }
            const T gainConst = stageGainSm_.getCurrentValue();
            const T ceilConst = ceilingSm_.getCurrentValue();
 
            for (int ch = 0; ch < nCh; ++ch)
            {
                T* data = buffer.getChannel(ch) + start;
                for (int j = 0; j < n; ++j)
                {
                    const T stageGain = gliding ? gainRamp_[static_cast<size_t>(j)] : gainConst;
                    const T ceiling   = gliding ? ceilRamp_[static_cast<size_t>(j)] : ceilConst;
                    T sample = data[j];
                    T totalGain = stageGain;
                    for (int s = 1; s < numStages; ++s) totalGain *= stageGain;
                    const T driven = sample * totalGain;
 
                    // Compiler will unroll this loop for small bounded N
                    for (int s = 0; s < numStages; ++s)
                    {
                        sample *= stageGain;
                        sample = processSample<M>(sample, ceiling);
                    }
 
                    // Slew Limiter processing (branch highly predictable if static)
                    const T maxSlewDelta = ceiling * slewScale;
                    if (maxSlewDelta > T(0))
                    {
                        T delta = sample - slewPrev_[ch];
                        if (std::abs(delta) > maxSlewDelta)
                            sample = slewPrev_[ch] + std::copysign(maxSlewDelta, delta);
                    }
 
                    slewPrev_[ch] = sample;
 
                    peakIn  = std::max(peakIn, std::abs(driven));
                    peakOut = std::max(peakOut, std::abs(sample));
                    data[j] = sample;
                }
            }
        }
 
        // Safe gain reduction calculation
        if (peakIn > T(1e-6)) {
            auto ratio = std::min(peakOut / peakIn, T(1));
            gainReductionDb_.store(gainToDecibels(ratio, T(-100)), std::memory_order_relaxed);
        } else {
            gainReductionDb_.store(T(0), std::memory_order_relaxed);
        }
    }
 
    template <Mode M>
    [[nodiscard]] static inline T processSample(T sample, T ceiling) noexcept
    {
        if constexpr (M == Mode::Hard)
            return detail::clipperShape<detail::ClipperCurve::Hard>(sample, ceiling);
        else if constexpr (M == Mode::Soft)
            return detail::clipperShape<detail::ClipperCurve::Tanh>(sample, ceiling);
        else if constexpr (M == Mode::Analog)
            return detail::clipperShape<detail::ClipperCurve::Sine>(sample, ceiling);
        else // Mode::GoldenRatio (the mode switch instantiates no other value)
            return detail::clipperShape<detail::ClipperCurve::GoldenRatio>(sample, ceiling);
    }
 
    // Mathematical utility helpers
    [[nodiscard]] static T dbToLinear(T dB) noexcept { return std::pow(T(10), dB / T(20)); }
    [[nodiscard]] static T gainToDecibels(T linear, T minusInfinityDb) noexcept
    {
        return linear > T(1e-5) ? T(20) * std::log10(linear) : minusInfinityDb;
    }
 
    AudioSpec spec_ {};
    std::atomic<bool> prepared_ { false };
    DryWetMixer<T> mixer_;
    std::unique_ptr<Oversampling<T>> oversampler_;
 
    // Lock-free parameter states
    std::atomic<Mode> mode_ { Mode::Hard };
    std::atomic<T> ceilingDb_ { T(0) };
    std::atomic<T> inputGainDb_ { T(0) };
    std::atomic<int> stages_ { 1 };
    std::atomic<T> mix_ { T(1) };
    std::atomic<T> slewLimitMs_ { T(0) };
    std::atomic<int> osFactor_ { 1 }; // Default to 1 (off)
 
    // History states per channel
    T slewPrev_[kMaxChannels] {};
 
    // Parameter glides (processing rate) and their per-chunk ramps.
    static constexpr double kParamRampMs = 20.0;
    static constexpr int kChunk = 256;
    SmoothedValue<T> stageGainSm_;
    SmoothedValue<T> ceilingSm_;
    std::array<T, kChunk> gainRamp_ {};
    std::array<T, kChunk> ceilRamp_ {};
 
    // Metering state
    std::atomic<T> gainReductionDb_ { T(0) };
};
 
} // namespace dspark