parameter.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <atomic>
#include <bit>
#include <cctype>
#include <cmath>
#include <cstdint>
#include <functional>
#include <limits>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::state {

struct BaseOffsetValue {
    float base = 0.0f;
    float offset = 0.0f;
 
    constexpr float effective() const noexcept {
        return base + offset;
    }
    constexpr BaseOffsetValue without_offset() const noexcept {
        return {base, 0.0f};
    }
};
 
enum class BaseOffsetRefusal : std::uint8_t {
    None,
    NonFiniteBase,
    NonFiniteOffset,
    OutOfRange,
};
 
inline BaseOffsetRefusal validate_base_offset(BaseOffsetValue value, float minimum,
                                              float maximum) noexcept {
    if (!std::isfinite(value.base))
        return BaseOffsetRefusal::NonFiniteBase;
    if (!std::isfinite(value.offset))
        return BaseOffsetRefusal::NonFiniteOffset;
    if (!std::isfinite(minimum) || !std::isfinite(maximum) || minimum > maximum ||
        value.effective() < minimum || value.effective() > maximum)
        return BaseOffsetRefusal::OutOfRange;
    return BaseOffsetRefusal::None;
}

using ParamID = uint32_t;

enum class ParamRate {
    ControlRate,
    AudioRate,
};

enum class ParamKind {
    Continuous,
    Integer,
    Toggle,
    Enum,
};

enum class ParamDesignation {
    None,
    Bypass,
    Reset,
};

struct ParamRange {
    float min = 0.0f;
    float max = 1.0f;
    float default_value = 0.0f;
    float step = 0.0f;           
    float skew = 1.0f;           
    bool symmetric_skew = false; 

    static ParamRange linear(float lo, float hi, float def = 0.0f,
                             float step_value = 0.0f) {
        return ParamRange{lo, hi, def, step_value, 1.0f, false};
    }

    static ParamRange with_center(float lo, float hi, float center,
                                  float def = 0.0f, float step_value = 0.0f) {
        ParamRange r{lo, hi, def, step_value, 1.0f, false};
        if (hi > lo && center > lo && center < hi) {
            const float proportion = (center - lo) / (hi - lo);
            r.skew = std::log(0.5f) / std::log(proportion);
        }
        return r;
    }

    bool is_linear() const { return skew == 1.0f && !symmetric_skew; }

    float normalize(float value) const {
        if (max == min) return 0.0f;
        // Bit-identical linear fast path — preserves legacy behavior exactly.
        if (is_linear()) {
            return std::clamp((value - min) / (max - min), 0.0f, 1.0f);
        }
        float proportion = std::clamp((value - min) / (max - min), 0.0f, 1.0f);
        if (symmetric_skew) {
            const float centerd = (proportion * 2.0f) - 1.0f; // [-1, 1]
            const float magnitude = std::pow(std::abs(centerd), skew);
            const float signed_mag = centerd < 0.0f ? -magnitude : magnitude;
            return (signed_mag + 1.0f) * 0.5f;
        }
        return std::pow(proportion, skew);
    }

    float denormalize(float normalized) const {
        // Bit-identical linear fast path — preserves legacy behavior exactly.
        if (is_linear()) {
            auto value = min + normalized * (max - min);
            if (step > 0.0f) {
                value = min + std::round((value - min) / step) * step;
            }
            return std::clamp(value, min, max);
        }
        normalized = std::clamp(normalized, 0.0f, 1.0f);
        float proportion;
        if (symmetric_skew) {
            const float centerd = (normalized * 2.0f) - 1.0f; // [-1, 1]
            const float magnitude = std::pow(std::abs(centerd), 1.0f / skew);
            const float signed_mag = centerd < 0.0f ? -magnitude : magnitude;
            proportion = (signed_mag + 1.0f) * 0.5f;
        } else {
            proportion = std::pow(normalized, 1.0f / skew);
        }
        float value = min + proportion * (max - min);
        if (step > 0.0f) {
            value = min + std::round((value - min) / step) * step;
        }
        return std::clamp(value, min, max);
    }
};

template<typename T = float>
struct SkewedRange {
    T min = T(0);
    T max = T(1);
    T interval = T(0);          
    T skew = T(1);              
    bool symmetric_skew = false;
 
