warp.hpp

Go to the documentation of this file.

// sbl/dsp/warp.hpp — Curve warp engines for envelopes and parameter scaling
//
// Each engine warps a linear phase [0, 65535] into a shaped phase using a
// curve parameter: 0 = full concave (log), 32768 = linear, 65535 = full convex (exp).
//
// Engines are stateless structs with a single static method, selected at
// compile time as a template parameter to SegmentGenerator/Envelope.
//
// See FDP-016 for design rationale.
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/fixed.hpp>
#include <sbl/dsp/lut.hpp>
#include <sbl/dsp/tables/exp_curve_256.hpp>
 
namespace sbl::dsp {
 
// ─── Curve shape presets ─────────────────────────────────────────────
//
// Named constants for the curve parameter used by warp engines and
// scaled_curved(). Arbitrary uint16_t values work too — these are the
// three common presets.
//
//   Log:    logarithmic shape (concave, above diagonal)
//           Output rises quickly then flattens. More resolution at high values.
//
//   Linear: identity (no shaping). Same as scaled().
//
//   Exp:    exponential shape (convex, below diagonal)
//           Output is flat then rises sharply. More resolution at low values.
//           Matches audio-taper pot behavior — use for frequency, pitch, cutoff.
 
namespace curve {
 
static constexpr uint16_t Log     = 0;       // Full concave: fast start, slow approach
static constexpr uint16_t Linear  = U16_MID; // No shaping (identity)
static constexpr uint16_t Exp     = U16_MAX; // Full convex: slow start, fast snap
 
} // namespace curve
 
// ─── lut_curve_warp ──────────────────────────────────────────────────
//
// Generic LUT-based curve warp. Works with any monotonically increasing
// uint16_t table of the given Size. Uses the complement trick + crossfade
// to produce concave, linear, and convex shapes from a single table.
//
// This is the core algorithm extracted from ExpCurveWarp — users can call
// it directly with custom LUTE-generated tables.
 
template<uint16_t Size>
inline uint16_t lut_curve_warp(const uint16_t* table, uint16_t phase, uint16_t curve) {
    if (curve == U16_MID) return phase;
 
    uint32_t phase32 = static_cast<uint32_t>(phase) << 16;
    uint16_t shaped;
    uint32_t amount;
 
    if (curve < U16_MID) {
        // Concave (logarithmic feel): fast start, slow approach to target
        shaped = lut::lookup_linear<Size>(table, phase32);
        uint32_t dc = U16_MID - curve;
        amount = (dc >= U16_MID) ? U16_MAX : dc * 2;
    } else {
        // Convex (exponential feel): slow start, fast snap to target
        // Complement trick: max - f(max - t)
        uint32_t inv_phase32 = static_cast<uint32_t>(U16_MAX - phase) << 16;
        shaped = U16_MAX - lut::lookup_linear<Size>(table, inv_phase32);
        uint32_t dc = curve - U16_MID;
        amount = (dc >= U16_MID) ? U16_MAX : dc * 2;
    }
 
    // Crossfade between linear (phase) and shaped value
    // amount=0 → pure linear, amount=65534 → pure shaped
    return static_cast<uint16_t>(
        phase + ((static_cast<int32_t>(shaped) - phase) * amount >> 16));
}
 
// ─── ExpCurveWarp ────────────────────────────────────────────────────
//
// Single exponential LUT with complement trick. 514 bytes flash, zero RAM.
// True RC charge/discharge character — the Maths approach.
//
// Cost: ~10 cycles on M0+, ~5 cycles on M7.
 
struct ExpCurveWarp {
    /// @note ISR-safe — bounded computation, no I/O.
    static uint16_t warp(uint16_t phase, uint16_t curve) {
        return lut_curve_warp<256>(lut::exp_curve_256, phase, curve);
    }
};
 
// ─── RationalWarp ────────────────────────────────────────────────────
//
// Stages-inspired rational function: f(t) = (1+a)*t / (1+a*t).
// Zero flash, zero RAM. Computed per-sample.
//
// The coefficient a = STAGES_K * (dc/65536)^2 gives a range of [0, ~32],
// matching MI Stages' WarpPhase function.
//
// Cost: ~60 cycles on M0+ (software division), ~15 cycles on M7.
//
// Reference: MI Stages segment_generator.cc (MIT), WarpPhase()
 
struct RationalWarp {
    /// @note ISR-safe — bounded computation, no I/O.
 
