timeline_graph_binding.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/audio/rt_safety_contract.hpp>
#include <pulp/host/signal_graph_prepared_topology_edit.hpp>
#include <pulp/host/timeline_device_resolver.hpp>
#include <pulp/playback/audio_renderer.hpp>
#include <pulp/playback/automation_limits.hpp>
#include <pulp/playback/event_compensation.hpp>
#include <pulp/playback/note_renderer.hpp>
#include <pulp/runtime/slot.hpp>
 
#include <cstddef>
#include <cstdint>
#include <memory>
#include <span>
#include <vector>
 
namespace pulp::host {
 
namespace detail {
struct TimelineGraphSharedBlockState;
struct TimelineGraphBoundTrack;
struct TimelineGraphBindingState;
struct TimelineGraphPreparedCandidate;
} // namespace detail

struct TimelineDeviceGraphRoute {
    timeline::ItemId device_placement_id;
    NodeId plugin_node = 0;
};
 
struct TimelineTrackGraphRoute {
    timeline::ItemId track_id;
    NodeId audio_destination = 0;
    PortIndex audio_destination_first_port = 0;
    NodeId midi_destination = 0;
    std::span<const TimelineDeviceGraphRoute> device_routes{};
    NodeId post_device_audio_source = 0;
    PortIndex post_device_audio_source_first_port = 0;
    NodeId post_mixer_audio_destination = 0;
    PortIndex post_mixer_audio_destination_first_port = 0;
};
 
struct TimelineGraphBindingConfig {
    std::uint32_t audio_channels = 2;
    std::size_t maximum_note_events_per_track_per_block = 1024;
    playback::AudioRendererLimits audio_limits{};
    playback::AutomationPlaybackLimits automation_limits =
        playback::AutomationPlaybackLimits::platform_defaults();
};
 
enum class TimelineGraphAdmissionCode : std::uint8_t {
    Accepted,
    InvalidConfiguration,
    DuplicateTrack,
    MissingTrack,
    MissingDestination,
    DestinationPortRange,
    IncompletePostDeviceRoute,
    MissingPostDeviceRoute,
    SourcePortRange,
    NodeLimitExceeded,
    ConnectionLimitExceeded,
    PerNodePortLimitExceeded,
    TotalPortLimitExceeded,
    RoutedPlanRejected,
    RoutedTopologyIneligible,
    GraphMutationFailed,
    GraphPrepareFailed,
    SampleRateMismatch,
    NoteCapacityExceeded,
    MissingDevicePlacement,
    UnexpectedDevicePlacement,
    DuplicateDevicePlacement,
    MissingDeviceNode,
    DeviceNodeNotPlugin,
    UnresolvedDevicePlugin,
    DuplicateDeviceNodeOwnership,
    UnknownAutomationParameter,
    ReadOnlyAutomationParameter,
    NonAutomatableAutomationParameter,
    DeviceNodeAutomationConflict,
    AutomationRendererRejected,
    RealtimeStretchRejected,
    CleanupRecoveryRequired,
    MissingProgramProject,
    ProgramProjectMismatch,
    MissingProgramSequence,
    UnsupportedDeviceChain,
    UnsupportedDevicePosition,
    UnsupportedDeviceSlotKind,
    UnsupportedDeviceKind,
    UnsupportedDeviceBinding,
    UnsupportedDeviceBypass,
    UnsupportedDeviceWetDry,
    UnsupportedDeviceState,
    MixedDeviceOwnership,
    DeviceFactoryFailed,
    EventDeviceLatencyUnavailable,
    EventDeviceLatencyOutOfRange,
    EventChainLiveInputUnsupported,
};

struct TimelineGraphAdmission {
    TimelineGraphAdmissionCode code = TimelineGraphAdmissionCode::Accepted;
    std::uint64_t actual = 0;
    std::uint64_t limit = 0;
    timeline::ItemId item;
    NodeId node = 0;
    constexpr explicit operator bool() const noexcept {
        return code == TimelineGraphAdmissionCode::Accepted;
    }
};
 
enum class TimelineGraphProcessCode : std::uint8_t {
    Ok,
    MissingProgram,
    InvalidTransport,
    NoteRenderFailed,
    AudioRenderFailed,
    RealtimeStretchGap,
    RealtimeStretchStateRequired,
    RealtimeStretchStalePublication,
    RealtimeStretchImpossibleRatio,
    RealtimeStretchBackpressure,
    RealtimeStretchUnderflow,
    RealtimeStretchUnsupportedScrubbing,
    CapacityExceeded,
    InputShapeMismatch,
    TopologyChanged,
    AutomationRenderFailed,
    AutomationDeliveryFailed,
    RoutedDispatchFailed,
    CleanupFailed,
    EventCompensationUnsupported,
};
 
struct TimelineGraphProcessResult {
    TimelineGraphProcessCode code = TimelineGraphProcessCode::Ok;
    std::uint32_t emitted_note_events = 0;
    std::uint32_t dropped_note_events = 0;
    std::uint32_t candidate_automation_events = 0;
    std::uint32_t emitted_automation_events = 0;
    std::uint32_t coalesced_automation_events = 0;
    constexpr explicit operator bool() const noexcept {
        return code == TimelineGraphProcessCode::Ok;
    }
};

class TimelineGraphPlaybackBinding {
  public:
    static constexpr audio::RtSafetyClass process_rt_safety_class =
        audio::RtSafetyClass::AudioCallbackSafeAfterPrepare;
    static constexpr std::size_t maximum_graph_midi_events_per_block = 1024;
 
