program_wire.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/playback/automation_cursor.hpp>
#include <pulp/playback/automation_limits.hpp>
#include <pulp/playback/program.hpp>
#include <pulp/runtime/result.hpp>
#include <pulp/timebase/compiled_tempo_map.hpp>
#include <pulp/timebase/rational_time.hpp>
#include <pulp/timebase/tick.hpp>
#include <pulp/timeline/item_id.hpp>
 
#include <array>
#include <bit>
#include <cstddef>
#include <cstdint>
#include <span>
#include <type_traits>
 
namespace pulp::playback {
 
namespace detail {
struct ProgramWireDecoder;
}
 
static_assert(std::endian::native == std::endian::little,
              "the program wire is a native-layout little-endian byte range; a big-endian "
              "host must gain an explicit byte-swapping codec before it can produce or "
              "consume one, not silently emit records a reader would misread");

inline constexpr std::uint16_t kProgramWireVersion = 3;

inline constexpr std::uint16_t kProgramWireMinReaderVersion = 2;

inline constexpr std::uint16_t kProgramWireControllerMinReaderVersion = 3;

inline constexpr std::uint32_t kProgramWireMagic = 0x5750'4C50u;

inline constexpr std::uint32_t kProgramWireNoLane = 0xFFFF'FFFFu;

inline constexpr std::size_t kProgramWireMaximumTracks = 1'024;

inline constexpr std::size_t kProgramWireMaximumAutomationLanes = 1'024;

inline constexpr std::size_t kProgramWireMaximumControllerEventsPerTrack =
    kMaximumControllerEventsPerTrack;
 
enum class ProgramWireSection : std::uint32_t {
    Program = 1,
    TempoPoints = 2,
    Tracks = 3,
    ClipIds = 4,
    NoteEvents = 5,
    NoteModifiers = 6,
    DevicePlacementIds = 7,
    AutomationLanes = 8,
    AutomationSegments = 9,
    ControllerRanges = 10,
    ControllerEvents = 11,
};

inline constexpr std::uint32_t kProgramWireSectionOptional = 1u << 0u;

enum class AutomationEvaluationRate : std::uint8_t {
    SampleAccurate = 0,
    BlockRate = 1,
};
 
enum class ProgramWireTargetKind : std::uint8_t {
    DeviceParameter = 0,
    TrackMixer = 1,
};
 
enum class ProgramWireErrorCode : std::uint8_t {
    InsufficientCapacity,
    MisalignedBuffer,
    TempoMapMismatch,
    AudioProgramUnsupported,
    ProductionDeclarationUnsupported,
    MixerAutomationUnresolved,
    CountOverflow,

