clap_adapter.hpp

Go to the documentation of this file.

#pragma once
 
// CLAP Adapter for Pulp
// Implements the CLAP plugin entry point wrapping pulp::format::Processor
// Built from CLAP specification headers (MIT license)
 
#include <pulp/format/processor.hpp>
#include <pulp/runtime/trace_session.hpp>
#include <pulp/format/state_restore_gate.hpp>
#include <pulp/format/adapter_boundary.hpp>
#include <pulp/format/ara.hpp>
#include <pulp/format/host_quirks.hpp>
#include <pulp/format/detail/playhead_diff.hpp>
#include <pulp/events/plugin_main_thread.hpp>
#include <pulp/runtime/alive_token.hpp>
#include <pulp/runtime/spsc_queue.hpp>
#include <pulp/state/parameter_event_queue.hpp>
#include <pulp/state/modulation_lane.hpp>
#include <pulp/state/preset_manager.hpp>
#include <pulp/signal/delay_line.hpp>
#include <clap/clap.h>
#include <clap/ext/timer-support.h>
#include <clap/ext/params.h>
#include <array>
#include <atomic>
#include <cstdint>
#include <memory>
#include <optional>
#include <thread>
#include <vector>
 
// View includes only when building GUI-capable CLAP targets.
//
// Important: PulpClapPlugin is shared across clap_entry.hpp (compiled into the
// plugin module) and clap_adapter.cpp (compiled into pulp-format). Both
// translation units must see the same PULP_CLAP_GUI value or the instance
// layout diverges and lifecycle callbacks write through the wrong offsets.
#if defined(PULP_CLAP_GUI) && PULP_CLAP_GUI
#include <pulp/format/view_bridge.hpp>
#include <pulp/view/plugin_view_host.hpp>
#endif
 
namespace pulp::format::clap_adapter {
 
// Per-bus channel ceiling. Single source of truth is
// boundary::kBoundaryMaxChannels (adapter_boundary.hpp) — kept as an `int` here
// because CLAP's channel counts, loop indices, and clamps are all signed. Same
// value (8) across every adapter; change it once at the boundary.
static constexpr int kMaxChannels =
    static_cast<int>(boundary::kBoundaryMaxChannels);
// The Processor surface currently exposes a main input and one optional
// sidechain input. Keep the process-time layout cache fixed-size so validating
// a host block never allocates on the audio thread.
static constexpr int kMaxInputBuses = 2;
// Upper bound on output buses routed to the Processor in one block. Index 0 is
// the main output; indices 1..kMaxOutputBuses-1 are secondary (aux) outputs for
// multi-out instruments (drum machines, multitimbral, stem renderers). Host
// output buses beyond this cap are zero-filled, never routed — same safe
// fallback as before, just with a higher ceiling than one.
static constexpr int kMaxOutputBuses = 8;
static constexpr state::ModulationSourceId kClapHostModulationSourceId = 1;
 
enum class OutboundParamEventKind : std::uint8_t {
    GestureBegin,
    Value,
    GestureEnd,
};
 
struct OutboundParamEvent {
    OutboundParamEventKind kind = OutboundParamEventKind::Value;
    state::ParamID param_id = 0;
    float value = 0.0f;
};
 
// A UI drag normally contributes a few dozen events. This intentionally leaves
// enough headroom for several controls to move before a stopped host services
// request_flush(), while remaining bounded and allocation-free at either drain.
static constexpr std::size_t kOutboundParamEventCapacity = 1024;
 
// CLAP plugin instance — wraps a Pulp Processor
struct PulpClapPlugin {
    // Declared FIRST so it is destroyed LAST: the final detach cancels and joins
    // the tracing auto-flush timer and writes the .pftrace, and that must happen
    // after every span this instance can still emit. Tracing used to be wired
    // into VST3 ONLY, so a Perfetto capture of a CLAP/AU/AAX/standalone session
    // recorded nothing while the API happily claimed to be process-global.
    // No-op unless PULP_TRACING=ON.
    runtime::ScopedTracingAttachment tracing;
    clap_plugin_t plugin;
    // The store is declared before the Processor so it is destroyed after it.
    // `Processor::state()` dereferences a pointer to this store, and a Processor
    // may read it from its destructor or from a worker thread that destructor is
    // about to join. Reversing these two lines hands that thread a freed store.
    state::StateStore store;
    std::unique_ptr<Processor> processor;
    // Panic requests (Processor::request_panic), serviced before each block.
    std::shared_ptr<PanicState> panic_state;
    // Keeps a host state.load off the processor while clap_process() is inside
    // it. Declared after processor so it outlives every render that consults it.
    StateRestoreGate state_restore_gate;
    // Declared after processor so reverse member destruction retires retained
    // editor handles before either referenced object is released.
    runtime::AliveToken owner_alive;
    ProcessorFactory factory;
 
