exp_mod.hpp

Go to the documentation of this file.

// sbl/signal/exp_mod.hpp — Exponential modulation converter (Signal layer)
//
// The "exponential converter IC" of the digital world. In analog synths,
// a dedicated circuit converts linear control voltage to exponential
// frequency scaling — this is what makes 1V/oct work. Without it,
// modulation is perceptually broken: ±200 Hz is 2.3 octaves at 300 Hz
// but 0.03 octaves at 10 kHz.
//
// exp_mod() bridges normalized modulation signals [-1.0, 1.0] and
// engineering-unit parameters (Hz). This is the application point where
// the Signal principle holds: "Signals follow [-1.0, 1.0]. Configuration
// uses engineering units."
//
// Part of the Audio Stack: Atoms → Signal → Widgets
// See FDP-031 for architecture rationale, RPT-014 for the triggering bug.
//
// Usage:
//   // Scalar — inside a per-sample loop
//   float freq = sbl::signal::exp_mod(cutoff_hz, lfo_value, 2.0f);
//
//   // Block — apply to an entire modulation buffer
//   float freq_buf[48];
//   sbl::signal::exp_mod_block(lfo_buf, freq_buf, n, cutoff_hz, 2.0f);
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/fast_math.hpp>
 
namespace sbl::signal {
 
/// Apply exponential modulation to a base frequency (scalar).
///
/// Converts a normalized modulation signal to a frequency via:
///   freq = base * 2^(mod * depth)
///
/// At depth = 2.0 and mod = 1.0, output is base * 4 (2 octaves up).
/// At depth = 2.0 and mod = -1.0, output is base / 4 (2 octaves down).
/// The relationship is perceptually uniform — equal mod deltas produce
/// equal musical intervals regardless of the base frequency.
///
/// @param base   Center frequency in Hz (e.g., filter cutoff)
/// @param mod    Normalized modulation value, typically [-1.0, 1.0]
/// @param depth  Modulation depth in octaves (e.g., 2.0 = ±2 octaves)
/// @param lo     Minimum output frequency in Hz (default 20)
/// @param hi     Maximum output frequency in Hz (default 20000)
/// @return       Modulated frequency in Hz, clamped to [lo, hi]
inline float exp_mod(float base, float mod, float depth,
                     float lo = 20.0f, float hi = 20000.0f) {
    float freq = base * dsp::fast_exp2f(mod * depth);
    if (freq < lo) freq = lo;
    if (freq > hi) freq = hi;
    return freq;
}
 
/// Apply exponential modulation to an entire block (buffer version).
///
/// Writes modulated frequencies to freq_out[] for each sample. Use this
/// when you need the frequency buffer for direct coefficient computation
/// (e.g., feeding into a filter's set_cutoff per-sample).
///
/// @param mod       Normalized modulation signal buffer [-1.0, 1.0]
/// @param freq_out  Output frequency buffer (Hz)
/// @param n         Frame count
/// @param base      Center frequency in Hz
/// @param depth     Modulation depth in octaves
/// @param lo        Minimum output frequency in Hz (default 20)
/// @param hi        Maximum output frequency in Hz (default 20000)
inline void exp_mod_block(const float* mod, float* freq_out, uint16_t n,
                          float base, float depth,
                          float lo = 20.0f, float hi = 20000.0f) {
    for (uint16_t i = 0; i < n; ++i) {
        freq_out[i] = exp_mod(base, mod[i], depth, lo, hi);
    }
}
 
} // namespace sbl::signal