processor.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/audio/buffer.hpp>
#include <pulp/midi/buffer.hpp>
#include <pulp/midi/mpe_buffer.hpp>
#include <pulp/midi/ump_buffer.hpp>
#include <pulp/format/editor_host_kind.hpp>
#include <pulp/format/process_block.hpp>
#include <pulp/runtime/node_abi.hpp>
#include <pulp/state/parameter_event_queue.hpp>
#include <pulp/format/note_name.hpp>
#include <pulp/format/panic.hpp>
#include <pulp/state/store.hpp>
#include <pulp/format/plugin_descriptor.hpp>
#include <pulp/format/prepare_resources.hpp>
#include <pulp/format/process_context.hpp>
#include <array>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <mutex>
#include <optional>
#include <unordered_map>
#include <memory>
#include <span>
#include <string>
#include <string_view>
#include <vector>

#define PULP_FORMAT_HAS_EDITOR_BACKGROUND 1
 
// Forward-declared, never included: `pulp-wclap-dsp` compiles core/format
// without the data-plane include path (the wasm DSP build has no editor), so
// pulling in value_channel_set.hpp here breaks that target. A pointer return
// needs only the declaration. pulp::view::ValueChannelSet names the same class
// as pulp::dataplane::ValueChannelSet.
namespace pulp::dataplane {
class ValueChannelSet;
}
 
namespace pulp::view {
class ScriptedUiSession;
class View;
using dataplane::ValueChannelSet;
}
 
namespace pulp::format {
 
namespace detail {

inline std::mutex& editor_resize_mutex() {
    static std::mutex m;
    return m;
}
using EditorResizeHandler =
    std::function<bool(uint32_t, uint32_t)>;
struct EditorResizeHandlerEntry {
    EditorResizeHandler handler;
    std::function<bool()> is_active;
};
using EditorResizeHandlerSet =
    std::unordered_map<const void*, EditorResizeHandlerEntry>;
 
inline std::unordered_map<const void*, EditorResizeHandlerSet>&
editor_resize_handlers() {
    static std::unordered_map<const void*, EditorResizeHandlerSet> table;
    return table;
}

inline std::unordered_map<const void*, bool>& standalone_processors() {
    static std::unordered_map<const void*, bool> table;
    return table;
}

inline std::unordered_map<const void*, std::shared_ptr<PanicState>>& panic_states() {
    static std::unordered_map<const void*, std::shared_ptr<PanicState>> table;
    return table;
}
 
}  // namespace detail
 
class EditorFactory;

namespace detail {
struct ParamEventsOptOutSlot {
    std::atomic<const void*> queue{nullptr};
    std::atomic<bool> read{false};
};
inline constexpr std::size_t kParamEventsOptOutSlots = 256;
inline constexpr std::size_t kParamEventsOptOutProbe = 8;
inline ParamEventsOptOutSlot param_events_opt_out_slots[kParamEventsOptOutSlots];
inline std::atomic<std::size_t> param_events_opt_out_count{0};
 
inline std::size_t param_events_opt_out_home(const void* queue) noexcept {
    auto v = static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(queue));
    v ^= v >> 33;
    v *= 0xff51afd7ed558ccdULL;
    v ^= v >> 33;
    return static_cast<std::size_t>(v) & (kParamEventsOptOutSlots - 1);
}

inline ParamEventsOptOutSlot* param_events_opt_out_find(const void* queue) noexcept {
    const auto home = param_events_opt_out_home(queue);
    for (std::size_t i = 0; i < kParamEventsOptOutProbe; ++i) {
        auto& slot = param_events_opt_out_slots[(home + i) & (kParamEventsOptOutSlots - 1)];
        if (slot.queue.load(std::memory_order_acquire) == queue)
            return &slot;
    }
    return nullptr;
}
} // namespace detail
 
