latch.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/midi/utility_contract.hpp>
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <optional>
 
namespace pulp::midi {

enum class LatchMode : std::uint8_t {
    Off,
    Hold,
    Toggle,
};
 
struct LatchSpec {
    LatchMode mode = LatchMode::Off;
    constexpr auto operator<=>(const LatchSpec&) const = default;
};

class Latch {
  public:
    static constexpr std::size_t kKeySpace = 16 * 128;
 
    static constexpr MidiUtilityContract contract() noexcept {
        return {2, kKeySpace, MidiUtilityOverflowPolicy::FailOpenBalanced,
                MidiUtilitySameSampleOrder::ReleaseBeforeAttack,
                MidiUtilityTransportRequirement::FlushOnDiscontinuity};
    }
 
    static constexpr bool valid_spec(LatchSpec spec) noexcept {
        return spec.mode == LatchMode::Off || spec.mode == LatchMode::Hold ||
               spec.mode == LatchMode::Toggle;
    }
 
    explicit constexpr Latch(LatchSpec spec = {}) noexcept
        : spec_(spec), valid_(valid_spec(spec)) {}
 
    constexpr bool valid() const noexcept {
        return valid_;
    }
 
    constexpr LatchSpec spec() const noexcept {
        return spec_;
    }
 
    MidiUtilityProcessReport process(const MidiBuffer& input, MidiBuffer& output) noexcept {
        if (utility_detail::blocks_alias(input, output))
            return {0, input.size(), 0, false};
        utility_detail::clear_output(output);
        MidiUtilityProcessReport report;
        if (!utility_detail::ready(output) || !valid_) {
            report.dropped = input.size();
            report.complete = false;
            return report;
        }
        drain_pending_releases(output, report);
        for (const auto& event : input) {
            const bool is_attack = event.is_note_on() && event.velocity() != 0;
            const bool is_release =
                event.is_note_off() || (event.is_note_on() && event.velocity() == 0);
            if (!is_attack && !is_release) {
                utility_detail::emit(output, event, report);
                continue;
            }
            const int key = utility_detail::key_index(event.channel(), event.note());
            if (is_attack)
                handle_attack(key, event, output, report);
            else
                handle_release(key, event, output, report);
        }
        utility_detail::copy_sidecars(input, output, report);
        output.sort();
        return report;
    }

    MidiUtilityProcessReport flush(MidiBuffer& output) noexcept {
        utility_detail::clear_output(output);
        MidiUtilityProcessReport report;
        if (!utility_detail::ready(output)) {
            report.complete = false;
            return report;
        }
        drain_pending_releases(output, report);
        if (pending_release_total_ != 0)
            return report;
        for (std::size_t key = 0; key < kKeySpace && owned_total_ != 0; ++key) {
            while (owned_depth_[key] != 0) {
                if (!utility_detail::emit(output, note_off_for(key), report)) {
                    ++report.deferred;
                    report.complete = false;
                    return report;
                }
                --owned_depth_[key];
                --owned_total_;
            }
        }
        physical_depth_.fill(0);
        physical_down_ = 0;
        report.complete = empty();
        if (report.complete && pending_spec_) {
            spec_ = *pending_spec_;
            valid_ = true;
            pending_spec_.reset();
        }
        return report;
    }
 
    MidiUtilityProcessReport reset(MidiBuffer& output) noexcept {
        return flush(output);
    }

    MidiUtilityProcessReport replace_spec(LatchSpec spec, MidiBuffer& output) noexcept {
        if (!valid_spec(spec)) {
            utility_detail::clear_output(output);
            return {0, 0, 0, false};
        }
        auto report = flush(output);
        if (report.complete) {
            spec_ = spec;
            valid_ = true;
            pending_spec_.reset();
        } else {
            pending_spec_ = spec;
        }
        return report;
    }
 
    bool empty() const noexcept {
        return owned_total_ == 0;
    }

    std::uint32_t owned_depth(std::uint8_t channel, std::uint8_t note) const noexcept {
        return owned_depth_[static_cast<std::size_t>(utility_detail::key_index(channel, note))];
    }
 