    // Descriptor snapshot cached at create_plugin() from this instance's plugin
    // record. In a multi-plugin bundle there is no single global descriptor, so
    // extension callbacks that may fire before clap_init() constructs `processor`
    // (audio-ports / note-ports enumeration) read bus/MIDI metadata from here
    // instead of a shared global. Once `processor` exists, callbacks prefer its
    // live descriptor.
    PluginDescriptor descriptor_snapshot{};
 
    // Host accommodations, resolved once in clap_init() via the runtime
    // policy. Adapters consult these instead of hardcoding workarounds.
    HostQuirks host_quirks{};
 
    // Cached ParamID of the "Bypass" parameter, plugin-declared or synthesized
    // via synthesize_bypass_parameter. 0 when none; clap_process() then never
    // short-circuits to pass-through.
    state::ParamID bypass_param_id = 0;
 
    // Per-output-channel dry delay used by the bypass pass-through. The host
    // compensates the plugin path by its reported latency, so the bypassed
    // dry signal must be delayed by the same amount to stay sample-aligned
    // with the host's plugin-delay-compensation. Storage is allocated in
    // clap_activate() (off the audio thread) via prepare(); unused when the
    // reported latency is 0, preserving the zero-copy pass-through. Shared
    // adapter-boundary component (SF-1) so every format's bypass latency is
    // identical by construction.
    boundary::LatencyCompensatedBypassT<static_cast<std::size_t>(kMaxChannels)> bypass;
 
    // Stored at create_plugin() time so the adapter can publish
    // latency / tail change notifications back to the
    // host. `clap_on_main_thread()` consumes the processor's pending
    // flags and calls `clap_host_latency->changed()` /
    // `clap_host_tail->changed()` — never from process() itself.
    const clap_host_t* host = nullptr;
    const clap_host_params_t* host_params = nullptr;
 
    // True between a successful clap_activate() and the matching
    // clap_deactivate(). `clap.latency` only permits the reported latency to
    // move during plugin->activate, so an ACTIVE plugin whose latency changed
    // must ask the host for a deactivate / reactivate cycle
    // (`clap_host->request_restart()`) instead of publishing the new value
    // where the host is not allowed to act on it. An inactive plugin has no
    // such window to protect and simply reports the new value.
    bool is_active = false;
 
    // Latched when an active plugin has asked the host to restart because its
    // latency moved, and cleared once the new value is published inside the
    // reactivating clap_activate(). Two jobs:
    //   * Coalescing. A host may take arbitrarily long to honour a restart (or
    //     decline it); latency can move many times meanwhile. One outstanding
    //     request is the whole contract, so further edges must not re-ask.
    //   * Deferral. `clap_host_latency->changed()` is `[main-thread &
    //     being-activated]`, so the push waits for the activate this latch
    //     survives a deactivate to reach.
    bool latency_restart_pending = false;
 