class Processor {
public:
    Processor() {
        // Adapters clear the handler on editor close. If abnormal teardown
        // skips that close, make address reuse safe before this new instance
        // can observe a stale handler left under the same `this` key. Keep the
        // virtual destructor exactly defaulted: its spelling/order is part of
        // the frozen Processor node ABI.
        std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
        detail::editor_resize_handlers().erase(this);
        detail::standalone_processors().erase(this);
        detail::panic_states().erase(this);
    }
    virtual ~Processor();

    EditorHostKind editor_host_kind() const {
        std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
        return detail::standalone_processors().count(this) != 0
                   ? EditorHostKind::standalone
                   : EditorHostKind::plugin;
    }

    void set_editor_host_kind(EditorHostKind kind) {
        std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
        if (kind == EditorHostKind::standalone)
            detail::standalone_processors()[this] = true;
        else
            detail::standalone_processors().erase(this);
    }

    virtual PluginDescriptor descriptor() const = 0;

    virtual void define_parameters(state::StateStore& store) = 0;

    virtual void prepare(const PrepareContext& context) = 0;

    virtual void release() {}

    virtual void suspend() {}

    virtual void resume() {}

    virtual std::vector<uint8_t> serialize_plugin_state() const { return {}; }

    void publish_plugin_state_snapshot(std::vector<uint8_t> bytes) {
        auto snapshot = std::make_shared<const std::vector<uint8_t>>(std::move(bytes));
        std::atomic_store_explicit(&published_plugin_state_, std::move(snapshot),
                                   std::memory_order_release);
    }
 
    void publish_plugin_state_snapshot(std::span<const uint8_t> bytes) {
        publish_plugin_state_snapshot(std::vector<uint8_t>(bytes.begin(), bytes.end()));
    }

    std::shared_ptr<const std::vector<uint8_t>> published_plugin_state_snapshot() const {
        return std::atomic_load_explicit(&published_plugin_state_,
                                         std::memory_order_acquire);
    }

    virtual bool deserialize_plugin_state(std::span<const uint8_t>) { return true; }

    enum class MemoryPressure {
        Advisory,
        Critical,
    };

    virtual void on_memory_pressure(MemoryPressure /*level*/) {}

    virtual int latency_samples() const { return 0; }


    struct BusesLayout {
        std::vector<int> inputs;
        std::vector<int> outputs;
    };

    virtual bool is_bus_layout_supported(const BusesLayout& layout) const {
        const auto desc = descriptor();
        if (!desc.supported_bus_layouts.empty()) {
            return std::any_of(desc.supported_bus_layouts.begin(),
                               desc.supported_bus_layouts.end(),
                               [&](const auto& declared) {
                                   return declared.inputs == layout.inputs &&
                                          declared.outputs == layout.outputs;
                               });
        }
        if (!layout.inputs.empty() &&
            layout.inputs.size() != desc.input_buses.size())
            return false;
        if (!layout.outputs.empty() &&
            layout.outputs.size() != desc.output_buses.size())
            return false;
        auto side_ok = [](const auto& proposed, const auto& declared) {
            for (std::size_t i = 0; i < proposed.size(); ++i) {
                const int channels = proposed[i];
                if (channels == 1 || channels == 2) continue;
                if (channels == 0 &&
                    (declared[i].default_channels == 0 || declared[i].optional))
                    continue;
                return false;
            }
            return true;
        };
        if (!layout.inputs.empty() && !side_ok(layout.inputs, desc.input_buses))
            return false;
        if (!layout.outputs.empty() && !side_ok(layout.outputs, desc.output_buses))
            return false;
        return true;
    }

    void flag_latency_changed() noexcept {
        latency_changed_.store(true, std::memory_order_release);
    }
    void flag_tail_changed() noexcept {
        tail_changed_.store(true, std::memory_order_release);
    }

    // Polled by the adapters every block; a plain load keeps the common
    // nothing-changed case free of read-modify-write traffic.
    bool consume_latency_changed_flag() noexcept {
        return latency_changed_.load(std::memory_order_relaxed) &&
               latency_changed_.exchange(false, std::memory_order_acq_rel);
    }
    bool consume_tail_changed_flag() noexcept {
        return tail_changed_.load(std::memory_order_relaxed) &&
               tail_changed_.exchange(false, std::memory_order_acq_rel);
    }

