adapter_boundary.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/format/processor.hpp>
#include <pulp/format/detail/playhead_diff.hpp>
#include <pulp/signal/delay_line.hpp>
#include <pulp/state/parameter_event_queue.hpp>
#include <pulp/state/store.hpp>
 
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <span>
#include <vector>
 
namespace pulp::format::boundary {

inline constexpr std::size_t kBoundaryMaxChannels = 8;
 
// ---------------------------------------------------------------------------
// 1. f64 (double) marshalling
//
// Raw-pointer block copies for the double-precision host boundary. A host that
// runs the graph in `double` hands the adapter `double*` buffers; the shared
// `Processor` renders in `float`, so the adapter converts in and out. These are
// the exact loops that were duplicated in three TUs. `count` is the per-block
// frame count; all three are branch-light and vectorise.
// ---------------------------------------------------------------------------

inline void copy_f32_to_f64(const float* src, double* dst,
                            std::uint32_t count) noexcept {
    if (!src || !dst) return;
    for (std::uint32_t i = 0; i < count; ++i)
        dst[i] = static_cast<double>(src[i]);
}

inline void copy_f64_to_f32(const double* src, float* dst,
                            std::uint32_t count) noexcept {
    if (!src || !dst) return;
    for (std::uint32_t i = 0; i < count; ++i)
        dst[i] = static_cast<float>(src[i]);
}

inline void zero_f64(double* dst, std::uint32_t count) noexcept {
    if (!dst) return;
    for (std::uint32_t i = 0; i < count; ++i) dst[i] = 0.0;
}
 
// ---------------------------------------------------------------------------
// 2. transport → ProcessContext
// ---------------------------------------------------------------------------

struct HostTransport {
    TransportValidity validity{};
 
    bool is_playing = false;
    bool is_recording = false;
    bool is_looping = false;
 
    double tempo_bpm = 120.0;
 
    double position_beats = 0.0;  
 
    std::int64_t position_samples = 0;
 
    int time_sig_numerator = 4;
    int time_sig_denominator = 4;
 
    double loop_start_beats = 0.0;  
    double loop_end_beats = 0.0;

    std::int64_t host_bar = 0;
 
    std::int64_t host_time_ns = 0;
    FrameRate frame_rate = FrameRate::unknown;
};

inline void apply_host_transport(ProcessContext& ctx, const HostTransport& transport,
                                 detail::PlayheadSnapshot& snapshot) noexcept {
    ctx.transport_validity = transport.validity;
    if (transport.validity.has(TransportField::Playing))
        ctx.is_playing = transport.is_playing;
    if (transport.validity.has(TransportField::Recording))
        ctx.is_recording = transport.is_recording;
    if (transport.validity.has(TransportField::Looping))
        ctx.is_looping = transport.is_looping;
    if (transport.validity.has(TransportField::Tempo))
        ctx.tempo_bpm = transport.tempo_bpm;
    if (transport.validity.has(TransportField::BeatPosition))
        ctx.position_beats = transport.position_beats;
    if (transport.validity.has(TransportField::SamplePosition))
        ctx.position_samples = transport.position_samples;
    if (transport.validity.has(TransportField::TimeSignature)) {
        ctx.time_sig_numerator = transport.time_sig_numerator;
        ctx.time_sig_denominator = transport.time_sig_denominator;
    }
    if (transport.validity.has(TransportField::LoopRange)) {
        ctx.loop_start_beats = transport.loop_start_beats;
        ctx.loop_end_beats = transport.loop_end_beats;
    }
    if (transport.validity.has(TransportField::HostTime))
        ctx.host_time_ns = transport.host_time_ns;
    if (transport.validity.has(TransportField::FrameRate))
        ctx.frame_rate = transport.frame_rate;
    if (transport.validity.has(TransportField::Bar)) {
        ctx.bar = transport.host_bar;
    } else if (transport.validity.has(TransportField::BeatPosition) &&
               transport.validity.has(TransportField::TimeSignature) &&
               std::isfinite(ctx.position_beats) &&
               ctx.time_sig_numerator > 0 && ctx.time_sig_denominator > 0) {
        detail::derive_bar_from_beats(ctx);
        ctx.transport_validity.set(TransportField::Bar);
    }
    detail::compute_playhead_changes(
        ctx, snapshot, detail::TransportDiffMode::FieldValidity);
}
 
// ---------------------------------------------------------------------------
// 3. latency-compensated bypass
// ---------------------------------------------------------------------------

template <std::size_t MaxChannels = kBoundaryMaxChannels>
class LatencyCompensatedBypassT {
public:
    void prepare(int latency_samples) {
        delay_samples_ = latency_samples > 0 ? latency_samples : 0;
        if (delay_samples_ > 0) {
            for (auto& line : lines_) line.prepare(delay_samples_);
        }
    }