    ShortBuffer,
    BadMagic,
    UnsupportedVersion,
    BadHeaderSize,
    ChecksumMismatch,
    SectionOutOfBounds,
    SectionsNotTiled,
    SectionMisaligned,
    NonCanonicalSectionOrder,
    DuplicateSection,
    UnknownSection,
    MissingSection,
    TrailingData,
    BadRecordSize,
    BadSectionCardinality,
    RangeOutOfBounds,
    NonCanonicalRangeOwnership,
    AutomationTargetUnresolved,
    DuplicateAutomationTarget,
    StaleLaneGeneration,
    InvalidEnum,
    MalformedNoteModifier,
    MalformedSegment,
    MalformedControllerEvent,
    InvalidSampleRate,
    InvalidLimits,
    InvalidProducerEpoch,
    InvalidInstanceToken,
};
 
struct ProgramWireError {
    ProgramWireErrorCode code = ProgramWireErrorCode::ShortBuffer;
    std::uint32_t section = 0;
    std::uint64_t detail = 0;
};
 
#pragma pack(push, 8)

struct ProgramWireHeader {
    std::uint32_t magic = kProgramWireMagic;
    std::uint16_t version = kProgramWireVersion;
    std::uint16_t min_reader_version = kProgramWireMinReaderVersion;
    std::uint32_t header_bytes = 0;
    std::uint32_t section_count = 0;
    std::uint64_t payload_bytes = 0;
    std::uint64_t body_checksum = 0;
    std::uint64_t reserved0 = 0;
    std::uint64_t reserved1 = 0;
    std::uint64_t reserved2 = 0;
    std::uint64_t reserved3 = 0;
};
 
struct ProgramWireSectionEntry {
    std::uint32_t id = 0;
    std::uint32_t flags = 0;
    std::uint64_t offset = 0;
    std::uint64_t bytes = 0;
};

struct ProgramWireProgramRecord {
    std::uint64_t producer_epoch = 0;
    std::uint64_t generation = 0;
    std::uint64_t document_revision = 0;
    std::uint64_t project_id = 0;
    std::uint64_t sequence_id = 0;
    std::uint64_t generated_id_base = 0;
    std::uint64_t sample_rate_numerator = 0;
    std::uint64_t sample_rate_denominator = 0;
    std::uint32_t max_device_placements_per_track = 0;
    std::uint32_t max_lanes_per_track = 0;
    std::uint32_t max_points_per_lane = 0;
    std::uint32_t max_points_per_track = 0;
    std::uint32_t max_intersecting_segments_per_block = 0;
    std::uint32_t max_events_per_device_per_block = 0;
};

struct ProgramWireTempoPointRecord {
    std::int64_t tick = 0;
    std::uint64_t bpm_bits = 0;
    std::uint8_t curve_to_next = 0;
    std::uint8_t pad[7] = {};
};

struct ProgramWireTrackRecord {
    std::uint64_t id = 0;
    std::uint64_t generation = 0;
    std::uint32_t clip_first = 0;
    std::uint32_t clip_count = 0;
    std::uint32_t note_event_first = 0;
    std::uint32_t note_event_count = 0;
    std::uint32_t note_modifier_first = 0;
    std::uint32_t note_modifier_count = 0;
    std::uint32_t device_placement_first = 0;
    std::uint32_t device_placement_count = 0;
    std::uint32_t automation_lane_first = 0;
    std::uint32_t automation_lane_count = 0;
    std::uint64_t expanded_clip_count = 0;
    std::uint64_t expanded_note_event_count = 0;
    std::uint64_t generated_id_start = 0;
    std::uint64_t generated_id_count = 0;
    float mixer_gain_linear = 1.0f;
    float mixer_pan = 0.0f;
    std::uint32_t mixer_gain_lane = kProgramWireNoLane;
    std::uint32_t mixer_pan_lane = kProgramWireNoLane;
    std::uint8_t provider_selected = 0;
    std::uint8_t provider_available_mask = 0;
    std::uint8_t state_policy = 0;
    std::uint8_t flags = 0;
    std::uint32_t pad = 0;
};
 
inline constexpr std::uint8_t kProgramWireTrackHasAutomationProgram = 1u << 0u;
 
struct ProgramWireIdRecord {
    std::uint64_t value = 0;
};

struct ProgramWireNoteEventRecord {
    std::int64_t sample = 0;
    std::int64_t tick = 0;
    std::uint64_t clip_id = 0;
    std::uint64_t note_id = 0;
    std::uint16_t velocity = 0;
    std::uint8_t pitch = 0;
    std::uint8_t channel = 0;
    std::uint8_t kind = 0;
    std::uint8_t pad[3] = {};
};
 
struct ProgramWireNoteModifierRecord {
    std::uint64_t draw_key = 0;
    std::uint64_t note_id = 0;
    std::uint16_t probability = 0;
    std::uint16_t condition_period = 0;
    std::uint16_t condition_offset = 0;
    std::uint16_t ratchet_count = 0;
    std::uint8_t condition = 0;
    std::uint8_t pad[7] = {};
};

struct ProgramWireControllerRangeRecord {
    std::uint32_t first = 0;
    std::uint32_t count = 0;
};

struct ProgramWireControllerEventRecord {
    std::int64_t sample = 0;
    std::int64_t tick = 0;
    std::uint64_t clip_id = 0;
    std::uint64_t lane_id = 0;
    std::uint64_t point_id = 0;
    std::uint32_t value = 0;
    std::uint8_t group = 0;
    std::uint8_t channel = 0;
    std::uint8_t status = 0;
    std::uint8_t bank = 0;
    std::uint8_t index = 0;
    std::uint8_t origin = 0;
    std::uint8_t pad[6] = {};
};

struct ProgramWireAutomationLaneRecord {
    std::uint64_t lane_id = 0;
    std::uint64_t generation = 0;
    std::uint64_t instance_token = 0;
    std::uint32_t segment_first = 0;
    std::uint32_t segment_count = 0;
    float leading_value = 0.0f;
    std::uint8_t target_kind = 0;
    std::uint8_t evaluation_rate = 0;
    std::uint16_t pad0 = 0;
    std::uint64_t device_placement_id = 0;
    std::uint32_t device_param_id = 0;
    std::uint8_t mixer_parameter = 0;
    std::uint8_t pad1[3] = {};
};

struct ProgramWireAutomationSegmentRecord {
    std::int64_t start_tick = 0;
    std::int64_t end_tick = 0;
    std::int64_t start_sample = 0;
    std::int64_t end_sample = 0;
    float start_value = 0.0f;
    float end_value = 0.0f;
    float curvature = 0.0f;
    std::uint8_t interpolation = 0;
    std::uint8_t pad[3] = {};
};
 
#pragma pack(pop)
 
// A record whose size changes is a wire-format change. These are the
// compile-time half of the format's stability guard; the byte-level golden in
// the tests is the other half.
static_assert(sizeof(ProgramWireHeader) == 64);
static_assert(sizeof(ProgramWireSectionEntry) == 24);
static_assert(sizeof(ProgramWireProgramRecord) == 88);
static_assert(sizeof(ProgramWireTempoPointRecord) == 24);
static_assert(sizeof(ProgramWireTrackRecord) == 112);
static_assert(sizeof(ProgramWireIdRecord) == 8);
static_assert(sizeof(ProgramWireNoteEventRecord) == 40);
static_assert(sizeof(ProgramWireNoteModifierRecord) == 32);
static_assert(sizeof(ProgramWireAutomationLaneRecord) == 56);
static_assert(sizeof(ProgramWireAutomationSegmentRecord) == 48);
static_assert(sizeof(ProgramWireControllerRangeRecord) == 8);
static_assert(sizeof(ProgramWireControllerEventRecord) == 56);

static_assert(sizeof(ProgramWireHeader) % 8 == 0);
static_assert(sizeof(ProgramWireSectionEntry) % 8 == 0);
static_assert(sizeof(ProgramWireProgramRecord) % 8 == 0);
static_assert(sizeof(ProgramWireTempoPointRecord) % 8 == 0);
static_assert(sizeof(ProgramWireTrackRecord) % 8 == 0);
static_assert(sizeof(ProgramWireIdRecord) % 8 == 0);
static_assert(sizeof(ProgramWireNoteEventRecord) % 8 == 0);
static_assert(sizeof(ProgramWireNoteModifierRecord) % 8 == 0);
static_assert(sizeof(ProgramWireAutomationLaneRecord) % 8 == 0);
static_assert(sizeof(ProgramWireAutomationSegmentRecord) % 8 == 0);
static_assert(sizeof(ProgramWireControllerRangeRecord) % 8 == 0);
static_assert(sizeof(ProgramWireControllerEventRecord) % 8 == 0);
 
static_assert(std::is_trivially_copyable_v<ProgramWireHeader>);
static_assert(std::is_trivially_copyable_v<ProgramWireControllerRangeRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireControllerEventRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireProgramRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireTrackRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireNoteEventRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireAutomationLaneRecord>);
static_assert(std::is_trivially_copyable_v<ProgramWireAutomationSegmentRecord>);

inline constexpr std::size_t kProgramWireAlignment = 8;

constexpr std::uint64_t program_wire_checksum(std::span<const std::byte> bytes) noexcept {
    std::uint64_t hash = 0xcbf2'9ce4'8422'2325ull;
    for (const auto byte : bytes) {
        hash ^= static_cast<std::uint64_t>(std::to_integer<std::uint8_t>(byte));
        hash *= 0x0000'0100'0000'01b3ull;
    }
    return hash;
}

class ProgramWireView {
  public:
    ProgramWireView() = default;
 