    // Host render mode from the `clap.render` extension. A host doing an
    // offline (faster-than-realtime) render calls render->set(OFFLINE) on the
    // main thread; every block then reports ProcessMode::Offline. Atomic because
    // a host may switch modes while the plugin is active.
    std::atomic<bool> render_offline{false};
 
    // Audio working state
    double sample_rate = 48000.0;
    int max_buffer_size = 512;
    clap_id selected_bus_layout = 0;
    uint32_t declared_input_bus_count = 0;
    uint32_t declared_output_bus_count = 0;
    std::array<int, kMaxInputBuses> declared_input_channels{};
    std::array<int, kMaxOutputBuses> declared_output_channels{};
 
    // Pre-allocated buffers — no heap allocation on audio thread
    float* output_ptrs[kMaxChannels] = {};
    const float* input_ptrs[kMaxChannels] = {};
    double* output64_ptrs[kMaxChannels] = {};
    const double* input64_ptrs[kMaxChannels] = {};
    std::array<std::vector<float>, kMaxChannels> f64_input_scratch{};
    std::array<std::vector<float>, kMaxChannels> f64_output_scratch{};
    // Per-bus channel-pointer storage for secondary (aux) output buses, indexed
    // [aux_bus_minus_1][channel]: row i backs the BufferView for the host output
    // bus at index i+1 (the main bus at index 0 uses output_ptrs above). Pre-
    // allocated so the multi-out routing path allocates nothing on the audio
    // thread.
    float* aux_output_ptrs[kMaxOutputBuses - 1][kMaxChannels] = {};
    double* aux_output64_ptrs[kMaxOutputBuses - 1][kMaxChannels] = {};
    std::array<std::array<std::vector<float>, kMaxChannels>, kMaxOutputBuses - 1>
        f64_aux_output_scratch{};
    // Descriptor-declared channel count per secondary output bus, cached in
    // clap_activate() (off the audio thread) so the process path can report a
    // bus's declared layout without calling descriptor() on the audio thread.
    // declared_aux_channels[i] is the declared channel count for the host
    // output bus at index i+1; 0 when the descriptor declares no such bus.
    int declared_aux_channels[kMaxOutputBuses - 1] = {};
    // Second input bus routed to Processor::set_sidechain(). Up to
    // kMaxChannels. Additional input buses beyond index 1 are currently
    // ignored; the Processor API is single-sidechain today.
    const float* sidechain_ptrs[kMaxChannels] = {};
    const double* sidechain64_ptrs[kMaxChannels] = {};
    std::array<std::vector<float>, kMaxChannels> f64_sidechain_scratch{};
    bool native_f64_enabled = false;
 
    // Parameter snapshot for detecting plugin-side changes during process.
    // Refreshed only when the store generation moved since it was taken; the
    // post-process diff only runs when the generation moved across process().
    std::vector<float> param_snapshot;
    // Processor::wants_sample_accurate_parameters(), asked in clap_init().
    bool sample_accurate_params = false;
    // Records an opted-out processor reading param_events(); see processor.hpp.
    ParamEventsOptOutMonitor param_events_monitor;
    // For a block-rate processor: each parameter's latest value in the block,
    // indexed like StateStore::all_params(), written to the store once after
    // the events are read. Sized in clap_activate().
    std::vector<float> latest_param_value;
    std::vector<std::uint8_t> latest_param_pending;
    std::vector<std::uint32_t> latest_param_touched;
    std::vector<state::StateStore::ParamWrite> latest_param_writes;
    boundary::ParamSnapshotState snapshot_state;
    std::uint64_t pre_process_generation = 0;
    // Bus views handed to the Processor. Members so a block writes only the
    // entries it routes instead of value-initialising every slot.
    std::array<ProcessBusBufferView<float>, kMaxOutputBuses> rt_output_buses{};
    std::array<ProcessBusBufferView<double>, kMaxOutputBuses> rt_output64_buses{};
    state::ParameterEventQueue param_events;
    // Timestamp-preserving host PARAM_MOD lane for processors that apply
    // modulation sample-accurately. The StateStore offset remains a bounded
    // compatibility snapshot for legacy processors.
    state::ModulationEventQueue modulation_events;
    // Sample-accurate parameter OUTPUT: the processor pushes offset-tagged events
    // via push_output_param_event(); we merge them (by ascending sample offset)
    // with the plugin's MIDI-out shorts and sysex into out_events, which CLAP
    // requires to be globally time-ordered. output_param_has_event is the
    // skip-set that keeps the offset-0 snapshot fallback from double-reporting a
    // param that already emitted explicit events. Both are sized off the audio
    // thread at block start so the drain stays allocation-free.
    state::ParameterEventQueue output_param_events;
    std::vector<std::uint8_t> output_param_has_event;
 