    void reset() {
        for (auto& line : lines_) line.reset();
    }

    bool is_latency_compensated() const noexcept { return delay_samples_ > 0; }

    int delay_samples() const noexcept { return delay_samples_; }

    static constexpr std::size_t channel_capacity() noexcept { return MaxChannels; }

    float process_sample(float in, std::size_t ch) {
        if (delay_samples_ <= 0 || ch >= lines_.size()) return in;
        return lines_[ch].process(in, static_cast<float>(delay_samples_));
    }

    void process_channel(float* out, const float* in, std::uint32_t count,
                         std::size_t ch) {
        if (!out) return;
        if (delay_samples_ <= 0 || ch >= lines_.size()) {
            // Uncompensated: straight dry passthrough (or silence with no input).
            if (in) {
                if (out != in) std::memcpy(out, in, sizeof(float) * count);
            } else {
                std::memset(out, 0, sizeof(float) * count);
            }
            return;
        }
        auto& line = lines_[ch];
        const float delay = static_cast<float>(delay_samples_);
        if (in) {
            for (std::uint32_t i = 0; i < count; ++i)
                out[i] = line.process(in[i], delay);
        } else {
            for (std::uint32_t i = 0; i < count; ++i)
                out[i] = line.process(0.0f, delay);
        }
    }
 
private:
    std::array<signal::DelayLine, MaxChannels> lines_{};
    int delay_samples_ = 0;
};
 
using LatencyCompensatedBypass = LatencyCompensatedBypassT<kBoundaryMaxChannels>;

template <std::size_t MaxChannels>
inline void render_bypass_passthrough(
    LatencyCompensatedBypassT<MaxChannels>& bypass,
    float* const* out_ptrs, int out_channels,
    const float* const* in_ptrs, int in_channels,
    std::uint32_t count) {
    const bool delayed = bypass.is_latency_compensated() &&
        out_channels <= static_cast<int>(bypass.channel_capacity());
    for (int ch = 0; ch < out_channels; ++ch) {
        float* dst = out_ptrs ? out_ptrs[ch] : nullptr;
        if (dst == nullptr) continue;
        const float* src =
            (in_ptrs && ch < in_channels) ? in_ptrs[ch] : nullptr;
        if (delayed) {
            // process_channel emits `src[n - latency]`, or delayed silence when
            // src is null — every channel takes the same delayed path.
            bypass.process_channel(dst, src, count,
                                   static_cast<std::size_t>(ch));
        } else if (src != nullptr) {
            std::memcpy(dst, src, sizeof(float) * count);
        } else {
            std::memset(dst, 0, sizeof(float) * count);
        }
    }
}
 
// ---------------------------------------------------------------------------
// 4. parameter dual-write
// ---------------------------------------------------------------------------

inline bool apply_param_value(state::ParameterEventQueue& queue,
                              state::StateStore& store,
                              state::ParamID id,
                              std::int32_t sample_offset,
                              float value) {
    const bool queued = queue.push(state::ParameterEvent{id, sample_offset, value});
    store.set_value_rt(id, value);
    return queued;
}
 
// ---------------------------------------------------------------------------
// 5. output-parameter publication
//
// The mirror of (4): values the *plugin* changed during process() have to reach
// the host so it can record automation. The host-ABI emit differs per format
// (VST3 `IParamValueQueue::addPoint`, CLAP `out_events->try_push`), but the
// bookkeeping around it does not: snapshot every parameter before process(),
// diff after, and skip any parameter that already reported sample-accurate
// explicit events. These are the pieces of that bookkeeping which carry no
// format currency. Consumed by `clap_adapter.cpp` and `vst3_adapter.cpp`.
// ---------------------------------------------------------------------------

inline constexpr std::size_t kParamIndexNotFound = static_cast<std::size_t>(-1);

inline std::size_t find_param_index(std::span<const state::ParamInfo> all_params,
                                    state::ParamID id) noexcept {
    for (std::size_t i = 0; i < all_params.size(); ++i) {
        if (all_params[i].id == id) return i;
    }
    return kParamIndexNotFound;
}

inline void snapshot_param_values(const state::StateStore& store,
                                  std::span<const state::ParamInfo> all_params,
                                  std::vector<float>& snapshot) {
    snapshot.resize(all_params.size());
    for (std::size_t i = 0; i < all_params.size(); ++i) {
        snapshot[i] = store.get_value(all_params[i].id);
    }
}

struct ParamSnapshotState {
    std::uint64_t generation = 0;
    bool valid = false;
};

template <typename AfterRead = void (*)()>
inline void refresh_param_snapshot(
    const state::StateStore& store, std::span<const state::ParamInfo> all_params,
    std::vector<float>& snapshot, ParamSnapshotState& state, std::uint64_t generation,
    AfterRead&& after_read = [] {}) {
    if (state.valid && state.generation == generation && snapshot.size() == all_params.size())
        return;
    const bool quiet_before = store.state_snapshot_is_current(generation);
    snapshot_param_values(store, all_params, snapshot);
    after_read();
    state.generation = generation;
    state.valid = quiet_before && store.state_snapshot_is_current(generation);
}

inline bool changed_since_snapshot(float current, float snapshotted) noexcept {
    return std::memcmp(&current, &snapshotted, sizeof(float)) != 0;
}
 
// ---------------------------------------------------------------------------
// 6. MPE per-note-expression sidecar
//
// A format that carries per-note expression feeds a Processor that opted into
// MPE (PluginDescriptor::supports_mpe) through Pulp's MPE model: inbound MIDI
// runs an MpeVoiceTracker whose callbacks append per-note deltas to an
// MpeBuffer, and that buffer is handed to the Processor for exactly the duration
// of one process() call. CLAP and VST3 each open-coded the identical enable /
// bind / per-block clear-run-attach dance around their own event decode;
// MpeSidecar is the single owner of it. The per-format expression *decode*
// (VST3 kNoteExpressionValueEvent, CLAP clap_event_note_expression_t) stays in
// the adapter — it synthesizes channel-wide MIDI via mpe_expression.hpp into the
// shared MidiBuffer this consumes.
// ---------------------------------------------------------------------------

struct MpeSidecar {
    midi::MpeVoiceTracker tracker;
    midi::MpeBuffer buffer;
    std::int32_t current_sample_offset = 0;
    bool enabled = false;
    bool expression_event_dropped = false;
 
