DryWetMixer.h

Go to the documentation of this file.

// DSPark -- Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi -- MIT License
 
#pragma once
 
#include "AudioBuffer.h"
#include "AudioSpec.h"
 
#include <algorithm>
#include <atomic>
#include <cmath>
 
// DSPARK_RESTRICT is normally provided by SimdOps.h (pulled in via AudioBuffer.h).
// Guard against redefinition so this header stays self-contained if included alone.
#ifndef DSPARK_RESTRICT
  #if defined(__clang__) || defined(__GNUC__)
    #define DSPARK_RESTRICT __restrict__
  #elif defined(_MSC_VER)
    #define DSPARK_RESTRICT __restrict
  #else
    #define DSPARK_RESTRICT
  #endif
#endif
 
namespace dspark {
 
template <typename T, int MaxChannels = 16>
class DryWetMixer
{
public:
    enum class MixRule {
        Linear,
        EqualPower
    };
 
    DryWetMixer() noexcept = default;
 
    // The atomic mix rule makes the implicit move operations vanish. Provide
    // manual moves so the mixer keeps working inside movable owners; moves
    // are single-threaded setup-time relocations, so plain relaxed transfers
    // of the atomic are sufficient. Copying is deleted by the owned buffers.
    DryWetMixer(DryWetMixer&& other) noexcept
        : dryBuffer_(std::move(other.dryBuffer_)),
          capturedSamples_(other.capturedSamples_),
          delayHist_(std::move(other.delayHist_)),
          latencySamples_(other.latencySamples_),
          histPos_(other.histPos_),
          mixRule_(other.mixRule_.load(std::memory_order_relaxed)),
          currentMix_(other.currentMix_)
    {}
 
    DryWetMixer& operator=(DryWetMixer&& other) noexcept
    {
        if (this == &other) return *this;
        dryBuffer_       = std::move(other.dryBuffer_);
        capturedSamples_ = other.capturedSamples_;
        delayHist_       = std::move(other.delayHist_);
        latencySamples_  = other.latencySamples_;
        histPos_         = other.histPos_;
        mixRule_.store(other.mixRule_.load(std::memory_order_relaxed),
                       std::memory_order_relaxed);
        currentMix_      = other.currentMix_;
        return *this;
    }
 
    DryWetMixer(const DryWetMixer&)            = delete;
    DryWetMixer& operator=(const DryWetMixer&) = delete;
 
    void prepare(const AudioSpec& spec)
    {
        dryBuffer_.resize(spec.numChannels, spec.maxBlockSize);
 
        // If latency compensation was configured before prepare(), the delay
        // history was sized with 0 channels; rebuild it now that the channel
        // count is known (otherwise pushDry would index a 0-channel buffer).
        if (latencySamples_ > 0)
        {
            delayHist_.resize(spec.numChannels, latencySamples_);
            histPos_ = 0;
        }
 
        reset();
    }
 
    void reset() noexcept
    {
        dryBuffer_.clear();
        if (delayHist_.getNumSamples() > 0) delayHist_.clear();
        histPos_ = 0;
        capturedSamples_ = 0;  // No valid dry snapshot until the next pushDry().
        currentMix_ = T(-1); // Forces immediate jump on first use
    }
 
    void setMixRule(MixRule rule) noexcept
    {
        mixRule_.store(rule, std::memory_order_relaxed);
    }
 
    void setLatencyCompensation(int samples)
    {
        samples = std::max(0, samples);
        if (samples == latencySamples_) return;
        latencySamples_ = samples;
        delayHist_.resize(dryBuffer_.getNumChannels(), samples);
        histPos_ = 0;
    }
 
    [[nodiscard]] int getLatencyCompensation() const noexcept { return latencySamples_; }
 
    void pushDry(const AudioBufferView<const T>& input) noexcept
    {
        if (dryBuffer_.getNumSamples() == 0) return; // Prevent ops if unprepared
 
        const int chCount  = std::min(input.getNumChannels(), dryBuffer_.getNumChannels());
        const int nSamples = std::min(input.getNumSamples(), dryBuffer_.getNumSamples());
 
        if (latencySamples_ <= 0)
        {
            for (int ch = 0; ch < chCount; ++ch)
            {
                const T* DSPARK_RESTRICT src = input.getChannel(ch);
                T* DSPARK_RESTRICT dst       = dryBuffer_.getChannel(ch);
                std::copy_n(src, nSamples, dst);
            }
        }
        else
        {
            // Latency-compensated capture: route the dry through a per-channel
            // circular delay of exactly latencySamples_ so it stays time-aligned
            // with a wet path that incurs the same delay.
            const int D = latencySamples_;
            for (int ch = 0; ch < chCount; ++ch)
            {
                const T* DSPARK_RESTRICT src = input.getChannel(ch);
                T* DSPARK_RESTRICT dst       = dryBuffer_.getChannel(ch);
                T* DSPARK_RESTRICT hist      = delayHist_.getChannel(ch);
                int pos = histPos_;
                for (int i = 0; i < nSamples; ++i)
                {
                    dst[i]    = hist[pos];   // sample written D steps ago
                    hist[pos] = src[i];
                    if (++pos == D) pos = 0;
                }
            }
            histPos_ = (histPos_ + nSamples) % D;
        }
 
        capturedSamples_ = nSamples;
    }
 
