ntk 8.11.1 → 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.
  *
@@ -432,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
@@ -564,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,
@@ -1348,9 +1391,13 @@ export default class Window extends Drawable {
    *    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
@@ -1371,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.
    *
@@ -1636,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();
       });
@@ -2139,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) {
@@ -2159,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.
@@ -2188,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;
     }
@@ -2252,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);
@@ -2333,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._presentAbandoned()) return false;
     safeRelease(this.X, () => {
       this._fixesExt.SetRegion(
         this._updateRegion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.11.1",
+  "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",