DSParkPlugin.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/AudioSpec.h"
#include "../Core/AudioBuffer.h"
#include "../Core/DenormalGuard.h"
 
#include <array>
#include <concepts>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <type_traits>
#include <vector>
 
namespace dspark::plugin {
 
// -- Descriptor ---------------------------------------------------------------
 
enum class Category
{
    Fx,           
    Instrument    
};
 
struct Descriptor
{
    const char* name      = "DSPark Plugin";
    const char* vendor    = "DSPark";
    const char* url       = "";
    const char* email     = "";
    const char* productId = "com.dspark.plugin";
    const char* version   = "1.0.0";
    Category    category  = Category::Fx;
};
 
// -- Parameters ---------------------------------------------------------------
 
struct Param
{
    const char* id   = "";     
    const char* name = "";     
    float minValue   = 0.0f;
    float maxValue   = 1.0f;
    float defValue   = 0.0f;
    const char* unit = "";     
    int steps        = 0;      
};
 
constexpr Param param(const char* id, const char* name,
                      float minValue, float maxValue, float defValue,
                      const char* unit) noexcept
{
    return Param { id, name, minValue, maxValue, defValue, unit, 0 };
}
 
constexpr Param toggle(const char* id, const char* name, bool defaultOn) noexcept
{
    return Param { id, name, 0.0f, 1.0f, defaultOn ? 1.0f : 0.0f, "", 1 };
}
 
template <typename... Ps>
constexpr std::array<Param, sizeof...(Ps)> params(Ps... ps) noexcept
{
    return { ps... };
}
 
// -- Normalisation ------------------------------------------------------------
 
constexpr double toNormalized(const Param& p, double plain) noexcept
{
    const double range = static_cast<double>(p.maxValue) - p.minValue;
    if (range <= 0.0) return 0.0;
    double n = (plain - p.minValue) / range;
    return n < 0.0 ? 0.0 : (n > 1.0 ? 1.0 : n);
}
 
constexpr double toPlain(const Param& p, double normalized) noexcept
{
    double n = normalized < 0.0 ? 0.0 : (normalized > 1.0 ? 1.0 : normalized);
    if (p.steps > 0)
    {
        // Snap to the nearest of steps+1 positions.
        const double scaled = n * p.steps + 0.5;
        const double idx = static_cast<double>(static_cast<long long>(scaled));
        n = idx / p.steps;
        n = n < 0.0 ? 0.0 : (n > 1.0 ? 1.0 : n);
    }
    return p.minValue + n * (static_cast<double>(p.maxValue) - p.minValue);
}
 
inline int parseToggleText(const char* text) noexcept
{
    auto lower = [](char c) { return c >= 'A' && c <= 'Z' ? static_cast<char>(c + 32) : c; };
    if (text == nullptr) return -1;
    if (lower(text[0]) == 'o' && lower(text[1]) == 'n' && text[2] == '\0') return 1;
    if (lower(text[0]) == 'o' && lower(text[1]) == 'f' && lower(text[2]) == 'f'
        && text[3] == '\0') return 0;
    return -1;
}
 
inline void formatValue(const Param& p, double plain, char* out, int outSize) noexcept
{
    if (p.steps == 1)
    {
        std::snprintf(out, static_cast<size_t>(outSize), "%s",
                      plain >= 0.5 * (p.minValue + p.maxValue) ? "On" : "Off");
        return;
    }
    if (p.unit && p.unit[0] != '\0')
        std::snprintf(out, static_cast<size_t>(outSize), "%.2f %s", plain, p.unit);
    else
        std::snprintf(out, static_cast<size_t>(outSize), "%.2f", plain);
}
 
// -- Stable hashing (parameter ids, class UIDs) -------------------------------
 
constexpr uint32_t hash32(const char* s) noexcept
{
    uint32_t h = 2166136261u;
    while (*s != '\0')
    {
        h ^= static_cast<uint8_t>(*s++);
        h *= 16777619u;
    }
    return h;
}
 
constexpr uint64_t hash64(const char* s, uint64_t salt) noexcept
{
    uint64_t h = 14695981039346656037ull ^ salt;
    while (*s != '\0')
    {
        h ^= static_cast<uint8_t>(*s++);
        h *= 1099511628211ull;
    }
    return h;
}
 
template <typename P>
constexpr bool paramIdsUnique() noexcept
{
    constexpr size_t n = P::parameters.size();
    for (size_t i = 0; i < n; ++i)
    {
        const uint32_t h = hash32(P::parameters[i].id);
        if (h == 0x5052474Du || h == 0x42595053u) return false; // 'PRGM'/'BYPS'
        for (size_t j = i + 1; j < n; ++j)
            if (hash32(P::parameters[j].id) == h) return false;
    }
    return true;
}
 
constexpr std::array<uint8_t, 16> makeUid(const char* productId, uint64_t salt) noexcept
{
    const uint64_t a = hash64(productId, salt);
    const uint64_t b = hash64(productId, salt ^ 0x9E3779B97F4A7C15ull);
    std::array<uint8_t, 16> uid {};
    for (int i = 0; i < 8; ++i)
    {
        uid[static_cast<size_t>(i)]     = static_cast<uint8_t>(a >> (8 * i));
        uid[static_cast<size_t>(i + 8)] = static_cast<uint8_t>(b >> (8 * i));
    }
    return uid;
}
 
// -- Capability detection -----------------------------------------------------
 
template <typename P>
concept HasReset = requires(P p) { p.reset(); };
 
template <typename P>
concept HasLatency = requires(const P p) { { p.getLatency() } -> std::convertible_to<int>; };
 
template <typename P>
concept HasTail = requires(const P p) { { p.getTailSeconds() } -> std::convertible_to<double>; };
 
template <typename P>
concept HasGetState = requires(const P p) {
    { p.getState() } -> std::convertible_to<std::vector<uint8_t>>;
};
 
template <typename P>
concept HasSetState = requires(P p, const uint8_t* d, size_t n) {
    { p.setState(d, n) } -> std::convertible_to<bool>;
};
 
template <typename P>
concept HasEditor = requires { P::hasEditor; } && P::hasEditor;
 
template <typename P>
concept HasSidechain = requires(P p, AudioBufferView<float> io,
                                AudioBufferView<float> sc) {
    p.processBlock(io, sc);
};
 
// -- Transport (host tempo & timeline) ------------------------------------------
 
struct TransportInfo
{
    double tempoBpm = 120.0;          
    double ppqPosition = 0.0;         
    double barStartPpq = 0.0;         
    int    timeSigNumerator = 4;      
    int    timeSigDenominator = 4;    
    double loopStartPpq = 0.0;        
    double loopEndPpq = 0.0;          
    bool   playing = false;           
    bool   recording = false;         
    bool   looping = false;           
    bool   tempoValid = false;        
    bool   positionValid = false;     
    bool   timeSigValid = false;      
    bool   loopValid = false;         
 