    std::span<const std::byte> bytes() const noexcept {
        return bytes_;
    }
    const ProgramWireHeader& header() const noexcept {
        return *header_;
    }
    const ProgramWireProgramRecord& program() const noexcept {
        return *program_;
    }
    std::uint64_t producer_epoch() const noexcept {
        return program_->producer_epoch;
    }
    timebase::RationalRate sample_rate() const noexcept {
        return {program_->sample_rate_numerator, program_->sample_rate_denominator};
    }
    AutomationPlaybackLimits automation_limits() const noexcept;
 
    std::span<const ProgramWireTempoPointRecord> tempo_points() const noexcept {
        return tempo_points_;
    }
    std::span<const ProgramWireTrackRecord> tracks() const noexcept {
        return tracks_;
    }
    std::span<const ProgramWireIdRecord> clip_ids() const noexcept {
        return clip_ids_;
    }
    std::span<const ProgramWireNoteEventRecord> note_events() const noexcept {
        return note_events_;
    }
    std::span<const ProgramWireNoteModifierRecord> note_modifiers() const noexcept {
        return note_modifiers_;
    }
    std::span<const ProgramWireIdRecord> device_placement_ids() const noexcept {
        return device_placement_ids_;
    }
    std::span<const ProgramWireAutomationLaneRecord> automation_lanes() const noexcept {
        return automation_lanes_;
    }
    std::span<const ProgramWireAutomationSegmentRecord> automation_segments() const noexcept {
        return automation_segments_;
    }

