fix(render): one fence per frame for the vertex ring; two qt6 adapter fixes

The persistent-mapped instance ring had three slots and recorded a fence per
upload, so a frame recycled a slot whose fence was recorded a few draws earlier
*in that same frame*: from the fourth of the demos' nine uploads on, each one
waited on the frame's own work. It is free on a driver that retires draws
promptly (the GLFW host, 1.07 ms/frame) and ~4 ms of the Qt widget's 7.11 ms
under llvmpipe, and it grows with the trace and cursor counts this library
exists for.

* The ring grows to cover a frame's upload count, the frame's write cursor is
  the ring index (so a frame writes 0, 1, 2, ... and never a slot twice), one
  fence is recorded after the frame's last draw, and the only wait is at the
  start of the next frame. A wait that times out, or a slot written with no
  fence ever recorded behind it, drops the store to the orphan path -- the
  treatment a refused fence already had -- so nothing is ever written into
  storage the GPU may still be reading.
* New test-only counters (PLOT_RING_STATS, the PLOT_PYRAMID_COUNT_* pattern:
  free functions, no member, so no consumer's layout changes) pin a frame's
  upload and wait counts. The new tests assert the frame's slot offsets are
  distinct, that the ring grew past its floor to cover the frame, and that a
  frame waits at most once per store -- read from the counters and from
  glClientWaitSync itself.
* qt6: print the unresolved entry-point names before the load-failure branch,
  which used to return first and leave the one failure this widget can have
  reporting nothing but a generic message.
* qt6: the cached pointer anchor is now in logical pixels and a move's delta is
  the logical difference scaled by the DPR in effect, so a scale change between
  two move events (the window dragged onto another monitor mid-drag) is no
  longer a cross-scale jump applied as a pan. The anchor moved into a
  toolkit-free unit (adapters/qt6/qt_pointer.hpp) with its own test.

GLFW demo headless: 1.07 -> 0.73 ms/frame. Qt widget under xvfb/llvmpipe:
7.1 -> 3.8 ms at dpr 1.0, 6.7 -> 3.6 ms at 1.25, with both upload paths still
rendering and the demo's scripted pan/box-zoom checks passing at both scales.

include/plot/render/buffer.hpp

@@ -35,10 +35,12 @@ static_assert(sizeof(TextInstance) == 4 * sizeof(f32), "text instance must stay
 /// - `Orphan`: the GL 3.3 baseline. Every upload re-specifies the store with a
 ///   null `glBufferData` (orphaning it, so the driver never has to wait for the
 ///   draw that is still reading the previous one) and then refills it.
-/// - `PersistentMapped`: GL 4.4 / ARB_buffer_storage. Three slots of immutable
-///   storage are mapped once and written directly, and the fence recorded after
-///   each slot's draw guards its reuse, so the render thread never waits on the
-///   GPU. The vertex array's attribute pointers move with the slot.
+/// - `PersistentMapped`: GL 4.4 / ARB_buffer_storage. Immutable storage is mapped
+///   once and written directly, one slot per upload. A slot is never written
+///   twice within a frame, one fence is recorded after the frame's last draw, and
+///   the only wait is at the start of the next frame -- so the render thread
+///   never synchronises with GPU work it has just issued. The vertex array's
+///   attribute pointers move with the slot.
 enum class UploadMode { Orphan, PersistentMapped };
 
 namespace detail {
@@ -50,11 +52,13 @@ namespace detail {
 /// `UploadMode` is live.
 class InstanceStore {
  public:
-  /// Slots the persistent ring rotates through. Three is the smallest ring that
-  /// lets a frame's draw finish while the CPU fills two more.
-  static constexpr u32 kSlots = 3;
-  /// Upper bound on the wait for a slot's draw to retire: a driver that has
-  /// stopped making progress must not stall the render thread forever.
+  /// Slots the persistent ring starts with. The floor, not the ring's size: it
+  /// grows to cover the uploads a frame actually performs (see `upload()`), and
+  /// never shrinks, so a steady workload grows it at most a logarithmic number of
+  /// times over the life of the store.
+  static constexpr u32 kInitialSlots = 3;
+  /// Upper bound on the wait for the previous frame's draws to retire: a driver
+  /// that has stopped making progress must not stall the render thread forever.
   static constexpr u64 kFenceWaitNs = 1'000'000'000ull;
 
   /// Creates the vertex buffer in `mode`. Reports `ErrorCode::Unsupported` while
@@ -64,19 +68,34 @@ class InstanceStore {
   /// store created that way on a machine without them would never draw.
   bool create(UploadMode mode, Status* st = nullptr) noexcept;
 
+  /// Starts a frame: waits, once, for the frame before it to retire the draws
+  /// that read the ring, so no slot about to be written can still be being read.
+  /// False when that wait timed out -- or when a slot was written without a fence
+  /// ever being recorded for it -- in which case the store has dropped to the
+  /// baseline path, which has no such hazard, and the caller reports it (see
+  /// `Renderer::begin_frame`).
+  ///
+  /// One wait covers every slot because no slot is written twice within a frame
+  /// (`upload()` grows the ring rather than wrapping it), so each slot this frame
+  /// touches was last written in the previous frame or earlier -- and the
+  /// previous frame's fence sits behind every draw that read one.
+  bool begin_frame() noexcept;
+
   /// Uploads `count` instances of `instance_bytes`. `Orphan` mode orphans and
-  /// refills; `PersistentMapped` mode writes the next slot of the ring, waiting
-  /// out any draw still reading it.
+  /// refills; `PersistentMapped` mode writes the next slot of the ring, growing
+  /// the ring first when the frame has already written all of its slots.
   void upload(const void* data, u32 count, usize instance_bytes) noexcept;
 
-  /// Records that the draw the caller just issued read the current slot, so the
-  /// fence guarding that slot's reuse ends up in the command stream behind the
-  /// draw. True when the slot is guarded, and always in `Orphan` mode, where
-  /// nothing reads the store after the orphan.
+  /// Records the frame's single fence, behind every draw that read the ring, so
+  /// the next `begin_frame()` can wait for them. Called once per frame, after the
+  /// last draw that consumes the store. True in `Orphan` mode, where nothing
+  /// reads the store after the orphan, and true when the frame drew nothing from
+  /// the ring.
   ///
-  /// False when the driver refused the fence: the slot would stay unsynchronised,
-  /// so the store drops the mapped ring for the orphan path instead of rotating
-  /// through it (the caller reports the failure -- see `Renderer`).
+  /// False when the driver refused the fence: the slots written this frame would
+  /// stay unsynchronised, so the store drops the mapped ring for the orphan path
+  /// instead of rotating through it (the caller reports the failure -- see
+  /// `Renderer::end_frame`).
   bool mark_drawn() noexcept;
 
   /// Byte offset the current slot's instances start at: 0 in `Orphan` mode,
@@ -101,24 +120,33 @@ class InstanceStore {
   bool persistent() const noexcept { return mode_ == UploadMode::PersistentMapped; }
 
  private:
-  /// Grows the mapped ring to `bytes` per slot. False when the driver refuses the
-  /// storage or the map, in which case the store has fallen back to a fresh
-  /// `Orphan` buffer and the frame still draws.
-  bool grow_persistent(usize bytes) noexcept;
-  /// Deletes every fence, unmaps and releases the GL buffer. `slot_bytes_` drops
-  /// to 0 so the next upload regrows.
+  /// (Re)allocates the mapped ring with `slots` slots of `bytes` each. False when
+  /// the driver refuses the storage or the map, in which case the store has fallen
+  /// back to a fresh `Orphan` buffer and the frame still draws.
+  bool grow_persistent(usize bytes, u32 slots) noexcept;
+  /// Deletes the frame fence, unmaps and releases the GL buffer. `slot_bytes_`
+  /// drops to 0 so the next upload regrows.
   void release_storage() noexcept;
+  /// Abandons the mapped ring for the baseline path and re-creates the empty
+  /// buffer that path needs. Used wherever the ring can no longer be guarded.
+  void drop_to_orphan() noexcept;
 
   gl::Buffer buffer_;
   UploadMode mode_ = UploadMode::Orphan;
-  u32 capacity_ = 0;        ///< instances the orphan store can hold
-  usize slot_bytes_ = 0;    ///< bytes per slot of the persistent ring
-  u32 slot_ = kSlots - 1u;  ///< last slot written; an upload advances it first
+  u32 capacity_ = 0;                ///< instances the orphan store can hold
+  usize slot_bytes_ = 0;            ///< bytes per slot of the persistent ring
+  u32 slot_count_ = kInitialSlots;  ///< slots the ring has; grows, never shrinks
+  u32 slot_ = 0;                    ///< slot the last upload wrote
+  /// Slots written since this frame began, and the index the next upload takes.
+  /// It is the ring index itself, which is what keeps a frame's slots distinct.
+  u32 frame_uploads_ = 0;
   /// Times an upload landed in a new slot. Kept apart from the buffer's own
   /// identity (see `epoch()`) so neither has to know about the other.
   u32 slot_epoch_ = 0;
-  u8* mapped_ = nullptr;    ///< base of the mapped ring, null in `Orphan` mode
-  gl::Fence fences_[kSlots];
+  u8* mapped_ = nullptr;  ///< base of the mapped ring, null in `Orphan` mode
+  /// Guards every slot the frame just ended wrote. Recorded once, after its last
+  /// draw; waited on once, at the start of the next frame.
+  gl::Fence frame_fence_;
 };
 
 }  // namespace detail
@@ -129,6 +157,7 @@ class LineBuffer {
   bool create(Status* st = nullptr, UploadMode mode = UploadMode::Orphan) noexcept {
     return store_.create(mode, st);
   }
+  bool begin_frame() noexcept { return store_.begin_frame(); }
   void upload(const f32* interleaved, u32 count) noexcept {
     store_.upload(interleaved, count, sizeof(LineInstance));
   }
@@ -148,6 +177,7 @@ class TextBuffer {
   bool create(Status* st = nullptr, UploadMode mode = UploadMode::Orphan) noexcept {
     return store_.create(mode, st);
   }
+  bool begin_frame() noexcept { return store_.begin_frame(); }
   void upload(const f32* interleaved, u32 count) noexcept {
     store_.upload(interleaved, count, sizeof(TextInstance));
   }

include/plot/render/detail/ring_stats.hpp

@@ -0,0 +1,62 @@
+#pragma once
+
+#ifdef PLOT_RING_STATS
+
+#include <atomic>
+
+#include <plot/core/types.hpp>
+
+namespace plot::render::detail {
+
+/// Test-only instrumentation for the persistent-mapped instance ring (see
+/// `InstanceStore`). Every counter exists only when PLOT_RING_STATS is defined
+/// -- the test build defines it, on the library and on the suite -- and none of
+/// them is a data member of any class, so a consumer compiled without the macro
+/// still lays `InstanceStore` out identically. No other build carries a counter
+/// or an increment on the upload, frame or wait path.
+///
+/// The properties they pin are invisible in the pixels a frame draws: a ring that
+/// syncs mid-frame rasterises exactly what one that does not does, and a ring that
+/// recycles a slot within a frame draws correctly until the GPU happens to be
+/// slower than the CPU. So `InstanceStore` counts
+///
+///   * `ring_uploads()` -- one per upload, i.e. a frame's upload count;
+///   * `ring_waits()`   -- one per fence wait. At most one per store per frame:
+///     the wait is at the start of the frame, on the previous frame's fence;
+///   * `ring_slots()`   -- the largest ring any store has grown to, which must
+///     cover the uploads a frame performs.
+///
+/// They are process-global rather than per-store because a test that drives one
+/// `InstanceStore` reads them directly; a test that drives the whole `Renderer`
+/// reads the aggregate, where there are two stores and so at most two waits a
+/// frame.
+///
+/// Not part of any query surface and not meant for production use.
+inline std::atomic<u64>& ring_uploads() {
+  static std::atomic<u64> count{0};
+  return count;
+}
+
+inline std::atomic<u64>& ring_waits() {
+  static std::atomic<u64> count{0};
+  return count;
+}
+
+inline std::atomic<u64>& ring_slots() {
+  static std::atomic<u64> count{0};
+  return count;
+}
+
+/// Records `slots` as the ring's largest size so far. A compare-exchange loop
+/// rather than a store because two stores report into one counter.
+inline void note_ring_slots(u64 slots) noexcept {
+  std::atomic<u64>& count = ring_slots();
+  u64 largest = count.load(std::memory_order_relaxed);
+  while (largest < slots &&
+         !count.compare_exchange_weak(largest, slots, std::memory_order_relaxed)) {
+  }
+}
+
+}  // namespace plot::render::detail
+
+#endif  // PLOT_RING_STATS

include/plot/render/renderer.hpp

@@ -80,6 +80,12 @@ class Renderer {
   /// `viewport_px` (top-left origin, like every `Rect` in this library) into GL's
   /// bottom-left origin once, clears that region to `style().background` and
   /// empties the staging batches.
+  ///
+  /// It is also where the instance stores wait -- once each -- for the previous
+  /// frame's draws to retire the ring they read, before this frame writes any
+  /// slot (see `InstanceStore::begin_frame`): a frame never synchronises with the
+  /// work it issued itself. A store that cannot retire that frame drops to the
+  /// baseline path, which this frame reports (see `last_frame_had_gl_error()`).
   void begin_frame(u32 fb_w, u32 fb_h, Rect viewport_px) noexcept;
 
   /// Draws `plot`, refreshing its layout, ticks and grid first.
@@ -98,6 +104,10 @@ class Renderer {
   /// Ends the frame, draining `glGetError()` in a loop so a stale error cannot be
   /// attributed to a later frame (see `last_frame_had_gl_error()`).
   ///
+  /// It also records each instance store's single fence for the frame, behind
+  /// every draw that read the ring, which is what the next `begin_frame()` waits
+  /// on (see `InstanceStore::mark_drawn`).
+  ///
   /// The GL state it leaves behind, so a host can embed the plot without guessing:
   /// vertex array 0, program 0, `GL_ARRAY_BUFFER` 0, texture unit 0 active and
   /// nothing bound to `GL_TEXTURE_2D` on it, blending off, scissoring off, and the
@@ -115,7 +125,7 @@ class Renderer {
 
   /// True when the last frame reported a GL failure: an error drained from
   /// `glGetError()` in `end_frame()`, or a fence the driver refused, which the
-  /// store reports when the draw that should have been guarded is issued (such a
+  /// store reports when the frame's fence is recorded or waited on (such a
   /// frame has already fallen back to the baseline path). Errors are drained in a
   /// loop, so a stale one cannot be attributed to a later frame.
   bool last_frame_had_gl_error() const noexcept { return gl_error_; }

include/plot/render/vertex_array.hpp

@@ -30,11 +30,14 @@ class LineVertexArray {
   void upload(const f32* interleaved, u32 segments) noexcept;
 
   void bind() const noexcept { vao_.bind(); }
-  /// Records that the draw just issued read the instance buffer's current slot,
-  /// which is what lets the mapped path reuse it safely. True in the baseline
-  /// mode, so a caller always calls it the same way. False only when the driver
-  /// refused the fence: the buffer has then fallen back to the baseline path, and
-  /// `persistent()` says so from the next call on.
+  /// Waits, once, for the previous frame's draws to retire the ring before any
+  /// slot of this frame is written (see `InstanceStore::begin_frame`). False when
+  /// the store had to drop to the baseline path; the caller reports it.
+  bool begin_frame() noexcept { return buffer_.begin_frame(); }
+  /// Records the frame's single fence, behind every draw that read the ring (see
+  /// `InstanceStore::mark_drawn`); called once per frame, after its last draw.
+  /// False only when the driver refused the fence: the buffer has then fallen
+  /// back to the baseline path, and `persistent()` says so from the next call on.
   bool mark_drawn() noexcept { return buffer_.mark_drawn(); }
   /// True while this array's instance buffer is the mapped ring (see
   /// `UploadMode`); a failure that falls back clears it.
@@ -62,6 +65,9 @@ class TextVertexArray {
   void upload(const f32* interleaved, u32 glyphs) noexcept;
 
   void bind() const noexcept { vao_.bind(); }
+  /// The line pipeline's frame pair, for the text store (see
+  /// `LineVertexArray::begin_frame` / `mark_drawn`).
+  bool begin_frame() noexcept { return buffer_.begin_frame(); }
   bool mark_drawn() noexcept { return buffer_.mark_drawn(); }
   bool persistent() const noexcept { return buffer_.persistent(); }