The ring-buffer pointer sampler both hosts feed: the compositor from slotMouseChanged, the preview from its figure-eight driver. More...
#include <PhosphorPointer/PointerHistory.h>
Public Member Functions | |
| PointerHistory () | |
| void | setTrailSeconds (double seconds) |
| The window the ring must span, in seconds: the furthest back any pack this history feeds actually READS, which is not the same as how long those packs stay live. | |
| double | trailSeconds () const |
| The window currently in force. | |
| qint64 | sampleIntervalMs () const |
| Minimum gap between two appended samples, in ms. | |
| void | notePointer (const QPointF &devicePx, qint64 nowMs) |
Record a pointer position at nowMs (see the sampling rule above). | |
| void | seedPosition (const QPointF &devicePx, qint64 nowMs) |
| Give an EMPTY ring a position without recording motion: the slot lands (age 0, speed 0, not a motion sample) so the first live frame has a pointer to hand out, while the idle clock, the velocity pairing and the filtered speed stay untouched. | |
| void | noteButtons (Qt::MouseButtons now, Qt::MouseButtons before, const QPointF &devicePx, qint64 nowMs) |
Record a button transition from before to now at devicePx. | |
| PointerFrameState | frameState (qint64 nowMs, double scale) const |
The contract tail for a frame at nowMs with canvas scale scale. | |
| bool | isLive (qint64 nowMs, double trailSeconds) const |
True while a motion or button event is younger than trailSeconds. | |
| QRectF | damageRect (double reachDevicePx, qint64 nowMs, double trailSeconds) const |
Bounding box of the trail samples, press and release points younger than trailSeconds, inflated by reachDevicePx on every side plus the overshoot the packs' curve is allowed outside the straight path between those samples. | |
| void | reset () |
Static Public Attributes | |
| static constexpr int | kCapacity = PointerShaderContract::kMaxTrailPoints |
| static constexpr double | kMinSampleDistancePx = 1.0 |
| DEVICE px, deliberately, like every other position in this class: the ring stores device px and the packs read them, so a cutoff in logical px would be the one quantity here that changed meaning with the output scale. | |
| static constexpr qint64 | kMinSampleGapMs = 8 |
| static constexpr double | kMaxTrailSeconds = 3600.0 |
| Upper bound on the accepted trail window. | |
| static constexpr double | kVelocityMinDtSeconds = 0.001 |
| Floor on the dt a speed is divided by, guarding against a zero or denormal gap between two events that arrive in the same millisecond. | |
| static constexpr qint64 | kVelocityHoldMs = 100 |
| How long after the newest sample the velocity is still reported, and the longest gap between two samples that still forms a speed pairing. | |
| static constexpr double | kSpeedFilterTauSeconds = 0.05 |
| Time constant of the speed filter (filteredSpeed()), in seconds. | |
The ring-buffer pointer sampler both hosts feed: the compositor from slotMouseChanged, the preview from its figure-eight driver.
It keeps the last kMaxTrailPoints position samples plus the last press and release (positions, because the ring also carries the slots a resting pointer and a bare seed leave, which the motion flag tells apart), and answers the per-frame questions the contract needs (frameState), whether a chain still needs frames (isLive) and where it may paint (damageRect).
Positions are in device px of the canvas the caller chose; timestamps are caller-supplied milliseconds on one monotonic clock.
Sampling rule: the ring has kCapacity slots and has to cover the pack's whole trailSeconds window with them, so notePointer appends a new sample only when the gap since the newest one is at least the sample interval (sampleIntervalMs, derived from setTrailSeconds: the window spread over kCapacity - 1 gaps, never under kMinSampleGapMs). An event inside that gap that has moved at least 1 device px REFRESHES the newest sample in place, so index 0 is always exactly where the pointer is, and a sub-pixel drift inside the gap is dropped. "Moved" is measured against the last ACCEPTED event (the head slot when there is none), so a creep of under a pixel per interval accumulates into a move rather than ageing the idle clock. (A stamp more than kVelocityHoldMs behind the previous event is read as a CLOCK STEP rather than a shared tick: it skips the interval gate and appends, re-anchoring the ring on the new timeline. Neither shipped host can produce one, since both feed a monotonic clock, but this is exported API.) Without the interval a 1000 Hz mouse filled all 32 slots in 32 ms, and a pack's tail could never be longer than that however long its length parameter asked for. A sample appended once the interval has passed WITHOUT the pointer having moved a pixel (any host that keeps feeding while the pointer is still, or a drift slower than a pixel per interval) keeps the ring's minimum sampling rate but is not motion: it neither resets the idle clock nor becomes a velocity pairing, so a resting pointer idles the same way on both hosts. Ages are computed at frameState time. Velocity is the finite difference over the last two ACCEPTED events (appended or folded into the head alike) with a floor of kVelocityMinDtSeconds on dt, and the head sample's speed is scored over the same pairing so the two agree. An event stamped at or just before the previous accepted one — the same millisecond, or a clock nudged back by less than kVelocityHoldMs — is not a usable pairing (nothing can be divided over it), so it carries the previous event's speed and leaves the pairing where it was, and the next event pairs across both moves; a multi-kHz mouse then reads its true speed instead of a zero for every event that shared a millisecond.
A stamp further back than that is a clock DISCONTINUITY, not a shared tick, and is handled the opposite way: it is accepted at speed 0 and re-anchors the pairing. Carrying it as a shared tick would leave the pairing frozen, so no event for the length of the step would be accepted and the idle clock would stand still while the pointer was plainly moving. Both shipped hosts feed a monotonic clock and cannot reach this.
A gap of kVelocityHoldMs or more (the pointer was parked) records speed 0, starts the pairing fresh rather than averaging the move over the idle time, and marks the sample as the START OF A STROKE.
The frame state also carries filteredSpeed, the same exponential filter the shared shader library used to walk per fragment, computed here once per frame over the current stroke: the motion samples back from the head to the nearest stroke start. Marking the start at the event, from the event gap, is what makes this independent of how far apart the ring's slots are: a shader-side walk over sample ages had to guess a pause from a gap, and at a long window every slot gap looked like one. Samples appended while the pointer rested are not motion and are skipped, so a host that keeps feeding through a rest holds the filtered speed across it the way the compositor does, for as long as the chain is live. Rest long enough and the rest slots rotate the last motion sample out of the ring and the figure reads zero, which is just past the point where any pack is still drawing, and further past whenever the interval is on its floor or set by a longer pack in the chain. The packs' own idle fades end the drawing, not the gate.
The interval is one per chain, from its LONGEST read window, so a chain that mixes a short pack with a long one samples at the long pack's spacing and the short pack draws its tail from a few slots plus the refreshed head. A per-layer spread would need a ring per layer. Every recency window in this class is a strict <: velocity is reported while the newest sample is younger than kVelocityHoldMs, the chain is live while an event is younger than trailSeconds, and the damage rect includes a point while it is younger than trailSeconds. At exactly the bound the window has closed.
| PhosphorPointerShaders::PointerHistory::PointerHistory | ( | ) |
|
nodiscard |
Bounding box of the trail samples, press and release points younger than trailSeconds, inflated by reachDevicePx on every side plus the overshoot the packs' curve is allowed outside the straight path between those samples.
Null when not live.
|
nodiscard |
The contract tail for a frame at nowMs with canvas scale scale.
cursorRect and hasSprite are left at their defaults for the host to fill.
Every slot the ring holds is emitted, INCLUDING entries older than the trail window, while damageRect counts only the ones inside it. So a pack that draws every entry without gating on .z paints outside the rect the host asked to repaint, and the surplus is never cleaned up. Events arriving slower than the sample interval are the ordinary way the ring comes to span longer than its window. Gate on age.
A caller feeding a non-monotonic clock can also leave entries stamped in the FUTURE after a step. Those report age 0, because the age is floored, until they rotate out over one ring's worth of appends, so they read as newer than the head. damageRect counts those too, which over-repaints rather than under-repaints.
|
nodiscard |
True while a motion or button event is younger than trailSeconds.
| void PhosphorPointerShaders::PointerHistory::noteButtons | ( | Qt::MouseButtons | now, |
| Qt::MouseButtons | before, | ||
| const QPointF & | devicePx, | ||
| qint64 | nowMs ) |
Record a button transition from before to now at devicePx.
A newly pressed button becomes the last press (left, then right, then middle when several land at once) and a newly released one the last release. The pressed-button mask always tracks now.
| void PhosphorPointerShaders::PointerHistory::notePointer | ( | const QPointF & | devicePx, |
| qint64 | nowMs ) |
Record a pointer position at nowMs (see the sampling rule above).
A non-finite position is dropped: see the note in the implementation.
| void PhosphorPointerShaders::PointerHistory::reset | ( | ) |
|
inlinenodiscard |
Minimum gap between two appended samples, in ms.
Derived from trailSeconds(), and like it read by the tests rather than the hosts.
| void PhosphorPointerShaders::PointerHistory::seedPosition | ( | const QPointF & | devicePx, |
| qint64 | nowMs ) |
Give an EMPTY ring a position without recording motion: the slot lands (age 0, speed 0, not a motion sample) so the first live frame has a pointer to hand out, while the idle clock, the velocity pairing and the filtered speed stay untouched.
The compositor seeds from a buttons-only event after a reset this way; a ring with samples is left alone.
| void PhosphorPointerShaders::PointerHistory::setTrailSeconds | ( | double | seconds | ) |
The window the ring must span, in seconds: the furthest back any pack this history feeds actually READS, which is not the same as how long those packs stay live.
Sets the sample interval (see the sampling rule above). 0 (the default, and what a chain of packs that read nothing gives) means the kMinSampleGapMs floor alone. Survives reset().
|
inlinenodiscard |
The window currently in force.
Read by the tests that pin the sampling arithmetic; the hosts set it and do not read it back.
|
staticconstexpr |
|
staticconstexpr |
Upper bound on the accepted trail window.
Not a policy limit — the pack schema caps trailSeconds far below it — but the value that keeps the interval arithmetic in setTrailSeconds defined for any caller of this exported class.
|
staticconstexpr |
DEVICE px, deliberately, like every other position in this class: the ring stores device px and the packs read them, so a cutoff in logical px would be the one quantity here that changed meaning with the output scale.
The consequence is that a HiDPI output resolves a slower drift as motion than a 1x one does, which is the same asymmetry the trail positions themselves already carry.
|
staticconstexpr |
|
staticconstexpr |
Time constant of the speed filter (filteredSpeed()), in seconds.
A TIME constant, not a per-sample blend factor. The filter used to fold each sample in with a fixed weight, which made its response depend on how far apart the samples happened to be, and the sampler spaces them by the trail window (see the sampling rule above). The same hand movement therefore filtered over about 49 ms at a 0.9 s window and about 210 ms at a 4 s one, so activationSpeed and every other gate read from this figure behaved differently depending on a setting in a pack that may not even be the one being gated. Weighting by the real gap removes that: the figure now answers to the pointer, not to the window it is being watched through.
50 ms reproduces what the old blend did at the common 0.9 s window, where samples land about 30 ms apart: 1 - exp(-0.030 / 0.050) = 0.45, against the 0.46 the fixed blend used. So the default setting behaves as it always has and only the other windows move.
|
staticconstexpr |
How long after the newest sample the velocity is still reported, and the longest gap between two samples that still forms a speed pairing.
Past it the pointer is parked and the next sample starts fresh: a 5 px move after ten idle seconds is a fresh move, not 0.5 px/s.
|
staticconstexpr |
Floor on the dt a speed is divided by, guarding against a zero or denormal gap between two events that arrive in the same millisecond.
It must stay far below the real sampling interval. The distance is NOT floored alongside it, so whenever the sampler runs faster than 1/kVelocityMinDtSeconds every speed is under-reported by exactly dt/kVelocityMinDtSeconds. This was 1/30 s, which is slower than any real source: a 60 Hz motion stream reported half the true speed and a 125 Hz mouse a quarter of it, so activationSpeed and every other px-per-second parameter meant nothing like px per second. 1 ms clears a 1000 Hz mouse. Noise in the resulting figure is the exponential filter's job (filteredSpeed(), which the shader library reads as pointerFilteredSpeed()), not this floor's.