RingModulator.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/DenormalGuard.h"
#include "../Core/DspMath.h"
#include "../Core/Phasor.h"
#include "../Core/StateBlob.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <numbers>
#include <vector>
 
namespace dspark {
 
template <FloatType T>
class RingModulator
{
public:
    enum class Mode
    {
        Classic,        
        GeometricMean   
    };
 
    void prepare(const AudioSpec& spec) noexcept
    {
        if (!spec.isValid()) return; // release-safe: keep previous state
 
        phasor_.prepare(spec.sampleRate);
 
        const T initialFreq = frequency_.load(std::memory_order_relaxed);
        const T initialMix = mix_.load(std::memory_order_relaxed);
 
        phasor_.setFrequency(initialFreq);
        currentFreq_ = initialFreq;
        currentMix_ = initialMix;
        numChannels_ = spec.numChannels;
    }
 
    void processBlock(AudioBufferView<T> buffer) noexcept
    {
        const int numCh = std::min(buffer.getNumChannels(), numChannels_);
        const int numSamples = buffer.getNumSamples();
        if (numSamples <= 0 || numCh <= 0) return;
 
        // RT denormal hygiene: consistent with the framework's other audio-path
        // processors (the GeometricMean sqrt/copysign chain can carry denormal
        // inputs into the slow path).
        DenormalGuard guard;
 
        // Fetch targets for smoothing
        const T targetFreq = frequency_.load(std::memory_order_relaxed);
        const T targetMix = mix_.load(std::memory_order_relaxed);
        const T soarVal = soar_.load(std::memory_order_relaxed);
        const auto modeVal = mode_.load(std::memory_order_relaxed);
 
        // Calculate smoothing steps
        const T invSamples = T(1) / static_cast<T>(numSamples);
        const T freqStep = (targetFreq - currentFreq_) * invSamples;
        const T mixStep = (targetMix - currentMix_) * invSamples;
 
        // Process in L1-cache friendly chunks to allow outer channel loop
        constexpr int CHUNK_SIZE = 64;
        std::array<T, CHUNK_SIZE> carrierChunk;
        std::array<T, CHUNK_SIZE> mixChunk;
 
        const T twoPi = T(2) * static_cast<T>(std::numbers::pi);
 
        for (int start = 0; start < numSamples; start += CHUNK_SIZE)
        {
            const int chunkLen = std::min(CHUNK_SIZE, numSamples - start);
 
            // 1. Precalculate shared carrier and mix block
            for (int i = 0; i < chunkLen; ++i)
            {
                currentFreq_ += freqStep;
                currentMix_ += mixStep;
 
                phasor_.setFrequency(currentFreq_);
                T phase = phasor_.advance();
 
                // fastSin: error > 100 dB below the carrier - inaudible even
                // though the carrier itself is audible in ring modulation.
                carrierChunk[i] = fastSin(phase * twoPi);
                mixChunk[i] = currentMix_;
            }
 
            // 2. Process channels with hoisted branches and SIMD-friendly loops
            if (modeVal == Mode::GeometricMean)
            {
                for (int ch = 0; ch < numCh; ++ch)
                {
                    T* data = buffer.getChannel(ch) + start;
 
                    for (int i = 0; i < chunkLen; ++i)
                    {
                        const T dry = data[i];
                        const T carrier = carrierChunk[i];
 
                        const T absIn = std::abs(dry);
                        const T absCarrier = std::abs(carrier);
 
                        // Scaled soarVal prevents DC offset when input is zero
                        const T gm = std::sqrt(absIn * absCarrier + soarVal * absIn);
 
                        // Ultra-fast sign evaluation without branching
                        const T wet = gm * std::copysign(T(1), dry * carrier);
 
                        data[i] = dry + (wet - dry) * mixChunk[i];
                    }
                }
            }
            else // Mode::Classic
            {
                for (int ch = 0; ch < numCh; ++ch)
                {
                    T* data = buffer.getChannel(ch) + start;
 
                    for (int i = 0; i < chunkLen; ++i)
                    {
                        const T dry = data[i];
                        const T wet = dry * carrierChunk[i];
                        data[i] = dry + (wet - dry) * mixChunk[i];
                    }
                }
            }
        }
 
        // Land exactly on the published targets: the accumulated ramp ends
        // within rounding of them, and the next block must start settled
        // (matches the framework's smoothing convention).
        currentFreq_ = targetFreq;
        currentMix_ = targetMix;
    }
 
    void reset() noexcept { phasor_.reset(); }
 
    void setFrequency(T hz) noexcept
    {
        if (!std::isfinite(hz)) return; // NaN/Inf would poison the smoothed ramp
        frequency_.store(hz, std::memory_order_relaxed);
    }
 
    void setMix(T mix) noexcept
    {
        if (!std::isfinite(mix)) return;
        mix_.store(std::clamp(mix, T(0), T(1)), std::memory_order_relaxed);
    }
 
    void setMode(Mode m) noexcept
    {
        const int v = std::clamp(static_cast<int>(m),
                                 static_cast<int>(Mode::Classic),
                                 static_cast<int>(Mode::GeometricMean));
        mode_.store(static_cast<Mode>(v), std::memory_order_relaxed);
    }
 
    void setSoar(T amount) noexcept
    {
        if (!std::isfinite(amount)) return;
        soar_.store(std::max(amount, T(0)), std::memory_order_relaxed);
    }
 
    [[nodiscard]] T getFrequency() const noexcept { return frequency_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getMix() const noexcept { return mix_.load(std::memory_order_relaxed); }
    [[nodiscard]] Mode getMode() const noexcept { return mode_.load(std::memory_order_relaxed); }
    [[nodiscard]] T getSoar() const noexcept { return soar_.load(std::memory_order_relaxed); }
 
    [[nodiscard]] std::vector<uint8_t> getState() const
    {
        // The blob stores float (setState reads float back); the explicit
        // casts also keep this overload resolvable when T is double.
        StateWriter w(stateId("RING"), 1);
        w.write("frequency", static_cast<float>(frequency_.load(std::memory_order_relaxed)));
        w.write("mix", static_cast<float>(mix_.load(std::memory_order_relaxed)));
        w.write("mode", static_cast<int32_t>(mode_.load(std::memory_order_relaxed)));
        w.write("soar", static_cast<float>(soar_.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("RING")) return false;
        setFrequency(static_cast<T>(r.read("frequency", 440.0f)));
        setMix(static_cast<T>(r.read("mix", 1.0f)));
        setMode(static_cast<Mode>(r.read("mode", 0)));
        setSoar(static_cast<T>(r.read("soar", 0.0f)));
        return true;
    }
 
private:
    int numChannels_ = 0;
 
    // Atomic targets for lock-free UI/Thread communication
    std::atomic<T> frequency_ { T(440) };
    std::atomic<T> mix_ { T(1) };
    std::atomic<Mode> mode_ { Mode::Classic };
    std::atomic<T> soar_ { T(0) };
 
    // DSP State (Internal audio-thread only, no atomics required)
    T currentFreq_ { T(440) };
    T currentMix_ { T(1) };
    Phasor<T> phasor_;
};
 
} // namespace dspark