pointer_coalescer.hpp

Go to the documentation of this file.

// pointer_coalescer.hpp — collapse a burst of pointer motion into one
// dispatch per presented frame.
//
// A host receives pointer motion at the input device's rate; it presents
// frames at the display's rate, or slower when a frame is expensive. Those two
// rates are independent, and when motion outruns presentation every extra
// sample costs a full delivery — hit test, handler invocation (which for a
// scripted UI means entering the JS engine), and an invalidation whose only
// effect is to re-dirty a surface that is already dirty. None of that work
// reaches the screen: only the last sample before the next presented frame is
// visible.
//
// Measured on Spectr Native Preview before this existed: at 60 input events
// per second — an ordinary hand-drag rate, not a synthetic one — the app
// presented 2.7 frames per second while issuing ~997 repaint requests per
// second, i.e. ~363 repaint requests per presented frame. Holding the button
// still (no motion) stayed at 7.5 fps, so it is the motion, not the gesture
// state, that costs.
//
// ── What this deliberately does NOT decide ──────────────────────────────────
//
// This type coalesces a STREAM. It knows nothing about views, hit testing, or
// dispatch, so it can be unit-tested without a window and reused by any host.
// The caller decides what a flushed sample means.
//
// It also does not assume the consumer can reconstruct skipped motion. Some
// consumers can: Spectr's band paint sends (start_band, current_band) and
// repaints that whole span every message, so dropping intermediate samples
// provably cannot leave gaps. Others cannot — anything that stamps one value
// per sample would draw a dotted line instead of a stroke. So a coalesced move
// carries the full merged `path` alongside the surviving position, and a
// consumer that needs the intermediate points can walk it. Nothing here forces
// the span interpretation into shared code.
 
#pragma once
 
#include "pulp/view/input_events.hpp"
#include "pulp/view/pointer_dispatch.hpp"
 
#include <cstddef>
#include <vector>
 
namespace pulp::view {

struct PointerSample {
    Point position{};
    std::vector<Point> path;
    std::uint16_t modifiers = 0;
    int click_count = 0;
    MousePhase phase = MousePhase::automatic;
    MouseButton button = MouseButton::left;
    PointerAttributes pointer{};

    bool is_motion() const {
        return phase == MousePhase::drag || phase == MousePhase::hover;
    }
};

class PointerCoalescer {
public:
    std::vector<PointerSample> submit(const PointerSample& sample);

    std::vector<PointerSample> flush_frame();

    bool has_pending() const { return has_pending_; }

    const std::vector<Point>& pending_path() const { return path_; }

    std::size_t last_merged_count() const { return last_merged_; }

    std::size_t total_merged() const { return total_merged_; }

    void reset();
 
private:
    std::vector<PointerSample> take_pending_();
 
    PointerSample pending_{};
    std::vector<Point> path_;
    bool has_pending_ = false;
    std::size_t merged_in_pending_ = 0;
    std::size_t last_merged_ = 0;
    std::size_t total_merged_ = 0;
};
 
}  // namespace pulp::view