saturate.hpp

Go to the documentation of this file.

// sbl/dsp/saturate.hpp — Soft clipping and saturation
//
// Analytical saturation functions that produce musically useful harmonics
// instead of the harsh artifacts from hard clipping. Zero flash cost
// (no lookup tables), works on M7 FPU or soft-float.
//
// soft_limit(x): Smooth saturation with unity gain at origin. For small
//   inputs, output ≈ input. NOT bounded — approaches x/9 for large x.
//   Use soft_clip() for bounded output.
//
// soft_clip(x): Pre-clamps to [-3, 3] then applies soft_limit.
//   Output is bounded to exactly [-1, 1]. soft_clip(±3) = ±1.
//
// soft_clip_24(x): 24-bit audio output limiter. Unity gain for small
//   signals, smooth compression as level approaches ±SAMPLE_MAX_24.
//   Full-scale input produces ~78% output (gentle compression).
//   Useful for overdrive/warmth, or as a musical alternative to hard clamp.
//
// Inspired by Mutable Instruments stmlib (MIT).
//
// Usage:
//   float out = sbl::dsp::soft_clip(drive * input);   // [-1, 1] output
//   int32_t out = sbl::dsp::soft_clip_24(sample);     // 24-bit audio
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/fixed.hpp>
 
namespace sbl::dsp {
 
/**
 * @brief Smooth saturation with unity gain at origin
 *
 * Uses rational approximation: x * (27 + x²) / (27 + 9x²).
 * Monotonic, odd-symmetric, derivative = 1 at x=0. NOT bounded —
 * approaches x/9 for large x. Use soft_clip() for bounded output.
 *
 * Key values: soft_limit(1.0) ≈ 0.78, soft_limit(3.0) = 1.0
 */
inline float soft_limit(float x) {
    float x2 = x * x;
    return x * (27.0f + x2) / (27.0f + 9.0f * x2);
}
 
/**
 * @brief Bounded soft clipper — output in [-1, 1]
 *
 * Pre-clamps to [-3, 3] then applies soft_limit. Since
 * soft_limit(3) = 1.0 exactly, output is bounded to [-1, 1].
 * Gentle compression: soft_clip(1.0) ≈ 0.78, soft_clip(2.0) ≈ 0.98.
 */
inline float soft_clip(float x) {
    if (x < -3.0f) x = -3.0f;
    if (x >  3.0f) x =  3.0f;
    return soft_limit(x);
}
 
/**
 * @brief Soft saturation for 24-bit audio samples
 *
 * Normalizes to [-1, 1], applies soft_limit, scales back. Unity gain
 * for very small signals, gentle 3rd-harmonic compression as level
 * increases. Full-scale produces ~78% output — this is intentional
 * musical compression, not transparent limiting.
 *
 * For transparent hard limiting, use saturate_24() from fixed.hpp.
 * For overdrive, pre-multiply by a gain factor before calling.
 */
inline int32_t soft_clip_24(int32_t x) {
    constexpr float INV_MAX = 1.0f / static_cast<float>(SAMPLE_MAX_24);
    float f = static_cast<float>(x) * INV_MAX;  // normalize to ~[-1, 1]
    // Clamp to [-3, 3] to handle signals beyond full scale
    if (f < -3.0f) f = -3.0f;
    if (f >  3.0f) f =  3.0f;
    float sat = soft_limit(f);
    return static_cast<int32_t>(sat * static_cast<float>(SAMPLE_MAX_24));
}
 
} // namespace sbl::dsp