    bool latency_change_pending() const noexcept {
        return latency_changed_.load(std::memory_order_acquire);
    }
    bool tail_change_pending() const noexcept {
        return tail_changed_.load(std::memory_order_acquire);
    }

    void flag_note_names_changed() noexcept {
        note_names_changed_.store(true, std::memory_order_release);
    }
    bool consume_note_names_changed_flag() noexcept {
        return note_names_changed_.exchange(false, std::memory_order_acq_rel);
    }
    bool note_names_change_pending() const noexcept {
        return note_names_changed_.load(std::memory_order_acquire);
    }

    void flag_state_dirty() noexcept {
        state_dirty_.store(true, std::memory_order_release);
    }
    bool consume_state_dirty_flag() noexcept {
        return state_dirty_.exchange(false, std::memory_order_acq_rel);
    }
    bool state_dirty_pending() const noexcept {
        return state_dirty_.load(std::memory_order_acquire);
    }

    virtual void process(
        audio::BufferView<float>& audio_output,
        const audio::BufferView<const float>& audio_input,
        midi::MidiBuffer& midi_in,
        midi::MidiBuffer& midi_out,
        const ProcessContext& context) = 0;


    virtual bool has_editor() const { return true; }

    struct EditorPrewarm {
        std::vector<std::string_view> scripts;
        std::vector<std::string_view> materialized_documents;
        bool empty() const noexcept { return scripts.empty() && materialized_documents.empty(); }
    };

    virtual std::pair<uint32_t, uint32_t> editor_size() const { return {400, 300}; }

    virtual ViewSize view_size() const {
#ifdef PULP_PLUGIN_DESIGN_W
        return view_size_from_design(
            PULP_PLUGIN_DESIGN_W, PULP_PLUGIN_DESIGN_H,
            PULP_PLUGIN_DESIGN_MIN_W, PULP_PLUGIN_DESIGN_MIN_H,
            PULP_PLUGIN_DESIGN_MAX_W, PULP_PLUGIN_DESIGN_MAX_H);
#else
        auto [w, h] = editor_size();
        return ViewSize{w, h, 0, 0, 0, 0};
#endif
    }

    virtual std::unique_ptr<view::View> create_view();

    struct SettingsSection {
        using ViewDeleter = void (*)(view::View*);
 
        SettingsSection() noexcept : view(nullptr, &no_view) {}
        SettingsSection(std::string title, std::unique_ptr<view::View> view);
        ~SettingsSection() = default;
        SettingsSection(SettingsSection&&) noexcept = default;
        SettingsSection& operator=(SettingsSection&&) noexcept = default;
        SettingsSection(const SettingsSection&) = delete;
        SettingsSection& operator=(const SettingsSection&) = delete;

        std::unique_ptr<view::View> take_view();
 
        std::string title;  
        std::unique_ptr<view::View, ViewDeleter> view;
 
    private:
        static void no_view(view::View*) noexcept {}
    };

    virtual void on_view_opened(view::View& /*view*/) {}

    virtual void on_view_closed(view::View& /*view*/) {}

    virtual void on_view_resized(view::View& /*view*/, uint32_t /*w*/, uint32_t /*h*/) {}

