event_compensation.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/playback/program.hpp>
#include <pulp/playback/transport.hpp>
#include <pulp/timebase/rational_time.hpp>
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <span>
 
namespace pulp::playback {

struct EventCompensationShift {
    std::int64_t samples = 0;
 
    constexpr bool compensating() const noexcept {
        return samples != 0;
    }
    constexpr bool operator==(const EventCompensationShift&) const noexcept = default;
};
 
enum class EventCompensationCode : std::uint8_t {
    Ok,
    NegativeDeviceLatency,
    DeviceLatencyOutOfRange,
    ChainShiftOutOfRange,
};
 
struct EventCompensationResult {
    EventCompensationCode code = EventCompensationCode::Ok;
    EventCompensationShift shift{};
    std::int64_t actual = 0;
    std::int64_t limit = 0;
    std::size_t index = 0;
 
    constexpr explicit operator bool() const noexcept {
        return code == EventCompensationCode::Ok;
    }
};

constexpr EventCompensationResult
accumulate_event_chain_shift(std::span<const int> device_latency_samples,
                             int ceiling_samples) noexcept {
    EventCompensationResult result;
    if (ceiling_samples < 0) {
        result.code = EventCompensationCode::ChainShiftOutOfRange;
        result.limit = ceiling_samples;
        return result;
    }
    const auto limit = static_cast<std::int64_t>(ceiling_samples);
    result.limit = limit;
    std::int64_t total = 0;
    for (std::size_t index = 0; index < device_latency_samples.size(); ++index) {
        const auto latency = static_cast<std::int64_t>(device_latency_samples[index]);
        if (latency < 0) {
            result.code = EventCompensationCode::NegativeDeviceLatency;
            result.actual = latency;
            result.index = index;
            return result;
        }
        if (latency > limit) {
            result.code = EventCompensationCode::DeviceLatencyOutOfRange;
            result.actual = latency;
            result.index = index;
            return result;
        }
        // Bounded by the ceiling on both the addend and the running total, so
        // the sum cannot overflow before the range check sees it.
        total += latency;
        if (total > limit) {
            result.code = EventCompensationCode::ChainShiftOutOfRange;
            result.actual = total;
            result.index = index;
            return result;
        }
    }
    result.shift = {total};
    return result;
}

constexpr timebase::SamplePosition shifted_range_origin(const TransportRange& range,
                                                        EventCompensationShift shift) noexcept {
    constexpr auto maximum = std::numeric_limits<std::int64_t>::max();
    constexpr auto minimum = std::numeric_limits<std::int64_t>::min();
    const auto origin = range.timeline_sample_start.value;
    if (shift.samples > 0 && origin > maximum - shift.samples)
        return {maximum};
    if (shift.samples < 0 && origin < minimum - shift.samples)
        return {minimum};
    return {origin + shift.samples};
}

constexpr bool range_admits_event_compensation(const TransportRange& range,
                                               EventCompensationShift shift) noexcept {
    return !shift.compensating() || !range.host_beat_mapping;
}

constexpr bool loop_admits_event_compensation(const TransportRange& range,
                                              EventCompensationShift shift,
                                              timebase::SamplePosition loop_end_samples) noexcept {
    if (!shift.compensating())
        return true;
    const auto origin = shifted_range_origin(range, shift);
    const auto frames = static_cast<std::int64_t>(range.frame_count);
    return origin.value <= loop_end_samples.value - frames;
}

struct CompensatedReadSegment {
    timebase::SamplePosition document_start{};
    std::uint32_t frame_count = 0;
    std::uint32_t range_offset = 0;
    std::uint64_t pass_offset = 0;
};

struct CompensatedReadPlan {
    std::array<CompensatedReadSegment, 2> segments{};
    std::uint8_t segment_count = 0;
    bool wraps_inside_range = false;
};

constexpr CompensatedReadPlan plan_compensated_read(const TransportRange& range,
                                                    EventCompensationShift shift) noexcept {
    CompensatedReadPlan plan;
    plan.segments[0] = {shifted_range_origin(range, shift), range.frame_count, 0, 0};
    plan.segment_count = 1;
    return plan;
}

constexpr CompensatedReadPlan
plan_compensated_read(const TransportRange& range, EventCompensationShift shift,
                      timebase::SamplePosition loop_start_samples,
                      timebase::SamplePosition loop_end_samples) noexcept {
    CompensatedReadPlan plan;
    auto start = shifted_range_origin(range, shift);
    const auto length = loop_end_samples.value - loop_start_samples.value;
    if (length <= 0)
        return plan_compensated_read(range, shift);
    const auto span = static_cast<std::uint64_t>(length);
    std::uint64_t pass_offset = 0;
    if (start.value >= loop_end_samples.value) {
        const auto past = static_cast<std::uint64_t>(start.value - loop_start_samples.value);
        pass_offset = past / span;
        start = {loop_start_samples.value + static_cast<std::int64_t>(past % span)};
    }
    auto head = range.frame_count;
    if (start.value < loop_end_samples.value) {
        const auto until_wrap = static_cast<std::uint64_t>(loop_end_samples.value - start.value);
        if (until_wrap < head)
            head = static_cast<std::uint32_t>(until_wrap);
    }
    plan.segments[0] = {start, head, 0, pass_offset};
    plan.segment_count = 1;
    if (head < range.frame_count) {
        plan.segments[1] = {loop_start_samples, range.frame_count - head, head, pass_offset + 1};
        plan.segment_count = 2;
        plan.wraps_inside_range = true;
    }
    return plan;
}

constexpr bool event_compensation_admits_live_input(EventCompensationShift shift,
                                                    ProviderSelectorProgram provider) noexcept {
    return !shift.compensating() || !provider.available(ProviderKind::ExternalInput);
}
 
} // namespace pulp::playback