au_v2_common.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/alive_token.hpp>
 
// Pieces of the AU v2 adapter surface that no single adapter owns.
//
// Pulp has three AU v2 adapters — the effect (`AUMIDIEffectBase`), the
// instrument (`MusicDeviceBase`), and the MIDI processor (`MusicDeviceBase`
// with no audio buses) — and the AudioUnitSDK forces each to derive a
// different base. Everything here is expressed against `AUBase`, `StateStore`,
// `Processor`, or plain bytes rather than a specific adapter base, so all
// three route through one implementation instead of three copies that drift.
//
// Apple-only: the whole header is gated on __APPLE__ so it stays an empty
// no-op on the Linux header-hygiene check.
#if defined(__APPLE__)
 
#include <AudioUnitSDK/AUBase.h>
 
#include <cstddef>
#include <AudioToolbox/AudioUnitProperties.h>
 
#include <AudioUnit/AudioUnit.h>
#include <CoreFoundation/CoreFoundation.h>
#include <CoreMIDI/MIDIServices.h>
#include <mach/mach_time.h>
#include <pulp/format/au_factory_presets.hpp>
#include <pulp/format/detail/host_sample_position.hpp>
 
#include <pulp/format/processor.hpp>
#include <pulp/format/state_restore_gate.hpp>
#include <pulp/format/detail/midi_out_offset.hpp>
#include <pulp/format/detail/playhead_diff.hpp>
#include <pulp/midi/buffer.hpp>
#include <pulp/midi/message.hpp>
#include <pulp/state/listener_token.hpp>
#include <pulp/state/store.hpp>
 
#include <array>
#include <atomic>
#include <cstdint>
#include <functional>
#include <limits>
#include <memory>
 
namespace pulp::format {
class AudioWorkgroupClient;
class ContractEditorSession;
class ContractSessionRegistry;
} // namespace pulp::format
 
namespace pulp::format::au {

inline constexpr std::size_t kMaxChannelInfoPairs = 16;

static constexpr AudioUnitPropertyID kPulpEditorContextProperty = 0x50754564; // 'PuEd'
 
struct PulpEditorContext {
    pulp::format::Processor* processor = nullptr;
    pulp::state::StateStore* store = nullptr;
    pulp::runtime::AliveToken::Handle owner_alive;
    pulp::format::ContractSessionRegistry* contract_sessions = nullptr;
};

using CocoaViewInfoFiller = bool (*)(void*);
extern CocoaViewInfoFiller g_cocoa_view_info_filler;

bool fill_cocoa_view_info(void* outData);

ContractEditorSession* contract_view_session(void* ns_view);

midi::MidiEvent decode_midi_event(uint8_t inStatus,
                                  uint8_t inChannel,
                                  uint8_t inData1,
                                  uint8_t inData2) noexcept;

inline ProcessContext make_render_process_context(double sample_rate,
                                                  int num_samples,
                                                  bool offline = false) noexcept {
    ProcessContext ctx;
    ctx.sample_rate = sample_rate;
    ctx.num_samples = num_samples;
    ctx.process_mode = offline ? ProcessMode::Offline : ProcessMode::Realtime;
    ctx.render_speed_hint = offline ? RenderSpeedHint::FasterThanRealtime
                                    : RenderSpeedHint::Realtime;
    return ctx;
}

class OfflineRenderProperty {
public:
    OSStatus property_info(AudioUnitScope scope, UInt32& out_size,
                           bool& out_writable) const noexcept {
        if (scope != kAudioUnitScope_Global) return kAudioUnitErr_InvalidScope;
        out_size = sizeof(UInt32);
        out_writable = true;
        return noErr;
    }
 
    OSStatus get(AudioUnitScope scope, void* out_data) const noexcept {
        if (scope != kAudioUnitScope_Global) return kAudioUnitErr_InvalidScope;
        if (!out_data) return kAudioUnitErr_InvalidPropertyValue;
        *static_cast<UInt32*>(out_data) = offline() ? 1u : 0u;
        return noErr;
    }
 
    OSStatus set(AudioUnitScope scope, const void* in_data,
                 UInt32 in_size) noexcept {
        if (scope != kAudioUnitScope_Global) return kAudioUnitErr_InvalidScope;
        if (!in_data || in_size < sizeof(UInt32))
            return kAudioUnitErr_InvalidPropertyValue;
        offline_.store(*static_cast<const UInt32*>(in_data) != 0,
                       std::memory_order_release);
        written_since_session_start_.store(true, std::memory_order_release);
        return noErr;
    }

