vst3_adapter.hpp

Go to the documentation of this file.

#pragma once
 
// VST3 Adapter for Pulp
// Implements Steinberg's VST3 interfaces by wrapping pulp::format::Processor
// Uses SingleComponentEffect pattern (combined processor + controller)
// Built from VST3 SDK headers (MIT license), not from any existing adapter
 
// VST3 SDK requires one of these to be defined
#ifndef NDEBUG
    #ifndef DEVELOPMENT
        #define DEVELOPMENT 1
    #endif
#else
    #ifndef RELEASE
        #define RELEASE 1
    #endif
#endif
 
// Must come first per VST3 SDK requirements
#include <public.sdk/source/vst/vstsinglecomponenteffect.h>
 
#include <pluginterfaces/vst/ivstparameterchanges.h>
#include <pluginterfaces/vst/ivstevents.h>
#include <pluginterfaces/vst/ivstmidicontrollers.h>
#include <pluginterfaces/vst/ivstnoteexpression.h>
#include <pluginterfaces/vst/ivstunits.h>
#include <pluginterfaces/base/ibstream.h>
 
#include <pulp/events/plugin_main_thread.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/format/host_parameter_edit.hpp>
#include <pulp/format/state_restore_gate.hpp>
#include <pulp/format/host_quirks.hpp>
#include <pulp/runtime/trace_session.hpp>
#include <pulp/format/detail/playhead_diff.hpp>
#include <pulp/format/detail/vst3_restart_publisher.hpp>
#include <pulp/midi/mpe_buffer.hpp>
#include <pulp/midi/mpe_voice_tracker.hpp>
#include <pulp/state/parameter_event_queue.hpp>
#include <pulp/format/adapter_boundary.hpp>
#include <pulp/format/factory_program_table.hpp>
#include <pulp/format/param_group_projection.hpp>
#include <pulp/signal/delay_line.hpp>
#include <pulp/runtime/alive_token.hpp>
 
#include <array>
#include <set>
#include <atomic>
#include <cstdint>
#include <filesystem>
#include <memory>
#include <span>
#include <vector>
 
#include <pluginterfaces/gui/iplugview.h>
 
namespace pulp::format {
struct HostActionRequest;
}
 
