au_v2_instrument.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/alive_token.hpp>
 
// The AU v2 instrument adapter wraps Apple's AudioUnitSDK (Apple-only,
// developer-supplied). The whole header is gated on __APPLE__ so it stays
// self-contained — an empty no-op — on the Linux header-hygiene check and any
// non-Apple TU.
#if defined(__APPLE__)
 
#include <AudioUnitSDK/MusicDeviceBase.h>
 
#include <pulp/format/processor.hpp>
#include <pulp/format/adapter_boundary.hpp>
#include <pulp/format/contract_editor_session.hpp>
#include <pulp/format/au_v2_common.hpp>
#include <pulp/format/host_quirks.hpp>
#include <pulp/format/detail/playhead_diff.hpp>
#include <pulp/runtime/spsc_queue.hpp>
#include <pulp/runtime/trace_session.hpp>
 
#include <array>
#include <cstdint>
#include <memory>
#include <vector>
 
namespace pulp::format::au {

inline std::size_t instrument_output_element_count(
    const PluginDescriptor& desc) noexcept {
    const std::size_t declared =
        desc.output_buses.empty() ? std::size_t{1} : desc.output_buses.size();
    return declared < BusBufferSet::kMaxBuses ? declared
                                              : BusBufferSet::kMaxBuses;
}

inline std::size_t build_output_bus_infos(const PluginDescriptor& desc,
                                          ProcessBusBufferInfo* out,
                                          std::size_t cap) noexcept {
    std::size_t n = 0;
    for (std::size_t i = 0; i < desc.output_buses.size() && n < cap; ++i) {
        out[n].name = desc.output_buses[i].name;
        out[n].index = i;
        out[n].direction = BusDirection::Output;
        out[n].role = (i == 0) ? BusRole::Main : BusRole::Aux;
        out[n].declared_channels = desc.output_buses[i].default_channels;
        // Aux buses are optional; a host may leave them disconnected. The main
        // bus (index 0) is always required.
        out[n].optional = (i != 0);
        out[n].active = true;
        ++n;
    }
    return n;
}
 
class PulpAUInstrument : public ausdk::MusicDeviceBase {
public:
    explicit PulpAUInstrument(AudioComponentInstance ci);
    // Multi-plugin-bundle ctor — see PulpAUEffect. The bound factory is used
    // both for the output-element-count probe in the base-ctor argument list
    // and to construct the processor.
    PulpAUInstrument(AudioComponentInstance ci, ProcessorFactory factory);
 
    OSStatus GetParameterList(AudioUnitScope inScope,
                              AudioUnitParameterID* outParameterList,
                              UInt32& outNumParameters) override;
    OSStatus GetParameterInfo(AudioUnitScope inScope,
                              AudioUnitParameterID inParameterID,
                              AudioUnitParameterInfo& outParameterInfo) override;
 
