daniel/reasampler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Q-W2v: split VST god-modules — editor 8 face-axis TUs (+pure layout hoist), processor 3 TUs, component_state_io codec split (extension drops the voice engine), zone_params.h, core/wire putLE; formats frozen, 61/61 green

Browse Source
This commit is contained in:
Daniel Harvey
2026-07-29 10:56:09 -04:00
parent 9d5783453c
commit ea86f540b8
37 changed files with 6202 additions and 5352 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/shell/instrument/reasampler_processor.h
+517
View File
@@ -0,0 +1,517 @@
// reasampler_processor.h — the VST3 SingleComponentEffect (Phase S4, Tier 0). Wires the
// pure S3 sampler core into a real VSTi: it declares an event-input bus + a stereo audio
// output bus, marshals host MIDI note-on/off into the VoiceEngine, and renders the
// engine's audio into the output bus — so a chosen bank sample plays chromatically from
// its root note in REAPER's routing/record/render path.
//
// SingleComponentEffect is the SDK's combined processor+controller base — sanctioned
// for a non-distributable, REAPER-only plugin under D5/D6. It gives us
// addAudioOutput/addEventInput, IComponent setState/getState for the instance's own
// state (the selected sample), and the IEditController seat so createView() can hand the
// host our IPlugView LICE editor.
//
// SELF-CONTAINED PLAYBACK (pS architecture correction). The instance OWNS its sample: the
// component state persists, per referenced bank sample, the project-relative WAV path +
// decode intrinsics (SampleRefs), and reloadInstrument decodes straight from that table.
// The extension's bank blob is a BROWSER SOURCE that opportunistically refreshes the refs
// when readable — NEVER a runtime requirement for playback. A project restored before the
// extension's PROJEXTSTATE parses (or with the extension absent) plays on load; the old
// reopen-heal timer + poll-to-play machinery that papered over the bank dependency is gone.
//
// REAL-TIME DISCIPLINE (S4 hard constraint). The audio thread (process) does NO
// allocation, NO file I/O, NO bridge calls, NO locks. Sample loading — ref resolve, WAV
// decode, keymap build, VoiceEngine construction — all happens OFF the audio thread
// (reloadInstrument, driven from the main/UI thread) and is handed to process via a
// single atomic pointer swap. See the LoadedInstrument handoff below.
#pragma once
#include <atomic>
#include <cstdint>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
#include "public.sdk/source/vst/vstsinglecomponenteffect.h"
#include "shell/instrument/reaper_bridge.h"
#include "core/instrument/map/sample_map.h" // PerformanceMap (the instrument's owned zoned keymap)
#include "core/instrument/map/component_state_io.h" // ComponentState codec (Q-W2v split)
#include "core/instrument/engine/sampler_core.h"
namespace reasampler::vst {
// Cross-subsystem deps by their real namespace homes (Q-W2v: the core/namespaces.h shim
// is retired from the processor family; the engine family's symbols — Keymap, VoiceEngine,
// ChannelMode, VoiceMode, MonoTrigger, the voice-count constants — still live in flat
// `reasampler` and resolve via the enclosing namespace).
using instrument::map::ComponentState;
using instrument::map::PerformanceMap;
using instrument::map::SampleRefs;
using instrument::map::kPreviewVelocityDefault;
class ReaSamplerEmbed; // S6 embedded TCP/MCP UI shell (owned below; see queryInterface)
// One fully-built, ready-to-play instrument snapshot: the decoded keymap and the voice
// engine that plays it. The engine holds references into the keymap, so the two MUST live
// and die together at a STABLE address — hence this is heap-allocated and neither copyable
// nor movable. The audio thread only ever reads it through an atomic pointer; it is built
// and destroyed off the audio thread.
//
// installedAt: the reloadGeneration_ value at which this instrument was atomically
// installed into live_. Set on the reload path before the exchange. process() publishes
// this field (not a fresh re-read of reloadGeneration_) so the published generation is
// exactly the generation of the instrument actually in hand for the block.
struct LoadedInstrument {
Keymap keymap;
VoiceEngine engine;
std::uint64_t installedAt = 0; // reload generation at which this was installed
// The takeover declick (GA fix, rev 2) is opted IN here — the PRODUCT default: any
// restart of a sounding voice (mono Retrigger takeover/fallback, cross-sample legato
// restart, POLY at-cap steal — the preview note included, now that it is a real pool
// voice) smooths the cut via the difference-seeded ramp instead of clicking. The pure
// core defaults it off (regression baseline) — same layering as kDefaultPitchEngine.
LoadedInstrument(Keymap km, std::size_t maxVoices,
std::uint64_t gen, std::size_t preserveVoiceCap = 0,
std::int64_t preserveWindowFrames = 0,
VoiceMode voiceMode = VoiceMode::Poly,
MonoTrigger monoTrigger = MonoTrigger::Retrigger)
: keymap(std::move(km)),
engine(maxVoices, keymap, preserveVoiceCap, preserveWindowFrames,
voiceMode, monoTrigger, /*takeoverDeclick=*/true),
installedAt(gen) {}
// True when nothing in this snapshot is sounding. process() publishes this for the
// drain slot so the off-thread retirer can park an idle drain in the graveyard early
// (FA1-review Major #2). Bounded scan (<= maxVoices).
bool fullyIdle() const { return engine.activeVoiceCount() == 0; }
LoadedInstrument(const LoadedInstrument&) = delete;
LoadedInstrument& operator=(const LoadedInstrument&) = delete;
};
class ReaSamplerProcessor : public Steinberg::Vst::SingleComponentEffect {
public:
ReaSamplerProcessor() = default;
// Out-of-line so the owned ReaSamplerEmbed (held by unique_ptr, forward-declared here)
// is a complete type at the destruction point (defined in the .cpp).
~ReaSamplerProcessor() override;
// The factory create function (registered in vst_entry.cpp).
static Steinberg::FUnknown* createInstance(void* /*context*/);
//--- from IComponent / IPluginBase -------------------------------------
// Connects the REAPER bridge (context is REAPER's IHostApplication) and declares
// the instrument bus topology.
Steinberg::tresult PLUGIN_API initialize(Steinberg::FUnknown* context) override;
Steinberg::tresult PLUGIN_API terminate() override;
Steinberg::tresult PLUGIN_API setActive(Steinberg::TBool state) override;
// Instance state = the selected bank sample id (D-B: a performance choice the
// instrument owns; NEVER written back to the bank). Component-state, so a saved
// REAPER project restores which sample each instance plays.
Steinberg::tresult PLUGIN_API setState(Steinberg::IBStream* state) override;
Steinberg::tresult PLUGIN_API getState(Steinberg::IBStream* state) override;
//--- from IAudioProcessor ----------------------------------------------
Steinberg::tresult PLUGIN_API setupProcessing(
Steinberg::Vst::ProcessSetup& setup) override;
// Marshals MIDI -> VoiceEngine -> audio output. Real-time safe (no alloc/IO/lock).
Steinberg::tresult PLUGIN_API process(
Steinberg::Vst::ProcessData& data) override;
// Output-bus negotiation. The instrument has ONE canonical output arrangement: a FIXED
// stereo bus (GA fix — the channel mode is a decode policy, never a bus fact; mono mode
// renders dual-mono through it). We accept the host's proposal only when it is a single
// stereo output; otherwise we reject (kResultFalse) but keep our stereo arrangement, so
// getBusArrangement / getBusInfo always report 2 channels and the host routes accordingly.
Steinberg::tresult PLUGIN_API setBusArrangements(
Steinberg::Vst::SpeakerArrangement* inputs, Steinberg::int32 numIns,
Steinberg::Vst::SpeakerArrangement* outputs, Steinberg::int32 numOuts) override;
//--- from IEditController -----------------------------------------------
// Hands the host our LICE IPlugView editor.
Steinberg::IPlugView* PLUGIN_API createView(Steinberg::FIDString name) override;
// Override queryInterface to additionally expose REAPER's IReaperUIEmbedInterface (S6):
// REAPER queries the IEditController for it to drive the inline TCP/MCP embed surface.
// All other iids delegate to SingleComponentEffect's implementation unchanged.
Steinberg::tresult PLUGIN_API queryInterface(const Steinberg::TUID iid,
void** obj) override;
// The embedded-strip activity level (0..1), read by the S6 embed shell on the UI thread.
// Backed by embedPeak_, the per-block mono peak the audio thread stores relaxed — a
// lock-free advisory readout, never touched with a lock the audio thread could contend.
double embedActivityLevel() const {
return static_cast<double>(embedPeak_.load(std::memory_order_relaxed));
}
// Called by the editor (main/UI thread) when the user picks a sample, and internally
// on load. SELF-CONTAINED (pS): resolves the selection/zones against the instance-OWNED
// SampleRefs table, decodes each WAV OFF the audio thread, and publishes the built
// instrument to process() via an atomic swap — NO bank read is required for playback.
// When the live bank blob IS readable it is first folded into the refs table
// (refreshRefsFromBank), which is both the browser's copy-the-ref-in mechanism and the
// S9 live-recapture sync. A missing/unreadable WAV is the defined no-play (silence, no
// retry). Returns the resolved selection id ("" if nothing was loaded) for the editor.
std::string reloadInstrument();
// The result of a bank-sync poll (S9/S8): what pollBankSync did this tick, so the editor
// can react (repaint / re-snapshot its own view) only when something actually changed.
struct BankSyncResult {
// The bank generation changed (or a pre-v10 legacy lift landed an instrument) ->
// reloadInstrument ran and the editor should re-snapshot its bank view.
bool reloaded = false;
bool applied = false; // a new assignment request was applied -> selection changed
};
// Poll the S9 bank-generation counter and the S8 assignment request over the bridge, OFF
// THE AUDIO THREAD (the editor's UI timer drives this — NEVER process()). This is an
// EDITOR/BROWSER sync path — playback never depends on it (pS). Semantics:
// * S9: if the bank generation differs from what we last saw, call reloadInstrument() so
// a recapture/ingest refreshes playback hands-free (atomic swap, glitch-free).
// * S8: if a NEW (generation > last consumed) assignment request names a resolvable
// sample AND this instance is the target (isFocusedTarget), apply it as the selection
// and reload; an unresolvable request is DROPPED silently (marker advanced, no change);
// a non-target instance neither applies nor advances its marker.
// * LEGACY LIFT: a pre-v10 blob restored with intent but no refs retries the (cheap)
// bank read until the blob is parseable, then reloads ONCE to copy the refs in.
// TERMINATING: once the blob parses and NO referenced id resolves, the ids are
// provably stale — the lift concludes permanently (legacyLiftShouldRun) instead of
// churning a full bank read + reload every tick forever.
// The consumed marker advances in component state (marked dirty via the host handler) so a
// re-open does not re-apply. `isFocusedTarget` is the shell's thundering-herd policy input
// (the editor passes true only for the instance whose editor is open — see the handoff).
// Idempotent on an idle tick (generation unchanged + no new request -> no work).
BankSyncResult pollBankSync(bool isFocusedTarget);
// The bridge, for the editor's live-state readout + sample list. Owned here; the
// editor borrows it (outlives the editor).
ReaperBridge& bridge() { return bridge_; }
// The live host sample rate latched from setupProcessing (the SAME rate reloadInstrument
// resolves seconds->frames against). The editor's S-VIEW-3 envelope overlay reads it to place
// its wall-clock seconds on the same time base the voice engine plays them over. 0.0 before
// setupProcessing runs (the editor guards). Read on the UI thread; a plain load — sampleRate_
// is set once by setupProcessing before any audio and does not change under the editor.
double sampleRate() const { return sampleRate_; }
// The current single-capture selection id (main/UI thread reads for the editor). Guarded
// by selectionMutex_ — never touched on the audio thread. Since S10 this is the ONE picked
// capture the default face plays chromatically when the performance map is empty; an EMPTY
// id resolves to SILENCE (no first-sample fallback). A non-empty zoned map supersedes it.
std::string selectedSampleId();
void setSelectedSampleId(const std::string& id);
// The performance map (Tier 1: the zoned keymap the instrument owns; D-B). Read/written
// by the editor on the UI thread; snapshotted under performanceMutex_. NEVER read on the
// audio thread — reloadInstrument bakes it into the LoadedInstrument's Keymap off-thread.
PerformanceMap performanceMap();
void setPerformanceMap(const PerformanceMap& map);
// The per-instance channel mode (S7, D-E: mono | stereo). Read/written on the UI thread
// (the editor toggle) and read off-thread by getState/reloadInstrument; guarded by
// channelModeMutex_. NEVER read on the audio thread — process() renders against the host's
// negotiated output channel count, and reloadInstrument bakes the mode into the decode.
// GA fix: the mode is a DECODE policy only (downmix vs L/R split). The output bus is a
// FIXED stereo bus — mono mode renders dual-mono through it (centered) — so a mode change
// never renegotiates host I/O (the mono<->stereo bus flip's live pin remap was the
// hard-right-pan defect).
ChannelMode channelMode();
// Sets the mode from the EDITOR TOGGLE (a deliberate user choice): latches the mode
// EXPLICIT (the GA auto-default stops fighting it), and on a CHANGE reloads the instrument
// so the next block decodes the new channel count. UI thread only.
void setChannelMode(ChannelMode mode);
// The per-instance preview-trigger velocity (S-VIEW-4, MIDI 1..127). Read/written on the
// UI thread (the Sample-view velocity knob) and by getState/setState (host load-save thread);
// guarded by previewMutex_. Persisted in component state (v6). NOT read on the audio thread.
std::uint8_t previewVelocity();
void setPreviewVelocity(std::uint8_t velocity);
// --- Phase S voice-system parameters (per-instance, persisted in component state v7) ---
// Read/written on the UI thread (the editor's voice deck) and by getState/setState; guarded
// by voiceParamsMutex_. NOT read on the audio thread — each setter rebuilds the VoiceEngine
// OFF-thread via rebuildVoiceEngine (a LIGHT rebuild around the already-decoded keymap; no
// bridge read, no WAV re-decode) published through the same tail-preserving drain-slot swap,
// so changing polyphony / mode / the retrigger toggle never cuts a ringing tail.
int voiceCount();
void setVoiceCount(int count); // clamped to kMinVoiceCount..kMaxVoiceCount
VoiceMode voiceMode();
void setVoiceMode(VoiceMode mode);
MonoTrigger monoTrigger();
void setMonoTrigger(MonoTrigger trigger);
// --- FB1 post-mixer master gain (per-instance, persisted in component state v8) ---------
// LINEAR gain in [0, masterGainMaxLinear()] (0.0 = -inf/true silence, 1.0 = unity, cap =
// +24 dB; the pure master_gain module owns the dB knob taper). Held in an atomic so the
// audio thread applies it with ONE relaxed load per block as a post-sum multiply over the
// rendered output (engine + drain + preview) — no lock, no rebuild, no per-voice cost.
// Written by the editor's Gain knob (UI thread) and setState; read by getState + process().
double masterGainLinear() const {
return static_cast<double>(masterGain_.load(std::memory_order_relaxed));
}
void setMasterGainLinear(double linear); // clamped to [0, masterGainMaxLinear()]
// Fire a one-shot PREVIEW note-on / note-off through the live instrument's MAIN
// VoiceEngine — the SAME noteOn/noteOff calls host MIDI takes, so a preview is a REAL
// voice: it counts against the voice count, can steal / be stolen, and respects
// Poly/Mono + Retrigger/Legato (deliberate reversal of the retired PreviewCard's
// isolation — preview must obey voicing). The editor posts the loaded capture's /
// selected zone's ROOT note (plays at unity); previewNoteOn plays it at the current
// previewVelocity() (the velocity curve applies); previewNoteOff releases it (Gate) —
// Trigger zones ignore note-off and play through. OFF the audio thread (the editor's
// preview-trigger button, UI thread); the request is handed to process() via a
// lock-free single-slot mailbox drained at block start — no allocation, no lock on the
// audio thread. A momentary button (down = on, up = off) reads as a natural key press.
// This is PLAYBACK ONLY: it never captures, never inserts a timeline item.
void previewNoteOn(int note);
void previewNoteOff(int note);
// The instance-owned sample refs (pS self-contained playback): a snapshot copy for the
// editor (waveform/loop-intrinsic fallback when the bank blob is not readable). UI
// thread; guarded by refsMutex_.
SampleRefs sampleRefs();
private:
// Phase S drain retirement (FA1-review Major #2): if process() has published that the
// CURRENT drain instrument is fully idle (every engine voice silent),
// move it out of the drain slot into the graveyard and prune — so an edited-away snapshot
// stops costing resident memory as soon as its tails die, instead of squatting in the slot
// until the NEXT reload. Off the audio thread only (takes reloadMutex_); driven from
// pollBankSync's UI-timer tick (the same cadence that drives reloads — an idle drain with
// no editor open simply waits for the next reload/deactivate, exactly the pre-fix bound).
// Safe against a racing process(): idleness is monotone (the drain receives no note-ons)
// and the published value names the drain's OWN installedAt, so a stale publication about
// an OLDER drain can never retire a newer one; the graveyard prune's monotone-generation
// proof (see below) covers the free.
void retireIdleDrain();
// Phase S voice-param LIGHT rebuild (voice-review Major #3): rebuild the engine
// around a COPY of the LIVE instrument's already-decoded Keymap — no bridge read, no
// filesystem, no WAV re-decode — and publish through the same tail-preserving drain-slot
// swap as a full reload. A polyphony/mode/trigger change touches no audio data, so the
// full reloadInstrument (which re-decodes every zone WAV from disk on the UI thread) was
// pure waste — a visible UI stall on a many-zone instrument. Copying the keymap is safe:
// it is immutable after construction and, under reloadMutex_, the live instrument can
// neither be swapped nor freed while we read it. When nothing is loaded this is a no-op —
// the new params bake into the next real reload. Off the audio thread only.
void rebuildVoiceEngine();
// The pre-v10 LEGACY LIFT gate (#A): true when a lift attempt this tick could make
// progress. Latches legacyLiftConcluded_ on a Stale proof (see the member below); the
// pure decision itself is sample_map's legacyLiftDecision. Off the audio thread only
// (bridge read + bank parse).
bool legacyLiftShouldRun();
// Publish `built` (null = install silence) into live_: prune the graveyard by the last
// process()-published generation, swap `built` into live_, displace the previous live into
// the drain slot, and park the drain-evicted instrument in the graveyard. REQUIRES
// reloadMutex_ held — factored out so reloadInstrument and rebuildVoiceEngine share the ONE
// safety-critical swap dance (see the handoff proof below).
void publishBuiltLocked(std::unique_ptr<LoadedInstrument> built);
// pS-usage: publish this instance's held captures to its per-instance ext-state key
// ("rsusage_<instanceGuid>") so the extension's prune counts them as referenced — a
// capture a live instance holds can never be pruned. Called at the end of every
// reloadInstrument (the ONE choke point every play-set change funnels through:
// selection change, zone edits, assignment consume, bank refresh, setState load), so
// publishing is EAGER and needs no timer — a closed-editor instance's record is
// already in ext-state from its last change/load. OFF THE AUDIO THREAD only (bridge
// calls). Mints instanceGuid_ on first need; RE-mints when planUsagePublish detects
// this state was cloned onto another track (FX copy / track duplication). Idempotent
// on an unchanged play-set (skipWrite). `refs`/`ids` are reloadInstrument's own
// snapshot — the refs table and the id set the instance currently plays.
void publishUsage(const SampleRefs& refs, const std::vector<std::string>& ids);
ReaperBridge bridge_;
// --- The audio-thread handoff (S4 real-time discipline, FA1 drain slot) --
// process() atomically loads `live_` AND `draining_` at block start and marshals/renders
// against them — two atomic acquires, no lock, no free on the audio thread.
//
// reloadInstrument() (off-thread, serialized by reloadMutex_) builds a new
// LoadedInstrument and atomically swaps it into `live_`. The DISPLACED instrument is
// NOT freed and NOT silenced: it moves into `draining_`, where process() keeps
// rendering its already-sounding voices (and routes note-offs to it) so a reload —
// a curve/param edit, a bank-generation refresh, an applied assignment — never cuts a
// ringing note (FA1, bug 3b). New note-ons go ONLY to the live instrument, so the next
// trigger plays the new state. The instrument evicted FROM the drain slot (two reloads
// old) is parked in `graveyard_` for reclaim — a rapid second reload hard-cuts only the
// oldest edit's tails (bounded compromise, documented).
//
// Bounded reclaim: process() publishes the MINIMUM installedAt over the (non-null)
// pointers it holds this block via processGeneration_ — a single atomic store, RT-safe.
// The reload path frees graveyard entries whose installedAt < seen (the last published
// value).
//
// Safety argument: both slots are monotone in installedAt over time (live_ receives
// successively newer builds; draining_ receives successively newer displaced lives), so
// the published minimum is monotone across blocks, and any future process() load yields
// installedAt >= seen. An entry only reaches the graveyard by leaving BOTH slots
// (single-writer under reloadMutex_), so a graveyard entry with installedAt < seen can
// never again be loaded and is not currently held — freeing it is safe. process()
// publishes BEFORE rendering, so the pointers it renders with are covered by the value
// the pruner reads (a stale lower read is merely conservative).
//
// The graveyard's upper bound is the number of reloads since process last ran
// (typically 0–1 in normal use). Remaining entries drain at setActive(false) /
// terminate(), when the host guarantees process is stopped.
std::atomic<LoadedInstrument*> live_{nullptr};
std::atomic<LoadedInstrument*> draining_{nullptr}; // displaced instrument still rendering its tails
std::atomic<std::uint64_t> reloadGeneration_{0}; // incremented by each reload (off-thread, under reloadMutex_; read atomically by process)
std::atomic<std::uint64_t> processGeneration_{0}; // min installedAt held by process (written on audio thread, read off-thread)
// Phase S: the installedAt of the drain instrument process() last observed FULLY IDLE
// (every engine voice silent; 0 = none / the current drain still sounds). Written relaxed on the audio thread each
// block; read by retireIdleDrain() off-thread. Naming the generation (not a bool) closes
// the swap race: a publication about an old drain can never retire its successor.
std::atomic<std::uint64_t> drainIdleGeneration_{0};
std::vector<std::unique_ptr<LoadedInstrument>> graveyard_; // drained on reclaim + setActive(false) + terminate
std::mutex reloadMutex_; // serializes off-thread reloads + graveyard access
// The single-capture selection id (S10: the ONE picked capture; "" = no pick -> silence).
// Off-thread only; a small mutex guards the string against a getState/editor race. NOT
// read on the audio thread.
std::mutex selectionMutex_;
std::string selectedSampleId_;
// The performance map (Tier 1: the instrument's owned zoned keymap). Off-thread only;
// guarded against a getState/editor race. NOT read on the audio thread — reloadInstrument
// bakes it into the LoadedInstrument's Keymap under the reload lock.
std::mutex performanceMutex_;
PerformanceMap performanceMap_;
// The instance-OWNED sample refs (pS self-contained playback): the path + intrinsics
// per referenced bank sample that setState restores, reloadInstrument resolves/decodes
// from, and getState persists (v10). Refreshed opportunistically from the bank blob
// when it is readable; NEVER a bank dependency for playback. Off-thread only (UI +
// load/save + reload); guarded against a getState/reload race. NOT read on the audio
// thread.
std::mutex refsMutex_;
SampleRefs sampleRefs_;
// pS-usage publish identity + lifetime nonce (see publishUsage). instanceGuid_ is
// the persisted per-instance identity (ComponentState v11; empty until first
// publish); usageNonce_ is THIS incarnation's per-LIFETIME owner nonce, carried
// INSIDE the published wire (UsageRecord.ownerNonce) — planUsagePublish's exact
// ownership discriminator between "my own write" (clean replace) and "a foreign
// writer" (union / re-mint). NEVER persisted: a persisted nonce would clone with
// the state on FX copy, and two same-track copies converging on byte-identical
// wires is exactly the ambiguity the nonce exists to break (a wire-equality
// discriminator let sibling A clean-replace over sibling B's still-held paths —
// the delete direction). Minted lazily on first publish; cleared on setState (a
// restored blob is a new lifetime). Guarded by usageMutex_ (publish runs under
// reloadMutex_ but getState/setState do not).
std::mutex usageMutex_;
std::string instanceGuid_;
std::string usageNonce_;
// The per-instance channel mode (S7). Off-thread only (UI + getState + reloadInstrument);
// guarded against a getState/editor race. Default Mono preserves pre-S7 behavior. NOT read
// on the audio thread — process renders against the host's negotiated output channel count.
// channelModeExplicit_ (GA, persisted v9): false = the mode is an un-touched default that
// reloadInstrument may auto-default from the loaded capture's channel count; true = the user
// deliberately toggled the mode (setChannelMode latches it) and it is never fought.
std::mutex channelModeMutex_;
ChannelMode channelMode_ = ChannelMode::Mono;
bool channelModeExplicit_ = false;
// The last assignment-request generation this instance CONSUMED (S8 reader). Persisted in
// component state (v5) so a re-open does not re-apply a request the user already got and
// then changed away from. Written by pollBankSync (UI/timer thread) and getState; read by
// pollBankSync + getState; seeded by setState. Guarded against a getState/poll race. NEVER
// read on the audio thread. Default 0 -> a genuinely new first assign (gen >= 1) applies.
std::mutex assignMarkerMutex_;
std::int64_t lastConsumedAssignGeneration_ = 0;
// The bank generation this instance last SAW (S9 reader). UI/timer-thread only (pollBankSync
// is the sole reader/writer) — no mutex needed, and it is NOT persisted. Initialized to a
// -1 SENTINEL (no real generation can be negative — parseBankGeneration yields >= 0) so the
// FIRST poll after an editor open BASELINES the seen value without a redundant reload
// (setState already loaded the instrument from the OWNED refs); a subsequent generation
// CHANGE then drives the reload. Since pS there is NO reopen-heal here: playback never
// depends on this poll — a v10 blob plays from its own refs at setState time. Besides a
// generation change, pollBankSync reloads only for an APPLIED S8 assignment and for the
// pre-v10 LEGACY LIFT. NOT read on the audio thread.
std::int64_t lastSeenBankGeneration_ = -1;
// The pre-v10 LEGACY LIFT's terminating latch (#A): set once legacyLiftShouldRun proves
// the referenced ids STALE against a readable bank blob (LegacyLiftDecision::Stale) —
// there is nothing to lift, so the lift stops re-firing (the steady state is one relaxed
// load per tick, no bank read). Reset by setState (a new blob = new facts). NOT consulted
// by the genChanged/applied reload paths, so a later bank change that re-introduces an id
// (e.g. an extension-side undo) still refreshes the refs — the latch only gates the lift.
// Atomic: written on the UI-timer thread (pollBankSync) and the host load thread (setState).
std::atomic<bool> legacyLiftConcluded_{false};
// S-VIEW-4 preview-trigger velocity (MIDI 1..127). Persisted in component state (v6) so the
// user's chosen strike velocity survives a project save/reload. Since Wave 2 the Sample-view
// velocity knob writes it on the UI thread, so it is guarded by previewMutex_; setState and
// getState (load/save thread) share the same guard. Default kPreviewVelocityDefault (64). NOT
// read on the audio thread.
std::mutex previewMutex_;
std::uint8_t previewVelocity_ = kPreviewVelocityDefault;
// Phase S voice-system parameters (per-instance, persisted in component state v7). Off-thread
// only (UI voice deck + getState/setState + reloadInstrument); guarded against a getState/editor
// race. Defaults {16, Poly, Retrigger} reproduce pre-Phase-S behavior. NOT read on the audio
// thread — reloadInstrument bakes them into the LoadedInstrument's engine off-thread.
std::mutex voiceParamsMutex_;
int voiceCount_ = kDefaultVoiceCount;
VoiceMode voiceMode_ = VoiceMode::Poly;
MonoTrigger monoTrigger_ = MonoTrigger::Retrigger;
// FB1 post-mixer master gain (LINEAR; persisted in component state v8). A lock-free
// atomic — the target the UI thread writes; the audio thread ramps gainCurrent_ toward
// it per-sample each block (linear interpolation, ~20 ms wall-clock at every host rate)
// so sudden knob moves produce no zipper noise and the true-zero bottom causes no click.
std::atomic<float> masterGain_{1.0f};
// The audio-thread running gain value: tracks masterGain_ across blocks, stepping at
// most gainRampStep_ per sample toward the target. Starts at unity (pre-FB1 default).
// Written and read exclusively on the audio thread — no atomics needed.
float gainCurrent_ = 1.0f;
// T3-01: the per-sample ramp step, derived from kGainRampSeconds (20 ms wall-clock)
// against the live host rate in setupProcessing — never a baked-in rate. The default is
// the 48 kHz value so behavior before the first setupProcessing is unchanged. Written in
// setupProcessing (host-serialized against process), read on the audio thread.
float gainRampStep_ = 1.0f / 960.0f;
// --- S-VIEW-4 preview-trigger mailbox (off-thread -> audio thread, lock-free) ---------
// The editor's preview-trigger button posts a note-on/off request from the UI thread; process()
// drains it at block start and drives the live instrument's MAIN VoiceEngine — the same
// noteOn/noteOff host MIDI takes, so the preview obeys voicing. ONE slot per direction, each a packed
// request whose high bits are a monotonically-incrementing sequence so process() detects a NEW
// request by comparing against the last sequence it consumed (never re-firing a stale one). The
// low 8 bits carry the note (on) / note (off); the on request also carries the velocity in the
// next 8 bits, latched at post time so the audio thread reads no shared velocity field. A single
// relaxed atomic load per block on the audio thread — RT-safe (no alloc, no lock).
// packed = (seq << 16) | (velocity << 8) | note [note-on]
// packed = (seq << 16) | note [note-off]
std::atomic<std::uint32_t> previewOnRequest_{0}; // 0 = no request posted yet
std::atomic<std::uint32_t> previewOffRequest_{0};
std::uint16_t previewOnSeq_ = 0; // UI-thread post counter (never 0 after first post)
std::uint16_t previewOffSeq_ = 0;
std::uint16_t previewOnConsumed_ = 0; // audio-thread: last on-seq fired
std::uint16_t previewOffConsumed_ = 0; // audio-thread: last off-seq fired
// Latched from setupProcessing so setActive/reload can size against it. Read
// off-thread only. 0.0 is explicitly invalid — setupProcessing sets the real host rate
// before any audio, and reloadInstrument guards on it before use.
double sampleRate_ = 0.0;
Steinberg::int32 maxBlockSize_ = 4096;
// --- S6 embedded TCP/MCP UI ---------------------------------------------
// The embed shell (IReaperUIEmbedInterface), created lazily on the first queryInterface
// and owned here for the processor's lifetime. REAPER borrows AddRef'd references from
// queryInterface; the shell's refcount is a no-op because THIS unique_ptr governs its
// destruction (the processor always outlives the borrowed references).
std::unique_ptr<ReaSamplerEmbed> embed_;
// The per-block mono peak (0..1+) the audio thread stores relaxed; the embed strip's
// level indicator reads it via embedActivityLevel(). Advisory only — a plain atomic,
// no ordering coupling, never guarded by a lock the audio thread touches.
std::atomic<float> embedPeak_{0.f};
};
} // namespace reasampler::vst