namespace pulp::format::vst3 {
 
class ContractPlugView;
 
// Constructs the editor IPlugView, defined in vst3_plug_view.cpp.
//
// This declaration is the adapter's only seam to its own GUI, and it is
// deliberately view-free: PulpPlugView owns a ViewBridge and a
// view::PluginViewHost, so naming the concrete type here would put
// pulp/view on the include path of every translation unit that adapts VST3
// audio. Returning the SDK interface instead keeps the audio adapter
// compilable without the view layer, which is what lets it live in
// pulp-format-core.
//
// vst3_plug_view.cpp is compiled per-plugin rather than into the shared
// library, so this resolves the same way the direct constructor call did:
// an undefined symbol satisfied by the plugin target.
//
// Both this call site and the definition are guarded by PULP_VST3_GUI, so
// the two must agree: a GUI-capable adapter linked against a non-GUI
// vst3_plug_view.cpp leaves this symbol undefined at link time rather than
// silently losing the editor.
Steinberg::IPlugView* make_plug_view(Processor& processor,
                                     state::StateStore& store,
                                     runtime::AliveToken::Handle owner_alive);
 
// The process-context fields this adapter's decoder actually consumes,
// as an IProcessContextRequirements flag mask.
//
// VST3 3.7+ makes this a *request*: the host supplies only the
// ProcessContext fields the plug-in asks for here. The SDK is blunt about
// the consequence of staying silent -- "If you do not implement this
// interface, you may not get any information at all of the process
// function!" -- and the trap is that SingleComponentEffect already
// inherits IProcessContextRequirements and answers with
// `processContextRequirements.flags`, which defaults to 0. So the
// interface is advertised whether or not this mask is assigned: leaving it
// unset is not a compile error and not a missing override, it is a
// silently empty request that a strict host honours literally by sending
// no tempo, no time signature and no transport state.
//
// Each flag below is here because build_process_context() reads the
// matching kXxxValid bit; fields the decoder ignores (continuous time
// samples, bar position -- derived from beats + time signature instead --
// samples-to-next-clock, chord) are deliberately NOT requested, because
// the point of the mask is to let the host skip work nobody consumes.
// The host latches this once between initialize() and setActive().
inline constexpr Steinberg::uint32 kProcessContextRequirements =
    Steinberg::Vst::IProcessContextRequirements::kNeedTempo |
    Steinberg::Vst::IProcessContextRequirements::kNeedTimeSignature |
    Steinberg::Vst::IProcessContextRequirements::kNeedTransportState |
    Steinberg::Vst::IProcessContextRequirements::kNeedProjectTimeMusic |
    Steinberg::Vst::IProcessContextRequirements::kNeedCycleMusic |
    Steinberg::Vst::IProcessContextRequirements::kNeedSystemTime |
    Steinberg::Vst::IProcessContextRequirements::kNeedFrameRate;
 
// The VST3 combined processor + controller
// Wraps a pulp::format::Processor for the VST3 host
//
// Also implements IMidiMapping so MIDI controllers (CCs, mod wheel,
// sustain, channel aftertouch, pitch bend) reach instruments. VST3 has no
// raw MIDI controller events: the host queries getMidiControllerAssignment
// for the ParamID each controller maps to, then delivers them as ordinary
// parameter changes. The adapter reserves a private ParamID range for these
// controllers (see detail/vst3_midi_mapping.hpp) and decodes them back into
// MIDI messages in process().
//
// Implements INoteExpressionController so per-note expression (MPE) reaches
// MPE-aware instruments. VST3 delivers per-note pitch / pressure / timbre as
// Event::kNoteExpressionValueEvent keyed by the originating note-on's noteId.
// The host first queries getNoteExpressionInfo to learn which expression
// types the plug-in accepts; the adapter declares them only when the
// descriptor opts into MPE. process() routes each value event through the
// shared MpeVoiceTracker / MpeBuffer sidecar (the same contract the CLAP
// adapter uses), mapping VST3 tuning -> per-note pitch bend, a volume-domain
// expression -> per-note pressure, and brightness -> per-note timbre (CC74).
class PulpVst3Processor : public Steinberg::Vst::SingleComponentEffect,
                          public Steinberg::Vst::IMidiMapping,
                          public Steinberg::Vst::INoteExpressionController,
                          public Steinberg::Vst::IKeyswitchController {
public:
    PulpVst3Processor(ProcessorFactory factory);
    ~PulpVst3Processor() override;
 
    // FUnknown — expose IMidiMapping alongside the SingleComponentEffect
    // interfaces. Refcounting is inherited from EditControllerEx1 via the
    // base; only queryInterface needs the extra interface.
    Steinberg::tresult PLUGIN_API queryInterface(const Steinberg::TUID iid,
                                                 void** obj) override;
    Steinberg::uint32 PLUGIN_API addRef() override {
        return Steinberg::Vst::SingleComponentEffect::addRef();
    }
    Steinberg::uint32 PLUGIN_API release() override {
        return Steinberg::Vst::SingleComponentEffect::release();
    }
 
    // IPluginBase
    Steinberg::tresult PLUGIN_API initialize(Steinberg::FUnknown* context) override;
    Steinberg::tresult PLUGIN_API terminate() override;
 
    // IMidiMapping — report which ParamID each (bus, channel, controller)
    // maps to. Only populated when the descriptor accepts MIDI input.
    Steinberg::tresult PLUGIN_API getMidiControllerAssignment(
        Steinberg::int32 busIndex, Steinberg::int16 channel,
        Steinberg::Vst::CtrlNumber midiControllerNumber,
        Steinberg::Vst::ParamID& id) override;
 
    // INoteExpressionController — declare the per-note expression types the
    // plug-in accepts and convert between normalized values and strings.
    // getNoteExpressionCount returns 0 (and the info/string methods decline)
    // unless the descriptor opted into MPE, so a non-MPE plug-in advertises
    // no note-expression surface and pays zero per-note cost in process().
    Steinberg::int32 PLUGIN_API getNoteExpressionCount(
        Steinberg::int32 busIndex, Steinberg::int16 channel) override;
    Steinberg::tresult PLUGIN_API getNoteExpressionInfo(
        Steinberg::int32 busIndex, Steinberg::int16 channel,
        Steinberg::int32 noteExpressionIndex,
        Steinberg::Vst::NoteExpressionTypeInfo& info /*out*/) override;
    Steinberg::tresult PLUGIN_API getNoteExpressionStringByValue(
        Steinberg::int32 busIndex, Steinberg::int16 channel,
        Steinberg::Vst::NoteExpressionTypeID id,
        Steinberg::Vst::NoteExpressionValue valueNormalized /*in*/,
        Steinberg::Vst::String128 string /*out*/) override;
    Steinberg::tresult PLUGIN_API getNoteExpressionValueByString(
        Steinberg::int32 busIndex, Steinberg::int16 channel,
        Steinberg::Vst::NoteExpressionTypeID id,
        const Steinberg::Vst::TChar* string /*in*/,
        Steinberg::Vst::NoteExpressionValue& valueNormalized /*out*/) override;
 
    // IKeyswitchController — publishes Processor::note_names() as VST3 key
    // switches, which is the surface a VST3 host uses to label individual keys
    // (a drum instrument's "Kick", a sampler's articulation switches) instead
    // of showing bare pitches. Each name becomes a single-key switch. A plug-in
    // that names no notes reports a count of 0 and the host falls back to
    // pitches, so nothing changes for existing plug-ins.
    Steinberg::int32 PLUGIN_API getKeyswitchCount(
        Steinberg::int32 busIndex, Steinberg::int16 channel) override;
    Steinberg::tresult PLUGIN_API getKeyswitchInfo(
        Steinberg::int32 busIndex, Steinberg::int16 channel,
        Steinberg::int32 keySwitchIndex,
        Steinberg::Vst::KeyswitchInfo& info /*out*/) override;
 
    Steinberg::int32 PLUGIN_API getUnitCount() override;
    Steinberg::tresult PLUGIN_API getUnitInfo(
        Steinberg::int32 unitIndex, Steinberg::Vst::UnitInfo& info) override;
    Steinberg::int32 PLUGIN_API getProgramListCount() override;
    Steinberg::tresult PLUGIN_API getProgramListInfo(
        Steinberg::int32, Steinberg::Vst::ProgramListInfo&) override;
    Steinberg::tresult PLUGIN_API getProgramName(
        Steinberg::Vst::ProgramListID, Steinberg::int32,
        Steinberg::Vst::String128) override;
    Steinberg::tresult PLUGIN_API getProgramInfo(
        Steinberg::Vst::ProgramListID, Steinberg::int32,
        Steinberg::Vst::CString, Steinberg::Vst::String128) override;
    Steinberg::tresult PLUGIN_API hasProgramPitchNames(
        Steinberg::Vst::ProgramListID, Steinberg::int32) override;
    Steinberg::tresult PLUGIN_API getProgramPitchName(
        Steinberg::Vst::ProgramListID, Steinberg::int32, Steinberg::int16,
        Steinberg::Vst::String128) override;
    Steinberg::Vst::UnitID PLUGIN_API getSelectedUnit() override;
    Steinberg::tresult PLUGIN_API selectUnit(Steinberg::Vst::UnitID) override;
    Steinberg::tresult PLUGIN_API getUnitByBus(
        Steinberg::Vst::MediaType, Steinberg::Vst::BusDirection,
        Steinberg::int32, Steinberg::int32,
        Steinberg::Vst::UnitID&) override;
    Steinberg::tresult PLUGIN_API setUnitProgramData(
        Steinberg::int32, Steinberg::int32, Steinberg::IBStream*) override;
 
    // IEditController — parameter value/string conversion. Route through the
    // author-supplied ParamInfo::to_string / from_string so a host's generic
    // editor and text-entry field show and accept the plugin's own formatting
    // (e.g. "-6.0 dB", "1.2 kHz"). Both decline to SingleComponentEffect's
    // stock numeric formatting when the parameter declares no converter, so
    // existing plugins are unchanged.
    Steinberg::tresult PLUGIN_API getParamStringByValue(
        Steinberg::Vst::ParamID tag,
        Steinberg::Vst::ParamValue valueNormalized,
        Steinberg::Vst::String128 string) override;
    Steinberg::tresult PLUGIN_API getParamValueByString(
        Steinberg::Vst::ParamID tag, Steinberg::Vst::TChar* string,
        Steinberg::Vst::ParamValue& valueNormalized) override;
 
    // Keep Pulp-authored parameters in their declared plain StateStore domain
    // when a host asks the VST3 controller to convert values. Unknown IDs,
    // including hidden controller IDs, retain the SDK's normalized fallback.
    Steinberg::Vst::ParamValue PLUGIN_API normalizedParamToPlain(
        Steinberg::Vst::ParamID id, Steinberg::Vst::ParamValue valueNormalized) override;
    Steinberg::Vst::ParamValue PLUGIN_API plainParamToNormalized(
        Steinberg::Vst::ParamID id, Steinberg::Vst::ParamValue plainValue) override;
 
    // IEditController — editor view creation
    Steinberg::IPlugView* PLUGIN_API createView(Steinberg::FIDString name) override;
 
    // IAudioProcessor
    Steinberg::tresult PLUGIN_API setBusArrangements(
        Steinberg::Vst::SpeakerArrangement* inputs, Steinberg::int32 numIns,
        Steinberg::Vst::SpeakerArrangement* outputs, Steinberg::int32 numOuts) override;
 
    Steinberg::tresult PLUGIN_API canProcessSampleSize(
        Steinberg::int32 symbolicSampleSize) override;
 
    Steinberg::tresult PLUGIN_API setupProcessing(
        Steinberg::Vst::ProcessSetup& setup) override;
 
    Steinberg::tresult PLUGIN_API setActive(Steinberg::TBool state) override;
 
    Steinberg::uint32 PLUGIN_API getLatencySamples() override;
    Steinberg::uint32 PLUGIN_API getTailSamples() override;
 
    Steinberg::tresult PLUGIN_API process(
        Steinberg::Vst::ProcessData& data) override;
 
    const state::ParameterEventQueue& last_input_param_events() const {
        return param_events_;
    }
 
    ParamEventsOptOutMonitor& param_events_monitor() {
        return param_events_monitor_;
    }

    state::ParamID bypass_parameter_id() const { return bypass_param_id_; }

    std::uint32_t note_expression_drop_count() const {
        return note_expression_drops_.load(std::memory_order_relaxed);
    }
 
    // IComponent (state)
    // A host parameter write must land in the StateStore synchronously.
    // Without this it only arrives via the process() parameter queue, so a host
    // that writes a parameter and saves before the next audio block serializes
    // a stale value.
    Steinberg::tresult PLUGIN_API setParamNormalized(Steinberg::Vst::ParamID id,
                                                     Steinberg::Vst::ParamValue value) override;
    Steinberg::tresult PLUGIN_API getState(Steinberg::IBStream* state) override;
    Steinberg::tresult PLUGIN_API setState(Steinberg::IBStream* state) override;

    void set_factory_presets_directory(std::filesystem::path dir) {
        factory_presets_dir_ = std::move(dir);
    }
 
    static Steinberg::FUnknown* createInstance(void*);

    void forget_contract_view(ContractPlugView* view);
 
  private:
    // Tell every live contract view that the processor is going away, so each
    // invalidates and destroys its editor while the processor that owns the
    // editor factory, and the store its port reads, are still alive.
    void terminate_contract_views();
    bool contract_host_action(const HostActionRequest& request);
 
    // 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. RAII rather than a
    // hand-balanced attach/detach pair — a leaked attachment silently produces
    // an empty capture. No-op unless PULP_TRACING=ON.
    runtime::ScopedTracingAttachment tracing_;
    ProcessorFactory factory_;
    // 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_;
    std::unique_ptr<ParamGroupProjection> param_groups_;
    Steinberg::Vst::UnitID selected_unit_ = Steinberg::Vst::kRootUnitId;
 
    // Factory presets, published as the VST3 program list. Built once in
    // initialize(); `program_list_active_` is false when the plug-in ships none
    // (or a real parameter already owns the program-change ParamID), in which
    // case the adapter publishes no list and registers no program parameter.
    std::filesystem::path factory_presets_dir_;
    FactoryProgramTable programs_;
    bool program_list_active_ = false;
    // The current program, mirrored from the StateStore parameter that holds
    // the selection. `program_applied_` is false until a program has been
    // applied or a saved selection restored; until then any selection counts.
    // Written by whichever thread delivers the program change, read by both.
    std::atomic<std::int64_t> program_index_{0};
    std::atomic<bool> program_applied_{false};
    bool program_change_needed(std::size_t index) const;
    // Set when the audio thread applied a program: the VST3 parameter objects
    // still hold the old values until the main thread syncs them.
    std::atomic<bool> parameter_objects_stale_{false};
    // Applies program @p index. @p audio_thread selects the write path that
    // never touches the file system, allocates, or calls the host.
    void apply_program(std::size_t index, bool audio_thread, std::int32_t offset);
    // Copies every StateStore value (and the program selection) into the VST3
    // parameter objects the host reads back. Main thread only.
    void sync_parameter_objects_from_store();
    // Keeps a host setState() off the processor while 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_;
    // Contract views the host still holds (not owned: the host releases them).
    std::vector<ContractPlugView*> contract_views_;
 
    // Working buffers
    std::vector<float*> input_ptrs_;
    std::vector<float*> output_ptrs_;
    std::vector<const double*> input64_ptrs_;
    std::vector<double*> output64_ptrs_;
    std::vector<std::vector<float>> f64_input_scratch_;
    std::vector<std::vector<float>> f64_output_scratch_;
    // Second input bus routed to Processor::set_sidechain(). Only input
    // bus 1 is consumed; additional buses are ignored because the
    // Processor API exposes a single sidechain slot. These arrays are sized in
    // setupProcessing() to max(declared, natively accepted) channels so native
    // layout negotiation cannot allocate or truncate on the audio thread. The
    // unsupported-layout silence path retains the declared safe width.
    std::vector<float*> sidechain_ptrs_;
    std::vector<const double*> sidechain64_ptrs_;
    std::vector<std::vector<float>> f64_sidechain_scratch_;
    // Per-bus channel-pointer storage for secondary (aux) output buses,
    // indexed [aux_bus][channel]. aux_output_ptrs_[i] backs the BufferView for
    // the host output bus at index i+1, routed to the Processor's richer
    // process(ProcessBuffers&) surface for multi-out instruments. Each
    // sub-vector is sized in setupProcessing() from the ACCEPTED VST3 bus
    // arrangement (which setBusArrangements() may have shifted mono↔stereo away
    // from the descriptor default), so the routing path reuses this storage,
    // allocates nothing on the audio thread, and never silently drops a channel
    // the host negotiated.
    std::vector<std::vector<float*>> aux_output_ptrs_;
    std::vector<std::vector<double*>> aux_output64_ptrs_;
    // Accepted native channel count per secondary output bus (index i = host
    // output bus i+1), captured in setupProcessing(). The unsupported-layout
    // silence path retains the descriptor-safe width. Reported as the aux
    // ProcessBusBufferView's declared_channels so matches_declared_layout()
    // compares host buffers against the active processing contract.
    std::vector<int> declared_aux_channels_;
    std::vector<std::vector<std::vector<float>>> f64_aux_output_scratch_;
 
    // Per-block MIDI buffers, reused across process() calls. Reserved +
    // realtime-capacity-limited in setupProcessing() so add()/add_sysex_copy()
    // never heap-allocate on the audio thread (they drop past the reserved
    // worst-case instead). Previously these were block-local, so the first
    // add() on any block carrying MIDI allocated.
    midi::MidiBuffer midi_in_;
    midi::MidiBuffer midi_out_;
 
    // Editor -> host parameter reporting. Owns the provenance decision (which
    // writes are the EDITOR's), the single normalized snapshot per edit, and
    // the begin/value/end ordering. Replaces a local "is a gesture open?"
    // inference that host automation could satisfy — see
    // host_parameter_edit.hpp. Held by pointer because it installs store
    // callbacks in its constructor and removes them in its destructor, which
    // must happen at defined points in this object's lifetime.
    std::unique_ptr<HostParameterEditBridge> edit_bridge_;
 
    // Parameter output: snapshot values before process to detect plugin-side changes
    std::vector<float> param_snapshot_;
    state::ParameterEventQueue param_events_;
    // Processor::wants_sample_accurate_parameters(), asked in initialize().
    bool sample_accurate_params_ = false;
    // Records an opted-out processor reading param_events(); see processor.hpp.
    ParamEventsOptOutMonitor param_events_monitor_;
    // A block's automated values, written to the store in one batch after the
    // input queues are read; one slot per parameter, reserved in
    // setupProcessing().
    std::vector<state::StateStore::ParamWrite> param_writes_;
    void queue_param_write(state::ParamID id, float value);
    // Lent to param_events_.sort(); sized in setupProcessing().
    std::vector<state::ParameterEvent> param_sort_scratch_;
    std::vector<std::uint32_t> param_offset_counts_;
    // Sample-accurate parameter OUTPUT: the processor pushes offset-tagged events
    // via push_output_param_event(); we drain them into per-parameter VST3 output
    // queues after process(). All three vectors are sized off the audio thread
    // (at prepare / block start alongside param_snapshot_) so the per-block drain
    // stays allocation-free. 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; output_param_queue_cache_ caches one VST3 queue
    // per parameter index so a param with multiple offsets reuses one queue in
    // ascending-offset order.
    state::ParameterEventQueue output_param_events_;
    std::vector<std::uint8_t> output_param_has_event_;
    std::vector<Steinberg::Vst::IParamValueQueue*> output_param_queue_cache_;
    // StateStore generation param_snapshot_ was taken at. Every store write
    // advances the generation, so while it is unchanged the snapshot still
    // equals the live values and the per-block refresh is skipped; likewise the
    // post-process diff only runs when the generation moved across process().
    // The snapshot is untrusted until the first refresh and after a refresh
    // that overlapped a writer (boundary::refresh_param_snapshot).
    boundary::ParamSnapshotState snapshot_state_;
    std::uint64_t pre_process_generation_ = 0;
 
    // Bus views handed to the Processor, kept as members so a block only
    // writes the entries it routes instead of value-initialising every slot.
    std::array<ProcessBusBufferView<float>, BusBufferSet::kMaxBuses> rt_output_buses_{};
    std::array<ProcessBusBufferView<double>, BusBufferSet::kMaxBuses> rt_output64_buses_{};
    std::array<ProcessBusBufferView<const double>, 2> rt_input64_buses_{};
    // Channel count each declared bus expects, captured when the arrangement
    // is (re)negotiated so process() validates layout without SDK RTTI string
    // compares per block. Index past the cached count falls back to the bus.
    static constexpr std::size_t kCachedBusCount = 32;
    std::array<int, kCachedBusCount> expected_in_channels_{};
    std::array<int, kCachedBusCount> expected_out_channels_{};
    std::size_t cached_in_bus_count_ = 0;
    std::size_t cached_out_bus_count_ = 0;
    std::atomic<bool> bus_channel_cache_valid_{false};
    void refresh_bus_channel_cache();
 
    // Runs the adapter's own per-block path once on silence at activation so
    // the host's first real block does not pay to fault in cold code and
    // buffers. It never runs Processor::process() / process_f64() and publishes
    // nothing to the host; it does hand the Processor the per-block pointers
    // (parameter events, output events, MPE input) that every block sets and
    // the first real block sets again. While set, process() also skips the
    // trigger reset and every store- and host-visible side effect.
    bool warming_render_path_ = false;
    void warm_render_path();
 
    // ── Per-note expression (MPE) sidecar ───────────────────────────────────
    //
    // Mirrors the CLAP adapter's MPE wiring: inbound note events plus the MIDI
    // messages synthesized from note-expression value events run through the
    // sidecar's tracker, whose callbacks append per-note expression deltas to
    // its buffer. The buffer is handed to the Processor via set_mpe_input() for
    // the duration of each process() call. Reserved + capacity-limited in
    // setupProcessing() so the process path never allocates. Only active when
    // the descriptor opts into MPE (mpe_.enabled). See boundary::MpeSidecar.
    boundary::MpeSidecar mpe_;
 
    // noteId -> (channel, note) linkage. VST3 note-expression value events
    // reference the noteId carried by the originating note-on, so the adapter
    // must remember which (channel, note) each live noteId maps to in order to
    // route an expression to the right MPE voice. Fixed-capacity and
    // allocation-free: a note-on with noteId >= 0 claims a slot, the matching
    // note-off releases it. A slot's `active` flag identifies a live mapping.
    struct NoteIdSlot {
        bool active = false;
        Steinberg::int32 note_id = -1;
        uint8_t channel = 0;
        uint8_t note = 0;
    };
    static constexpr std::size_t kMaxLiveNoteIds = 128;
    std::array<NoteIdSlot, kMaxLiveNoteIds> note_id_map_{};
 
    // Saturating drop counter for per-note expression routing failures (full
    // noteId map on insert, or a value event for an unmapped noteId). Atomic so
    // a host thread can read it via note_expression_drop_count() while the audio
    // thread increments it; never the source of an audio-thread log.
    std::atomic<std::uint32_t> note_expression_drops_{0};
 
    // Record / release / look up a noteId -> (channel, note) mapping. All
    // O(kMaxLiveNoteIds), allocation-free, audio-thread safe.
    // note_id_map_insert returns false when the table is full (the mapping was
    // dropped) so the caller can bump the drop counter.
    bool note_id_map_insert(Steinberg::int32 note_id, uint8_t channel,
                            uint8_t note);
    void note_id_map_erase(Steinberg::int32 note_id);
    const NoteIdSlot* note_id_map_find(Steinberg::int32 note_id) const;
    void note_id_map_clear();
 
    // Cached parameter ID of the VST3 bypass parameter. 0 when none is
    // available, so process() never short-circuits.
    state::ParamID bypass_param_id_ = 0;
 
    // True when the descriptor accepts MIDI input, so the adapter has
    // registered the reserved hidden controller parameters and
    // getMidiControllerAssignment / the process()-side controller decode
    // are live. Mirrors the accepts_midi gating on the event input bus.
    bool midi_controller_mapping_active_ = false;
 
    // Membership bitmap over the reserved controller ParamID range, indexed
    // by (id - kVst3MidiCcParamBase). A slot is true only if the adapter
    // ACTUALLY registered that ID as a hidden controller parameter — i.e.
    // the ID did not collide with a real plug-in parameter. Registration,
    // getMidiControllerAssignment, and the process()-side diversion all use
    // this one predicate, so a real plug-in parameter that happens to fall
    // in the reserved range is never reported as a controller assignment and
    // never diverted to MIDI (its host param-changes still reach store_).
    // Sized once at init; the process()-thread lookup is O(1) and never
    // allocates. Empty when MIDI mapping is inactive.
    std::vector<bool> registered_controller_ids_;
 
    // True iff `id` was registered as a hidden controller parameter. O(1),
    // allocation-free — safe to call on the audio thread.
    bool is_registered_controller(state::ParamID id) const;
 
    // ── process() phase helpers ──────────────────────────────────────────────
    // process() runs these phases in a fixed order. Each reads adapter member
    // state (midi_in_, param_events_, output_ptrs_, store_, processor_, …)
    // directly; only per-block locals are threaded explicitly. This is pure
    // code motion — the audio output is bit-identical to the previously
    // monolithic process(). See vst3_adapter.cpp.
 
    // Phase (a): clear the reused param/MIDI buffers, decode host input
    // parameter changes into the StateStore boundary, and divert
    // IMidiMapping-registered controller changes into midi_in_. Sorts
    // param_events_ on exit.
    void process_decode_input_parameters(Steinberg::Vst::ProcessData& data);
 
    // Validate the host block against the currently negotiated component-bus
    // topology. Malformed layouts are zeroed and rejected before any host
    // storage is published to the Processor.
    bool process_validate_layout(Steinberg::Vst::ProcessData& data,
                                 bool host_f64,
                                 int original_num_samples);
 
    // Phase (d, f32 half): wire the host's main input, sidechain, and main
    // output channel pointers (with f64 boundary marshalling) into the reused
    // ptr vectors, pre-zero routed aux output buses, and report the resolved
    // channel counts.
    void process_wire_buffers(Steinberg::Vst::ProcessData& data, bool host_f64,
                              bool native_f64, bool boundary_f64,
                              int num_samples, int original_num_samples,
                              int& in_channels, int& out_channels,
                              int& sc_channels);
 
    // Phase (c): VST3 processBlockBypassed pass-through. Returns true when the
    // bypass parameter is engaged and the block was handled here (the caller
    // returns kResultOk); false when the plugin should process normally.
    bool process_maybe_bypass(Steinberg::Vst::ProcessData& data, bool host_f64,
                              int in_channels, int out_channels,
                              int original_num_samples);
 
    // Phase (b): decode host input events (notes, per-note expression, SysEx)
    // onto midi_in_, then sort the combined controller+note stream.
    void process_decode_input_events(Steinberg::Vst::ProcessData& data);
 
    // Phase (f): drain the processor's sample-accurate output parameter events
    // and the snapshot-diff fallback into the host output parameter queues.
    void process_publish_output_params(
        Steinberg::Vst::ProcessData& data,
        std::span<const state::ParamInfo> all_params);
 
    // Phase (h): OR-accumulate the processor's pending latency/tail restart
    // flags into restart_publisher_ (RT-safe; the host callback fires later on
    // the main thread).
    void process_publish_restart_flags();
 
    // Per-output-channel dry delay used during the bypass pass-through.
    // A plugin that reports latency gets host plugin-delay-compensation on
    // its path, so the bypassed dry signal must be delayed by exactly that
    // many samples to stay sample-aligned with the compensated timeline.
    // Sized once in setupProcessing() (off the audio thread); leaves the
    // zero-copy fast path in place when the reported latency is 0. Shared
    // adapter-boundary component so every format's bypass latency behaves
    // identically (CLAP uses the same class).
    boundary::LatencyCompensatedBypass bypass_;
 
    // Host accommodations, resolved once in initialize() via the runtime
    // policy (env / API / compile default). Adapters consult these flags
    // instead of hardcoding DAW workarounds.
    HostQuirks quirks_{};
 
    // The processor is always prepare()'d with the descriptor-default
    // channel counts (see setupProcessing), so these cache what the
    // processor's buffers are sized for. When setBusArrangements accepts
    // an arrangement the processor does not natively support, process()
    // hands the processor only its prepared channel counts and zero-fills
    // the host's extra channels.
    int native_in_ = 0;
    int native_out_ = 0;
    // Descriptor contract cached during setupProcessing(); process() must not
    // materialize the by-value descriptor on the audio thread.
    bool descriptor_main_mono_ = false;
    bool silence_unsupported_active_ = false;
    bool native_f64_enabled_ = false;
    Steinberg::int32 selected_sample_size_ = Steinberg::Vst::kSample32;
    // setupProcessing() may be followed by setActive(false)/setActive(true)
    // during an offline host render. Keep the prepared contract so activation
    // can restore Processor-owned scratch and DSP state after release().
    PrepareContext prepared_context_{};
    Processor::BusesLayout prepared_layout_{};
    bool has_prepared_context_ = false;
 
    // Block size the processor's scratch buffers were prepared for in
    // setupProcessing() (setup.maxSamplesPerBlock). process() clamps an
    // oversized render to this so a host that exceeds the advertised max
    // can't overrun the prepared buffers. 0 means "no limit set yet".
    int max_block_size_ = 0;
 
    // Previous-block transport snapshot used to derive the
    // `tempo_changed` / `time_sig_changed` / `transport_changed` flags
    // on `ProcessContext`. Default-constructed so the first process()
    // call after construction reports no changes.
    detail::PlayheadSnapshot playhead_prev_{};
 
    // MainThreadDispatcher backend token. Acquired in initialize(),
    // released in terminate(). On macOS this lets adapter-side and
    // view-side code marshal work onto the DAW's main thread via
    // `pulp::events::MainThreadDispatcher::call_async`.
    pulp::events::MainThreadDispatcher::Token main_thread_token_ = 0;
 
    // Marshals IComponentHandler::restartComponent off the audio thread.
    // process() OR-accumulates latency/tail restart flags into this publisher
    // (RT-safe); the actual host callback fires on the main thread via
    // deliver_pending_restart() at a main-thread safe point outside any host
    // call. See vst3_restart_publisher.hpp for the contract.
    detail::Vst3RestartPublisher restart_publisher_;
 
    // Liveness/lifetime token shared with every main-thread lambda this adapter
    // posts to the MainThreadDispatcher. A posted lambda captures this shared_ptr
    // (keeping the flag alive) plus a raw `this`, and checks the flag before
    // touching `this`. terminate() flips it to false, so a callback still queued
    // on the host's main thread when the component is destroyed becomes a no-op
    // instead of dereferencing freed memory. Created in initialize().
    std::shared_ptr<std::atomic<bool>> drain_alive_;
 
    // True between setActive(true) and setActive(false)/terminate(): drives the
    // self-rescheduling paced main-thread poll so a mid-stream latency/tail
    // change is delivered without depending on an incidental host query.
    std::shared_ptr<std::atomic<bool>> poll_active_;
 
    // Deferred delivery of the two host callbacks this adapter owns:
    // restart_publisher_ (componentHandler->restartComponent(flags)) and the
    // Processor's state-dirty flag (IComponentHandler2::setDirty). Neither may
    // be called from process(), and neither may be called from inside a
    // host-initiated call (setActive / getLatencySamples / getTailSamples /
    // getState): hosts invoke those while holding their own processing lock,
    // and a host that services restartComponent synchronously (deactivating
    // and reactivating the component on kReloadComponent, retaking that same
    // non-recursive lock) deadlocks if the plug-in calls back into it
    // re-entrantly.
    //
    // Delivery therefore only happens at a main-thread safe point outside any
    // host call: (a) the paced self-rescheduling poll tick while active, and
    // (b) a coalesced one-shot main-thread post that host entrypoints request
    // via schedule_host_notifications(). The post runs after the host call has
    // returned and released its locks.
    enum class InlineFallback : std::uint8_t {
        // The entrypoint may deliver inline when no main-thread dispatcher can
        // accept a post (Windows / Linux hosts without a registered backend).
        // Only state-free queries allow this; it keeps notifications flowing
        // on those platforms, and a re-entrancy guard still refuses a nested
        // delivery.
        allowed,
        // Never deliver inline, even without a dispatcher: the entrypoint is a
        // host activation transition, where hosts hold their processing lock.
        // The flags stay latched for the next safe delivery point.
        forbidden,
    };
    void schedule_host_notifications(InlineFallback fallback);
    void deliver_pending_restart();
    // Delivers the Processor's state-dirty edge as IComponentHandler2::setDirty.
    // Main-thread only; a host that predates IComponentHandler2, or that does not
    // implement it, simply drops the edge (the flag is still consumed).
    void deliver_pending_dirty();
    // Both of the above, in order. Every main-thread delivery path calls this.
    // Guarded against re-entry: a host that calls back into the plug-in from
    // inside restartComponent/setDirty cannot trigger a nested delivery.
    void deliver_pending_host_notifications();
 
    // True while a one-shot main-thread delivery post is queued, so a burst of
    // host entrypoint calls coalesces into one post. Cleared by the post
    // itself before it delivers. Main-thread only after initialize().
    std::shared_ptr<std::atomic<bool>> deferred_delivery_posted_;
    // True while deliver_pending_host_notifications() is calling into the
    // host. Main-thread only.
    bool delivering_host_notifications_ = false;
 
    // Start / stop the paced main-thread poll loop. start is idempotent; stop
    // relies on poll_active_ going false so the next scheduled tick does not
    // re-post. Both are main-thread only.
    void start_restart_poll();
    void schedule_restart_poll_tick();
 
public:
    // Test-only hook: drive the main-thread restart drain directly. Mirrors
    // what a host-driven main-thread entrypoint does in production. Returns the
    // coalesced flags delivered (0 when nothing was pending).
    std::int32_t poll_pending_restart_for_test() {
        std::int32_t delivered = 0;
        if (parameter_objects_stale_.exchange(false, std::memory_order_acq_rel))
            sync_parameter_objects_from_store();
        auto* handler = getComponentHandler();
        restart_publisher_.poll_main_thread(
            [&](std::int32_t flags) {
                delivered = flags;
                if (handler) handler->restartComponent(flags);
            });
        return delivered;
    }
 
    bool restart_dispatch_armed_for_test() const {
        return restart_publisher_.dispatch_armed();
    }
};
 
} // namespace pulp::format::vst3