    void begin_session() noexcept {
        if (!written_since_session_start_.exchange(false,
                                                    std::memory_order_acq_rel))
            offline_.store(false, std::memory_order_release);
    }

    bool offline() const noexcept {
        return offline_.load(std::memory_order_acquire);
    }
 
private:
    std::atomic<bool> offline_{false};
    std::atomic<bool> written_since_session_start_{false};
};

inline void apply_host_callbacks_to_process_context(
    ProcessContext& ctx,
    const ausdk::AUBase& unit,
    detail::PlayheadSnapshot& previous) noexcept {
    Float64 beat = 0.0;
    Float64 tempo = 0.0;
    if (unit.CallHostBeatAndTempo(&beat, &tempo) == noErr) {
        ctx.position_beats = beat;
        ctx.transport_validity.set(TransportField::BeatPosition);
        if (tempo > 0.0) {
            ctx.tempo_bpm = tempo;
            ctx.transport_validity.set(TransportField::Tempo);
        }
    }
 
    UInt32 delta_samples = 0;
    Float32 ts_num = 0.0f;
    UInt32 ts_denom = 0;
    Float64 current_measure_downbeat = 0.0;
    if (unit.CallHostMusicalTimeLocation(&delta_samples, &ts_num, &ts_denom,
                                         &current_measure_downbeat) == noErr) {
        if (ts_num > 0.0f && ts_denom > 0) {
            ctx.time_sig_numerator = static_cast<int>(ts_num);
            ctx.time_sig_denominator = static_cast<int>(ts_denom);
            ctx.transport_validity.set(TransportField::TimeSignature);
        }
    }
 
    Boolean is_playing = false;
    Boolean transport_state_changed = false;
    Float64 current_sample_in_timeline = 0.0;
    Boolean is_cycling = false;
    Float64 cycle_start = 0.0;
    Float64 cycle_end = 0.0;
    if (unit.CallHostTransportState(&is_playing, &transport_state_changed,
                                    &current_sample_in_timeline, &is_cycling,
                                    &cycle_start, &cycle_end) == noErr) {
        ctx.is_playing = (is_playing != 0);
        ctx.is_looping = (is_cycling != 0);
        ctx.transport_validity.set(TransportField::Playing);
        ctx.transport_validity.set(TransportField::Looping);
        if (const auto position = detail::host_sample_position(current_sample_in_timeline)) {
            ctx.position_samples = *position;
            ctx.transport_validity.set(TransportField::SamplePosition);
        }
        if (ctx.is_looping) {
            ctx.loop_start_beats = cycle_start;
            ctx.loop_end_beats = cycle_end;
            ctx.transport_validity.set(TransportField::LoopRange);
        }
    }
 
    static mach_timebase_info_data_t timebase = {0, 0};
    if (timebase.denom == 0) mach_timebase_info(&timebase);
    if (timebase.denom != 0) {
        const uint64_t now = mach_absolute_time();
        ctx.host_time_ns = static_cast<int64_t>(
            (now * timebase.numer) / timebase.denom);
        ctx.transport_validity.set(TransportField::HostTime);
    }
 
    detail::derive_bar_from_beats(ctx);
    if (ctx.has_transport(TransportField::BeatPosition) &&
        ctx.has_transport(TransportField::TimeSignature)) {
        ctx.transport_validity.set(TransportField::Bar);
    }
    detail::compute_playhead_changes(
        ctx, previous, detail::TransportDiffMode::FieldValidity);
}
 
inline Float64 tail_samples_to_seconds(int tail_samples,
                                       double sample_rate) noexcept {
    if (tail_samples < 0) return std::numeric_limits<Float64>::infinity();
    if (tail_samples == 0 || sample_rate <= 0.0) return 0.0;
    return static_cast<Float64>(tail_samples) / sample_rate;
}

//
// The per-block MIDI event budget shared by every AU v2 adapter's
// `kMaxEventsPerBlock` and the output packet builder's `kMaxOutputEvents`.
// This lives in one place on purpose: if the input bound and the output bound
// ever drift apart, host-bound MIDI is silently truncated on a dense
// arp/generator block. Reference this constant, never re-spell the literal.
inline constexpr std::size_t kMaxMidiEventsPerBlock = 2048;
 
struct MidiOutputPacketBuilder {
    // Bound the per-block output by the same event budget the MIDI input path
    // reserves, so a dense arp/generator block is delivered in full rather than
    // silently truncated. Short messages are at most 3 wire bytes; the CoreMIDI
    // packet header + per-packet overhead is small, so a budget of
    // (events * ~16 bytes) comfortably covers the worst case. SysEx shares the
    // same buffer and yields to the byte bound. Events past the buffer bound are
    // dropped (counted in `dropped`) rather than overflowing.
    static constexpr std::size_t kMaxOutputEvents = kMaxMidiEventsPerBlock;
    static constexpr std::size_t kBufferBytes = kMaxOutputEvents * 16;
    alignas(MIDIPacketList) std::array<std::uint8_t, kBufferBytes> storage{};
 
