units.hpp

Go to the documentation of this file.

#pragma once

 
#include <algorithm>
#include <cmath>
#include <cstdint>
#include <pulp/timebase/beat_division.hpp>
 
namespace pulp::signal::units {

inline constexpr double kDbFloorAmplitude = 1e-10;

inline constexpr double kMidiA4 = 69.0;

inline constexpr double kA4Hz = 440.0;

inline constexpr double kSemitonesPerOctave = 12.0;
inline constexpr double kCentsPerSemitone = 100.0;

inline constexpr double kSemitonesPerVolt = kSemitonesPerOctave;
 
// ── Amplitude ↔ decibels ──────────────────────────────────────────────────

template <typename T>
inline T db_to_linear(T db) {
    return std::pow(T{10}, db / T{20});
}

template <typename T>
inline T linear_to_db(T linear) {
    return T{20} * std::log10(std::max(std::abs(linear), static_cast<T>(kDbFloorAmplitude)));
}
 
// ── Pitch ─────────────────────────────────────────────────────────────────

template <typename T>
inline T midi_to_hz(T note) {
    return static_cast<T>(kA4Hz) *
           std::pow(T{2}, (note - static_cast<T>(kMidiA4)) / static_cast<T>(kSemitonesPerOctave));
}

template <typename T>
inline T hz_to_midi(T hz) {
    const T safe = std::max(hz, static_cast<T>(kDbFloorAmplitude));
    return static_cast<T>(kMidiA4) +
           static_cast<T>(kSemitonesPerOctave) * std::log2(safe / static_cast<T>(kA4Hz));
}

template <typename T>
inline T semitones_to_ratio(T semitones) {
    return std::pow(T{2}, semitones / static_cast<T>(kSemitonesPerOctave));
}

template <typename T>
inline T ratio_to_semitones(T ratio) {
    return static_cast<T>(kSemitonesPerOctave) *
           std::log2(std::max(ratio, static_cast<T>(kDbFloorAmplitude)));
}

template <typename T>
inline T cents_to_ratio(T cents) {
    return std::pow(T{2}, cents / (static_cast<T>(kSemitonesPerOctave) *
                                   static_cast<T>(kCentsPerSemitone)));
}

template <typename T>
inline T ratio_to_cents(T ratio) {
    return ratio_to_semitones(ratio) * static_cast<T>(kCentsPerSemitone);
}

template <typename T>
inline T volts_to_semitones(T volts) {
    return volts * static_cast<T>(kSemitonesPerVolt);
}

template <typename T>
inline T semitones_to_volts(T semitones) {
    return semitones / static_cast<T>(kSemitonesPerVolt);
}
 
// ── Time ↔ samples ────────────────────────────────────────────────────────

template <typename T>
inline T ms_to_samples(T ms, T sample_rate) {
    return ms * sample_rate / T{1000};
}

template <typename T>
inline T samples_to_ms(T samples, T sample_rate) {
    return sample_rate > T{0} ? samples * T{1000} / sample_rate : T{0};
}

template <typename T>
inline T hz_to_period_samples(T hz, T sample_rate) {
    return hz > T{0} ? sample_rate / hz : T{0};
}

template <typename T>
inline T period_samples_to_hz(T samples, T sample_rate) {
    return samples > T{0} ? sample_rate / samples : T{0};
}
 
// ── Frequency → internal filter/oscillator quantities ─────────────────────

template <typename T>
inline T hz_to_cycles_per_sample(T hz, T sample_rate) {
    return sample_rate > T{0} ? hz / sample_rate : T{0};
}

template <typename T>
inline T hz_to_radians_per_sample(T hz, T sample_rate) {
    constexpr T two_pi = static_cast<T>(6.283185307179586476925286766559L);
    return sample_rate > T{0} ? two_pi * hz / sample_rate : T{0};
}
 
// ── One-pole coefficients ─────────────────────────────────────────────────

template <typename T>
inline T ms_to_onepole_coef(T ms, T sample_rate) {
    if (!(ms > T{0}) || !(sample_rate > T{0})) return T{1};
    const T samples = ms * sample_rate / T{1000};
    return T{1} - std::exp(T{-1} / samples);
}

template <typename T>
inline T ms_to_onepole_pole(T ms, T sample_rate) {
    return T{1} - ms_to_onepole_coef(ms, sample_rate);
}

template <typename T>
inline T t60_ms_to_tau_ms(T t60_ms) {
    constexpr T ln1000 = static_cast<T>(6.907755278982137L);
    return t60_ms / ln1000;
}
 
// ── Parameter tapers ──────────────────────────────────────────────────────

template <typename T>
inline T taper_log(T u, T lo, T hi) {
    if (!(lo > T{0}) || !(hi > T{0})) return lo;
    const T clamped = std::clamp(u, T{0}, T{1});
    return lo * std::pow(hi / lo, clamped);
}

template <typename T>
inline T untaper_log(T value, T lo, T hi) {
    if (!(lo > T{0}) || !(hi > T{0}) || hi == lo) return T{0};
    const T clamped = std::clamp(value, std::min(lo, hi), std::max(lo, hi));
    return std::log(clamped / lo) / std::log(hi / lo);
}

template <typename T>
inline T taper_linear(T u, T lo, T hi) {
    return lo + std::clamp(u, T{0}, T{1}) * (hi - lo);
}

template <typename T>
inline T untaper_linear(T value, T lo, T hi) {
    if (hi == lo) return T{0};
    return std::clamp((value - lo) / (hi - lo), T{0}, T{1});
}

template <typename T>
inline T taper_log_inverse(T value, T lo, T hi) {
    return untaper_log(value, lo, hi);
}

template <typename T>
inline T t60_to_per_sample_gain(T t60_seconds, T sample_rate) {
    const T samples = std::max(T{1}, t60_seconds * sample_rate);
    return std::pow(T{10}, T{-3} / samples);
}
 
template <typename T>
inline T beats_to_seconds(T beats, T bpm) {
    return beats * T{60} / std::max(T{1e-3}, bpm);
}
 
template <typename T>
inline T seconds_to_beats(T seconds, T bpm) {
    return seconds * std::max(T{1e-3}, bpm) / T{60};
}

enum class Division : std::uint8_t {
    whole = 0,
    whole_dotted = 1,
    whole_triplet = 2,
    half = 3,
    half_dotted = 4,
    half_triplet = 5,
    quarter = 6,
    quarter_dotted = 7,
    quarter_triplet = 8,
    eighth = 9,
    eighth_dotted = 10,
    eighth_triplet = 11,
    sixteenth = 12,
    sixteenth_dotted = 13,
    sixteenth_triplet = 14,
    thirty_second = 15,
    thirty_second_dotted = 16,
    thirty_second_triplet = 17,
    sixty_fourth = 18,
    sixty_fourth_dotted = 19,
    sixty_fourth_triplet = 20,
    count = 21,
};
 
inline constexpr int kDivisionCount = static_cast<int>(Division::count);

constexpr timebase::BeatDivision to_beat_division(Division division) noexcept {
    return static_cast<timebase::BeatDivision>(static_cast<std::uint8_t>(division));
}
 
static_assert(static_cast<std::uint8_t>(Division::count) ==
              static_cast<std::uint8_t>(timebase::BeatDivision::Count));
 
constexpr float division_to_beats(Division division) {
    const int index = static_cast<int>(division);
    if (index < 0 || index >= kDivisionCount) return 1.0f;
    const auto fraction = timebase::beat_fraction_or(to_beat_division(division), {1, 1});
    return static_cast<float>(fraction.numerator) /
           static_cast<float>(fraction.denominator);
}
 
constexpr float division_to_beats(int index) {
    return division_to_beats(static_cast<Division>(index));
}
 
inline float division_to_seconds(Division division, float bpm) {
    return beats_to_seconds(division_to_beats(division), bpm);
}
 
inline double division_to_samples(Division division, float bpm, double sample_rate) {
    return static_cast<double>(division_to_seconds(division, bpm)) * sample_rate;
}
 
inline float division_to_hz(Division division, float bpm) {
    return 1.0f / std::max(1.0e-6f, division_to_seconds(division, bpm));
}
 
}  // namespace pulp::signal::units