    // UI -> host parameter automation. StateStore gesture callbacks and an
    // inline value listener preserve exact BEGIN/VALUE/END order in this SPSC
    // queue. CLAP guarantees params.flush() and process() do not run
    // concurrently, so the consumer endpoint may safely move between them as
    // transport starts and stops.
    runtime::SpscQueue<OutboundParamEvent, kOutboundParamEventCapacity>
        outbound_param_events;
    std::optional<OutboundParamEvent> pending_outbound_param_event;
    state::ListenerToken outbound_param_listener;
    std::thread::id main_thread_id;
 
    // Reused per-block MIDI buffers. Reserved and capacity-limited during
    // activate() so capacity survives warmup and processors can append
    // outbound MIDI while the process no-allocation guard is active.
    midi::MidiBuffer midi_in;
    midi::MidiBuffer midi_out;
 
    // Host out_events may reject a suffix of a process block. Retain only
    // ownership-releasing MIDI in fixed storage and retry it before later
    // attacks. Saturated per-key/control counters collapse to one channel
    // All Sound Off debt, so this path remains allocation-free and bounded.
    std::array<std::uint8_t, 16 * 128> outbound_note_release_debt{};
    std::array<std::uint8_t, 16 * 6> outbound_control_release_debt{};
    std::array<bool, 16> outbound_panic_debt{};
    std::size_t outbound_release_drain_cursor = 0;
    // True while any of the three debt arrays above may be nonzero. Lets the
    // per-block drain skip its full slot walk in the normal no-debt case.
    bool outbound_release_debt_pending = false;
 
    // MPE sidecar — populated from midi_in before each process() call when
    // the Processor declares MPE in its effective PluginDescriptor capabilities.
    // Reserved and capacity-limited during activate(); one MIDI event can fan
    // out to many MPE callbacks. See boundary::MpeSidecar.
    boundary::MpeSidecar mpe;
 
    // UMP sidecar — populated by converting midi_in to MIDI 2.0 UMP packets
    // when the Processor declares UMP in its effective PluginDescriptor
    // capabilities. Native CLAP_EVENT_MIDI2 packets also append directly.
    // Reserved and capacity-limited during activate().
    midi::UmpBuffer ump_buffer;
    bool ump_enabled = false;
 
    // Preset management (optional — set by plugins that provide presets)
    std::unique_ptr<state::PresetManager> preset_manager;
 
    // ARA document controller (optional; Processor opts in by overriding
    // create_ara_document_controller()).
    // Lives for the plugin's lifetime once created; surfaced through
    // get_extension(kClapAraFactoryExtension).
    std::unique_ptr<AraDocumentController> ara_controller;
    // The editor-host contract GUI (clap_contract_gui.cpp), type-erased so this
    // header and clap_adapter.cpp need no knowledge of it. Declared after
    // processor and store, so a GUI the host never destroyed goes before the
    // processor that owns its editor factory. Outside the GUI block, so its
    // offset does not depend on PULP_CLAP_GUI.
    std::shared_ptr<void> contract_gui;
    // The processor's editor factory, read once by clap_init() on the main
    // thread: get_extension() may run on any thread, and editor_factory() is
    // main-thread only.
    EditorFactory* editor_factory = nullptr;
 
