ntk 6.0.1 → 6.1.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/package.json

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