    std::span<const ProgramWireControllerRangeRecord> controller_ranges() const noexcept {
        return controller_ranges_;
    }
    std::span<const ProgramWireControllerEventRecord> controller_events() const noexcept {
        return controller_events_;
    }
 
    // Every range below was bounds-checked at decode, so these never read past
    // their section.
    std::span<const ProgramWireIdRecord>
    clip_ids_for(const ProgramWireTrackRecord& track) const noexcept {
        return clip_ids_.subspan(track.clip_first, track.clip_count);
    }
    std::span<const ProgramWireNoteEventRecord>
    note_events_for(const ProgramWireTrackRecord& track) const noexcept {
        return note_events_.subspan(track.note_event_first, track.note_event_count);
    }
    std::span<const ProgramWireNoteModifierRecord>
    note_modifiers_for(const ProgramWireTrackRecord& track) const noexcept {
        return note_modifiers_.subspan(track.note_modifier_first, track.note_modifier_count);
    }
    std::span<const ProgramWireIdRecord>
    device_placement_ids_for(const ProgramWireTrackRecord& track) const noexcept {
        return device_placement_ids_.subspan(track.device_placement_first,
                                             track.device_placement_count);
    }
    std::span<const ProgramWireAutomationLaneRecord>
    automation_lanes_for(const ProgramWireTrackRecord& track) const noexcept {
        return automation_lanes_.subspan(track.automation_lane_first, track.automation_lane_count);
    }
    std::span<const ProgramWireAutomationSegmentRecord>
    segments_for(const ProgramWireAutomationLaneRecord& lane) const noexcept {
        return automation_segments_.subspan(lane.segment_first, lane.segment_count);
    }

    std::span<const ProgramWireControllerEventRecord>
    controller_events_for(const ProgramWireControllerRangeRecord& range) const noexcept {
        return controller_events_.subspan(range.first, range.count);
    }
 
  private:
    friend struct detail::ProgramWireDecoder;
 
