au_v2_midi_processor.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/alive_token.hpp>
 
// The AU v2 MIDI-processor 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/contract_editor_session.hpp>
#include <pulp/format/au_v2_common.hpp>
#include <pulp/format/host_quirks.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/midi/buffer.hpp>
#include <pulp/runtime/spsc_queue.hpp>
#include <pulp/state/parameter_event_queue.hpp>
 
#include <array>
#include <cstdint>
#include <memory>
 
namespace pulp::format::au {

class PulpAUMidiProcessor : public ausdk::MusicDeviceBase {
public:
    explicit PulpAUMidiProcessor(AudioComponentInstance ci);
    // Multi-plugin-bundle ctor: the component is bound to its own factory
    // lexically (no global registry lookup). The single-arg ctor delegates here
    // with the legacy `registered_factory()` for single-plugin bundles.
    PulpAUMidiProcessor(AudioComponentInstance ci, ProcessorFactory factory);
 
    OSStatus GetParameterList(AudioUnitScope inScope,
                              AudioUnitParameterID* outParameterList,
                              UInt32& outNumParameters) override;
    OSStatus GetParameterInfo(AudioUnitScope inScope,
                              AudioUnitParameterID inParameterID,
                              AudioUnitParameterInfo& outParameterInfo) override;
    OSStatus GetParameterValueStrings(AudioUnitScope inScope,
                                      AudioUnitParameterID inParameterID,
                                      CFArrayRef* outStrings) override;
 
    // Single source of truth: the host reads/writes the plugin's StateStore
    // directly — no separate Globals copy to reconcile per block. See the auv2
    // skill's "Parameters are single-source-of-truth" section.
    OSStatus GetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32& outValue) override;
    OSStatus SetParameter(AudioUnitParameterID inID, AudioUnitScope inScope,
                          AudioUnitElement inElement, Float32 inValue,
                          UInt32 inBufferOffsetInFrames) override;
 
    OSStatus GetPropertyInfo(AudioUnitPropertyID inID, AudioUnitScope inScope,
                             AudioUnitElement inElement, UInt32& outDataSize,
                             bool& outWritable) override;
    OSStatus GetProperty(AudioUnitPropertyID inID, AudioUnitScope inScope,
                         AudioUnitElement inElement, void* outData) override;
    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;
 
    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;
 
    Float64 GetLatency() override;
 
protected:
    void publish_parameter_display_changes();

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

    OSStatus HandleSysEx(const UInt8* inData, UInt32 inLength) override;
 
private:
    bool bypass_engaged() const noexcept;
 
    // 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 so the render
    // path never copies the descriptor (which allocates std::string members) on
    // the audio thread.
    PluginDescriptor descriptor_{};
 
    // Host accommodations, resolved once in the constructor via the runtime
    // policy. Gates the non-negative latency clamp.
    HostQuirks host_quirks_{};
 
    // Cached ParamID of a plugin-declared Bypass parameter, 0 when there is
    // none. This adapter does NOT synthesize one: an `aumi` has no
    // kAudioUnitProperty_BypassEffect (that lives on AUEffectBase), so a
    // synthesized control would appear as an ordinary parameter with no host
    // bypass semantics behind it.
    state::ParamID bypass_param_id_ = 0;
 
    // Main-thread listener that pushes editor parameter edits to the host, kept
    // alive for the adapter's lifetime so host param notifications never run on
    // the render thread.
    state::ListenerToken ui_push_listener_;
    ParameterDisplayNamePublisher parameter_display_names_;
 
    // Parameter-event sidecar, set on the Processor each block so the
    // param-events contract is uniform across formats. AU v2 has no scheduled /
    // ramped parameter event source, so this queue stays empty and host
    // parameter changes reach the Processor through `store_`.
    state::ParameterEventQueue param_events_;
 
    // Per-block MIDI I/O. Members (not per-render locals) with reserved,
    // realtime-capacity-limited storage so the drain and the Processor's
    // appends never grow a vector on the audio thread. Capacities match the
    // effect adapter so behavior is uniform across formats.
    static constexpr std::size_t kMaxEventsPerBlock = kMaxMidiEventsPerBlock;
    static constexpr std::size_t kMaxSysexPerBlock = 64;
    static constexpr std::size_t kMaxSysexPayloadBytes = 512;
    midi::MidiBuffer midi_in_;
    midi::MidiBuffer midi_out_;
 
    // Lock-free MIDI input. Single producer (the host's MIDI delivery thread,
    // via HandleMIDIEvent / HandleSysEx), single consumer (Render). No mutex on
    // the audio thread; under flood, excess events are dropped rather than
    // blocking the render.
    runtime::SpscQueue<midi::MidiEvent, 1024> midi_in_queue_;
    struct SysexChunk {
        std::array<uint8_t, kMaxSysexPayloadBytes> bytes{};
        uint16_t length = 0;
    };
    runtime::SpscQueue<SysexChunk, 32> sysex_in_queue_;
 
    // MIDI output: the host installs a callback via
    // kAudioUnitProperty_MIDIOutputCallback (main thread) that the render path
    // reads every block. The publisher owns that cross-thread handoff.
    MidiOutputCallbackPublisher midi_output_callback_;
    // Pre-reserved packet-list storage so the render-path build never allocates.
    MidiOutputPacketBuilder midi_out_packet_builder_;
 
    // Previous-block transport snapshot used to derive playhead change flags.
    // Default-constructed so the first Render() 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_;
};
 
} // namespace pulp::format::au
 
#endif // defined(__APPLE__)