    void mixWet(AudioBufferView<T> wetBuffer, T targetMix) noexcept
    {
        // Handle invalid floating point inputs (NaN) safely
        if (std::isnan(targetMix)) targetMix = T(0);
        targetMix = std::clamp(targetMix, T(0), T(1));
 
        const int chCount  = std::min(wetBuffer.getNumChannels(), dryBuffer_.getNumChannels());
        const int nSamples = std::min(wetBuffer.getNumSamples(), capturedSamples_);
 
        if (nSamples == 0 || chCount == 0) return;
 
        // Initialize smoothing state on first run
        if (currentMix_ < T(0)) currentMix_ = targetMix;
 
        const bool needsSmoothing = std::abs(currentMix_ - targetMix) > T(1e-5);
        const T mixStep = needsSmoothing ? (targetMix - currentMix_) / T(nSamples) : T(0);
        const MixRule rule = mixRule_.load(std::memory_order_relaxed);
 
        // Every channel ramps from the same smoothed origin. The ramps below
        // are indexed (mix0 + mixStep * i) rather than accumulated: one
        // rounding per sample instead of a drift that grows with the block
        // (a serial accumulator can overshoot the [0, 1] range on long
        // blocks), and no loop-carried dependency in the way of the
        // auto-vectoriser.
        const T mix0 = currentMix_;
 
        for (int ch = 0; ch < chCount; ++ch)
        {
            T* DSPARK_RESTRICT wetData       = wetBuffer.getChannel(ch);
            const T* DSPARK_RESTRICT dryData = dryBuffer_.getChannel(ch);
 
            if (rule == MixRule::EqualPower)
            {
                if (!needsSmoothing)
                {
                    // Static mix: hoist both square roots out of the loop;
                    // the body becomes a single FMA per sample (vectorizable).
                    const T w = std::sqrt(mix0);
                    const T d = std::sqrt(T(1) - mix0);
                    for (int i = 0; i < nSamples; ++i)
                        wetData[i] = dryData[i] * d + wetData[i] * w;
                }
                else
                {
                    for (int i = 0; i < nSamples; ++i)
                    {
                        // Exact constant-power law: w^2 + d^2 = 1. The max()
                        // guards keep float rounding at the ramp ends from
                        // pushing a radicand a few ulp negative, where sqrt()
                        // would inject NaN into the output.
                        const T m = mix0 + mixStep * T(i);
                        const T w = std::sqrt(std::max(T(0), m));
                        const T d = std::sqrt(std::max(T(0), T(1) - m));
                        wetData[i] = dryData[i] * d + wetData[i] * w;
                    }
                }
            }
            else // MixRule::Linear
            {
                if (!needsSmoothing)
                {
                    const T w = mix0;
                    const T d = T(1) - w;
                    for (int i = 0; i < nSamples; ++i)
                        wetData[i] = dryData[i] * d + wetData[i] * w;
                }
                else
                {
                    for (int i = 0; i < nSamples; ++i)
                    {
                        const T w = mix0 + mixStep * T(i);
                        const T d = T(1) - w;
                        wetData[i] = dryData[i] * d + wetData[i] * w;
                    }
                }
            }
        }
 
        // Update the persistent state after the block is processed
        if (needsSmoothing) currentMix_ = targetMix;
    }
 
    [[nodiscard]] const T* getDryChannel(int ch) const noexcept
    {
        if (ch < 0 || ch >= dryBuffer_.getNumChannels()) return nullptr;
        return dryBuffer_.getChannel(ch);
    }
 
    [[nodiscard]] int getDryNumChannels() const noexcept { return dryBuffer_.getNumChannels(); }
 
    [[nodiscard]] int getDryCapturedSamples() const noexcept { return capturedSamples_; }
 
private:
    AudioBuffer<T, MaxChannels> dryBuffer_;
    int capturedSamples_ = 0;
 
    // Optional dry-path latency compensation (circular delay). Disabled (0) by default.
    AudioBuffer<T, MaxChannels> delayHist_;
    int latencySamples_ = 0;
    int histPos_        = 0;
 
    std::atomic<MixRule> mixRule_ { MixRule::Linear };
    T currentMix_ = T(-1); // Internal state for parameter smoothing
};
 
} // namespace dspark