    std::span<const std::byte> bytes_;
    const ProgramWireHeader* header_ = nullptr;
    const ProgramWireProgramRecord* program_ = nullptr;
    std::span<const ProgramWireTempoPointRecord> tempo_points_;
    std::span<const ProgramWireTrackRecord> tracks_;
    std::span<const ProgramWireIdRecord> clip_ids_;
    std::span<const ProgramWireNoteEventRecord> note_events_;
    std::span<const ProgramWireNoteModifierRecord> note_modifiers_;
    std::span<const ProgramWireIdRecord> device_placement_ids_;
    std::span<const ProgramWireAutomationLaneRecord> automation_lanes_;
    std::span<const ProgramWireAutomationSegmentRecord> automation_segments_;
    std::span<const ProgramWireControllerRangeRecord> controller_ranges_;
    std::span<const ProgramWireControllerEventRecord> controller_events_;
};

std::uint64_t program_wire_process_epoch() noexcept;

runtime::Result<std::size_t, ProgramWireError>
program_wire_encoded_size(const PlaybackProgram& program,
                          std::span<const timebase::TempoPoint> tempo_points) noexcept;

runtime::Result<std::size_t, ProgramWireError>
encode_program_wire(const PlaybackProgram& program,
                    std::span<const timebase::TempoPoint> tempo_points,
                    std::uint64_t producer_epoch, std::span<std::byte> out) noexcept;

runtime::Result<ProgramWireView, ProgramWireError>
decode_program_wire(std::span<const std::byte> bytes) noexcept;

bool program_wire_matches(const ProgramWireView& view, const PlaybackProgram& program,
                          std::span<const timebase::TempoPoint> tempo_points,
                          std::uint64_t producer_epoch) noexcept;

class ProgramWireBytePin {
  public:
    ProgramWireBytePin() = default;
    explicit ProgramWireBytePin(std::span<const std::byte> bytes,
                                std::uintptr_t owner_token = 0) noexcept
        : bytes_(bytes), owner_token_(owner_token) {}
    ProgramWireBytePin(const ProgramWireBytePin&) = delete;
    ProgramWireBytePin& operator=(const ProgramWireBytePin&) = delete;
    ProgramWireBytePin(ProgramWireBytePin&& other) noexcept
        : bytes_(other.bytes_), owner_token_(other.owner_token_) {
        other.bytes_ = {};
        other.owner_token_ = 0;
    }
    ProgramWireBytePin& operator=(ProgramWireBytePin&& other) noexcept {
        if (this != &other) {
            bytes_ = other.bytes_;
            owner_token_ = other.owner_token_;
            other.bytes_ = {};
            other.owner_token_ = 0;
        }
        return *this;
    }
 
    std::span<const std::byte> bytes() const noexcept {
        return bytes_;
    }
    std::uintptr_t owner_token() const noexcept {
        return owner_token_;
    }
    explicit operator bool() const noexcept {
        return !bytes_.empty();
    }
 
  private:
    std::span<const std::byte> bytes_;
    std::uintptr_t owner_token_ = 0;
};
 
enum class ProgramWireConsumerCode : std::uint8_t {
    Ok,
    DecodeRejected,
    TempoMapMismatch,
    StateCapacityExceeded,
    StalePublication,
    MissingProgram,
    InvalidTransport,
    OutputCapacityExceeded,
    CursorRejected,
};
 
enum class ProgramWireAdoption : std::uint8_t {
    Adopted,
    Unchanged,
    Rejected,
};
 
struct ProgramWireAdoptionResult {
    ProgramWireConsumerCode code = ProgramWireConsumerCode::Ok;
    ProgramWireAdoption adoption = ProgramWireAdoption::Unchanged;
    ProgramWireError wire_error{};
    ProgramWireBytePin returned_pin;
};
 
struct ProgramWireLaneIdentity {
    std::uint64_t producer_epoch = 0;
    ProgramGeneration program_generation = 0;
    timeline::ItemId track_id;
    ProgramGeneration track_generation = 0;
    timeline::ItemId lane_id;
    ProgramGeneration lane_generation = 0;
    AutomationProgramInstanceToken instance_token;
    constexpr bool operator==(const ProgramWireLaneIdentity&) const = default;
};

struct ProgramWireLaneState {
    ProgramWireLaneIdentity identity;
    AutomationCursor cursor;
    AutomationCursor next_cursor;
    std::array<AutomationBlockEvent, AutomationPlaybackLimits::kMaximumEventsPerDevicePerBlock>
        scratch{};
    AutomationCursorResult cursor_result;
    std::uint32_t event_count = 0;
    std::uint32_t merge_position = 0;
    std::uint32_t selected_count = 0;
    std::uint32_t write_position = 0;
    std::size_t output_index = 0;
    bool group_coalesced = false;
};
 
struct ProgramWireAutomationLaneOutput {
    timeline::ItemId track_id;
    timeline::ItemId lane_id;
    std::span<AutomationBlockEvent> events;
    AutomationCursorResult result;
};
 
struct ProgramWireAutomationRenderResult {
    ProgramWireConsumerCode code = ProgramWireConsumerCode::Ok;
    std::uint32_t rendered_lanes = 0;
};

class ProgramWireAutomationConsumer {
  public:
    static constexpr std::size_t kDefaultWireByteCapacity = 16u * 1'024u * 1'024u;
 
