fader.hpp

Go to the documentation of this file.

// sbl/dsp/comp/fader.hpp — Gain control with taper curve (Audio Stack — Compositions)
//
// Atomic gain element for mixer faders, VCA control, or any context where a
// normalized [0,1] signal controls amplitude. Applies a taper curve (linear,
// audio, or exponential) and per-sample one-pole smoothing for click-free
// gain changes.
//
// Taper curves shape the perceived loudness response:
//   Linear:      gain = su           (even distribution)
//   Audio:       gain = su^2         (perceived-loudness, log-like)
//   Exponential: gain = su^3         (aggressive low-end concentration)
//
// Signal Unit API (FDP-064):
//   set_level_su(float) — [0,1] port. Clamped, taper-mapped, smoothed.
//   set_taper(Taper)    — structural parameter, selects curve shape.
//
// Usage:
//   sbl::dsp::comp::Fader fader;
//   fader.set_level_su(0.7f);               // normalized fader position
//   fader.set_taper(Taper::Audio);          // default — perceived loudness
//   fader.process(buf, frames);             // per-sample smoothed gain
//   fader.process(buf_l, buf_r, frames);    // stereo variant
 
#ifndef SBL_DSP_COMP_FADER_HPP_
#define SBL_DSP_COMP_FADER_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/primitives/parameter_smoother.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::comp {
 
enum class Taper : uint8_t {
    Linear,       // gain = su
    Audio,        // gain = su^2 (perceived loudness, log-like)
    Exponential,  // gain = su^3 (aggressive low-end concentration)
};
 
class Fader {
public:
    static constexpr float kSettlingMs = 15.0f;
 
    /// Port: set the fader level [0, 1].
    /// Clamped, taper-mapped, and fed into internal smoother.
    void set_level_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        level_su_ = su;
        target_gain_ = apply_taper(su);
    }
 
    /// Parameter: set the taper curve (structural config).
    /// Recomputes target gain from current level.
    void set_taper(Taper t) {
        taper_ = t;
        target_gain_ = apply_taper(level_su_);
    }
 
    /// Apply gain to a mono buffer in-place.
    /// Per-sample smoothing toward target gain — click-free.
    void process(float* buf, uint16_t n) {
        ensure_smoother();
        for (uint16_t i = 0; i < n; ++i) {
            float g = smoother_.process(target_gain_);
            buf[i] *= g;
        }
    }
 
    /// Apply gain to stereo buffers in-place.
    /// Same smoothed gain applied to both channels per sample.
    void process(float* buf_l, float* buf_r, uint16_t n) {
        ensure_smoother();
        for (uint16_t i = 0; i < n; ++i) {
            float g = smoother_.process(target_gain_);
            buf_l[i] *= g;
            buf_r[i] *= g;
        }
    }
 
    /// Advance the smoother by n samples' worth without processing audio.
    /// Call once per block with the block size for control-rate gain updates
    /// (e.g., send levels) — settling time matches per-sample process()
    /// regardless of call rate.
    /// Returns the current smoothed gain.
    float tick(uint16_t n) {
        ensure_smoother();
        return smoother_.process_steps(target_gain_, n);
    }
 
    /// Current smoothed gain value (after taper mapping + smoothing).
    float gain() const { return smoother_.value(); }
 
    /// Raw su level (before taper mapping).
    float level() const { return level_su_; }
 
    /// Reset smoother state and level to defaults.
    void reset() {
        level_su_ = 1.0f;
        taper_ = Taper::Audio;
        target_gain_ = apply_taper(level_su_);
        smoother_.reset(target_gain_);
        smoother_configured_ = false;
    }
 
private:
    float apply_taper(float su) const {
        switch (taper_) {
            case Taper::Linear:      return su;
            case Taper::Audio:       return su * su;
            case Taper::Exponential: return su * su * su;
        }
        return su;  // unreachable, but satisfies compiler
    }
 
    void ensure_smoother() {
        if (!smoother_configured_) {
            smoother_.set_time_ms(kSettlingMs, types::SAMPLE_RATE_F);
            smoother_.reset(target_gain_);
            smoother_configured_ = true;
        }
    }
 
    Taper taper_ = Taper::Audio;
    float level_su_ = 1.0f;
    float target_gain_ = 1.0f;  // apply_taper(1.0f) for Audio = 1.0
    primitives::ParameterSmoother smoother_;
    bool smoother_configured_ = false;
};
 
} // namespace sbl::dsp::comp
 
#endif // SBL_DSP_COMP_FADER_HPP_