Clipper.h

Go to the documentation of this file.

// 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/StateBlob.h"
 
#include <algorithm>
#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);
 
        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);
        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);
 
        T ceiling      = dbToLinear(ceilDb);
        T totalGainLin = dbToLinear(gainDb);
 
        // Split gain logarithmically across cascaded stages
        T stageGain    = (numStages > 1)
                           ? std::pow(totalGainLin, T(1) / static_cast<T>(numStages))
                           : totalGainLin;
 
        // Calculate maximum allowed delta per sample based on the physical sample rate
        T maxSlewDelta = T(0);
        if (slewMs > T(0)) {
            maxSlewDelta = (ceiling / (slewMs * T(0.001))) / static_cast<T>(currentSampleRate);
        }
 
        // The mode switch is resolved once per block, outside the sample loop.
        switch (modeVal)
        {
            case Mode::Hard:        dispatchClipping<Mode::Hard>(buffer, totalGainLin, stageGain, numStages, ceiling, maxSlewDelta); break;
            case Mode::Soft:        dispatchClipping<Mode::Soft>(buffer, totalGainLin, stageGain, numStages, ceiling, maxSlewDelta); break;
            case Mode::Analog:      dispatchClipping<Mode::Analog>(buffer, totalGainLin, stageGain, numStages, ceiling, maxSlewDelta); break;
            case Mode::GoldenRatio: dispatchClipping<Mode::GoldenRatio>(buffer, totalGainLin, stageGain, numStages, ceiling, maxSlewDelta); break;
            default:                dispatchClipping<Mode::Hard>(buffer, totalGainLin, stageGain, numStages, ceiling, maxSlewDelta); break;
        }
    }
 
    template <Mode M>
    void dispatchClipping(AudioBufferView<T>& buffer, T totalGainLin, T stageGain, int numStages, T ceiling, T maxSlewDelta) noexcept
    {
        const int nCh = std::min(buffer.getNumChannels(), kMaxChannels);
        const int nS  = buffer.getNumSamples();
 
        T peakIn  = T(0);
        T peakOut = T(0);
 
        for (int ch = 0; ch < nCh; ++ch)
        {
            T* data = buffer.getChannel(ch);
            for (int i = 0; i < nS; ++i)
            {
                T sample = data[i];
                T driven = sample * totalGainLin;
 
                // 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)
                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[i] = 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 std::clamp(sample, -ceiling, ceiling);
        }
        else if constexpr (M == Mode::Soft)
        {
            return ceiling * std::tanh(sample / ceiling);
        }
        else if constexpr (M == Mode::Analog)
        {
            // Unity-slope sine shaper: sin(x/ceiling) has derivative 1 at the
            // origin, so quiet material passes at exactly 0 dB like the other
            // modes (the old pre-scaled form had slope pi/2, a +3.9 dB jump
            // when switching modes). The knee spans |x| in [~ceiling*0.5,
            // ceiling*pi/2] and lands exactly on the ceiling.
            constexpr T halfPi = static_cast<T>(std::numbers::pi * 0.5);
            return ceiling * fastSin(std::clamp(sample / ceiling, -halfPi, halfPi));
        }
        else // Mode::GoldenRatio (the mode switch instantiates no other value)
        {
            // True mathematical Golden Ratio soft-knee
            T threshold = ceiling / kPhi;
            T absSample = std::abs(sample);
 
            if (absSample <= threshold)
                return sample;
 
            // Rational asymptotic curve to the ceiling
            T sign = std::copysign(T(1), sample);
            T excess = absSample - threshold;
            T range = ceiling - threshold;
 
            return sign * (threshold + (range * excess) / (excess + range));
        }
    }
 
    // 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] {};
 
    // Metering state
    std::atomic<T> gainReductionDb_ { T(0) };
};
 
} // namespace dspark