    // Single source of truth: the host reads/writes the plugin's StateStore
    // directly — no separate Globals copy to reconcile per block. Mirrors the
    // effect adapter (see au_v2_adapter). See the auv2 skill.
    OSStatus GetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32& outValue) override;
    OSStatus SetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32 inValue,
                          UInt32 inBufferOffsetInFrames) override;
 
    // Value text for discrete parameters (value labels); continuous parameters
    // are served through the ParameterStringFromValue / ...ValueFromString
    // properties handled in GetProperty.
    OSStatus GetParameterValueStrings(AudioUnitScope inScope, AudioUnitParameterID inParameterID,
                                      CFArrayRef* outStrings) override;
 
    // Serve the Pulp editor-context property (so the Cocoa view factory can
    // reach this instance's Processor + StateStore) and advertise the Cocoa
    // view to the host (kAudioUnitProperty_CocoaUI). Without these the host
    // never loads the Pulp editor and shows its own generic param view —
    // the AU-instrument editor gap ChainerSynth surfaced.
    OSStatus GetPropertyInfo(AudioUnitPropertyID inID, AudioUnitScope inScope,
                             AudioUnitElement inElement, UInt32& outDataSize,
                             bool& outWritable) override;
    OSStatus GetProperty(AudioUnitPropertyID inID, AudioUnitScope inScope,
                         AudioUnitElement inElement, void* outData) override;
    // Accepts the host's kAudioUnitProperty_OfflineRender write.
    OSStatus SetProperty(AudioUnitPropertyID inID, AudioUnitScope inScope,
                         AudioUnitElement inElement, const void* inData,
                         UInt32 inDataSize) override;
 
    OSStatus Initialize() override;
    void Cleanup() override;
 
    bool StreamFormatWritable(AudioUnitScope scope, AudioUnitElement element) override;
    bool CanScheduleParameters() const noexcept override;
 
    // Channel capabilities for an instrument that also declares audio input:
    // the descriptor's input/output pairs, preceded by the no-input rows when
    // the main input is optional so the unit validates both connected and
    // unconnected. Without inputs the table is the classic {0, N} ladder.
    UInt32 SupportedNumChannels(const AUChannelInfo** outInfo) override;
    // The side-chain input element (element 1) accepts 1..kBoundaryMaxChannels
    // channels; an output sample-rate change carries over to every unconnected
    // input element so input and output run at one rate.
    bool ValidFormat(AudioUnitScope inScope, AudioUnitElement inElement,
                     const AudioStreamBasicDescription& inNewFormat) override;
    OSStatus ChangeStreamFormat(AudioUnitScope inScope, AudioUnitElement inElement,
                                const AudioStreamBasicDescription& inPrevFormat,
                                const AudioStreamBasicDescription& inNewFormat) override;
 
    OSStatus HandleNoteOn(UInt8 inChannel, UInt8 inNoteNumber,
                          UInt8 inVelocity, UInt32 inStartFrame) override;
    OSStatus HandleNoteOff(UInt8 inChannel, UInt8 inNoteNumber,
                           UInt8 inVelocity, UInt32 inStartFrame) override;

    OSStatus HandleNonNoteEvent(UInt8 inStatus, UInt8 inChannel, UInt8 inData1, UInt8 inData2,
                                UInt32 inStartFrame) override;

    OSStatus HandleSysEx(const UInt8* inData, UInt32 inLength) override;
 
    OSStatus Render(AudioUnitRenderActionFlags& ioActionFlags,
                    const AudioTimeStamp& inTimeStamp,
                    UInt32 inNumberFrames) override;

    OSStatus GetPresets(CFArrayRef* outData) const override;

    OSStatus NewFactoryPresetSet(const AUPreset& inNewFactoryPreset) override;

    FactoryPresetTable& factory_preset_table() noexcept {
        return factory_presets_;
    }
 
    OSStatus SaveState(CFPropertyListRef* outData) override;
    OSStatus RestoreState(CFPropertyListRef plist) override;
 
    bool SupportsTail() override;
    Float64 GetTailTime() override;
    Float64 GetLatency() override;
 
protected:
    void publish_parameter_display_changes();
 
    // clang-format off: preserve the repository's four-space private-section style.