    constexpr SkewedRange() = default;
    constexpr SkewedRange(T lo, T hi, T step = T(0), T skew_value = T(1),
                                bool symmetric = false)
        : min(lo), max(hi), interval(step),
          skew(skew_value), symmetric_skew(symmetric) {}

    static SkewedRange with_center(T lo, T hi, T center, T step = T(0)) {
        SkewedRange r{lo, hi, step};
        if (hi > lo && center > lo && center < hi) {
            const T proportion = (center - lo) / (hi - lo);
            // log(0.5) / log(proportion) gives the skew that lands `center` at 0.5.
            r.skew = std::log(T(0.5)) / std::log(proportion);
        }
        return r;
    }

    T normalize(T value) const {
        if (max == min) return T(0);
        T proportion = (value - min) / (max - min);
        proportion = std::clamp(proportion, T(0), T(1));
        if (symmetric_skew) {
            const T centerd = (proportion * T(2)) - T(1); // [-1, 1]
            const T magnitude = std::pow(std::abs(centerd), skew);
            const T signed_mag = centerd < T(0) ? -magnitude : magnitude;
            return (signed_mag + T(1)) * T(0.5);
        }
        return std::pow(proportion, skew);
    }

    T denormalize(T normalized) const {
        normalized = std::clamp(normalized, T(0), T(1));
        T proportion;
        if (symmetric_skew) {
            const T centerd = (normalized * T(2)) - T(1); // [-1, 1]
            const T magnitude = std::pow(std::abs(centerd), T(1) / skew);
            const T signed_mag = centerd < T(0) ? -magnitude : magnitude;
            proportion = (signed_mag + T(1)) * T(0.5);
        } else {
            proportion = std::pow(normalized, T(1) / skew);
        }
        T value = min + proportion * (max - min);
        if (interval > T(0)) {
            value = min + std::round((value - min) / interval) * interval;
        }
        return std::clamp(value, min, max);
    }

    T snap(T value) const {
        if (interval <= T(0)) return std::clamp(value, min, max);
        T snapped = min + std::round((value - min) / interval) * interval;
        return std::clamp(snapped, min, max);
    }
};
 

struct ParamInfo {
    ParamID id = 0;
    std::string name;
    std::string unit;       
    ParamRange range;
    int group_id = 0;       

    std::function<std::string(float)> to_string;
    std::function<float(const std::string&)> from_string;
 
    ParamRate rate = ParamRate::ControlRate;
    float smoothing_ramp_seconds = 0.0f; 

    ParamDesignation designation = ParamDesignation::None;

    bool is_trigger = false;

    ParamKind kind = ParamKind::Continuous;

    std::vector<std::string> value_labels;

    bool modulatable = true;

    bool hidden = false;

    bool read_only = false;

    bool automatable = true;

    bool auto_resets() const {
        return is_trigger || designation == ParamDesignation::Reset;
    }
};
 
inline bool is_discrete_param(const ParamInfo& info) {
    // Semantic kind is author-declared metadata. A continuous parameter may
    // still use range.step to quantize its plain value without being exposed
    // to hosts as an integer/indexed control.
    return info.kind != ParamKind::Continuous;
}

inline float value_from_host_normalized(const ParamInfo& info, double normalized) {
    const ParamRange& range = info.range;
    if (is_discrete_param(info))
        return range.denormalize(static_cast<float>(normalized));
    if (!range.is_linear()) {
        ParamRange exact = range;
        exact.step = 0.0f;
        return exact.denormalize(static_cast<float>(normalized));
    }
    const double n = std::clamp(normalized, 0.0, 1.0);
    const double plain = static_cast<double>(range.min) +
                         n * (static_cast<double>(range.max) - static_cast<double>(range.min));
    return std::clamp(static_cast<float>(plain), range.min, range.max);
}

inline double host_normalized_from_value(const ParamInfo& info, float value) {
    const ParamRange& range = info.range;
    if (!range.is_linear() || range.max == range.min)
        return static_cast<double>(range.normalize(value));
    const double span = static_cast<double>(range.max) - static_cast<double>(range.min);
    return std::clamp((static_cast<double>(value) - static_cast<double>(range.min)) / span, 0.0,
                      1.0);
}
 
inline bool is_boolean_param(const ParamInfo& info) {
    return info.kind == ParamKind::Toggle;
}
 
