SampleAndHold.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 <cmath>
#include <limits>
 
namespace dspark {
 
template <FloatType T>
class SampleAndHold
{
public:
    enum class Mode
    {
        Counter, 
        Trigger  
    };
 
    void setMode(Mode mode) noexcept { mode_ = mode; }
 
    void setHoldSamples(int numSamples) noexcept
    {
        holdPeriod_ = numSamples > 0 ? numSamples : 1;
    }
 
    void setHoldRate(double targetRate, double actualRate) noexcept
    {
        if (!(targetRate > 0.0) || !(actualRate > 0.0))
        {
            setHoldSamples(1);
            return;
        }
        // Clamp in double before the integer conversion: a huge ratio would
        // overflow the int cast (undefined behaviour).
        const double ratio = actualRate / targetRate;
        constexpr double maxPeriod = static_cast<double>(std::numeric_limits<int>::max());
        setHoldSamples(ratio >= maxPeriod ? std::numeric_limits<int>::max()
                                          : static_cast<int>(std::llround(ratio)));
    }
 
    [[nodiscard]] T process(T input, bool trigger = false) noexcept
    {
        if (mode_ == Mode::Counter)
        {
            ++counter_;
            if (counter_ >= holdPeriod_)
            {
                heldValue_ = input;
                counter_ = 0;
            }
        }
        else // Mode::Trigger
        {
            if (trigger)
            {
                heldValue_ = input;
            }
        }
        return heldValue_;
    }
 
    void processBlock(T* data, int numSamples) noexcept
    {
        if (mode_ == Mode::Counter)
        {
            // Branch hoisted out of the hot loop
            for (int i = 0; i < numSamples; ++i)
            {
                ++counter_;
                if (counter_ >= holdPeriod_)
                {
                    heldValue_ = data[i];
                    counter_ = 0;
                }
                data[i] = heldValue_;
            }
        }
        else
        {
            // In trigger mode with no triggers provided, it holds indefinitely.
            for (int i = 0; i < numSamples; ++i)
            {
                data[i] = heldValue_;
            }
        }
    }
 
    void processBlock(T* data, const bool* triggers, int numSamples) noexcept
    {
        if (mode_ == Mode::Trigger && triggers != nullptr)
        {
            // Branch hoisted out of the hot loop
            for (int i = 0; i < numSamples; ++i)
            {
                if (triggers[i])
                {
                    heldValue_ = data[i];
                }
                data[i] = heldValue_;
            }
        }
        else
        {
            processBlock(data, numSamples);
        }
    }
 
    [[nodiscard]] T getHeldValue() const noexcept { return heldValue_; }
 
    void reset(T initialValue = T(0)) noexcept
    {
        heldValue_ = initialValue;
        counter_ = 0; // Ensures initialValue is output before the next capture
    }
 
private:
    Mode mode_ = Mode::Counter;
    int holdPeriod_ = 1;
    int counter_ = 0;
    T heldValue_ = T(0);
};
 
} // namespace dspark