  private:
    void handle_attack(int key, const MidiEvent& event, MidiBuffer& output,
                       MidiUtilityProcessReport& report) noexcept {
        if (spec_.mode == LatchMode::Off) {
            if (utility_detail::emit(output, event, report))
                acquire(key);
            increment(physical_depth_[static_cast<std::size_t>(key)]);
            increment(physical_down_);
            return;
        }
        if (spec_.mode == LatchMode::Hold && physical_down_ == 0)
            release_all_owned(event.sample_offset, output, report);
        if (spec_.mode == LatchMode::Hold && physical_depth_[static_cast<std::size_t>(key)] == 0 &&
            owned_depth_[static_cast<std::size_t>(key)] != 0) {
            // Hold mode keeps one sounding voice per key. A re-press while
            // another physical key is held updates physical ownership but
            // does not retrigger the already latched voice.
            increment(physical_depth_[static_cast<std::size_t>(key)]);
            increment(physical_down_);
            return;
        }
        if (spec_.mode == LatchMode::Toggle &&
            owned_depth_[static_cast<std::size_t>(key)] != 0) {
            // A second press on a latched key releases it and consumes the
            // attack, so the key stops sounding instead of retriggering.
            release_key(key, event.sample_offset, output, report);
            increment(physical_depth_[static_cast<std::size_t>(key)]);
            increment(physical_down_);
            return;
        }
        if (utility_detail::emit(output, event, report))
            acquire(key);
        increment(physical_depth_[static_cast<std::size_t>(key)]);
        increment(physical_down_);
    }
 
    void handle_release(int key, const MidiEvent& event, MidiBuffer& output,
                        MidiUtilityProcessReport& report) noexcept {
        auto& physical = physical_depth_[static_cast<std::size_t>(key)];
        if (physical != 0) {
            --physical;
            if (physical_down_ != 0)
                --physical_down_;
        }
        if (spec_.mode == LatchMode::Off) {
            if (utility_detail::emit(output, event, report))
                surrender(key);
            else
                queue_pending_release(key);
            return;
        }
        // Retained: the latch, not the player, decides when this note ends.
        ++report.deferred;
    }
 
    void release_key(int key, std::int32_t sample_offset, MidiBuffer& output,
                     MidiUtilityProcessReport& report) noexcept {
        while (owned_depth_[static_cast<std::size_t>(key)] != 0) {
            auto off =
                utility_detail::at(note_off_for(static_cast<std::size_t>(key)), sample_offset);
            if (!utility_detail::emit(output, off, report)) {
                ++report.deferred;
                report.complete = false;
                return;
            }
            surrender(key);
        }
    }

    void acquire(int key) noexcept {
        auto& depth = owned_depth_[static_cast<std::size_t>(key)];
        if (depth == std::numeric_limits<std::uint32_t>::max())
            return;
        ++depth;
        increment(owned_total_);
    }
 
    void surrender(int key) noexcept {
        auto& depth = owned_depth_[static_cast<std::size_t>(key)];
        if (depth == 0)
            return;
        --depth;
        if (owned_total_ != 0)
            --owned_total_;
    }
 
    void release_all_owned(std::int32_t sample_offset, MidiBuffer& output,
                           MidiUtilityProcessReport& report) noexcept {
        // The retention table spans the whole key space so retention can never
        // overflow, which makes the scan the price of that guarantee. Counting
        // owned notes keeps the common case — a phrase start with nothing
        // retained — off the audio thread's critical path entirely.
        if (owned_total_ == 0)
            return;
        for (std::size_t key = 0; key < kKeySpace; ++key)
            release_key(static_cast<int>(key), sample_offset, output, report);
    }
 
    void queue_pending_release(int key) noexcept {
        auto& pending = pending_release_[static_cast<std::size_t>(key)];
        if (pending != std::numeric_limits<std::uint32_t>::max()) {
            ++pending;
            ++pending_release_total_;
        }
    }
 
    void drain_pending_releases(MidiBuffer& output, MidiUtilityProcessReport& report) noexcept {
        for (std::size_t key = 0; key < kKeySpace && pending_release_total_ != 0; ++key) {
            auto& pending = pending_release_[key];
            while (pending != 0) {
                if (!utility_detail::emit(output, note_off_for(key), report))
                    return;
                --pending;
                --pending_release_total_;
                surrender(static_cast<int>(key));
            }
        }
    }
 
    static MidiEvent note_off_for(std::size_t key) noexcept {
        return MidiEvent::note_off(static_cast<std::uint8_t>(key / 128),
                                   static_cast<std::uint8_t>(key % 128));
    }
 
    template <typename Counter> static void increment(Counter& value) noexcept {
        if (value != std::numeric_limits<Counter>::max())
            ++value;
    }
 
    LatchSpec spec_{};
    bool valid_ = true;
    std::optional<LatchSpec> pending_spec_{};
    std::array<std::uint32_t, kKeySpace> owned_depth_{};
    std::array<std::uint32_t, kKeySpace> physical_depth_{};
    std::array<std::uint32_t, kKeySpace> pending_release_{};
    std::uint32_t pending_release_total_ = 0;
    std::uint32_t physical_down_ = 0;
    std::uint32_t owned_total_ = 0;
};
 
} // namespace pulp::midi