    // Number of events dropped on the most recent build() because the packet
    // buffer or the merge index filled. 0 in steady state; a diagnostic the
    // adapter / tests can read to detect a too-dense block.
    std::size_t dropped = 0;

    const MIDIPacketList* build(const midi::MidiBuffer& midi_out,
                                std::uint32_t frame_count) noexcept {
        dropped = 0;
 
        // Build a merge index over both sources (short events + sysex) so we can
        // emit in ascending sample_offset order. Each source is referenced by a
        // tagged index; the index array is fixed-capacity (no allocation).
        struct Ref {
            std::int32_t offset;
            std::uint32_t order;  // stable tiebreak: preserves per-source order
            std::uint32_t index;  // index within its source
            bool is_sysex;
        };
        std::array<Ref, kMaxOutputEvents> refs;
        std::size_t n_refs = 0;
        std::uint32_t order = 0;
 
        const auto clamp_offset = [&](std::int32_t off) -> std::int32_t {
            // Shared cross-format offset contract (see detail/midi_out_offset.hpp
            // and test_midi_out_offset_parity.cpp): an in-block offset N is
            // preserved; a stray out-of-block offset is clamped into the block.
            return detail::au_output_offset(off, frame_count);
        };
 
        std::uint32_t ev_index = 0;
        for (const auto& e : midi_out) {
            const std::uint32_t len = e.message.length();
            if (len != 0 && len <= 3) {  // short messages only
                if (n_refs < refs.size()) {
                    refs[n_refs++] = Ref{clamp_offset(e.sample_offset),
                                         order++, ev_index, false};
                } else {
                    ++dropped;
                }
            }
            ++ev_index;
        }
        const auto& sysex = midi_out.sysex();
        for (std::uint32_t i = 0; i < sysex.size(); ++i) {
            if (sysex[i].data.empty()) continue;
            if (n_refs < refs.size()) {
                refs[n_refs++] = Ref{clamp_offset(sysex[i].sample_offset),
                                     order++, i, true};
            } else {
                ++dropped;
            }
        }
 
        // Stable sort by offset (insertion sort — small n, no allocation, and
        // stable so same-offset events keep per-source emission order).
        for (std::size_t i = 1; i < n_refs; ++i) {
            Ref key = refs[i];
            std::size_t j = i;
            while (j > 0 && (refs[j - 1].offset > key.offset ||
                             (refs[j - 1].offset == key.offset &&
                              refs[j - 1].order > key.order))) {
                refs[j] = refs[j - 1];
                --j;
            }
            refs[j] = key;
        }
 
        auto* list = reinterpret_cast<MIDIPacketList*>(storage.data());
        MIDIPacket* cur = MIDIPacketListInit(list);
        bool wrote = false;
 
        for (std::size_t i = 0; i < n_refs; ++i) {
            const Ref& r = refs[i];
            const auto ts = static_cast<MIDITimeStamp>(r.offset);
            MIDIPacket* next = nullptr;
            if (r.is_sysex) {
                const auto& sx = sysex[r.index];
                next = MIDIPacketListAdd(list, kBufferBytes, cur, ts,
                                         sx.data.size(), sx.data.data());
            } else {
                // Random-access the short event by its buffer index.
                const midi::MidiEvent& e = midi_out[r.index];
                const std::uint32_t len = e.message.length();
                std::uint8_t bytes[3] = {0, 0, 0};
                const auto* d = e.data();
                for (std::uint32_t b = 0; b < len; ++b) bytes[b] = d[b];
                next = MIDIPacketListAdd(list, kBufferBytes, cur, ts, len, bytes);
            }
            if (next == nullptr) {  // buffer full — drop the rest
                dropped += (n_refs - i);
                break;
            }
            cur = next;
            wrote = true;
        }
 
        return wrote ? list : nullptr;
    }
};
 
// ── Parameter surface ────────────────────────────────────────────────────
//
// The StateStore IS the host's parameter store (see the auv2 skill's
// "Parameters are single-source-of-truth" section) — these helpers only read
// and write it, never a parallel AUElement copy.

OSStatus fill_parameter_list(const state::StateStore& store,
                             AudioUnitScope scope,
                             AudioUnitParameterID* out_list,
                             UInt32& out_count);

OSStatus fill_parameter_info(const state::StateStore& store,
                             AudioUnitScope scope,
                             AudioUnitParameterID param_id,
                             AudioUnitParameterInfo& out_info,
                             bool advertise_value_strings);
 
OSStatus fill_parameter_clump_property_info(const state::StateStore& store,
                                            AudioUnitScope scope,
                                            UInt32& out_size,
                                            bool& out_writable);

OSStatus fill_supports_mpe_property_info(bool supports_mpe, AudioUnitScope scope, UInt32& out_size,
                                         bool& out_writable);
 
OSStatus fill_supports_mpe(bool supports_mpe, AudioUnitScope scope, void* out_data);

class RenderContextObserverProperty {
  public:
    RenderContextObserverProperty() = default;
    ~RenderContextObserverProperty();
    RenderContextObserverProperty(const RenderContextObserverProperty&) = delete;
    RenderContextObserverProperty& operator=(const RenderContextObserverProperty&) = delete;