inline uint32_t param_value_count(const ParamInfo& info) {
    if (!info.value_labels.empty())
        return static_cast<uint32_t>(info.value_labels.size());
    if (!is_discrete_param(info)) return 0;
    const float step = info.range.step > 0.0f ? info.range.step : 1.0f;
    const float span = std::max(0.0f, info.range.max - info.range.min);
    return static_cast<uint32_t>(std::llround(span / step)) + 1u;
}
 
inline float constrain_param_value(const ParamInfo& info, float value) {
    if (!std::isfinite(value)) return info.range.default_value;
    value = std::clamp(value, info.range.min, info.range.max);
    const float step = info.range.step > 0.0f
        ? info.range.step
        : (is_discrete_param(info) ? 1.0f : 0.0f);
    if (step > 0.0f) {
        value = info.range.min
            + std::round((value - info.range.min) / step) * step;
    }
    return std::clamp(value, info.range.min, info.range.max);
}
 
inline std::optional<float> param_value_for_label(const ParamInfo& info,
                                                   std::string_view text) {
    while (!text.empty() && std::isspace(static_cast<unsigned char>(text.front())))
        text.remove_prefix(1);
    while (!text.empty() && std::isspace(static_cast<unsigned char>(text.back())))
        text.remove_suffix(1);
    const float step = info.range.step > 0.0f ? info.range.step : 1.0f;
    for (std::size_t i = 0; i < info.value_labels.size(); ++i) {
        if (text == info.value_labels[i]) {
            return constrain_param_value(
                info, info.range.min + static_cast<float>(i) * step);
        }
    }
    return std::nullopt;
}

inline bool is_bypass_param(const ParamInfo& info) {
    if (info.designation == ParamDesignation::Bypass) return true;
    if (info.designation != ParamDesignation::None) return false;
    return info.name == "Bypass" && info.range.step >= 1.0f &&
           info.range.min == 0.0f && info.range.max == 1.0f;
}

inline bool is_modulatable_param(const ParamInfo& info) {
    if (!info.modulatable)
        return false;
    if (is_bypass_param(info))
        return false;
    if (is_discrete_param(info))
        return false;
    // A host may not offset a value it may not write. Without this the CLAP
    // adapter would advertise READONLY and MODULATABLE on the same parameter.
    if (info.read_only)
        return false;
    return !info.auto_resets();
}

inline bool is_hidden_param(const ParamInfo& info) {
    if (!info.hidden)
        return false;
    return !is_bypass_param(info);
}

inline bool is_read_only_param(const ParamInfo& info) {
    if (!info.read_only)
        return false;
    if (is_bypass_param(info))
        return false;
    return !info.auto_resets();
}

inline bool is_automatable_param(const ParamInfo& info) {
    if (!info.automatable)
        return false;
    return !is_read_only_param(info);
}

class ParamValue {
  public:
    using PackedIdentity = std::uint64_t;
    using VersionedValue = PackedIdentity; // source compatibility alias
 
    ParamValue() = default;

    explicit ParamValue(float initial) : value_(pack(initial, 0)) {}
 
    ParamValue(ParamValue&& other) noexcept
        : value_(other.value_.load()),
          committed_generation_(other.committed_generation_.load()) {}
    ParamValue& operator=(ParamValue&& other) noexcept {
        value_.store(other.value_.load());
        committed_generation_.store(other.committed_generation_.load());
        return *this;
    }
    ParamValue(const ParamValue& other)
        : value_(other.value_.load()),
          committed_generation_(other.committed_generation_.load()) {}
    ParamValue& operator=(const ParamValue& other) {
        value_.store(other.value_.load());
        committed_generation_.store(other.committed_generation_.load());
        return *this;
    }

    float get() const { return unpack_value(value_.load(std::memory_order_relaxed)); }

    void set(float v) noexcept {
        (void)set_revisioned(v, 0, 8);
    }
 
    VersionedValue versioned_value() const {
        return value_.load(std::memory_order_relaxed);
    }

    std::uint64_t committed_generation() const {
        return committed_generation_.load(std::memory_order_relaxed);
    }
 
    static VersionedValue make_versioned_value(float value, std::uint64_t revision) {
        return pack(value, static_cast<std::uint32_t>(revision));
    }
 
    static float value_from_versioned(VersionedValue value) {
        return unpack_value(value);
    }
 
    static std::uint32_t revision_from_versioned(VersionedValue value) {
        return unpack_generation(value);
    }
 
