ntk 6.2.0 → 6.3.0

package/lib/window.js

@@ -355,6 +355,20 @@ export default class Window extends Drawable {
     // (see docs/window.md "Frames, coalescing and slow connections")
     this._coalesce = args.coalesceEvents !== false;
     this._frameSyncEnabled = args.frameSync !== false;
+    // _NET_WM_SYNC_REQUEST (see enableSyncRequest): the counter the window
+    // manager watches, the value it last asked for, and the watchdog that
+    // guarantees an answer even when nothing repaints
+    this._syncCounter = null;
+    this._syncRequestAtom = 0;
+    this._syncPending = null;
+    this._syncWatchdog = null;
+    // Present-based blits (see enablePresent): the extension objects, the
+    // XFixes region reused as the update region, and the serial the server
+    // echoes back in its completion events
+    this._presentExt = null;
+    this._fixesExt = null;
+    this._updateRegion = 0;
+    this._presentSerial = 0;
     this.frameInterval = args.frameInterval ?? 16;
     this.frameLatency = null;
     this._frame = {
@@ -364,7 +378,12 @@ export default class Window extends Drawable {
       inFlight: false, // fence round-trip awaiting the server's reply
       timer: null,
       scheduled: false,
-      needsRedraw: false
+      needsRedraw: false,
+      // minimum inter-blit pacing: when the last blit went out, and the timer
+      // that guarantees a blit held back by the interval still lands.
+      // -Infinity so the first blit after construction is never delayed.
+      lastPresentAt: -Infinity,
+      presentTimer: null
     };
 
     if (!args.id) {
@@ -482,6 +501,17 @@ export default class Window extends Drawable {
     if (args.alwaysOnTop) {
       this.setAlwaysOnTop(true);
     }
+    if (args.syncRequest && !args.id) {
+      // fire and forget: the window manager only reads the counter when it
+      // starts managing the window, and map() is the caller's next line at
+      // the earliest. `await wnd.enableSyncRequest()` when that is too close.
+      this.enableSyncRequest().catch((err) => this.app.options.onXError?.(err));
+    }
+    if (args.present && !args.id) {
+      // fire and forget: until the extensions answer, blits use CopyArea,
+      // which is what they would have done anyway
+      this.enablePresent().catch((err) => this.app.options.onXError?.(err));
+    }
 
     X.event_consumers[this.id] = this;
     this.on('event', (ev) => {
@@ -537,7 +567,10 @@ export default class Window extends Drawable {
       this.emit(eventName, ntkev);
       // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
       // 'close' is that question in a form an application can answer
-      if (eventName === 'message') this._emitCloseRequest(ntkev);
+      if (eventName === 'message') {
+        this._emitCloseRequest(ntkev);
+        this._handleSyncRequest(ntkev);
+      }
       // anything drawn during the handlers becomes visible in one blit
       if (this._dirty) this._present();
     });
@@ -812,8 +845,13 @@ export default class Window extends Drawable {
    *  - a timer: at most one paced frame per `frameInterval` ms, so a fast
    *    local server doesn't get redraws at input-device rate.
    *
-   * Discrete events (mousedown, keydown, ...) bypass the timer for latency,
-   * but their blits still respect the fence via _present().
+   * Discrete events (mousedown, keydown, ...) bypass the timer for latency:
+   * the first blit after a quiet moment goes out with the handler's own
+   * requests. Their blits are still bounded, by the fence and by a minimum
+   * inter-blit interval (also `frameInterval`) — see _present(). Without that
+   * interval a stream of discrete events blits at round-trip rate, which on a
+   * local server is several hundred per second, and under a compositor every
+   * blit is a recomposite.
    */
   _scheduleFrame() {
     const f = this._frame;
@@ -831,7 +869,15 @@ export default class Window extends Drawable {
 
   _runFrame() {
     const f = this._frame;
-    if (!f.pending.size && !f.rafCbs.length && !f.needsRedraw && !this._dirty && !this._presentPending) return;
+    if (
+      !f.pending.size &&
+      !f.rafCbs.length &&
+      !f.needsRedraw &&
+      !this._dirty &&
+      !this._presentPending &&
+      this._syncPending == null
+    )
+      return;
     this._flushCoalesced();
     if (f.needsRedraw) {
       f.needsRedraw = false;
@@ -854,6 +900,9 @@ export default class Window extends Drawable {
       for (const entry of cbs) entry.cb(now);
     }
     if (this._dirty || this._presentPending) this._presentNow();
+    // covers a window with no backing store, and a resize that changed
+    // nothing: _presentNow did not run, but the frame is still "handled"
+    this._ackSyncRequest();
     this._armFence();
     this._armTimer();
   }
@@ -952,9 +1001,10 @@ export default class Window extends Drawable {
         f.inFlight = false;
         this.frameLatency = performance.now() - start;
         if (this._presentPending) {
-          // a blit deferred while the fence was in flight: show it now
-          this._presentNow();
-          this._armFence();
+          // a blit deferred while the fence was in flight: show it as soon as
+          // the minimum inter-blit interval allows (immediately when the last
+          // blit is already older than that, which is the common case)
+          this._present();
         }
         if ((f.pending.size || f.rafCbs.length || f.needsRedraw) && !f.timer) this._scheduleFrame();
       });
@@ -978,6 +1028,36 @@ export default class Window extends Drawable {
       clearTimeout(f.timer);
       f.timer = null;
     }
+    if (f.presentTimer) {
+      clearTimeout(f.presentTimer);
+      f.presentTimer = null;
+    }
+    if (this._syncWatchdog) {
+      clearTimeout(this._syncWatchdog);
+      this._syncWatchdog = null;
+    }
+    // Destroying the counter releases any Await the window manager is
+    // blocked in, so a window that goes away mid-drag does not strand it.
+    if (this._syncCounter && this._sync) {
+      const counter = this._syncCounter;
+      this._syncCounter = null;
+      this._syncPending = null;
+      safeRelease(this.X, () => {
+        this._sync.DestroyCounter(counter);
+        this.X.ReleaseID(counter);
+      });
+    }
+    if (this._updateRegion && this._fixesExt) {
+      const region = this._updateRegion;
+      this._updateRegion = 0;
+      this._presentExt = null;
+      const fixes = this._fixesExt;
+      this._fixesExt = null;
+      safeRelease(this.X, () => {
+        fixes.DestroyRegion(region);
+        this.X.ReleaseID(region);
+      });
+    }
     f.pending.clear();
     f.rafCbs = [];
     f.needsRedraw = false;
@@ -1014,9 +1094,11 @@ export default class Window extends Drawable {
    * Drawing the response inside the event handler costs a frame less latency:
    * the blit goes out with the handler's own requests (see the `_present()`
    * at the end of the event dispatch) instead of waiting for the next paced
-   * frame. Drawing it while a frame is in flight costs a frame's *work* for
-   * nothing: the present is deferred until the ack and coalesces with the
-   * one already pending, so only the last paint is ever seen. So `false`
+   * frame — provided the last blit is at least `frameInterval` old, which is
+   * what a discrete input arriving out of the blue always is. Drawing it while
+   * a frame is in flight costs a frame's *work* for nothing: the present is
+   * deferred until the ack and coalesces with the one already pending, so only
+   * the last paint is ever seen. So `false`
    * means "draw it now", `true` means "leave it to the frame clock" — which
    * is how a burst of discrete events (a spun wheel) paints its first notch
    * immediately and folds the rest into one catch-up frame.
@@ -1031,15 +1113,129 @@ export default class Window extends Drawable {
 
   _present() {
     if (!this._backing) return;
-    if (this._frame.inFlight) {
-      // the server hasn't confirmed the previous frame yet — defer the blit
-      this._presentPending = true;
+    const wait = this._presentWait();
+    if (this._frame.inFlight || wait > 0) {
+      // the server hasn't confirmed the previous frame yet, or the last blit
+      // was too recent — defer, and leave a wakeup behind
+      this._deferPresent(wait);
       return;
     }
     this._presentNow();
     this._armFence();
   }
 
+  /**
+   * How long until the next blit may go out; 0 when it may go now.
+   *
+   * The gate is `frameInterval`, the same knob that paces frames, so
+   * `frameInterval: 0` keeps the old fence-only behaviour — a caller who asked
+   * for no timer gate gets none here either.
+   */
+  _presentWait() {
+    const min = this.frameInterval;
+    if (!(min > 0)) return 0;
+    const since = performance.now() - this._frame.lastPresentAt;
+    return since >= min ? 0 : min - since;
+  }
+
+  /**
+   * Hold a blit back, and guarantee it still happens.
+   *
+   * This is the only place `_presentPending` is set, because every deferral has
+   * to leave a wakeup behind: the fence reply when the fence is what we are
+   * waiting on, this timer when the interval is. Nothing else reschedules a
+   * present — `_scheduleFrame()` bails while a frame timer is armed, and
+   * neither reschedule condition (in `_armFence`'s reply or `_armTimer`'s
+   * callback) looks at the present. Without the timer the last blit of a burst
+   * would simply never go out, leaving stale pixels on screen.
+   */
+  _deferPresent(wait) {
+    this._presentPending = true;
+    if (wait <= 0) return; // waiting on the fence: its reply blits this
+    const f = this._frame;
+    if (f.presentTimer) return; // already armed
+    f.presentTimer = setTimeout(() => {
+      f.presentTimer = null;
+      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) return; // the fence ack is closer; it will blit
+      this._presentNow();
+      this._armFence();
+    }, wait);
+    if (typeof f.presentTimer.unref === 'function') f.presentTimer.unref();
+  }
+
+  /**
+   * Blit with the Present extension instead of `CopyArea`.
+   *
+   * A frame's dirty rectangles become one `PresentPixmap` with an update
+   * region, in place of one `CopyArea` per rectangle. Two things follow:
+   * a frame is a fixed two requests however fragmented the damage is, and
+   * `_blitList`'s bounding-box collapse becomes unnecessary — its whole
+   * premise is "each rectangle costs a request", so with Present the exact
+   * rectangles are sent and pixels outside them are never touched.
+   *
+   * Presents are also scheduled by the server against the display's refresh
+   * rather than executed on arrival, so a burst cannot produce more updates
+   * than the output can show; the server drops superseded frames itself.
+   *
+   * Worth being precise about what this does *not* do: under a compositing
+   * manager the window is redirected, so this schedules the server's copy
+   * into the redirect pixmap — the compositor still composites on its own
+   * schedule. Aligning with *that* is what `_NET_WM_SYNC_REQUEST`'s extended
+   * counters are for.
+   *
+   * Opt-in via `createWindow({ present: true })`, and inert unless both
+   * Present and XFixes are available — blits fall back to `CopyArea`, which
+   * stays correct at all times, so the two paths can even alternate.
+   *
+   * @returns {Promise<Window>}
+   */
+  enablePresent() {
+    if (this._presentExt || this._destroyed) return Promise.resolve(this);
+    const X = this.X;
+    const need = (name) =>
+      new Promise((resolve) => X.require(name, (err, ext) => resolve(err ? null : ext)));
+    return Promise.all([need('present'), need('fixes')]).then(([present, fixes]) => {
+      if (!present || !fixes || this._destroyed) return this; // stay on CopyArea
+      this._updateRegion = X.AllocID();
+      safeRelease(X, () => fixes.CreateRegion(this._updateRegion, []));
+      this._presentExt = present;
+      this._fixesExt = fixes;
+      return this;
+    });
+  }
+
+  /**
+   * 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) {
+    const P = this._presentExt;
+    if (!P || !this._fixesExt || !this._updateRegion) return false;
+    safeRelease(this.X, () => {
+      this._fixesExt.SetRegion(
+        this._updateRegion,
+        rects.map((r) => ({ x: r.x, y: r.y, width: r.w, height: r.h }))
+      );
+      this._presentExt.Pixmap(this.id, this._backing.id, {
+        serial: ++this._presentSerial,
+        update: this._updateRegion,
+        // Option.Copy forces the copy path. Without it the server may *flip*
+        // the pixmap to the screen and take ownership of it until an
+        // IdleNotify — and ntk reuses one grow-only backing pixmap, so
+        // drawing into it while the server owned it would paint the screen
+        // directly. Removing this needs a swap chain, not just a smaller diff.
+        options: P.Option.Copy
+        // targetMsc stays 0: "the next vblank", which is what we want. An
+        // explicit target only adds ways to fall behind.
+      });
+    });
+    return true;
+  }
+
   _presentNow() {
     this._presentPending = false;
     if (!this._backing) return;
@@ -1061,13 +1257,27 @@ export default class Window extends Drawable {
       if (x1 > x0 && y1 > y0) clamped.push({ x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
     }
     if (!clamped.length) return;
-    const rects = this._blitList(clamped);
-    // a paced frame can fire after the connection started closing
-    safeRelease(this.X, () => {
-      for (const r of rects) {
-        this.X.CopyArea(this._backing.id, this.id, this._presentGc, r.x, r.y, r.x, r.y, r.w, r.h);
-      }
-    });
+    // Stamped here rather than at the call sites so it is a true inter-blit
+    // interval across all three of them, and only when pixels really move — a
+    // present that copies nothing must not push the next one out.
+    this._frame.lastPresentAt = performance.now();
+    // Present sends the exact rectangles in one request, so the bounding-box
+    // collapse — which trades pixels for fewer requests — has nothing to buy
+    if (!this._presentWithExtension(clamped)) {
+      const rects = this._blitList(clamped);
+      // a paced frame can fire after the connection started closing
+      safeRelease(this.X, () => {
+        for (const r of rects) {
+          this.X.CopyArea(this._backing.id, this.id, this._presentGc, r.x, r.y, r.x, r.y, r.w, r.h);
+        }
+      });
+    }
+    // Queued behind whichever of the two put the pixels on their way, so the
+    // window manager hears about the new size only once the server has drawn
+    // it. Both paths must reach this: a window using Present *and*
+    // _NET_WM_SYNC_REQUEST would otherwise never answer, and the resize would
+    // stall.
+    this._ackSyncRequest();
   }
 
   /**
@@ -1504,6 +1714,10 @@ export default class Window extends Drawable {
    *
    * `WM_DELETE_WINDOW` needs none of this by hand: listening for the
    * `'close'` event adds the protocol and decodes the message for you.
+   * `_NET_WM_SYNC_REQUEST` likewise has a real opt-in — `enableSyncRequest()`
+   * / `createWindow({ syncRequest: true })`. Adding that atom here instead
+   * advertises a protocol this window cannot answer, which is worse than not
+   * advertising it: the counter the window manager looks for is missing.
    *
    * Replaces the whole list. `addProtocol`/`removeProtocol` are the
    * accumulating forms, and the ones to reach for: the property is a *set*,
@@ -2537,6 +2751,116 @@ export default class Window extends Drawable {
    * existed — keeps behaving exactly as it did, rather than suddenly
    * acquiring a second handler that destroys it.
    */
+  /**
+   * Opt into `_NET_WM_SYNC_REQUEST` (EWMH §6.2): let the window manager pace
+   * an interactive resize to how fast this window actually repaints.
+   *
+   * Without it a WM has no idea when a resize has been drawn, so it either
+   * throws ConfigureNotify at the client as fast as the pointer moves — and
+   * the window lags behind the frame the user is dragging — or guesses with a
+   * timer. With it, the WM sends a serial before each resize and waits for
+   * this window to echo it back once the new size is on screen.
+   *
+   * Also available as `createWindow({ syncRequest: true })`. This is the
+   * awaitable form, for when `map()` follows immediately: the counter and the
+   * `_NET_WM_SYNC_REQUEST_COUNTER` property have to exist before the window
+   * leaves the withdrawn state, because that is when the WM reads them.
+   *
+   * Silently does nothing when the server has no SYNC extension — a WM that
+   * finds no counter simply drives the resize the old way.
+   *
+   * Only basic (single-counter) synchronization is implemented. The extended
+   * two-counter form buys frame-timing feedback rather than resize pacing, and
+   * its odd/even parity rules freeze the window if they are ever got wrong; a
+   * compositor that supports it falls back to basic mode on its own when the
+   * property holds one counter.
+   *
+   * @returns {Promise<Window>}
+   */
+  enableSyncRequest() {
+    if (this._syncCounter || this._destroyed) return Promise.resolve(this);
+    const X = this.X;
+    return new Promise((resolve, reject) => {
+      X.require('sync', (err, Sync) => {
+        if (err || !Sync || this._destroyed) return resolve(this); // no SYNC: stay quiet
+        this._sync = Sync;
+        const counter = X.AllocID();
+        safeRelease(X, () => Sync.CreateCounter(counter, 0));
+        this._syncCounter = counter;
+        // The dispatch path compares against both atoms, and node-x11 caches
+        // interned atoms per connection, so this is one round trip and no more.
+        this.atom('WM_PROTOCOLS').catch(() => {});
+        this._withAtoms(['_NET_WM_SYNC_REQUEST_COUNTER', '_NET_WM_SYNC_REQUEST'], (atoms) => {
+          this._syncRequestAtom = atoms._NET_WM_SYNC_REQUEST;
+          safeRelease(X, () =>
+            X.ChangeProperty(
+              0,
+              this.id,
+              atoms._NET_WM_SYNC_REQUEST_COUNTER,
+              X.atoms.CARDINAL,
+              32,
+              [counter]
+            )
+          );
+          // property first, protocol second: a window manager that sees the
+          // protocol advertised must always find the counter behind it
+          this.addProtocol('_NET_WM_SYNC_REQUEST').then(() => resolve(this), reject);
+        });
+      });
+    });
+  }
+
+  /**
+   * The window manager asking us to report when a resize has been painted.
+   *
+   * Only the value is recorded here — acknowledging now would claim a frame
+   * that has not been drawn. `_ackSyncRequest` sends it once the pixels are on
+   * their way. EWMH is explicit that only the *last* message is acknowledged,
+   * so a newer request simply overwrites an older one.
+   */
+  _handleSyncRequest(ev) {
+    if (!this._syncCounter || ev.format !== 32) return;
+    const X = this.X;
+    if (!X.atoms.WM_PROTOCOLS || ev.message_type !== X.atoms.WM_PROTOCOLS) return;
+    if (!this._syncRequestAtom || ev.data?.[0] !== this._syncRequestAtom) return;
+    // data[2] is the low half of the 64-bit request number, data[3] the high
+    this._syncPending = ev.data[3] * 0x100000000 + ev.data[2];
+    // Not every request leads to a repaint — a move, or a resize to the size
+    // we already are, leaves nothing dirty and no frame scheduled. The
+    // watchdog turns a missed acknowledgement into a stutter instead of a
+    // window manager that waits forever.
+    this._armSyncWatchdog();
+  }
+
+  _armSyncWatchdog() {
+    if (this._syncWatchdog || this._syncPending == null) return;
+    this._syncWatchdog = setTimeout(() => {
+      this._syncWatchdog = null;
+      this._ackSyncRequest();
+    }, Math.max(this.frameInterval, 16) * 2);
+    if (typeof this._syncWatchdog.unref === 'function') this._syncWatchdog.unref();
+  }
+
+  /**
+   * Answer the window manager's last sync request.
+   *
+   * Called after the requests that repaint have been queued, never before: X
+   * runs a client's requests in order, so a SetCounter queued behind the
+   * copies is executed behind them too, which is exactly the "having handled
+   * all repainting" the spec asks for. (It rides the same output batch, which
+   * is flushed before the event loop polls — no manual flush needed.)
+   */
+  _ackSyncRequest() {
+    const value = this._syncPending;
+    if (value == null || !this._syncCounter || !this._sync) return;
+    this._syncPending = null;
+    if (this._syncWatchdog) {
+      clearTimeout(this._syncWatchdog);
+      this._syncWatchdog = null;
+    }
+    safeRelease(this.X, () => this._sync.SetCounter(this._syncCounter, value));
+  }
+
   _emitCloseRequest(ev) {
     if (ev.format !== 32 || !this.listenerCount('close')) return;
     // node-x11 caches interned atoms per connection, so these are the ids

package/package.json

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