Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PointerHistory.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
8#include <PhosphorPointer/phosphorpointer_export.h>
9
10#include <QPointF>
11#include <QRectF>
12#include <Qt>
13
14#include <array>
15
16namespace PhosphorPointerShaders {
17
94class PHOSPHORPOINTER_EXPORT PointerHistory
95{
96public:
104 static constexpr double kMinSampleDistancePx = 1.0;
105 static constexpr qint64 kMinSampleGapMs = 8;
106 // kCapacity is an alias for a contract constant that lives in another
107 // header, and setTrailSeconds divides by kCapacity - 1.
108 static_assert(kCapacity > 1, "the sample interval divides by kCapacity - 1");
113 static constexpr double kMaxTrailSeconds = 3600.0;
127 static constexpr double kVelocityMinDtSeconds = 0.001;
132 static constexpr qint64 kVelocityHoldMs = 100;
150 static constexpr double kSpeedFilterTauSeconds = 0.05;
151
153
159 void setTrailSeconds(double seconds);
162 [[nodiscard]] double trailSeconds() const
163 {
164 return m_trailSeconds;
165 }
166
168 [[nodiscard]] qint64 sampleIntervalMs() const
169 {
170 return m_sampleIntervalMs;
171 }
172
175 void notePointer(const QPointF& devicePx, qint64 nowMs);
176
183 void seedPosition(const QPointF& devicePx, qint64 nowMs);
184
189 void noteButtons(Qt::MouseButtons now, Qt::MouseButtons before, const QPointF& devicePx, qint64 nowMs);
190
207 [[nodiscard]] PointerFrameState frameState(qint64 nowMs, double scale) const;
208
210 [[nodiscard]] bool isLive(qint64 nowMs, double trailSeconds) const;
211
216 [[nodiscard]] QRectF damageRect(double reachDevicePx, qint64 nowMs, double trailSeconds) const;
217
218 void reset();
219
220private:
221 struct Sample
222 {
223 QPointF pos;
224 qint64 timeMs = 0;
228 qint64 anchorMs = 0;
229 double speed = 0.0;
233 bool motion = true;
237 bool strokeStart = false;
238 };
239
240 const Sample& sampleAt(int newestFirstIndex) const;
241 static double secondsBetween(qint64 laterMs, qint64 earlierMs);
244 static double speedOver(const QPointF& earlierPos, qint64 earlierMs, const QPointF& devicePx, qint64 nowMs);
248 void acceptEvent(const QPointF& devicePx, qint64 nowMs, double speed, bool hasPrev, const QPointF& prevPos,
249 qint64 prevMs);
252 [[nodiscard]] double filteredSpeed() const;
253
254 double m_trailSeconds = 0.0;
255 qint64 m_sampleIntervalMs = kMinSampleGapMs;
256
257 std::array<Sample, kCapacity> m_ring{};
258 int m_head = 0;
259 int m_count = 0;
260
261 qint64 m_lastMotionMs = 0;
262 bool m_hasMotion = false;
263
267 QPointF m_lastEventPos;
268 qint64 m_lastEventMs = 0;
269 double m_lastEventSpeed = 0.0;
270 QPointF m_prevEventPos;
271 qint64 m_prevEventMs = 0;
272 bool m_hasPrevEvent = false;
273
274 QPointF m_pressPos;
275 qint64 m_pressMs = 0;
276 int m_pressButton = 0;
277 bool m_hasPress = false;
278
279 QPointF m_releasePos;
280 qint64 m_releaseMs = 0;
281 int m_releaseButton = 0;
282 bool m_hasRelease = false;
283
284 int m_buttonsMask = 0;
285};
286
287} // namespace PhosphorPointerShaders
double trailSeconds() const
The window currently in force.
Definition PointerHistory.h:162
static constexpr qint64 kVelocityHoldMs
How long after the newest sample the velocity is still reported, and the longest gap between two samp...
Definition PointerHistory.h:132
static constexpr qint64 kMinSampleGapMs
Definition PointerHistory.h:105
qint64 sampleIntervalMs() const
Minimum gap between two appended samples, in ms.
Definition PointerHistory.h:168
static constexpr int kCapacity
Definition PointerHistory.h:97
static constexpr double kVelocityMinDtSeconds
Floor on the dt a speed is divided by, guarding against a zero or denormal gap between two events tha...
Definition PointerHistory.h:127
void noteButtons(Qt::MouseButtons now, Qt::MouseButtons before, const QPointF &devicePx, qint64 nowMs)
Record a button transition from before to now at devicePx.
static constexpr double kMaxTrailSeconds
Upper bound on the accepted trail window.
Definition PointerHistory.h:113
void setTrailSeconds(double seconds)
The window the ring must span, in seconds: the furthest back any pack this history feeds actually REA...
void seedPosition(const QPointF &devicePx, qint64 nowMs)
Give an EMPTY ring a position without recording motion: the slot lands (age 0, speed 0,...
PointerFrameState frameState(qint64 nowMs, double scale) const
The contract tail for a frame at nowMs with canvas scale scale.
QRectF damageRect(double reachDevicePx, qint64 nowMs, double trailSeconds) const
Bounding box of the trail samples, press and release points younger than trailSeconds,...
void notePointer(const QPointF &devicePx, qint64 nowMs)
Record a pointer position at nowMs (see the sampling rule above).
bool isLive(qint64 nowMs, double trailSeconds) const
True while a motion or button event is younger than trailSeconds.
static constexpr double kSpeedFilterTauSeconds
Time constant of the speed filter (filteredSpeed()), in seconds.
Definition PointerHistory.h:150
static constexpr double kMinSampleDistancePx
DEVICE px, deliberately, like every other position in this class: the ring stores device px and the p...
Definition PointerHistory.h:104
constexpr int kMaxTrailPoints
Ring capacity of uPointerTrail.
Definition PointerShaderContract.h:166
Definition PointerFrameState.h:16
Plain-data snapshot of everything the pointer contract's tail carries for one frame.
Definition PointerFrameState.h:27