    bool request_editor_resize(uint32_t width, uint32_t height) {
        std::vector<detail::EditorResizeHandlerEntry> candidates;
        {
            std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
            auto& table = detail::editor_resize_handlers();
            auto it = table.find(this);
            if (it == table.end()) return false;
            candidates.reserve(it->second.size());
            for (const auto& [owner, entry] : it->second) {
                (void)owner;
                candidates.push_back(entry);
            }
        }
 
        // Hosts may retain an editor object after detaching it from its
        // window. Such a stale-but-live registration must not make a reopened
        // editor look ambiguous. Evaluate attachment predicates outside the
        // side-table mutex: they are host callbacks and may re-enter teardown.
        // Two genuinely active views remain ambiguous and are refused.
        detail::EditorResizeHandler handler;
        for (const auto& candidate : candidates) {
            bool active = true;
            if (candidate.is_active) {
                // Format adapters own this predicate and must keep it
                // non-throwing: Processor is also compiled by exception-free
                // targets such as WebCLAP.
                active = candidate.is_active();
            }
            if (!active) continue;
            if (handler) return false;
            handler = candidate.handler;
        }
        return handler ? handler(width, height) : false;
    }

    virtual void on_host_transport_changed(bool /*is_playing*/,
                                           double /*position_seconds*/) {}

    virtual void on_host_tempo_changed(double /*new_tempo_bpm*/) {}

    virtual std::unique_ptr<class AraDocumentController>
    create_ara_document_controller();

    virtual view::ScriptedUiSession* active_scripted_ui() { return nullptr; }
    virtual const view::ScriptedUiSession* active_scripted_ui() const { return nullptr; }

    virtual std::vector<SettingsSection> settings_sections() { return {}; }

    virtual PrepareResourceUsage estimate_prepare_resources(
        const PrepareContext&) const {
        return {};
    }

    virtual PrepareResourceLimit check_prepare_resource_limits(
        const PrepareContext& context) const {
        return first_exceeded_prepare_resource_limit(
            estimate_prepare_resources(context), context.resource_limits);
    }

    virtual void process(
        ProcessBuffers& audio,
        midi::MidiBuffer& midi_in,
        midi::MidiBuffer& midi_out,
        const ProcessContext& context) {
        auto* output = audio.main_output();
        if (!output) return;
 
        audio::BufferView<const float> empty_input;
        auto* input = audio.main_input();
        auto* previous_sidechain = sidechain_;
        sidechain_ = audio.sidechain_input();
        process(*output, input ? *input : empty_input, midi_in, midi_out, context);
        sidechain_ = previous_sidechain;
    }

    virtual std::vector<std::byte> serialize_dsp_state() const { return {}; }
    virtual bool restore_dsp_state(const std::vector<std::byte>& /*blob*/) { return false; }

    virtual bool supports_editor_reload() const { return false; }

    virtual std::uint64_t editor_reload_generation() const { return 0; }

    void prepare_f64_fallback_scratch(const PrepareContext& context);
    void prepare_f64_fallback_scratch(const PrepareContext& context,
                                      const BusesLayout& layout);

    virtual void process_f64(
        audio::BufferView<double>& audio_output,
        const audio::BufferView<const double>& audio_input,
        midi::MidiBuffer& midi_in,
        midi::MidiBuffer& midi_out,
        const ProcessContext& context);

    virtual void process_f64(
        ProcessBuffers64& audio,
        midi::MidiBuffer& midi_in,
        midi::MidiBuffer& midi_out,
        const ProcessContext& context);

    virtual void on_non_realtime_tick() {}

    virtual bool non_realtime_tick_pending() const { return false; }

    state::StateStore& state() { return *state_store_; }
    const state::StateStore& state() const { return *state_store_; }

    const audio::BufferView<const float>* sidechain_input() const { return sidechain_; }

    const midi::MpeBuffer* mpe_input() const { return mpe_input_; }

    const midi::UmpBuffer* ump_input() const { return ump_input_; }

    const state::ParameterEventQueue* param_events() const {
        if (param_events_ != nullptr &&
            detail::param_events_opt_out_count.load(std::memory_order_relaxed) != 0) {
            if (auto* slot = detail::param_events_opt_out_find(param_events_))
                slot->read.store(true, std::memory_order_relaxed);
        }
        return param_events_;
    }

    const state::ModulationEventQueue* modulation_events() const {
        return modulation_events_;
    }

    bool push_output_param_event(state::ParamID id, float value,
                                 std::uint32_t sample_offset) noexcept {
        if (output_param_events_ == nullptr) return false;
        return output_param_events_->push(state::ParameterEvent{
            id, static_cast<int32_t>(sample_offset), value, 0});
    }

    const state::ParameterEventQueue* output_param_events() const {
        return output_param_events_;
    }

    void set_state_store(state::StateStore* store) { state_store_ = store; }
    void set_sidechain(const audio::BufferView<const float>* sc) { sidechain_ = sc; }
    void set_mpe_input(const midi::MpeBuffer* mpe) { mpe_input_ = mpe; }
    void set_ump_input(const midi::UmpBuffer* ump) { ump_input_ = ump; }
    void set_param_events(const state::ParameterEventQueue* events) { param_events_ = events; }
    void set_modulation_events(const state::ModulationEventQueue* events) {
        modulation_events_ = events;
    }

    void set_output_param_events(state::ParameterEventQueue* events) { output_param_events_ = events; }

    void set_editor_resize_handler(
        std::function<bool(uint32_t, uint32_t)> handler) {
        set_editor_resize_handler(this, std::move(handler));
    }

    void set_editor_resize_handler(
        const void* editor_owner,
        std::function<bool(uint32_t, uint32_t)> handler,
        std::function<bool()> is_active = {}) {
        if (!editor_owner) return;
        std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
        auto& table = detail::editor_resize_handlers();
        if (handler) {
            table[this][editor_owner] = {
                std::move(handler), std::move(is_active)};
        } else {
            auto it = table.find(this);
            if (it == table.end()) return;
            it->second.erase(editor_owner);
            if (it->second.empty()) table.erase(it);
        }
    }

    virtual std::vector<NoteName> note_names() const { return {}; }

    virtual view::ValueChannelSet* value_channels() { return nullptr; }

    virtual void visit_value_channels(
        const std::function<void(view::ValueChannelSet*)>& visitor) {
        if (visitor) visitor(value_channels());
    }

    virtual void visit_active_scripted_ui(
        const std::function<void(view::ScriptedUiSession*)>& visitor) {
        if (visitor) visitor(active_scripted_ui());
    }

    virtual void visit_active_scripted_ui(
        const std::function<void(const view::ScriptedUiSession*)>& visitor) const {
        if (visitor) visitor(active_scripted_ui());
    }

    virtual bool supports_in_place_scripted_ui_reload() const { return false; }

    virtual bool reload_active_scripted_ui_in_place(std::string* /*error*/) {
        return false;
    }

    virtual bool process_block(ProcessBlock&) {
        return false;
    }

    virtual std::optional<std::uint32_t> editor_background() const {
        return std::nullopt;
    }

    virtual EditorPrewarm editor_prewarm() const { return {}; }

    virtual bool wants_sample_accurate_parameters() const {
        return true;
    }

    virtual bool wants_au_scheduled_parameter_slices() const {
        return true;
    }

    virtual EditorFactory* editor_factory();

    virtual void on_panic(PanicMode /*mode*/) {}

    void request_panic(PanicMode mode = PanicMode::immediate) {
        panic_state()->request(mode);
    }

    PanicCapabilities panic_capabilities() const {
        return panic_state()->capabilities();
    }

    std::shared_ptr<PanicState> panic_state() const {
        std::lock_guard<std::mutex> lock(detail::editor_resize_mutex());
        auto& slot = detail::panic_states()[this];
        if (!slot)
            slot = std::make_shared<PanicState>();
        return slot;
    }
 
  private:
    std::shared_ptr<const std::vector<uint8_t>> published_plugin_state_;
    static constexpr std::size_t kF64FallbackMaxBuses = 16;
 
    static bool requires_rich_f64_fallback(const ProcessBuffers64& audio);
 
    bool f64_fallback_capacity_ok(std::size_t input_channels,
                                  std::size_t output_channels,
                                  std::size_t frames) const;
 
    bool f64_fallback_process_buffers_capacity_ok(
        const ProcessBuffers64& audio) const;
 