    // Coefficient scaling factor from MI Stages WarpPhase.
    // a_float = STAGES_K * curve_centered^2, giving a ∈ [0, ~32].
    static constexpr uint32_t STAGES_K = 128;
 
    static uint16_t warp(uint16_t phase, uint16_t curve) {
        if (curve == U16_MID) return phase;
 
        // Raw rational is concave (above diagonal). Flip for convex side.
        bool flip = curve > U16_MID;
        uint32_t t = flip ? (U16_MAX - phase) : phase;
 
        // Map curve distance from center to coefficient 'a'
        // a_q16 = a * 65536 for Q16 fixed-point arithmetic
        uint32_t dc = flip ? (curve - U16_MID) : (U16_MID - curve);
        uint32_t a_q16 = static_cast<uint32_t>((static_cast<uint64_t>(STAGES_K) * dc * dc) >> 16);
 
        // Rational function in Q16 fixed-point:
        //   result = (1 + a) * t / (1 + a * t)
        // where (1+a) is (Q16_ONE + a_q16) in Q16, and t is [0, U16_MAX]
        uint64_t num = static_cast<uint64_t>(Q16_ONE + a_q16) * t;
        uint32_t den = Q16_ONE + static_cast<uint32_t>(
            static_cast<uint64_t>(a_q16) * t >> 16);
 
        uint32_t result = static_cast<uint32_t>(num / den);
        if (result > U16_MAX) result = U16_MAX;
 
        return static_cast<uint16_t>(flip ? (U16_MAX - result) : result);
    }
};
 
// ─── DefaultWarp ─────────────────────────────────────────────────────
//
// The default uint16 engine for I/O stack (Pot::scaled_curved, CvInput::scaled_curved).
// ExpCurveWarp: best balance of quality, performance, and flash cost.
 
using DefaultWarp = ExpCurveWarp;
 
// ─── Float warp engines ─────────────────────────────────────────────
//
// Float-domain warp engines for the Audio stack (SegmentGenerator, Envelope).
// Phase and curve are both float; no LUT or fixed-point math required.
//
// Phase: [0.0, 1.0] — linear ramp through the segment
// Curve: [-1.0, 1.0] where:
//   -1.0 = full concave (fast start, slow approach to target)
//    0.0 = linear (no shaping)
//    1.0 = full convex (slow start, fast snap to target)
 
/// Rational function warp (float). Zero flash, zero RAM.
/// f(t) = (1+a)*t / (1+a*t), with a = K * curve^2.
/// Inspired by MI Stages WarpPhase (MIT).
struct FloatRationalWarp {
    static constexpr float K = 128.0f;
 
    /// @note ISR-safe — bounded computation, no I/O.
    static float warp(float phase, float curve) {
        if (curve > -0.001f && curve < 0.001f) return phase;
 
        bool flip = curve > 0.0f;
        float t = flip ? (1.0f - phase) : phase;
        float dc = flip ? curve : -curve;
 
        float a = K * dc * dc;
        float num = (1.0f + a) * t;
        float den = 1.0f + a * t;
        float result = num / den;
 
        if (result > 1.0f) result = 1.0f;
        return flip ? (1.0f - result) : result;
    }
};
 
/// Default float warp engine for SegmentGenerator and Envelope.
/// FloatRationalWarp: zero flash, analytical, good character.
using FloatDefaultWarp = FloatRationalWarp;
 
} // namespace sbl::dsp