    explicit ProgramWireAutomationConsumer(std::span<ProgramWireLaneState> lane_state,
                                           std::size_t track_capacity,
                                           std::size_t wire_byte_capacity) noexcept
        : lane_state_(lane_state), track_capacity_(track_capacity),
          wire_byte_capacity_(wire_byte_capacity) {}
    explicit ProgramWireAutomationConsumer(std::span<ProgramWireLaneState> lane_state,
                                           std::size_t track_capacity) noexcept
        : ProgramWireAutomationConsumer(lane_state, track_capacity,
                                        kDefaultWireByteCapacity) {}
    explicit ProgramWireAutomationConsumer(std::span<ProgramWireLaneState> lane_state) noexcept
        : ProgramWireAutomationConsumer(lane_state, lane_state.size()) {}
    ProgramWireAutomationConsumer(const ProgramWireAutomationConsumer&) = delete;
    ProgramWireAutomationConsumer& operator=(const ProgramWireAutomationConsumer&) = delete;
 
    ProgramWireAdoptionResult adopt(ProgramWireBytePin candidate,
                                    const timebase::CompiledTempoMap& tempo_map,
                                    std::span<const timebase::TempoPoint> tempo_points) noexcept;
    ProgramWireAutomationRenderResult
    render(const TransportSnapshot& transport,
           std::span<ProgramWireAutomationLaneOutput> output) noexcept;
 
    std::span<const std::byte> active_bytes() const noexcept {
        return active_pin_.bytes();
    }
    std::size_t lane_count() const noexcept {
        return lane_count_;
    }
 
  private:
    struct ActiveLane {
        ProgramWireLaneState* state = nullptr;
        const ProgramWireTrackRecord* track = nullptr;
        const ProgramWireAutomationLaneRecord* lane = nullptr;
        std::size_t group_index = 0;
    };
    struct CapacityGroup {
        std::size_t first_lane = 0;
        std::size_t lane_count = 0;
    };
    struct LaneHighWater {
        timeline::ItemId lane_id;
        ProgramGeneration generation = 0;
    };
 
    std::span<ProgramWireLaneState> lane_state_;
    ProgramWireBytePin active_pin_;
    ProgramWireView active_view_;
    const timebase::CompiledTempoMap* tempo_map_ = nullptr;
    std::size_t lane_count_ = 0;
    std::size_t track_capacity_ = 0;
    std::size_t wire_byte_capacity_ = 0;
    std::array<ActiveLane, kProgramWireMaximumAutomationLanes> active_lanes_{};
    std::array<CapacityGroup, kProgramWireMaximumAutomationLanes> groups_{};
    std::array<std::size_t, kProgramWireMaximumAutomationLanes>
        group_lane_indices_{};
    std::size_t group_count_ = 0;
    std::array<LaneHighWater, kProgramWireMaximumAutomationLanes * 2u> lane_high_water_{};
    std::uint64_t lane_high_water_epoch_ = 0;
    std::array<ProgramWireLaneState*, kProgramWireMaximumAutomationLanes>
        merge_heap_{};
};
 
} // namespace pulp::playback