    [[nodiscard]] double secondsPerBeat() const noexcept
    {
        return 60.0 / (tempoBpm > 1.0 ? tempoBpm : 120.0);
    }
 
    [[nodiscard]] double samplesPerBeat(double sampleRate) const noexcept
    {
        return secondsPerBeat() * sampleRate;
    }
};
 
template <typename P>
concept HasTransport = requires(P p, const TransportInfo& t) {
    p.setTransport(t);
};
 
// -- MIDI ------------------------------------------------------------------------
 
struct MidiEvent
{
    enum class Type : uint8_t
    {
        NoteOn,            
        NoteOff,           
        PitchBend,         
        ControlChange,     
        ChannelPressure,   
        PolyPressure       
    };
 
    Type    type = Type::NoteOn;
    uint8_t channel = 0;      
    uint8_t note = 0;         
    float   value = 0.0f;     
    int     sampleOffset = 0; 
};
 
template <typename P>
concept HasMidi = requires(P p, const MidiEvent& e) {
    p.handleMidiEvent(e);
};
 
// -- Offline rendering ------------------------------------------------------------
 
template <typename P>
concept HasOfflineMode = requires(P p, bool offline) {
    p.setOfflineRendering(offline);
};
 
// -- Channel support ----------------------------------------------------------------
 
enum class ChannelSupport
{
    MonoAndStereo,   
    StereoOnly,      
    MonoOnly         
};
 
template <typename P>
concept HasChannelSupport = requires {
    { P::channels } -> std::convertible_to<ChannelSupport>;
};
 
template <typename P>
constexpr ChannelSupport channelSupportOf() noexcept
{
    if constexpr (HasChannelSupport<P>)
        return P::channels;
    else
        return ChannelSupport::MonoAndStereo;
}
 
template <typename P>
constexpr bool supportsChannelCount(int numChannels) noexcept
{
    constexpr ChannelSupport s = channelSupportOf<P>();
    if (numChannels == 1) return s != ChannelSupport::StereoOnly;
    if (numChannels == 2) return s != ChannelSupport::MonoOnly;
    return false;
}
 
template <typename P>
constexpr int defaultChannelCount() noexcept
{
    return channelSupportOf<P>() == ChannelSupport::MonoOnly ? 1 : 2;
}
 
// -- Factory presets ----------------------------------------------------------------
 
template <size_t NumValues>
struct PresetDef
{
    const char* name = "";
    std::array<float, NumValues> values {};
};
 
template <typename... Vs>
constexpr PresetDef<sizeof...(Vs)> preset(const char* name, Vs... values) noexcept
{
    return PresetDef<sizeof...(Vs)> { name, { static_cast<float>(values)... } };
}
 
template <typename First, typename... Rest>
constexpr std::array<First, 1 + sizeof...(Rest)> presets(First first, Rest... rest) noexcept
{
    static_assert((std::is_same_v<First, Rest> && ...),
                  "every preset must list one value per parameter");
    return { first, rest... };
}
 
template <typename P>
concept HasFactoryPresets = requires {
    { P::factoryPresets.size() } -> std::convertible_to<size_t>;
    { P::factoryPresets[0].name } -> std::convertible_to<const char*>;
    { P::factoryPresets[0].values.size() } -> std::convertible_to<size_t>;
};
 
template <typename P>
constexpr int factoryPresetCountOf() noexcept
{
    if constexpr (HasFactoryPresets<P>)
    {
        static_assert(P::factoryPresets[0].values.size() == P::parameters.size(),
                      "factoryPresets must list one PLAIN value per parameter, "
                      "in parameter-table order");
        return static_cast<int>(P::factoryPresets.size());
    }
    else
        return 0;
}
 
template <typename P>
constexpr double presetNormalized(int presetIndex, size_t paramIndex) noexcept
{
    if constexpr (HasFactoryPresets<P>)
        return toNormalized(P::parameters[paramIndex],
                            P::factoryPresets[static_cast<size_t>(presetIndex)]
                                .values[paramIndex]);
    else
    {
        (void) presetIndex;
        (void) paramIndex;
        return 0.0;
    }
}
 
// -- Sample-accurate automation -------------------------------------------------------
 
template <typename P>
concept HasSampleAccurateOptOut = requires {
    { P::sampleAccurateAutomation } -> std::convertible_to<bool>;
};
 
template <typename P>
constexpr bool sampleAccurateOf() noexcept
{
    if constexpr (HasSampleAccurateOptOut<P>)
        return P::sampleAccurateAutomation;
    else
        return true;
}
 
inline constexpr int kAutomationQuantum = 32;
 
inline constexpr int kMaxBlockEvents = 256;
 
struct BlockEvent
{
    enum class Kind : uint8_t { Param, Bypass, Midi };
    int32_t  offset = 0;        
    Kind     kind = Kind::Param;
    uint32_t paramId = 0;       
    double   value = 0.0;       
    MidiEvent midi {};          
};
 
inline void sortBlockEvents(BlockEvent* events, int count) noexcept
{
    for (int i = 1; i < count; ++i)
    {
        BlockEvent key = events[i];
        int j = i - 1;
        while (j >= 0 && events[j].offset > key.offset)
        {
            events[j + 1] = events[j];
            --j;
        }
        events[j + 1] = key;
    }
}
 
// -- Editor contract (used by plugin/webview/DSParkWebViewEditor.h) -------------
 
struct EditorSize
{
    int width  = 480;
    int height = 320;
};
 
enum class EditorResize
{
    Fixed,        
    Free,         
    KeepAspect    
};
 
template <typename P>
concept HasEditorHtml = requires {
    { P::editorHtml() } -> std::convertible_to<const char*>;
};
 
template <typename P>
concept HasEditorSize = requires {
    { P::editorSize.width } -> std::convertible_to<int>;
    { P::editorSize.height } -> std::convertible_to<int>;
};
 
template <typename P>
constexpr EditorSize editorSizeOf() noexcept
{
    if constexpr (HasEditorSize<P>)
        return EditorSize { static_cast<int>(P::editorSize.width),
                            static_cast<int>(P::editorSize.height) };
    else
        return EditorSize {};
}
 
template <typename P>
concept HasEditorResizable = requires { P::editorResizable; } && P::editorResizable;
 
template <typename P>
concept HasEditorResize = requires {
    { P::editorResize } -> std::convertible_to<EditorResize>;
};
 
template <typename P>
constexpr EditorResize editorResizeOf() noexcept
{
    if constexpr (HasEditorResize<P>)
        return P::editorResize;
    else if constexpr (HasEditorResizable<P>)
        return EditorResize::Free;
    else
        return EditorResize::Fixed;
}
 
inline constexpr double kEditorMinSizeFactor = 0.5;
inline constexpr double kEditorMaxSizeFactor = 3.0;
 
template <typename P>
constexpr void constrainEditorSize(double& width, double& height, double scale) noexcept
{
    const EditorSize logical = editorSizeOf<P>();
    constexpr EditorResize mode = editorResizeOf<P>();
    if constexpr (mode == EditorResize::Fixed)
    {
        width  = logical.width * scale;
        height = logical.height * scale;
    }
    else
    {
        const double minW = logical.width * scale * kEditorMinSizeFactor;
        const double maxW = logical.width * scale * kEditorMaxSizeFactor;
        const double minH = logical.height * scale * kEditorMinSizeFactor;
        const double maxH = logical.height * scale * kEditorMaxSizeFactor;
        width  = width < minW ? minW : (width > maxW ? maxW : width);
        height = height < minH ? minH : (height > maxH ? maxH : height);
        if constexpr (mode == EditorResize::KeepAspect)
        {
            const double ratio = static_cast<double>(logical.width) / logical.height;
            double fitW = width;
            if (height * ratio < fitW) fitW = height * ratio;   // inside-fit
            fitW   = fitW < minW ? minW : (fitW > maxW ? maxW : fitW);
            width  = fitW;
            height = fitW / ratio;
        }
    }
}
 
template <typename P>
concept HasEditorDebug = requires { P::editorDebug; } && P::editorDebug;
 
template <typename P>
concept HasEditorDevFile = requires {
    { P::editorDevFile() } -> std::convertible_to<const char*>;
};
 
// -- PluginBase: the whole contract, visible in one place ----------------------
 
template <typename Derived>
struct PluginBase
{
    void reset() noexcept {}
 