private:
    // AU v2 instruments are a separate adapter path from PulpAUEffect. Keep
    // the tracing attachment on the actual host-facing object so a traced AU
    // instrument retains a live reference to the runtime trace controller.
    // Without this member, the traced SDK can carry its sentinel and Perfetto
    // archive while the linker dead-strips Tracing::attach/start/stop from
    // instrument bundles, making the advertised tracing mode inert.
    runtime::ScopedTracingAttachment tracing_;
 
    // 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_;
    // Factory presets, bound to store_ in the constructor. Declared after
    // store_ so reverse member destruction retires the PresetManager while the
    // store it holds a reference to is still alive.
    FactoryPresetTable factory_presets_;
    // kAudioUnitProperty_RenderContextObserver; bound once the processor
    // exists, advertised only for an AudioWorkgroupClient processor.
    RenderContextObserverProperty render_context_;
    // Keeps a host class-info restore off the processor while Render() 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 editors the host still holds. Declared after processor_ so its
    // destruction invalidates them while the processor and store_ exist.
    ContractSessionRegistry contract_sessions_;
 
    // Immutable plugin metadata, cached once in the constructor. Owns the bus
    // name strings that the per-block `ProcessBusBufferInfo`s view — copying it
    // per render block would allocate (std::string members) on the audio thread.
    PluginDescriptor descriptor_{};
 
    // Host accommodations, resolved once at init via the runtime policy.
    HostQuirks host_quirks_{};
 
    // Per-output-bus channel-pointer storage. One vector per AU output element
    // (bus); index 0 is the main bus, 1..N-1 the aux buses. Pre-reserved in
    // Initialize() so the per-block resize to the host buffer count is a no-op
    // realloc and the render path never grows a vector on the audio thread.
    static constexpr std::size_t kMaxOutputBuses = BusBufferSet::kMaxBuses;
    std::array<std::vector<float*>, kMaxOutputBuses> output_bus_ptrs_{};
 
    // Audio input elements. `MusicDeviceBase` creates the elements the
    // constructor asks for but never pulls them, so Render() pulls each
    // connected element itself: element 0 is the main input, element 1 the
    // side chain. Both are fixed at construction from the descriptor. The
    // pointer arrays are the per-block read pointers into the elements' own
    // preallocated buffer lists, so the pull never allocates on the audio
    // thread. Lifetime of a pulled list is one Render() call.
    bool has_input_element_ = false;
    bool has_sidechain_element_ = false;
    std::array<const float*, boundary::kBoundaryMaxChannels> input_ptrs_{};
    std::array<const float*, boundary::kBoundaryMaxChannels> sidechain_ptrs_{};
    // Capability table returned by SupportedNumChannels; the host reads it
    // after the call returns, so it is instance storage rather than a local.
    std::array<AUChannelInfo, kMaxChannelInfoPairs> channel_info_{};
 
    // Main-thread listener that pushes editor parameter edits to the host
    // (never from the render thread). Kept alive for the adapter's lifetime.
    state::ListenerToken ui_push_listener_;
    ParameterDisplayNamePublisher parameter_display_names_;
 
    // Lock-free MIDI note input (single producer = host MIDI/render thread via
    // HandleNoteOn/Off; single consumer = Render). No audio-thread mutex.
    runtime::SpscQueue<midi::MidiEvent, 1024> midi_in_queue_;
 
    // MusicDeviceSysEx has no frame offset at the AU v2 callback boundary.
    // Keep the bounded copy shape identical to the other AU v2 adapters so a
    // host SysEx callback never allocates or blocks.
    static constexpr std::size_t kMaxSysexPayloadBytes = 1024;
    struct SysexChunk {
        std::array<uint8_t, kMaxSysexPayloadBytes> bytes{};
        uint16_t length = 0;
    };
    runtime::SpscQueue<SysexChunk, 32> sysex_in_queue_;
 
    // Per-block buffers are members so their vectors and SysEx payload pool
    // can be reserved during Initialize(), never grown from Render().
    static constexpr std::size_t kMaxEventsPerBlock = kMaxMidiEventsPerBlock;
    static constexpr std::size_t kMaxSysexPerBlock = 64;
    midi::MidiBuffer midi_in_;
    midi::MidiBuffer midi_out_;
 
    // MIDI the Processor emits during process() reaches the host through
    // kAudioUnitProperty_MIDIOutputCallback, as for the effect and the MIDI
    // processor: one output stream (kAudioUnitProperty_MIDIOutputCallbackInfo),
    // packed allocation-free into a CoreMIDI packet list each block. Only a
    // processor whose descriptor sets produces_midi advertises it.
    bool plugin_produces_midi() const noexcept;
    MidiOutputCallbackPublisher midi_output_callback_;
    MidiOutputPacketBuilder midi_out_packet_builder_;
 
    // Previous-block transport snapshot used to derive change flags on
    // `ProcessContext`. Default-constructed so the first Render() call
    // after Initialize() reports no changes.
    detail::PlayheadSnapshot playhead_prev_{};
 
    // Host offline-render intent (kAudioUnitProperty_OfflineRender), written by
    // the host before a faster-than-realtime bounce and read each render block.
    OfflineRenderProperty offline_render_;
    // clang-format on
};
 
} // namespace pulp::format::au
 
#endif // defined(__APPLE__)