    void bind(Processor* processor);
 
    OSStatus property_info(AudioUnitScope scope, AudioUnitElement element, UInt32& out_size,
                           bool& out_writable) const;
    OSStatus get(AudioUnitScope scope, AudioUnitElement element, void* out_data) const;

    void prepare_for_render() const noexcept;

    void clear_after_render_resources() const noexcept;
 
    AudioWorkgroupClient* client() const noexcept {
        return client_;
    }
 
  private:
    AudioWorkgroupClient* client_ = nullptr;
    void* block_ = nullptr; // AURenderContextObserver, Block_copy-owned
};
 
OSStatus fill_parameter_clump_name(const state::StateStore& store,
                                   AudioUnitScope scope,
                                   void* out_data);

OSStatus fill_parameter_value_strings(const state::StateStore& store,
                                      AudioUnitScope scope,
                                      AudioUnitParameterID param_id,
                                      CFArrayRef* out_strings);

OSStatus parameter_string_from_value(const state::StateStore& store,
                                     void* out_data);

OSStatus parameter_value_from_string(const state::StateStore& store,
                                     void* out_data);
 
// ── Host ↔ store parameter bridge ────────────────────────────────────────

bool host_is_writing_param() noexcept;

class ScopedHostParamWrite {
public:
    ScopedHostParamWrite() noexcept;
    ~ScopedHostParamWrite() noexcept;
    ScopedHostParamWrite(const ScopedHostParamWrite&) = delete;
    ScopedHostParamWrite& operator=(const ScopedHostParamWrite&) = delete;
};

void wire_host_parameter_bridge(state::StateStore& store,
                                AudioUnit unit,
                                state::ListenerToken& out_listener);
 
// ── Host-facing parameter-name publishing ────────────────────────────────

class ParameterDisplayNamePublisher {
public:
    using Notify = std::function<void(state::ParamID)>;
 
    ParameterDisplayNamePublisher();
    ~ParameterDisplayNamePublisher();
 
    ParameterDisplayNamePublisher(const ParameterDisplayNamePublisher&) = delete;
    ParameterDisplayNamePublisher& operator=(const ParameterDisplayNamePublisher&) = delete;

    void start(state::StateStore& store, Notify notify);

    void stop() noexcept;

    void poll_main_thread();
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
// ── State (preset) serialization ─────────────────────────────────────────

OSStatus save_pulp_state(state::StateStore& store,
                         Processor& processor,
                         CFPropertyListRef* out_data);

OSStatus restore_pulp_state(state::StateStore& store,
                            Processor& processor,
                            StateRestoreGate& gate,
                            CFPropertyListRef plist);
 
// ── MIDI output callback publishing ──────────────────────────────────────

class MidiOutputCallbackPublisher {
public:
    struct Pair {
        AUMIDIOutputCallback callback = nullptr;
        void* user_data = nullptr;
    };

    OSStatus publish(const void* in_data, UInt32 in_data_size) noexcept;

    OSStatus reflect(void* out_data) const noexcept;

    const Pair* load() const noexcept {
        return active_.load(std::memory_order_acquire);
    }
 
private:
    std::array<Pair, 2> slots_{};
    std::atomic<std::uint8_t> write_slot_{0};
    std::atomic<const Pair*> active_{nullptr};
};

CFArrayRef make_midi_output_names(const char* stream_name);
 
} // namespace pulp::format::au
 
#endif // defined(__APPLE__)