Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
QtQuickClock.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
7#include <PhosphorAnimation/phosphoranimation_export.h>
8
9#include <QPointer>
10
11#include <atomic>
12#include <chrono>
13#include <memory>
14
15class QQuickWindow;
16
17namespace PhosphorAnimation {
18
118class PHOSPHORANIMATION_EXPORT QtQuickClock final : public IMotionClock
119{
120public:
126 explicit QtQuickClock(QQuickWindow* window);
127 ~QtQuickClock() override;
128
129 // IMotionClock
130 std::chrono::nanoseconds now() const override;
131 qreal refreshRate() const override;
132 void requestFrame() override;
133 const void* epochIdentity() const override;
134
136 QQuickWindow* window() const;
137
138private:
139 class SignalAdapter; // QObject helper defined in the .cpp
140 friend class SignalAdapter;
141
142 // Cached timestamp captured in the `beforeRendering` slot so
143 // `now()` returns the vsync-aligned reading for the frame being
144 // rendered. Written from the render thread by the SignalAdapter;
145 // may be read from the GUI thread (QML animation drivers that
146 // don't honour the render-thread-only contract). Stored as an atomic
147 // `nanoseconds::rep`, the duration's own representation, so nothing
148 // converts on the way in or out; the writer uses release and the
149 // reader uses acquire so a cross-thread reader sees a well-published
150 // value rather than just a tear-free one.
151 //
152 // `mutable` because the logically-const `now()` reader CAS-seeds
153 // the cache on the pre-handoff fallback path to guarantee
154 // monotonicity across the fallback→cache transition. Updating an
155 // internal cache from a const observer is the canonical mutable
156 // use case; the logical const contract ("now() returns the current
157 // time") is unaffected.
158 mutable std::atomic<std::chrono::nanoseconds::rep> m_nowCache{0};
159 // Set the first time `beforeRendering` fires — the render loop
160 // has become responsible for advancing `m_nowCache`. Until then
161 // `now()` falls back to reading `steady_clock` directly so an
162 // animation bound to a never-shown `QQuickWindow` (test mode,
163 // hidden offscreen render loop) doesn't freeze at the prime
164 // timestamp with dt=0 on every advance.
165 //
166 // One-shot: never flips back to false even if the window is
167 // hidden and `beforeRendering` stops firing. This is intentional —
168 // once the render loop has written a post-vsync-aligned timestamp
169 // into `m_nowCache`, subsequent `now()` readers should see THAT
170 // reading (via the cache load) instead of a fresh `steady_clock`
171 // read that might skew ahead of the last paint by an entire hidden
172 // frame budget. If the window is later re-shown the next
173 // `beforeRendering` fire overwrites the cache with a fresh
174 // vsync-aligned reading; readers during the hidden interval see a
175 // stale-but-monotonic timestamp, which produces `dt=0` progressions
176 // (correct — nothing is rendering, so no motion) rather than
177 // spurious forward steps. If a consumer needs to release resources
178 // on window hide, the QObject destroyed signal is the right hook —
179 // not the clock's internal latch.
180 std::atomic<bool> m_renderLoopActive{false};
181 QPointer<QQuickWindow> m_window;
182 std::unique_ptr<SignalAdapter> m_adapter;
183
184 // One-shot latch for the release-build half of `refreshRate()`'s GUI-thread contract.
185 // The Q_ASSERT_X there aborts a debug build; without this a release build would walk
186 // Qt's platform screen list off-thread instead, which is debug-only safety on exported
187 // API. `mutable` because refreshRate() is const, and atomic because the contract it
188 // reports on is precisely that the caller may be on another thread. Latched: a consumer
189 // that gets the thread wrong gets it wrong on every frame.
190 mutable std::atomic<bool> m_refreshRateThreadWarned{false};
191};
192
193} // namespace PhosphorAnimation
IMotionClock(const IMotionClock &)=delete
const void * epochIdentity() const override
Opaque epoch identity for rebindClock compatibility.
void requestFrame() override
Schedule another paint tick. Idempotent within a single frame.
std::chrono::nanoseconds now() const override
Monotonically non-decreasing steady-clock reading (nanoseconds).
friend class SignalAdapter
Definition QtQuickClock.h:140
QtQuickClock(QQuickWindow *window)
Construct a clock bound to window.
QQuickWindow * window() const
The QQuickWindow this clock is bound to. May be null.
qreal refreshRate() const override
Nominal refresh rate in Hz, or zero if unknown.
Definition AnimatedValue.h:32