QtQuickClock.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorAnimation/IMotionClock.h>
#include <PhosphorAnimation/phosphoranimation_export.h>
 
#include <QPointer>
 
#include <atomic>
#include <chrono>
#include <memory>
 
class QQuickWindow;
 
namespace PhosphorAnimation {
 
class PHOSPHORANIMATION_EXPORT QtQuickClock final : public IMotionClock
{
public:
    explicit QtQuickClock(QQuickWindow* window);
    ~QtQuickClock() override;
 
    // IMotionClock
    std::chrono::nanoseconds now() const override;
    qreal refreshRate() const override;
    void requestFrame() override;
    const void* epochIdentity() const override;
 
    QQuickWindow* window() const;
 
private:
    class SignalAdapter; // QObject helper defined in the .cpp
    friend class SignalAdapter;
 
    // Cached timestamp captured in the `beforeRendering` slot so
    // `now()` returns the vsync-aligned reading for the frame being
    // rendered. Written from the render thread by the SignalAdapter;
    // may be read from the GUI thread (QML animation drivers that
    // don't honour the render-thread-only contract). Stored as
    // atomic<int64_t>; the writer uses release and the reader uses
    // acquire so a cross-thread reader sees a well-published value
    // rather than just a tear-free one.
    //
    // `mutable` because the logically-const `now()` reader CAS-seeds
    // the cache on the pre-handoff fallback path to guarantee
    // monotonicity across the fallback→cache transition. Updating an
    // internal cache from a const observer is the canonical mutable
    // use case; the logical const contract ("now() returns the current
    // time") is unaffected.
    mutable std::atomic<std::chrono::nanoseconds::rep> m_nowCache{0};
    // Set the first time `beforeRendering` fires — the render loop
    // has become responsible for advancing `m_nowCache`. Until then
    // `now()` falls back to reading `steady_clock` directly so an
    // animation bound to a never-shown `QQuickWindow` (test mode,
    // hidden offscreen render loop) doesn't freeze at the prime
    // timestamp with dt=0 on every advance.
    //
    // One-shot: never flips back to false even if the window is
    // hidden and `beforeRendering` stops firing. This is intentional —
    // once the render loop has written a post-vsync-aligned timestamp
    // into `m_nowCache`, subsequent `now()` readers should see THAT
    // reading (via the cache load) instead of a fresh `steady_clock`
    // read that might skew ahead of the last paint by an entire hidden
    // frame budget. If the window is later re-shown the next
    // `beforeRendering` fire overwrites the cache with a fresh
    // vsync-aligned reading; readers during the hidden interval see a
    // stale-but-monotonic timestamp, which produces `dt=0` progressions
    // (correct — nothing is rendering, so no motion) rather than
    // spurious forward steps. If a consumer needs to release resources
    // on window hide, the QObject destroyed signal is the right hook —
    // not the clock's internal latch.
    std::atomic<bool> m_renderLoopActive{false};
    QPointer<QQuickWindow> m_window;
    std::unique_ptr<SignalAdapter> m_adapter;
};
 
} // namespace PhosphorAnimation