ntk 8.11.0 → 8.12.0

package/README.md

@@ -106,7 +106,8 @@ wnd.requestAnimationFrame(frame);
 ```
 
 See [docs/window.md](docs/window.md) for the knobs (`frameInterval`,
-`frameSync`, `coalesceEvents`) and the raw uncoalesced event stream.
+`frameSync`, `maxFramesInFlight`, `coalesceEvents`) and the raw uncoalesced
+event stream.
 
 ## Resource management
 

package/lib/window.js

@@ -60,6 +60,43 @@ const BACKING_GRANULARITY = 128;
  */
 const DEFAULT_FRAME_INTERVAL = 16;
 
+/**
+ * How many frames the fence clock lets the server owe a window at once,
+ * unless the window asks for another number.
+ *
+ * One is a frame per round trip: the client draws, the server works through
+ * it, the reply comes back, and only then does the next frame start. Neither
+ * side works while the other does, so a frame costs the sum of the two.
+ * Where the reply is slow for reasons of the server's own, most of that sum
+ * is waiting. XQuartz answers a fence only once the frame has gone to the
+ * macOS window server: 13 ms at the median during a drag, against about
+ * 0.1 ms for an idle round trip, and the drag ran at 75-78 fps on a 120 Hz
+ * panel (issue #369). With two, the next frame is drawn during that wait,
+ * and the same drag runs at 107-118. A slow link gains the same way: a frame
+ * per round trip becomes two.
+ *
+ * Not more, because past two the wait is already overlapped, and each frame
+ * queued behind a busy server, or on a link too narrow for it, is a frame of
+ * latency. Where a blit goes out through Present it stays one (see
+ * _frameLimit).
+ */
+const DEFAULT_MAX_FRAMES_IN_FLIGHT = 2;
+
+/**
+ * `maxFramesInFlight` as given, or a RangeError saying what it takes.
+ *
+ * Zero is refused, not read as "no limit", which is what `frameInterval: 0`
+ * would lead a reader to expect: a window that may have no frame in flight
+ * never draws. The way to wait on the server not at all is `frameSync: false`.
+ */
+function framesInFlightLimit(n) {
+  if (Number.isInteger(n) && n >= 1) return n;
+  throw new RangeError(
+    `ntk: maxFramesInFlight is a number of frames, 1 or more — got ${String(n)}. ` +
+      'For no limit at all, create the window with frameSync: false.'
+  );
+}
+
 /**
  * The range a measured vblank period has to fall in to be believed, in ms.
  *
@@ -109,6 +146,32 @@ const REFRESH_QUANTILE = 0.25;
 const STALL_TIMEOUT = 2000;
 const STALL_TIMEOUT_FIRST = 250;
 
+/**
+ * The frame period Present makes up for a screen with no vertical blank to
+ * offer it, in µs: 60Hz, which xorg-server 21.1 and later compute as
+ * `1000000 / 60` and 1.20 and earlier wrote down as 16667.
+ *
+ * A server started with `-fakescreenfps` at another rate is not recognised.
+ * It was asked for that clock, and keeps it.
+ */
+const FAKE_MSC_INTERVALS = [16666, 16667];
+
+/**
+ * How much of the counter a made-up msc has to account for before a window
+ * believes it, in vblanks: about a quarter of a second.
+ *
+ * One completion that fits proves little. A display's counter starts after
+ * the server's clock does, so its `ust / msc` falls toward its own period as
+ * it runs, and a display a little faster than 60Hz passes through the
+ * made-up line on the way down. It stays within half a tick of the line for
+ * `interval / (interval - period)` vblanks, so a fit across this span rules
+ * out every display more than `interval / span` µs faster than the tick, which
+ * is anything past 64Hz. A display closer than that fits only while its
+ * counter crosses the line, and only a window whose first frames land in that
+ * stretch is fooled.
+ */
+const SYNTHETIC_MSC_SPAN = 16;
+
 /**
  * MotionNotify detail saying "this is the only motion you get until you ask".
  *
@@ -406,6 +469,9 @@ export default class Window extends Drawable {
     if (args.id === 0) {
       throw new Error('ntk: 0 (None) is not a window id');
     }
+    const maxFramesInFlight = framesInFlightLimit(
+      args.maxFramesInFlight ?? DEFAULT_MAX_FRAMES_IN_FLIGHT
+    );
     if (args.id) {
       const cached = Window._cacheFor(app).get(args.id);
       // TODO: check event mask, if more events in args - update it
@@ -476,7 +542,9 @@ export default class Window extends Drawable {
     this._frameSyncEnabled = args.frameSync !== false;
     // which signal ends a frame (see _clockOnPresent): 'auto' takes the
     // display's own vblank where the Present path can supply it and the fence
-    // everywhere else, 'fence' pins the round-trip clock
+    // everywhere else, including a server whose Present has no display behind
+    // it (see _probeMsc); 'present' takes Present's clock even there; 'fence'
+    // pins the round-trip clock
     this._frameClockPref = args.frameClock ?? 'auto';
     // _NET_WM_SYNC_REQUEST (see enableSyncRequest): the counter the window
     // manager watches, the value it last asked for, and the watchdog that
@@ -520,6 +588,12 @@ export default class Window extends Drawable {
     this._refreshSamples = [];
     this._lastComplete = null;
     this._clockStalled = false;
+    // Whether the msc on those completions is a display's count or a number
+    // the server works out from its clock (see _probeMsc): while undecided,
+    // the fake intervals every completion so far fits and the msc of the
+    // first of them; then the verdict.
+    this._mscProbe = { intervals: FAKE_MSC_INTERVALS, since: null };
+    this._mscSynthetic = false;
     // `frameInterval` is a plain number, but whether the caller set it is what
     // decides its meaning under the vblank clock — an explicit value caps the
     // frame rate, an unasked-for default must not (see _armTimer). Assigning
@@ -530,12 +604,15 @@ export default class Window extends Drawable {
     // that probe answers adopts the result when it lands.
     this._frameInterval = args.frameInterval ?? app.frameInterval ?? DEFAULT_FRAME_INTERVAL;
     this._frameIntervalExplicit = args.frameInterval !== undefined;
+    // how many fences may be outstanding before the next frame waits for one
+    // (see _frameLimit)
+    this._maxFramesInFlight = maxFramesInFlight;
     this.frameLatency = null;
     this._frame = {
       pending: new Map(), // coalescible event name -> merged event
       rafCbs: [],
       rafId: 0,
-      inFlight: false, // fence round-trip awaiting the server's reply
+      fences: 0, // fence round trips awaiting the server's reply
       presentInFlight: false, // present awaiting the display's CompleteNotify
       presentAt: 0, // when that present was sent, for frameLatency
       stallTimer: null,
@@ -1311,10 +1388,16 @@ export default class Window extends Drawable {
    *  - a fence, everywhere else: a cheap request with a reply
    *    (GetInputFocus) sent after each frame; X processes requests in order,
    *    so its reply confirms the server consumed everything the frame drew.
+   *    That includes a server whose Present has no display behind it and
+   *    makes its vertical blanks up from a timer (see _probeMsc).
    *
-   * Either way at most one is outstanding, which is what bounds the work in
-   * flight: on a slow connection frames degrade to one per round-trip instead
-   * of queueing a trail of stale updates.
+   * Either way the frames outstanding are bounded, which is what bounds the
+   * work in flight: one present on the display's clock, and on the fence
+   * `maxFramesInFlight` fences, two unless the window asked otherwise (see
+   * _frameLimit). On a slow connection frames degrade to that many per round
+   * trip instead of queueing a trail of stale updates. Two rather than one so
+   * that the next frame can be drawn while the server is still working
+   * through the last, instead of each waiting out the other.
    *
    * A timer backs both up. Under the fence it is the rate limit — at most one
    * frame per `frameInterval` ms, so a fast local server isn't asked to redraw
@@ -1335,18 +1418,63 @@ export default class Window extends Drawable {
    */
   _scheduleFrame() {
     const f = this._frame;
-    if (f.scheduled || f.inFlight || f.presentInFlight || f.timer) return;
+    if (f.scheduled || this._fencesFull() || f.presentInFlight || f.timer) return;
     f.scheduled = true;
     setImmediate(() => {
       f.scheduled = false;
       // gates may have been armed after this got scheduled (work queued
       // from inside a running frame, e.g. a rAF loop re-registering) —
       // the completion / fence reply / timer expiry will reschedule then
-      if (f.inFlight || f.presentInFlight || f.timer) return;
+      if (this._fencesFull() || f.presentInFlight || f.timer) return;
       this._runFrame();
     });
   }
 
+  /**
+   * How many frames may be waiting for their fence before the next one waits
+   * too: `maxFramesInFlight`, except where a blit goes out through Present.
+   *
+   * A second frame is safe behind a CopyArea. The server runs requests in
+   * order, so the copy has read the backing store before anything drawn after
+   * it lands there, and the fence says no more than that the server read the
+   * frame — which is all the next one needs. A present with Option.Copy is
+   * different: it owns the backing store until the copy executes, at the next
+   * vertical blank, and the fence reply says only that the server has read the
+   * present. A frame drawn behind it early can put half of itself on the screen
+   * (the hazard issue #223 describes), and a second frame in flight would
+   * widen that window. So a window whose blits are presents keeps one, whether
+   * the fence or the display is ending its frames — on the display's clock a
+   * present outstanding is the gate anyway, and there is never more than one.
+   *
+   * A window with no backing store has no blit to protect. Its frames go by
+   * the limit as a CopyArea window's do.
+   */
+  _frameLimit() {
+    return this._blitsThroughPresent() ? 1 : this._maxFramesInFlight;
+  }
+
+  /** Have the frames waiting for their fence reached the limit? */
+  _fencesFull() {
+    return this._frame.fences >= this._frameLimit();
+  }
+
+  /**
+   * How many frames the server may owe this window at once, on the fence
+   * clock, before the next one waits for the reply to the oldest: 2 unless
+   * set. `1` is a frame per round trip. Where blits go through Present, or
+   * the display is ending frames, one is all there is, whatever this says —
+   * see _frameLimit.
+   */
+  get maxFramesInFlight() {
+    return this._maxFramesInFlight;
+  }
+
+  set maxFramesInFlight(n) {
+    // A raised limit needs no wakeup: the gate was shut because fences are
+    // outstanding, and the next reply runs what it held back.
+    this._maxFramesInFlight = framesInFlightLimit(n);
+  }
+
   /**
    * Minimum ms between paced frames, and between blits.
    *
@@ -1379,14 +1507,15 @@ export default class Window extends Drawable {
   /**
    * Which clock is ending this window's frames right now: 'present' when the
    * display is, 'fence' when the server round-trip is. Assignable with
-   * 'auto' (prefer the display) or 'fence' (never use it).
+   * 'auto' (prefer the display), 'present' (prefer Present's clock even
+   * where no display is behind it) or 'fence' (never use it).
    */
   get frameClock() {
     return this._clockOnPresent() ? 'present' : 'fence';
   }
 
   set frameClock(mode) {
-    this._frameClockPref = mode === 'present' ? 'auto' : mode;
+    this._frameClockPref = mode;
     if (this._frameClockPref !== 'fence') this._selectPresentInput();
   }
 
@@ -1400,21 +1529,35 @@ export default class Window extends Drawable {
    * completion that never came drops the window back to the fence until one
    * does, so a clock that stops cannot stop the window with it.
    *
-   * `_presentFlipped` is the one-way door — a server that has flipped a copy
-   * present is off this path for good, and its blits no longer produce the
-   * completions the clock is made of.
+   * `_presentAbandoned` is the one-way door — a window whose server turned
+   * out unable to do what the path is for is off it from then on, and its
+   * blits no longer produce the completions the clock is made of.
    */
   _clockOnPresent() {
     return (
       this._frameClockPref !== 'fence' &&
       this._frameSyncEnabled &&
       !this._clockStalled &&
-      !this._presentFlipped &&
+      !this._presentAbandoned() &&
       !!this._presentExt &&
       !!this._presentEid
     );
   }
 
+  /**
+   * Has this window stopped presenting through the extension, the blit along
+   * with the clock, because of what its server turned out to be?
+   *
+   * Two things close the door. A server that flipped a present sent with
+   * Option.Copy owns the pixmap it was handed (see _handlePresentEvent). A
+   * server whose msc is made up has no display behind the extension, and
+   * only holds each copy back for a timer (see _probeMsc) — that one stays
+   * open to a caller who asked for Present's clock by name.
+   */
+  _presentAbandoned() {
+    return !!this._presentFlipped || (this._mscSynthetic && this._frameClockPref !== 'present');
+  }
+
   _runFrame() {
     const f = this._frame;
     if (
@@ -1585,15 +1728,24 @@ export default class Window extends Drawable {
     for (const [name, ev] of pending) this.emit(name, ev);
   }
 
+  /**
+   * Fence the frame that just went out: one request with a reply, answered
+   * once the server has read everything before it.
+   *
+   * Every frame gets its own, so `fences` is exactly the number of frames the
+   * server has not confirmed. Nothing here refuses one past the limit — the
+   * callers only send a frame while the gate is open, and a frame sent some
+   * other way is still better counted than left unfenced, where the gate
+   * would open with it unconfirmed.
+   */
   _armFence() {
     if (!this._frameSyncEnabled) return;
     const f = this._frame;
-    if (f.inFlight) return;
     const start = performance.now();
     safeRelease(this.X, () => {
-      f.inFlight = true;
+      f.fences++;
       this.X.GetInputFocus(() => {
-        f.inFlight = false;
+        f.fences--;
         this.frameLatency = performance.now() - start;
         this._frameEnded();
       });
@@ -1823,6 +1975,7 @@ export default class Window extends Drawable {
     f.presentInFlight = false;
     this.frameLatency = now - f.presentAt;
     this._sampleRefresh(ev, now);
+    this._probeMsc(ev);
     this._frameEnded();
   }
 
@@ -1890,6 +2043,60 @@ export default class Window extends Drawable {
     this.refreshInterval = sorted[Math.floor(REFRESH_QUANTILE * (sorted.length - 1))];
   }
 
+  /**
+   * Is a display counting these frames, or is the server making the count up?
+   *
+   * Present waits for vertical blanks, and a screen whose driver has none to
+   * offer gets fake ones: xserver's present_fake.c computes the msc from its
+   * clock, `(ust + interval / 2) / interval`, and completes a present when a
+   * timer set for the next tick fires. That is XQuartz, Xvfb, Xephyr, Xnest,
+   * the VNC servers and Xorg on a driver without Present support. The
+   * vblank clock buys nothing there and costs throughput. It paces to a 60Hz
+   * timer rather than to the panel, which on XQuartz is the macOS
+   * compositor's business. And a present arriving past the middle of a
+   * period already counts as the next tick, and is aimed at the one after
+   * that, so a frame that takes more than half a period to turn round waits
+   * two (issue #366).
+   *
+   * The blit goes with the clock, as it does for a server that flips: the
+   * copy waits for the same timer, so a window on the fence would draw
+   * faster yet still update at most 60 times a second, and a copy could
+   * read a frame half drawn, because the fence reply only says the server
+   * has read the present, not run it. CopyArea runs in request order.
+   *
+   * So the question is whether `msc` is `ust` rounded to the nearest tick.
+   * A display's counter cannot keep to that for long (SYNTHETIC_MSC_SPAN),
+   * and a single completion off the line settles it the other way. Either
+   * verdict is final: whether Present has a driver behind it is settled per
+   * screen, when the server starts.
+   */
+  _probeMsc(ev) {
+    const probe = this._mscProbe;
+    if (!probe) return;
+    const intervals = probe.intervals.filter((interval) => {
+      // msc === floor((ust + half) / interval), in integers
+      const half = Math.floor(interval / 2);
+      const offset = ev.ust - ev.msc * interval;
+      return offset >= -half && offset < interval - half;
+    });
+    if (!intervals.length) {
+      this._mscProbe = null; // a count, so a display
+      return;
+    }
+    probe.intervals = intervals;
+    probe.since ??= ev.msc;
+    if (ev.msc - probe.since < SYNTHETIC_MSC_SPAN) return;
+    this._mscProbe = null;
+    this._mscSynthetic = true;
+    // What was measured was a timer: no display period to report, and no
+    // display to have dropped frames on. A window kept on this clock by
+    // `frameClock: 'present'` learns the timer's period again from here.
+    this.refreshInterval = null;
+    this._refreshSamples = [];
+    this._lastComplete = null;
+    this.droppedFrames = 0;
+  }
+
   /**
    * Guarantee that a frame ends even if its completion does not arrive.
    *
@@ -2033,8 +2240,9 @@ export default class Window extends Drawable {
    * DOM-style requestAnimationFrame: `cb(now)` runs on this window's next
    * paced frame — one per vertical blank where the display is the clock (see
    * _clockOnPresent), otherwise at most once per `frameInterval` ms — and
-   * always with at most one frame outstanding, so animation loops adapt to
-   * the output's rate and to connection latency instead of flooding either.
+   * always with a bounded number of frames outstanding (one on the display's
+   * clock, `maxFramesInFlight` on the fence), so animation loops adapt to the
+   * output's rate and to connection latency instead of flooding either.
    * Returns an id for cancelAnimationFrame().
    */
   requestAnimationFrame(cb) {
@@ -2053,9 +2261,12 @@ export default class Window extends Drawable {
 
   /**
    * Whether a blit this window already owes is still waiting to go out —
-   * because the last frame is unanswered (its fence unreplied, or its present
-   * not yet on the display), or because a present is deferred behind the
-   * minimum inter-blit interval.
+   * because the frames already sent are unanswered (as many fences unreplied
+   * as `maxFramesInFlight` allows, or a present not yet on the display), or
+   * because a present is deferred behind the minimum inter-blit interval.
+   *
+   * So it reads false with a frame in flight when the limit allows another:
+   * a blit drawn then goes out at once, which is the question this answers.
    *
    * The one bit of frame-clock state worth publishing, because it is the
    * difference between the two ways a toolkit can answer a discrete input.
@@ -2082,16 +2293,17 @@ export default class Window extends Drawable {
    * asked for both gets the unpaced behaviour those options ask for.
    */
   frameInFlight() {
-    return this._frame.inFlight || this._frame.presentInFlight || this._presentPending;
+    return this._fencesFull() || this._frame.presentInFlight || this._presentPending;
   }
 
   _present() {
     if (!this._backing) return;
     const f = this._frame;
     const wait = this._presentWait();
-    if (f.inFlight || f.presentInFlight || wait > 0) {
-      // the server hasn't confirmed the previous frame yet, the display hasn't
-      // shown it, or the last blit was too recent — defer, leaving a wakeup
+    if (this._fencesFull() || f.presentInFlight || wait > 0) {
+      // the server hasn't confirmed enough of the frames already sent, the
+      // display hasn't shown the last one, or the last blit was too recent —
+      // defer, leaving a wakeup
       this._deferPresent(wait);
       return;
     }
@@ -2146,7 +2358,7 @@ export default class Window extends Drawable {
       if (!this._presentPending && !this._dirty) return; // someone blitted it
       const again = this._presentWait();
       if (again > 0) return this._deferPresent(again); // a paced frame re-stamped
-      if (f.inFlight || f.presentInFlight) return; // the frame's end is closer
+      if (this._fencesFull() || f.presentInFlight) return; // the frame's end is closer
       this._presentNow();
       if (!f.presentInFlight) this._armFence();
     }, wait);
@@ -2227,15 +2439,25 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * Would a blit go out through the Present extension right now, rather than
+   * as CopyArea? Not before the extensions have answered, and not once the
+   * window has left the path (see _presentAbandoned).
+   */
+  _blitsThroughPresent() {
+    return (
+      !!this._presentExt && !!this._fixesExt && !!this._updateRegion && !this._presentAbandoned()
+    );
+  }
+
   /**
    * The Present form of the blit. Returns false when it did not happen, so
    * the caller falls back to CopyArea — which is also what runs before the
    * extensions have answered.
    */
   _presentWithExtension(rects) {
+    if (!this._blitsThroughPresent()) return false;
     const P = this._presentExt;
-    if (!P || !this._fixesExt || !this._updateRegion) return false;
-    if (this._presentFlipped) return false; // see _handlePresentEvent
     safeRelease(this.X, () => {
       this._fixesExt.SetRegion(
         this._updateRegion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.11.0",
+  "version": "8.12.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",