Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorPointerShaders::PointerHistory Class Reference

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.

Detailed Description

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.

Constructor & Destructor Documentation

◆ PointerHistory()

PhosphorPointerShaders::PointerHistory::PointerHistory ( )

Member Function Documentation

◆ damageRect()

QRectF PhosphorPointerShaders::PointerHistory::damageRect ( double reachDevicePx,
qint64 nowMs,
double trailSeconds ) const
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.

◆ frameState()

PointerFrameState PhosphorPointerShaders::PointerHistory::frameState ( qint64 nowMs,
double scale ) const
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.

◆ isLive()

bool PhosphorPointerShaders::PointerHistory::isLive ( qint64 nowMs,
double trailSeconds ) const
nodiscard

True while a motion or button event is younger than trailSeconds.

◆ noteButtons()

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.

◆ notePointer()

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.

◆ reset()

void PhosphorPointerShaders::PointerHistory::reset ( )

◆ sampleIntervalMs()

qint64 PhosphorPointerShaders::PointerHistory::sampleIntervalMs ( ) const
inlinenodiscard

Minimum gap between two appended samples, in ms.

Derived from trailSeconds(), and like it read by the tests rather than the hosts.

◆ seedPosition()

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.

◆ setTrailSeconds()

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().

◆ trailSeconds()

double PhosphorPointerShaders::PointerHistory::trailSeconds ( ) const
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.

Member Data Documentation

◆ kCapacity

int PhosphorPointerShaders::PointerHistory::kCapacity = PointerShaderContract::kMaxTrailPoints
staticconstexpr

◆ kMaxTrailSeconds

double PhosphorPointerShaders::PointerHistory::kMaxTrailSeconds = 3600.0
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.

◆ kMinSampleDistancePx

double PhosphorPointerShaders::PointerHistory::kMinSampleDistancePx = 1.0
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.

◆ kMinSampleGapMs

qint64 PhosphorPointerShaders::PointerHistory::kMinSampleGapMs = 8
staticconstexpr

◆ kSpeedFilterTauSeconds

double PhosphorPointerShaders::PointerHistory::kSpeedFilterTauSeconds = 0.05
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.

◆ kVelocityHoldMs

qint64 PhosphorPointerShaders::PointerHistory::kVelocityHoldMs = 100
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.

◆ kVelocityMinDtSeconds

double PhosphorPointerShaders::PointerHistory::kVelocityMinDtSeconds = 0.001
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.


The documentation for this class was generated from the following file: