host_drag_coalescer.hpp

Go to the documentation of this file.

// host_drag_coalescer.hpp — the host-side half of per-frame drag coalescing.
//
// `PointerCoalescer` collapses a STREAM and deliberately knows nothing about
// hosts. Every host that uses it still has to get the same four things right:
//
//   1. a fail-safe, so motion is never held when nothing will release it,
//   2. one dirty signal per HELD RUN rather than one per sample — the point of
//      coalescing is removing O(events) work, and an invalidation per sample
//      is exactly that work,
//   3. flush-before-handoff ordering at every path that ends a gesture, and
//   4. the counters that make "is coalescing actually on?" answerable, because
//      the fail-safe means a host that silently loses it looks *correct* and
//      merely runs at the old frame rate,
//   5. and the one rule that is NOT obvious: a RELATIVE motion delta must be
//      SUMMED across merged samples, never replaced by the last one. Keeping
//      only the survivor's delta silently shortens every relative drag in
//      proportion to how many samples were merged, which reads as "the knob
//      feels sluggish" and not as a dropped-input bug. Absolute position needs
//      no such care — the newest one is already the whole displacement — which
//      is exactly why the distinction is easy to miss.
//
// Those were written once, inline, in the standalone macOS window host. The
// macOS PLUG-IN editor host — the surface a musician actually drags in a DAW —
// got none of them, because it is a different ObjC class. That is what this
// type exists to stop: the rules live in one portable, headlessly testable
// place, and a host supplies only delivery.
//
// Diagnostics are not decoration here. (4) is the whole reason `stats()` is
// public: the standalone host lost coalescing once to a frame driver that
// never opted in, and because the fail-safe restored the old behaviour there
// was no crash, no log and no red test — only a measured 4x that reproduced on
// some runs and not others.
 
#pragma once
 
#include "pulp/view/pointer_coalescer.hpp"
 
#include <cstdint>
#include <functional>
 
namespace pulp::view {

class HostDragCoalescer {
  public:
    using Deliver = std::function<void(const PointerSample&)>;

    struct SubmitResult {
        bool arm_repaint = false;
        std::size_t delivered = 0;
    };
 
    struct Stats {
        std::uint64_t raw_samples = 0;
        std::uint64_t delivered_samples = 0;
        std::uint64_t flushes = 0;
        std::uint64_t merged_samples = 0;
    };

    void set_frame_driver_running(bool running, const Deliver& deliver);
 
    bool frame_driver_running() const {
        return frame_driver_running_;
    }

    SubmitResult submit(const PointerSample& sample, const Deliver& deliver);

    std::size_t flush_frame(const Deliver& deliver);

    void discard();
 
    bool has_pending() const {
        return coalescer_.has_pending();
    }
 
    const Stats& stats() const {
        return stats_;
    }
 
  private:
    std::size_t deliver_all_(std::vector<PointerSample>& samples, const Deliver& deliver);
    void apply_accumulated_movement_(std::vector<PointerSample>& samples);
    void accumulate_movement_(const PointerSample& sample);
 
    PointerCoalescer coalescer_;
    Stats stats_{};
    bool frame_driver_running_ = false;
    float pending_movement_x_ = 0.0f;
    float pending_movement_y_ = 0.0f;
    bool pending_has_movement_ = false;
};
 
} // namespace pulp::view