    static void copy_f64_to_f32(audio::BufferView<float> dst,
                                const audio::BufferView<const double>& src);
 
    static void copy_f32_to_f64(audio::BufferView<double> dst,
                                const audio::BufferView<const float>& src);
 
    static void clear_active_outputs(ProcessBuffers64& audio);
 
    void process_f64_via_f32_process_buffers(ProcessBuffers64& audio,
                                             midi::MidiBuffer& midi_in,
                                             midi::MidiBuffer& midi_out,
                                             const ProcessContext& context);
 
    state::StateStore* state_store_ = nullptr;
    const audio::BufferView<const float>* sidechain_ = nullptr;
    const midi::MpeBuffer* mpe_input_ = nullptr;
    const midi::UmpBuffer* ump_input_ = nullptr;
    const state::ParameterEventQueue* param_events_ = nullptr;
    const state::ModulationEventQueue* modulation_events_ = nullptr;
    state::ParameterEventQueue* output_param_events_ = nullptr;
    audio::Buffer<float> f64_fallback_input_scratch_;
    audio::Buffer<float> f64_fallback_output_scratch_;
    std::array<audio::Buffer<float>, kF64FallbackMaxBuses> f64_fallback_input_bus_scratch_{};
    std::array<audio::Buffer<float>, kF64FallbackMaxBuses> f64_fallback_output_bus_scratch_{};
    std::array<ProcessBusBufferView<const float>, kF64FallbackMaxBuses> f64_fallback_input_views_{};
    std::array<ProcessBusBufferView<float>, kF64FallbackMaxBuses> f64_fallback_output_views_{};
    // RT-safe pending flags published from process() and consumed by adapters
    // on the host / main thread.
    std::atomic<bool> latency_changed_{false};
    std::atomic<bool> tail_changed_{false};
    std::atomic<bool> note_names_changed_{false};
    std::atomic<bool> state_dirty_{false};
};

class ParamEventsOptOutMonitor {
  public:
    ParamEventsOptOutMonitor() = default;
    ParamEventsOptOutMonitor(const ParamEventsOptOutMonitor&) = delete;
    ParamEventsOptOutMonitor& operator=(const ParamEventsOptOutMonitor&) = delete;
    ~ParamEventsOptOutMonitor() {
        disarm();
    }

    void arm(bool opted_out, const state::ParameterEventQueue* queue) noexcept {
        disarm();
        if (!opted_out || queue == nullptr)
            return;
        const auto home = detail::param_events_opt_out_home(queue);
        for (std::size_t i = 0; i < detail::kParamEventsOptOutProbe; ++i) {
            auto& slot = detail::param_events_opt_out_slots[(home + i) &
                                                            (detail::kParamEventsOptOutSlots - 1)];
            const void* expected = nullptr;
            // Only a slot this monitor claims is reset: a probed slot may
            // belong to another adapter whose record must survive.
            if (slot.queue.compare_exchange_strong(expected, queue, std::memory_order_acq_rel)) {
                slot.read.store(false, std::memory_order_relaxed);
                slot_ = &slot;
                detail::param_events_opt_out_count.fetch_add(1, std::memory_order_relaxed);
                return;
            }
        }
    }

    bool read_while_opted_out() const noexcept {
        return slot_ != nullptr && slot_->read.load(std::memory_order_relaxed);
    }

    bool report(const Processor& processor);
 
  private:
    void disarm() noexcept {
        if (slot_ == nullptr)
            return;
        slot_->queue.store(nullptr, std::memory_order_release);
        slot_->read.store(false, std::memory_order_relaxed);
        detail::param_events_opt_out_count.fetch_sub(1, std::memory_order_relaxed);
        slot_ = nullptr;
    }
 
    detail::ParamEventsOptOutSlot* slot_ = nullptr;
    bool reported_ = false;
};

using ProcessorFactory = std::unique_ptr<Processor>(*)();
 
} // namespace pulp::format