    // Editor state (created on GUI create, destroyed on GUI destroy).
    // `bridge` owns the view tree and dispatches Processor lifecycle
    // callbacks (on_view_opened/closed/resized). editor_host is the
    // platform-native window surface that hosts bridge->view().
#if defined(PULP_CLAP_GUI) && PULP_CLAP_GUI
    std::unique_ptr<ViewBridge> bridge;
    std::unique_ptr<view::PluginViewHost> editor_host;
    // Forwards editor_host's GPU-surface transitions into bridge's scripted UI
    // session. Reset in gui_destroy() before either of them dies.
    view::PluginViewHost::GpuSurfaceSubscription gpu_surface_binding;
    // Native embedded CLAP editors use the host's timer-support extension as
    // their UI-thread frame source. The timer is registered only while the
    // editor is attached and visible; no worker or fabricated clock runs when
    // the host cannot provide this extension.
    const clap_host_timer_support_t* editor_host_timer = nullptr;
    clap_id editor_timer_id = CLAP_INVALID_ID;
    bool editor_parent_attached = false;
#endif
    bool editor_visible = false;
 
    // Previous-block transport snapshot used to derive the `tempo_changed` /
    // `time_sig_changed` / `transport_changed` flags on `ProcessContext`.
    // Default-constructed (no previous block) so the first process() call after
    // activation reports no changes.
    detail::PlayheadSnapshot playhead_prev{};
    // Set while clap_activate() runs the per-block path once on silence (see
    // clap_warm_render_path()); clap_process() then stops before the state-
    // restore gate, so the Processor, sidecars, triggers and host output are
    // never touched.
    bool warming_render_path = false;
 
    // clap_reset() is delivered while processing is stopped. The Processor API
    // exposes reset as a one-block ProcessContext signal rather than a virtual
    // callback, so carry that request to exactly the next process block.
    bool reset_requested = false;
    // A bypassed or render-contended block may contain an unreplayable note
    // lifecycle event. Reconcile adapter and processor ownership together on
    // the next block that actually reaches Processor::process().
    bool sidecar_reconcile_requested = false;
 
    // Process-wide MainThreadDispatcher backend token. Acquired in clap_init()
    // so adapter callsites (e.g. host-callback dispatches posted via
    // `clap_host->request_callback()`) and any view-side code can use
    // `pulp::events::MainThreadDispatcher::call_async` to marshal work onto
    // the DAW's main thread. Released in clap_destroy().
    pulp::events::MainThreadDispatcher::Token main_thread_token = 0;
};
 
// CLAP entry point and factory
const clap_plugin_entry_t* get_clap_entry();
 
// Create a CLAP plugin descriptor from a Pulp PluginDescriptor
clap_plugin_descriptor_t make_clap_descriptor(const PluginDescriptor& desc);
 
// Plugin lifecycle callbacks
bool clap_init(const clap_plugin_t* plugin);
void clap_destroy(const clap_plugin_t* plugin);
bool clap_activate(const clap_plugin_t* plugin, double sr, uint32_t min_frames, uint32_t max_frames);
void clap_deactivate(const clap_plugin_t* plugin);
bool clap_start_processing(const clap_plugin_t* plugin);
void clap_stop_processing(const clap_plugin_t* plugin);
void clap_reset(const clap_plugin_t* plugin);
clap_process_status clap_process(const clap_plugin_t* plugin, const clap_process_t* process);
void clap_params_flush(const clap_plugin_t* plugin,
                       const clap_input_events_t* in,
                       const clap_output_events_t* out);
bool clap_param_modulation_lane(const PulpClapPlugin& self,
                                const clap_event_param_mod_t& event,
                                state::ModulationLane& lane);
const void* clap_get_extension(const clap_plugin_t* plugin, const char* id);
void clap_on_main_thread(const clap_plugin_t* plugin);
 
} // namespace pulp::format::clap_adapter