    bool revision_available() const noexcept {
        return revisions_available(1);
    }
 
    bool revisions_available(std::uint32_t writes) const noexcept {
        const auto revision = revision_from_versioned(versioned_value());
        return revision <= std::numeric_limits<std::uint32_t>::max() - writes;
    }

    bool set_versioned_if_newer(float value, std::uint64_t generation,
                                std::uint32_t max_attempts) {
        auto committed = committed_generation_.load(std::memory_order_relaxed);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed >= generation)
                return false;
            if (committed_generation_.compare_exchange_strong(
                    committed, generation, std::memory_order_relaxed,
                    std::memory_order_relaxed))
                break;
        }
        if (committed_generation_.load(std::memory_order_relaxed) != generation)
            return false;
        auto current = value_.load(std::memory_order_acquire);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed_generation_.load(std::memory_order_relaxed) != generation)
                return false;
            const auto revision = unpack_generation(current);
            if (revision == std::numeric_limits<std::uint32_t>::max())
                return false;
            if (value_.compare_exchange_weak(current, pack(value, revision + 1),
                                             std::memory_order_acq_rel, std::memory_order_acquire))
                return true;
        }
        return false;
    }

    bool set_packed_revisioned(float value, std::uint64_t generation,
                               std::uint32_t max_attempts) noexcept {
        if (!claim_generation(generation, max_attempts))
            return false;
        return publish_after_generation_claim(value, generation, max_attempts);
    }
 
    bool compare_exchange_versioned(VersionedValue& expected,
                                    std::uint64_t expected_generation,
                                    float desired, std::uint64_t generation) {
        if (!committed_generation_.compare_exchange_strong(
                expected_generation, generation, std::memory_order_relaxed,
                std::memory_order_relaxed))
            return false;
        return value_.compare_exchange_strong(
            expected, pack(desired, static_cast<std::uint32_t>(generation)),
            std::memory_order_relaxed, std::memory_order_relaxed);
    }

    bool compare_exchange_packed(VersionedValue& expected, float desired,
                                 std::uint64_t generation) {
        const auto current_revision = unpack_generation(expected);
        if (current_revision == std::numeric_limits<std::uint32_t>::max())
            return false;
        const auto replacement = pack(desired, current_revision + 1);
        if (!value_.compare_exchange_strong(expected, replacement, std::memory_order_acq_rel,
                                            std::memory_order_acquire))
            return false;
        expected = replacement;
        raise_committed_generation(generation);
        return true;
    }

    float get_modulated() const {
        return unpack_value(value_.load(std::memory_order_relaxed))
             + unpack_value(mod_offset_.load(std::memory_order_relaxed));
    }
 
    float get_mod_offset() const {
        return unpack_value(mod_offset_.load(std::memory_order_relaxed));
    }

    BaseOffsetValue get_base_offset() const noexcept {
        return {get(), get_mod_offset()};
    }

    void set_mod_offset(float offset) {
        const auto current = mod_offset_.load(std::memory_order_relaxed);
        mod_offset_.store(pack(offset, unpack_generation(current)),
                          std::memory_order_relaxed);
    }
 
    bool set_mod_versioned_if_newer(float offset, std::uint64_t generation,
                                    std::uint32_t max_attempts) {
        auto committed = committed_mod_generation_.load(std::memory_order_relaxed);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed >= generation)
                return false;
            if (committed_mod_generation_.compare_exchange_strong(
                    committed, generation, std::memory_order_relaxed,
                    std::memory_order_relaxed))
                break;
        }
        if (committed_mod_generation_.load(std::memory_order_relaxed) != generation)
            return false;
        auto current = mod_offset_.load(std::memory_order_relaxed);
        const auto desired = pack(offset, static_cast<std::uint32_t>(generation));
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed_mod_generation_.load(std::memory_order_relaxed) != generation)
                return false;
            if (mod_offset_.compare_exchange_strong(current, desired,
                                                    std::memory_order_relaxed,
                                                    std::memory_order_relaxed))
                return true;
        }
        return false;
    }

    void add_mod_offset(float delta) {
        set_mod_offset(get_mod_offset() + delta);
    }

    void reset_mod() { set_mod_offset(0.0f); }

    void set_display_modulation(float plain) noexcept {
        display_mod_.store(plain, std::memory_order_relaxed);
    }
    void clear_display_modulation() noexcept {
        display_mod_.store(std::numeric_limits<float>::quiet_NaN(), std::memory_order_relaxed);
    }
    float display_modulation() const noexcept {
        return display_mod_.load(std::memory_order_relaxed);
    }

    float get_normalized(const ParamRange& range) const {
        return range.normalize(get());
    }

    void set_normalized(float n, const ParamRange& range) {
        set(range.denormalize(n));
    }
 
  private:
    friend class ParamValueTest;
 
    bool claim_generation(std::uint64_t generation, std::uint32_t max_attempts) noexcept {
        auto committed = committed_generation_.load(std::memory_order_relaxed);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed >= generation)
                return false;
            if (committed_generation_.compare_exchange_strong(
                    committed, generation, std::memory_order_acq_rel, std::memory_order_acquire))
                return true;
        }
        return false;
    }
 
    bool publish_after_generation_claim(float value, std::uint64_t generation,
                                        std::uint32_t max_attempts) noexcept {
        if (committed_generation_.load(std::memory_order_acquire) != generation)
            return false;
        auto current = value_.load(std::memory_order_acquire);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            if (committed_generation_.load(std::memory_order_acquire) != generation)
                return false;
            const auto revision = unpack_generation(current);
            if (revision == std::numeric_limits<std::uint32_t>::max())
                return false;
            const auto replacement = pack(value, revision + 1);
            if (value_.compare_exchange_weak(current, replacement, std::memory_order_acq_rel,
                                             std::memory_order_acquire))
                return true;
        }
        return false;
    }
 
    // Raise-only update. Lowering the mark would revoke the claim of an
    // ordinary writer that claimed a newer generation and has not published
    // yet, and would let an older writer claim past it.
    void raise_committed_generation(std::uint64_t generation) noexcept {
        auto committed = committed_generation_.load(std::memory_order_relaxed);
        while (committed < generation &&
               !committed_generation_.compare_exchange_weak(
                   committed, generation, std::memory_order_acq_rel, std::memory_order_relaxed)) {
        }
    }
 
    bool set_revisioned(float value, std::uint64_t generation,
                        std::uint32_t max_attempts) noexcept {
        auto current = value_.load(std::memory_order_acquire);
        for (std::uint32_t attempt = 0; attempt < max_attempts; ++attempt) {
            const auto revision = unpack_generation(current);
            if (revision == std::numeric_limits<std::uint32_t>::max())
                return false;
            const auto replacement = pack(value, revision + 1);
            if (value_.compare_exchange_weak(current, replacement, std::memory_order_acq_rel,
                                             std::memory_order_acquire)) {
                raise_committed_generation(generation);
                return true;
            }
        }
        return false;
    }
 
    static VersionedValue pack(float value, std::uint32_t generation) {
        return (static_cast<VersionedValue>(generation) << 32) |
               std::bit_cast<std::uint32_t>(value);
    }
 
    static float unpack_value(VersionedValue value) {
        return std::bit_cast<float>(static_cast<std::uint32_t>(value));
    }
 
    static std::uint32_t unpack_generation(VersionedValue value) {
        return static_cast<std::uint32_t>(value >> 32);
    }
 
    std::atomic<VersionedValue> value_{pack(0.0f, 0)};
    // Generation high-water mark. Ordinary writers claim it before publishing
    // (claim_generation) and abort publication if a newer claim replaced
    // theirs; every other writer may only raise it. The packed value CAS
    // remains the publication boundary.
    std::atomic<std::uint64_t> committed_generation_{0};
    std::atomic<VersionedValue> mod_offset_{pack(0.0f, 0)};
    std::atomic<std::uint64_t> committed_mod_generation_{0};
    std::atomic<float> display_mod_{std::numeric_limits<float>::quiet_NaN()};
 
    // The packed base value/revision identity and modulation offset are read
    // and written on the audio thread through lock-free atomics. Fail the build if a
    // target would implement either with a hidden mutex. See
    // docs/guides/dsp-threading.md "The three rules".
    static_assert(std::atomic<VersionedValue>::is_always_lock_free,
                  "Pulp requires lock-free atomic<uint64_t> for versioned real-time "
                  "parameter access");
};

using ParamChangeCallback = std::function<void(ParamID id, float new_value)>;
 
} // namespace pulp::state