    [[nodiscard]] int getLatency() const noexcept { return 0; }
 
    [[nodiscard]] double getTailSeconds() const noexcept { return 0.0; }
 
    [[nodiscard]] std::vector<uint8_t> getState() const { return {}; }
 
    bool setState(const uint8_t*, size_t) { return false; }
 
    void setTransport(const TransportInfo&) noexcept {}
 
    void setOfflineRendering(bool) noexcept {}
 
    static constexpr bool hasEditor = false;
};
 
// -- Wrapper-side state serialisation ------------------------------------------
//
// Every backend stores plugin state in ONE container format so presets stay
// portable across formats and tolerant across versions (same philosophy as
// Core/StateBlob): a magic/version header, the parameter table keyed by
// hash32(id) - unknown ids are skipped, missing ids keep defaults - and an
// optional opaque user-state section appended verbatim.
 
inline constexpr uint32_t kStateMagic   = 0x4453504Bu;   // "DSPK"
inline constexpr uint32_t kStateVersion = 1u;
 
inline constexpr uint32_t kProgramStateId = 0x5052474Du;
 
inline constexpr uint32_t kBypassStateId = 0x42595053u;
 
template <typename P>
inline std::vector<uint8_t> buildState(const P& user, const double* normalized,
                                       size_t numParams, int programIndex = -1,
                                       int bypassState = -1)
{
    auto push32 = [](std::vector<uint8_t>& v, uint32_t x) {
        v.push_back(static_cast<uint8_t>(x));
        v.push_back(static_cast<uint8_t>(x >> 8));
        v.push_back(static_cast<uint8_t>(x >> 16));
        v.push_back(static_cast<uint8_t>(x >> 24));
    };
    auto pushValue = [&push32](std::vector<uint8_t>& v, double value) {
        uint64_t bits = 0;
        static_assert(sizeof(bits) == sizeof(value));
        std::memcpy(&bits, &value, sizeof(bits));
        push32(v, static_cast<uint32_t>(bits));
        push32(v, static_cast<uint32_t>(bits >> 32));
    };
    std::vector<uint8_t> blob;
    push32(blob, kStateMagic);
    push32(blob, kStateVersion);
    push32(blob, static_cast<uint32_t>(numParams) + (programIndex >= 0 ? 1u : 0u)
                     + (bypassState >= 0 ? 1u : 0u));
    for (size_t i = 0; i < numParams; ++i)
    {
        push32(blob, hash32(P::parameters[i].id));
        pushValue(blob, normalized[i]);
    }
    if (programIndex >= 0)
    {
        // The active factory preset rides along as one more entry so hosts
        // restore the program selection with the session.
        push32(blob, kProgramStateId);
        pushValue(blob, static_cast<double>(programIndex));
    }
    if (bypassState >= 0)
    {
        push32(blob, kBypassStateId);
        pushValue(blob, bypassState > 0 ? 1.0 : 0.0);
    }
    if constexpr (HasGetState<P>)
    {
        const std::vector<uint8_t> userBlob = user.getState();
        push32(blob, static_cast<uint32_t>(userBlob.size()));
        blob.insert(blob.end(), userBlob.begin(), userBlob.end());
    }
    else
        push32(blob, 0u);
    return blob;
}
 
template <typename P>
inline bool applyState(P& user, const uint8_t* data, size_t size, double* normalized,
                       int* programIndex = nullptr, int* bypassState = nullptr)
{
    auto read32 = [&](size_t& pos, uint32_t& out) {
        if (pos + 4 > size) return false;
        out = static_cast<uint32_t>(data[pos])
            | static_cast<uint32_t>(data[pos + 1]) << 8
            | static_cast<uint32_t>(data[pos + 2]) << 16
            | static_cast<uint32_t>(data[pos + 3]) << 24;
        pos += 4;
        return true;
    };
    size_t pos = 0;
    uint32_t magic = 0, version = 0, count = 0;
    if (!read32(pos, magic) || magic != kStateMagic) return false;
    if (!read32(pos, version) || version == 0) return false;
    if (!read32(pos, count)) return false;
 
    constexpr size_t numParams = P::parameters.size();
    for (uint32_t i = 0; i < count; ++i)
    {
        uint32_t id = 0, lo = 0, hi = 0;
        if (!read32(pos, id) || !read32(pos, lo) || !read32(pos, hi)) return false;
        const uint64_t bits = static_cast<uint64_t>(lo) | (static_cast<uint64_t>(hi) << 32);
        double v = 0.0;
        std::memcpy(&v, &bits, sizeof(v));
        // A corrupt blob can carry any bit pattern: a NaN would survive both
        // range checks below (every comparison is false) and poison the
        // parameter shadow, so non-finite entries keep the default instead.
        if (v != v) continue;
        if (id == kProgramStateId)
        {
            if (programIndex != nullptr && v >= 0.0)
                *programIndex = static_cast<int>(v + 0.5);
            continue;
        }
        if (id == kBypassStateId)
        {
            if (bypassState != nullptr)
                *bypassState = v >= 0.5 ? 1 : 0;
            continue;
        }
        for (size_t k = 0; k < numParams; ++k)
            if (hash32(P::parameters[k].id) == id)
            {
                normalized[k] = v < 0.0 ? 0.0 : (v > 1.0 ? 1.0 : v);
                break;
            }
        // Unknown ids are skipped: forward-compatible by construction.
    }
 
    uint32_t userSize = 0;
    // Subtraction form: pos <= size is guaranteed after read32, and on
    // 32-bit size_t targets (WASM) the addition form `pos + userSize` could
    // wrap around and admit an out-of-bounds user section.
    if (read32(pos, userSize) && userSize > 0 && userSize <= size - pos)
    {
        if constexpr (HasSetState<P>)
            user.setState(data + pos, userSize);
    }
    return true;
}
 
} // namespace dspark::plugin