    MpeSidecar() = default;
    MpeSidecar(const MpeSidecar&) = delete;
    MpeSidecar& operator=(const MpeSidecar&) = delete;
    MpeSidecar(MpeSidecar&&) = delete;
    MpeSidecar& operator=(MpeSidecar&&) = delete;

    void configure(bool supports_mpe) {
        enabled = supports_mpe;
        if (enabled) {
            midi::bind_tracker_to_buffer(
                tracker, buffer, current_sample_offset, &expression_event_dropped);
        }
    }

    void reserve(std::size_t event_capacity) {
        buffer.reserve(event_capacity);
        buffer.set_realtime_capacity_limit(true);
    }

    void reset() noexcept {
        tracker.reset();
        buffer.clear();
        current_sample_offset = 0;
        expression_event_dropped = false;
    }

    template <typename MidiRange>
    [[nodiscard]] bool run(Processor& processor, const MidiRange& midi_in) {
        if constexpr (requires { midi_in.dropped_event_count(); }) {
            if (midi_in.dropped_event_count() != 0) {
                // Source-stream completeness is required even when the
                // processor did not opt into MPE: a retained attack followed
                // by a dropped release can stick an ordinary MIDI voice too.
                reset();
                processor.set_mpe_input(enabled ? &buffer : nullptr);
                return false;
            }
        }
        if (enabled) {
            buffer.clear();
            expression_event_dropped = false;
            // Releases that could not fit at the end of the previous block
            // must lead this block before any new starts. The tracker blocks
            // note-ons while this fixed queue is nonempty, so no voice can be
            // orphaned and the queue remains bounded by tracker polyphony.
            current_sample_offset = 0;
            tracker.flush_pending_note_offs();
            for (const auto& ev : midi_in) {
                current_sample_offset = ev.sample_offset;
                tracker.process(ev);
            }
            if (expression_event_dropped) {
                // Expression callbacks observe tracker state after mutation. If
                // any fixed-capacity append fails, discard the partial stream
                // and tracker state together; the adapter requests a processor
                // reset so neither side retains a newer voice snapshot.
                reset();
                processor.set_mpe_input(&buffer);
                return false;
            }
            processor.set_mpe_input(&buffer);
        } else {
            processor.set_mpe_input(nullptr);
        }
        return true;
    }
};
 
}  // namespace pulp::format::boundary