ntk 6.0.1 → 6.2.0

package/lib/app.js

@@ -4,6 +4,7 @@ import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
 import { DEFAULT_RASTER_POLICY, defaultRasterizer } from './rasterize.js';
+import { ShmUploader } from './shm-upload.js';
 import FontManager from './text/fontmanager.js';
 import Window from './window.js';
 
@@ -45,6 +46,7 @@ export default class App {
     this._cursors = null;
     this._solidPictures = new Map();
     this._rasterizer = undefined;
+    this._shm = undefined;
     // node-x11 emits X errors it cannot route to a request callback as
     // 'error' on the client — from inside its packet parser. With no
     // listener that emit throws and the parser never re-arms, silently
@@ -81,6 +83,22 @@ export default class App {
     this._rasterizer = value;
   }
 
+  /**
+   * The MIT-SHM upload helper: large PutImage/GetImage traffic (images,
+   * putImageData, getImageData) travels through shared memory on a local
+   * connection instead of the socket, and falls back to core requests
+   * everywhere else. Resolved lazily; availability follows node-x11's `shm`
+   * connection option (unset = on where possible, `false`/`'off'` = disabled).
+   * See lib/shm-upload.js and docs/context-2d.md.
+   */
+  get shm() {
+    if (this._shm === undefined) {
+      this._shm = new ShmUploader(this);
+      this._shm.resolve(() => {}); // probe availability in the background
+    }
+    return this._shm;
+  }
+
   /** thresholds for that decision, merged over DEFAULT_RASTER_POLICY */
   get rasterPolicy() {
     return this.options.rasterPolicy
@@ -212,6 +230,10 @@ export default class App {
       this._cursors.dispose();
       this._cursors = null;
     }
+    if (this._shm) {
+      this._shm.dispose();
+      this._shm = undefined;
+    }
     // shared by every context that ever asked (see solidPicture), so their
     // lifetime is the connection's — context teardown must not free them
     for (const picture of this._solidPictures.values()) {

package/lib/image.js

@@ -59,13 +59,17 @@ export class Image {
       gc = app._imageUploadGC = X.AllocID();
       X.CreateGC(gc, pixmap.id);
     }
-    // stay under the server's maximum request size by uploading row bands
-    const stride = this.width * 4;
-    const maxBytes = ((app.display.max_request_length ?? 65535) - 8) * 4;
-    const rowsPerBand = Math.max(1, Math.floor(maxBytes / stride));
-    for (let y = 0; y < this.height; y += rowsPerBand) {
-      const rows = Math.min(rowsPerBand, this.height - y);
-      X.PutImage(2, pixmap.id, gc, this.width, rows, 0, y, 0, 32, bgra.subarray(y * stride, (y + rows) * stride));
+    const bytes = Buffer.isBuffer(bgra) ? bgra : Buffer.from(bgra.buffer, bgra.byteOffset, bgra.byteLength);
+    // Shared memory for a large image; otherwise upload row bands that stay
+    // under the server's maximum request size.
+    if (!app.shm.putImage(pixmap.id, gc, { width: this.width, height: this.height, depth: 32, data: bytes })) {
+      const stride = this.width * 4;
+      const maxBytes = ((app.display.max_request_length ?? 65535) - 8) * 4;
+      const rowsPerBand = Math.max(1, Math.floor(maxBytes / stride));
+      for (let y = 0; y < this.height; y += rowsPerBand) {
+        const rows = Math.min(rowsPerBand, this.height - y);
+        X.PutImage(2, pixmap.id, gc, this.width, rows, 0, y, 0, 32, bytes.subarray(y * stride, (y + rows) * stride));
+      }
     }
 
     const picture = new Picture(app, { drawable: pixmap, format: Render.rgba32 });

package/lib/renderingcontext_2d.js

@@ -1942,24 +1942,36 @@ class RenderingContext2d {
 
     const layout = this._layout;
     const bytes = fromStraightRgba(rgba, layout, sw, sh);
-    // stay under the server's maximum request size by uploading row bands
-    const stride = sw * 4;
-    const maxBytes = ((this.display.max_request_length ?? 65535) - 8) * 4;
-    const rowsPerBand = Math.max(1, Math.floor(maxBytes / stride));
-    for (let row = 0; row < sh; row += rowsPerBand) {
-      const rows = Math.min(rowsPerBand, sh - row);
-      this.X.PutImage(
-        2, // ZPixmap
-        this._target.id,
-        this._gc,
-        sw,
-        rows,
-        x + sx,
-        y + sy + row,
-        0,
-        layout.depth,
-        bytes.subarray(row * stride, (row + rows) * stride),
-      );
+    // Shared memory for a large blit; otherwise upload row bands that stay
+    // under the server's maximum request size.
+    if (
+      !this.window.app.shm.putImage(this._target.id, this._gc, {
+        width: sw,
+        height: sh,
+        depth: layout.depth,
+        dstX: x + sx,
+        dstY: y + sy,
+        data: bytes,
+      })
+    ) {
+      const stride = sw * 4;
+      const maxBytes = ((this.display.max_request_length ?? 65535) - 8) * 4;
+      const rowsPerBand = Math.max(1, Math.floor(maxBytes / stride));
+      for (let row = 0; row < sh; row += rowsPerBand) {
+        const rows = Math.min(rowsPerBand, sh - row);
+        this.X.PutImage(
+          2, // ZPixmap
+          this._target.id,
+          this._gc,
+          sw,
+          rows,
+          x + sx,
+          y + sy + row,
+          0,
+          layout.depth,
+          bytes.subarray(row * stride, (row + rows) * stride),
+        );
+      }
     }
     this._markDirty();
   }
@@ -2007,20 +2019,31 @@ class RenderingContext2d {
    */
   readPixels(x, y, w, h) {
     const layout = this._layout;
+    const target = this._target.id;
+    const X = this.X;
     return new Promise((resolve, reject) => {
-      this.X.GetImage(
-        2,
-        this._target.id,
-        x,
-        y,
-        w,
-        h,
-        0xffffffff,
-        (err, img) => {
+      const coreGet = () =>
+        X.GetImage(2, target, x, y, w, h, 0xffffffff, (err, img) => {
           if (err) return reject(err);
           resolve({ width: w, height: h, data: img.data, layout, ...layout });
-        },
-      );
+        });
+
+      // A readback is where shared memory helps most: a core GetImage sends the
+      // whole image back over the socket and can block the server for tens of
+      // milliseconds. Route large ones through a segment; fall back on any miss.
+      const bytesPerPixel = layout.bitsPerPixel ? layout.bitsPerPixel >> 3 : 4;
+      const shm = this.window.app.shm;
+      if (shm.wantsReadback(w * h * bytesPerPixel)) {
+        shm.getImage(target, x, y, w, h, layout.depth, (err, buf, rep) => {
+          if (err) return coreGet();
+          // buf is the segment's own memory, reused after this callback returns
+          // — copy out synchronously before it is handed to the next reader
+          const data = Buffer.from(buf.subarray(0, rep.size));
+          resolve({ width: w, height: h, data, layout, ...layout });
+        });
+      } else {
+        coreGet();
+      }
     });
   }
 

package/lib/shm-upload.js

@@ -0,0 +1,166 @@
+// Optional MIT-SHM fast path for bulk pixel transfers.
+//
+// Large PutImage/GetImage traffic on a local connection is much cheaper through
+// shared memory than down the socket — roughly 2x on uploads and many times
+// faster on readbacks (which otherwise pay for a whole image-sized reply). This
+// wraps node-x11's provider-backed MIT-SHM API (X.require('shm')) into a small,
+// ordering-safe helper the 2d context and Image use, and falls back to core
+// PutImage/GetImage wherever SHM will not attach (remote display, old server,
+// no /dev/shm) or the transfer is too small to bother.
+//
+// Ordering discipline: an SHM upload is only ever issued through a segment that
+// is *already attached* — so it slots into the request stream synchronously,
+// exactly where a core PutImage would have gone, and never reorders drawing.
+// Attaching a segment costs a round trip, so the first upload of a given size
+// falls back to core and warms a segment in the background; the next one is a
+// synchronous shared-memory write. A segment is returned to the pool only after
+// the server signals (ShmCompletion) it has finished reading, so a reused
+// buffer is never overwritten mid-read.
+
+// Below this many bytes the socket is as fast as shared memory (measured: a
+// PutImage and a tmpfs write are both syscall-bound at a few KB; the win starts
+// around 64 KB and grows with size). Coverage masks (a8, 1 byte/pixel) stay
+// under it at every size the rasterizer produces, which is why the 2d fill mask
+// keeps using core PutImage.
+const MIN_UPLOAD_BYTES = 64 * 1024;
+// A readback pays the win sooner: a core GetImage reply carries the pixels back
+// over the socket and, on some drivers, blocks the server for tens of
+// milliseconds, so route more of them through shared memory.
+const MIN_READBACK_BYTES = 16 * 1024;
+// Round segment sizes up so a handful of buckets serve many nearby sizes and
+// the pool actually hits.
+const SIZE_QUANTUM = 64 * 1024;
+
+function roundUp(n) {
+  return Math.max(SIZE_QUANTUM, Math.ceil(n / SIZE_QUANTUM) * SIZE_QUANTUM);
+}
+
+export class ShmUploader {
+  /** @param {import('./app.js').default} app */
+  constructor(app) {
+    this.app = app;
+    this.X = app.X;
+    this.ext = null; // node-x11 shm extension once required; false if unavailable
+    this.ready = false; // usable() confirmed a segment attaches
+    this._pool = []; // free, already-read segments (not in flight)
+    this._warming = false;
+    this._resolving = null;
+  }
+
+  /**
+   * Resolve availability once (requires the extension and probes usable()).
+   * `cb(ready)`. Cheap and idempotent; safe to call before every draw.
+   */
+  resolve(cb) {
+    if (this.ready || this.ext === false) return cb(this.ready);
+    if (this._resolving) {
+      this._resolving.push(cb);
+      return;
+    }
+    this._resolving = [cb];
+    this.X.require('shm', (err, ext) => {
+      // The provider-backed API (usable/createSegment) needs x11 >= 3.7; an
+      // older x11 still resolves the extension but without it, so treat that
+      // as "no shared memory" rather than throwing.
+      if (err || !ext || typeof ext.usable !== 'function') return this._resolved(false, false);
+      ext.usable((e, ok) => this._resolved(ok ? ext : false, !!ok));
+    });
+  }
+
+  _resolved(ext, ready) {
+    this.ext = ext;
+    this.ready = ready;
+    const cbs = this._resolving || [];
+    this._resolving = null;
+    for (const cb of cbs) cb(ready);
+  }
+
+  _acquire(bytes) {
+    for (let i = 0; i < this._pool.length; ++i) {
+      if (this._pool[i].size >= bytes) return this._pool.splice(i, 1)[0];
+    }
+    return null;
+  }
+
+  _warm(bytes) {
+    if (this._warming || !this.ready) return;
+    this._warming = true;
+    this.ext.createSegment(roundUp(bytes), (err, seg) => {
+      this._warming = false;
+      if (!err && seg) this._pool.push(seg);
+    });
+  }
+
+  /**
+   * Upload `data` (server-layout pixels, `stride*height` bytes at offset 0) to
+   * `drawable` at `dstX,dstY` as a `depth` image `width*height`. Returns true
+   * when shared memory handled it (the caller must then issue nothing else),
+   * or false to signal "do it with core PutImage" — including every case where
+   * SHM is unavailable, too small, or momentarily out of free segments (a
+   * segment is warmed in the background for next time).
+   */
+  putImage(drawable, gc, { width, height, depth, dstX = 0, dstY = 0, data }) {
+    const bytes = data.length;
+    if (!this.ready || bytes < MIN_UPLOAD_BYTES) return false;
+    const seg = this._acquire(bytes);
+    if (!seg) {
+      this._warm(bytes);
+      return false;
+    }
+    data.copy ? data.copy(seg.buffer, 0, 0, bytes) : seg.buffer.set(data.subarray(0, bytes));
+    seg.putImage(drawable, gc, { width, height, depth, dstX, dstY, sendEvent: true });
+    // reuse only once the server is done reading it
+    seg.once('complete', () => this._pool.push(seg));
+    return true;
+  }
+
+  /**
+   * Whether a readback of `bytes` should use shared memory (usable and large
+   * enough). The caller does the async segment dance through `getImage` below.
+   */
+  wantsReadback(bytes) {
+    return this.ready && bytes >= MIN_READBACK_BYTES;
+  }
+
+  /**
+   * Read `width*height` pixels of `depth` from `drawable` at `x,y` through a
+   * shared segment. `cb(err, buffer)` — `buffer` is a view of the segment's
+   * bytes valid until the next `getImage`; copy out before then. Falls back is
+   * the caller's job: only call this when `wantsReadback` was true.
+   */
+  getImage(drawable, x, y, width, height, depth, cb) {
+    const bytes = width * height * ((depth + 7) >> 3 === 3 ? 4 : (depth + 7) >> 3);
+    const use = (seg) => {
+      seg.getImage(drawable, x, y, width, height, 0xffffffff, undefined, 0, (err, rep) => {
+        if (err) {
+          this._pool.push(seg);
+          return cb(err);
+        }
+        // hand back the buffer, then reclaim the segment after the caller has
+        // synchronously copied out (they must, per the doc above)
+        cb(null, seg.buffer, rep);
+        this._pool.push(seg);
+      });
+    };
+    const seg = this._acquire(bytes);
+    if (seg) return use(seg);
+    this.ext.createSegment(roundUp(bytes), (err, s) => {
+      if (err || !s) return cb(err || new Error('shm: no segment'));
+      use(s);
+    });
+  }
+
+  /** Detach every pooled segment (called from App#close). */
+  dispose() {
+    const pool = this._pool;
+    this._pool = [];
+    this.ready = false;
+    for (const seg of pool) {
+      try {
+        seg.detach();
+      } catch {
+        /* connection may already be gone */
+      }
+    }
+  }
+}

package/lib/widgets/htmlview.js

@@ -105,8 +105,10 @@ export default class HtmlView {
     if (this.window) {
       this._ctx = this.window.getContext('2d');
       this.window.on('expose', () => this.render());
-      this.window.on('resize', () => {
-        this._layoutWidth = -1;
+      // a move is a ConfigureNotify too; re-laying out a document per step
+      // of a window drag is exactly what ev.resized is for
+      this.window.on('resize', (ev) => {
+        if (ev.resized) this._layoutWidth = -1;
       });
       this.window.on('mousedown', (ev) => {
         if (ev.keycode === 4 || ev.keycode === 5) {

package/lib/widgets/markdownview.js

@@ -74,8 +74,10 @@ export default class MarkdownView {
     if (this.window) {
       this._ctx = this.window.getContext('2d');
       this.window.on('expose', () => this.render());
-      this.window.on('resize', () => {
-        this._layoutWidth = -1; // invalidate
+      // a move is a ConfigureNotify too; re-laying out a document per step
+      // of a window drag is exactly what ev.resized is for
+      this.window.on('resize', (ev) => {
+        if (ev.resized) this._layoutWidth = -1; // invalidate
       });
       this.window.on('mousedown', (ev) => {
         if (ev.keycode !== 1 || !this.onLink) return; // left button only

package/lib/window.js

@@ -386,6 +386,10 @@ export default class Window extends Drawable {
       this.height = args.height ?? 800;
       this.x = args.x ?? 0;
       this.y = args.y ?? 0;
+      // the baseline 'resize' compares against (see _tagResize): what the
+      // window was asked to be, so the window manager's first ConfigureNotify
+      // reports only what it actually overrode
+      this._deliveredGeom = { x: this.x, y: this.y, width: this.width, height: this.height };
       const values = {
         // NorthWest bit gravity: keep the old content anchored during
         // resize instead of discarding it (less flicker between the resize
@@ -419,6 +423,8 @@ export default class Window extends Drawable {
       this.eventMask = 0;
       this.visual = 0;
       this.depth = 0;
+      // an adopted window's geometry is not known until GetGeometry replies
+      this._deliveredGeom = null;
       // populate width and height
       X.GetGeometry(this.id, (err, res) => {
         if (!err) {
@@ -427,6 +433,10 @@ export default class Window extends Drawable {
           this.x = res.xPos;
           this.y = res.yPos;
           this.depth = res.depth;
+          // nothing was known about this window until now, so until this
+          // reply lands a 'resize' reports both moved and resized (see
+          // _tagResize) rather than guessing
+          this._deliveredGeom ??= { x: this.x, y: this.y, width: this.width, height: this.height };
         }
         this._readyPromiseResolve();
       });
@@ -523,6 +533,7 @@ export default class Window extends Drawable {
       // deliver buffered state events before a discrete one so handlers see
       // them in the order they happened (a drag sees the move, then the up)
       this._flushCoalesced();
+      if (eventName === 'resize') this._tagResize(ntkev);
       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
@@ -628,8 +639,6 @@ export default class Window extends Drawable {
     this._dirty = false;
     this._backingValid = false;
     this._presentScheduled = false;
-    this._backedW = this.width;
-    this._backedH = this.height;
 
     this._presentGc = this.X.AllocID();
     this.X.CreateGC(this._presentGc, this.id, { graphicsExposures: 0 });
@@ -642,10 +651,11 @@ export default class Window extends Drawable {
       this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, () => {});
     }
 
+    // a pure move is a ConfigureNotify too, and reallocating a backing
+    // pixmap per step of a window drag is the bug this flag exists to spare
+    // everyone (see _tagResize)
     this.on('resize', (ev) => {
-      if (ev.width === this._backedW && ev.height === this._backedH) return;
-      this._backedW = ev.width;
-      this._backedH = ev.height;
+      if (!ev.resized) return;
       this._allocBacking(ev.width, ev.height);
       this._backingValid = false;
       this._requestRedraw();
@@ -875,6 +885,46 @@ export default class Window extends Drawable {
     this._scheduleFrame();
   }
 
+  /**
+   * Say what a 'resize' actually changed.
+   *
+   * 'resize' is ConfigureNotify, which fires for pure moves and for
+   * reparents as much as for size changes — under an opaque-move window
+   * manager a window drag is one per pointer step. Every consumer used to
+   * rediscover that by keeping its own copy of the last size (this library
+   * included, in the backing-store listener), and one that didn't paid a
+   * full relayout per step of a drag.
+   *
+   * So the delivered event says which it was:
+   *
+   *   - `ev.resized` — the size differs from the last delivered event's
+   *   - `ev.moved` — the position does
+   *   - `ev.previous` — that event's `{x, y, width, height}`, for a delta;
+   *     null on an adopted window whose geometry is not known yet, where
+   *     both flags read true because nothing can be ruled out
+   *
+   * Measured against the last *delivered* event, not the last raw one, so
+   * that coalescing cannot swallow a change: a frame that merges two moves
+   * and a resize reports both, where per-hop flags would report only the
+   * final hop. The merged raw events in `ev.coalesced` are not tagged for
+   * that reason — the flags are a property of the delivery.
+   *
+   * Position is compared as reported. A reparenting window manager sends
+   * real ConfigureNotify in frame coordinates and synthetic ones in root
+   * coordinates (ICCCM 4.2.3), so a frame's own offset can read as a move
+   * on the first event after the switch. That is the safe direction —
+   * spurious work, never missed work — and the alternative is a
+   * TranslateCoordinates round trip per event, which is the cost this flag
+   * exists to avoid.
+   */
+  _tagResize(ev) {
+    const prev = this._deliveredGeom;
+    ev.previous = prev;
+    ev.moved = !prev || ev.x !== prev.x || ev.y !== prev.y;
+    ev.resized = !prev || ev.width !== prev.width || ev.height !== prev.height;
+    this._deliveredGeom = { x: ev.x, y: ev.y, width: ev.width, height: ev.height };
+  }
+
   _flushCoalesced() {
     const pending = this._frame.pending;
     if (!pending.size) return;
@@ -884,6 +934,7 @@ export default class Window extends Drawable {
       const ev = pending.get(name);
       if (ev) {
         pending.delete(name);
+        if (name === 'resize') this._tagResize(ev);
         this.emit(name, ev);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "parse-color": "^1.0.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.23",
-    "x11": "^3.6.0",
+    "x11": "^3.7.0",
     "yoga-layout": "^3.2.1"
   },
   "scripts": {