    TimelineGraphPlaybackBinding(SignalGraph& graph, const playback::PlaybackProgramStore& store);
    ~TimelineGraphPlaybackBinding();
    TimelineGraphPlaybackBinding(const TimelineGraphPlaybackBinding&) = delete;
    TimelineGraphPlaybackBinding& operator=(const TimelineGraphPlaybackBinding&) = delete;
 
    TimelineGraphAdmission preflight(const playback::PlaybackProgram& program,
                                     std::span<const TimelineTrackGraphRoute> routes,
                                     const TimelineGraphBindingConfig& config,
                                     int maximum_block_size) const;

    TimelineGraphAdmission prepare(const playback::PlaybackProgram& program,
                                   std::span<const TimelineTrackGraphRoute> routes,
                                   const TimelineGraphBindingConfig& config, double sample_rate,
                                   int maximum_block_size);

    TimelineGraphAdmission adopt_program(const playback::PlaybackProgram& program);
    TimelineGraphAdmission adopt_latest_program();

    TimelineGraphAdmission prepare_quiesced(const playback::PlaybackProgram& program,
                                            std::span<const TimelineTrackGraphRoute> routes,
                                            const TimelineGraphBindingConfig& config,
                                            double sample_rate, int maximum_block_size);
 
    using BeforeBindingPublishHookForTest = void (*)(void*) noexcept;
    void set_before_binding_publish_hook_for_test(BeforeBindingPublishHookForTest hook,
                                                  void* context = nullptr) noexcept {
        before_binding_publish_hook_for_test_ = hook;
        before_binding_publish_context_for_test_ = context;
    }
    void set_before_graph_commit_hook_for_test(BeforeBindingPublishHookForTest hook,
                                               void* context = nullptr) noexcept {
        before_graph_commit_hook_for_test_ = hook;
        before_graph_commit_context_for_test_ = context;
    }
 
    TimelineGraphProcessResult process(audio::BufferView<float>& output,
                                       const audio::BufferView<const float>& input,
                                       const playback::TransportSnapshot& transport) noexcept;
 
    NodeId audio_node_for(timeline::ItemId track_id) const noexcept;
    NodeId midi_input_node_for(timeline::ItemId track_id) const noexcept;
    NodeId device_node_for(timeline::ItemId placement_id) const noexcept;
    playback::EventCompensationShift
    event_compensation_shift_for(timeline::ItemId track_id) const noexcept;
    playback::RendererProgramKey renderer_key_for(timeline::ItemId track_id) const noexcept;
    playback::RendererCarryState renderer_state_for(timeline::ItemId track_id) const noexcept;

    void set_timeline_device_factory_for_test(TimelineDeviceSlotFactory factory) noexcept {
        timeline_device_factory_ = factory ? factory : &load_builtin_plugin;
    }
 
  private:
    TimelineGraphAdmission build_candidate(const playback::PlaybackProgram& program,
                                           std::span<const TimelineTrackGraphRoute> routes,
                                           const TimelineGraphBindingConfig& config,
                                           double sample_rate, int maximum_block_size,
                                           detail::TimelineGraphPreparedCandidate& candidate) const;
    TimelineGraphAdmission prepare_impl(const playback::PlaybackProgram& program,
                                        std::span<const TimelineTrackGraphRoute> routes,
                                        const TimelineGraphBindingConfig& config,
                                        double sample_rate, int maximum_block_size, bool quiesced);
    void remove_all_owned_nodes() noexcept;
 
    SignalGraph& graph_;
    const playback::PlaybackProgramStore& store_;
    std::shared_ptr<detail::TimelineGraphSharedBlockState> shared_;
    std::shared_ptr<detail::ExactParameterIngressOwner> automation_claim_owner_;
    runtime::Slot<const detail::TimelineGraphBindingState> state_;
    std::uint64_t binding_instance_id_ = 0;
    TimelineDeviceSlotFactory timeline_device_factory_ = &load_builtin_plugin;
    BeforeBindingPublishHookForTest before_binding_publish_hook_for_test_ = nullptr;
    void* before_binding_publish_context_for_test_ = nullptr;
    BeforeBindingPublishHookForTest before_graph_commit_hook_for_test_ = nullptr;
    void* before_graph_commit_context_for_test_ = nullptr;
};
 
} // namespace pulp::host