ntk 8.1.1 → 8.3.0

package/lib/pictformat.js

@@ -0,0 +1,196 @@
+/**
+ * Which RENDER picture format describes a drawable's pixels.
+ *
+ * A picture format is how the server is told to read and write a drawable:
+ * where the red, green, blue and alpha bits are and how many of each. Depth
+ * does not name one — a depth-16 visual can be 5:6:5 or 5:5:5 with a spare
+ * bit, a depth-24 one can be RGB or BGR, and both 8:8:8:8 and 10:10:10:2 are
+ * 32 bits wide. The **visual** is what fixes the layout, so that is what a
+ * format has to be picked from (issue #295).
+ *
+ * The mapping the server keeps is in `QueryPictFormats`' screens/depths/
+ * visuals section, which node-x11 decodes since 4.0.0
+ * ([node-x11#280](https://github.com/sidorares/node-x11/issues/280)) — that
+ * is the server's own answer, and it is what is used when the reply carries
+ * it.
+ *
+ * A visual the reply leaves out — one whose depth this server's RENDER does
+ * not describe — is reconstructed the way the server would have built it: a
+ * visual's `red_mask`/`green_mask`/`blue_mask` from the connection handshake,
+ * matched against the shift/mask pairs of the formats list. Both sides come
+ * from the same server, so this is a lookup rather than a guess — the only
+ * thing it cannot recover is a format for an *indexed* visual, which has no
+ * masks to match on and which only the reply can name.
+ */
+
+/** `type` in a formats-list entry. */
+export const PICT_TYPE = { Indexed: 0, Direct: 1 };
+
+/**
+ * The fields of a `QueryPictFormats` entry, which node-x11 hands over as a
+ * positional array (`x11/lib/ext/render.js`).
+ */
+const FIELD = {
+  id: 0,
+  type: 1,
+  depth: 2,
+  redShift: 3,
+  redMask: 4,
+  greenShift: 5,
+  greenMask: 6,
+  blueShift: 7,
+  blueMask: 8,
+  alphaShift: 9,
+  alphaMask: 10,
+  colormap: 11
+};
+
+/** A formats-list entry as an object, from node-x11's positional array. */
+export function parsePictFormats(reply) {
+  const list = (Array.isArray(reply) ? reply : reply?.formats) ?? [];
+  return list.map((f) => {
+    if (!Array.isArray(f)) return f;
+    const out = {};
+    for (const name in FIELD) out[name] = f[FIELD[name]];
+    return out;
+  });
+}
+
+/** Where a channel's bits sit in a pixel, as one mask over the whole word. */
+const channelMask = (shift, mask) => ((mask >>> 0) << shift) >>> 0;
+
+/** How many bits a mask covers. */
+function bitCount(mask) {
+  let n = 0;
+  for (let m = mask >>> 0; m; m >>>= 1) n += m & 1;
+  return n;
+}
+
+/**
+ * The format id for a visual, or `null` where the formats list holds none.
+ *
+ * The colour masks have to agree exactly; what is left over is the choice
+ * between, say, `a8r8g8b8` and `x8r8g8b8`, and the spare bits settle it. A
+ * whole byte the channels do not account for is the alpha channel every ARGB
+ * visual has; a bit or two — the spare bit of a 5:5:5 in 16, the two of a
+ * 10:10:10 in 32 — is padding no client ever wrote, and reading it as alpha
+ * would composite a garbage bit as transparency.
+ *
+ * Depth is matched first and relaxed only if that finds nothing, because the
+ * two lists do not always agree on it. A server names the format it created
+ * for a visual with that visual's depth, but the fixed formats every RENDER
+ * server also publishes carry the *pixel* width instead — `a2r10g10b10` is
+ * listed at depth 32, and a 10:10:10 visual is depth 30. Matching masks alone
+ * still identifies the layout, which is the part that decides how pixels are
+ * read.
+ *
+ * @param {object} visual a handshake visual (`{ red_mask, green_mask, blue_mask }`)
+ * @param {number} depth the depth its `depths` entry is under
+ * @param {Array<object>} formats parsed formats list
+ * @returns {number|null}
+ */
+export function matchVisualFormat(visual, depth, formats) {
+  const red = (visual?.red_mask ?? 0) >>> 0;
+  const green = (visual?.green_mask ?? 0) >>> 0;
+  const blue = (visual?.blue_mask ?? 0) >>> 0;
+  // An indexed visual (PseudoColor, GrayScale and the static pair) carries no
+  // masks: its format is an Indexed one, tied to a colormap this list cannot
+  // be matched against. Nothing here can name it, and saying so is better
+  // than naming a Direct format whose channels it does not have.
+  if (!(red || green || blue)) return null;
+
+  const wantAlpha = depth - (bitCount(red) + bitCount(green) + bitCount(blue)) >= 8;
+  // near misses, in the order they would be settled for: same depth but the
+  // wrong side of the alpha choice, then the two the same way round again
+  // with the depth relaxed
+  let sameDepthAlt = null;
+  let otherDepth = null;
+  let otherDepthAlt = null;
+
+  for (const f of formats) {
+    if (f.type !== PICT_TYPE.Direct) continue;
+    if (channelMask(f.redShift, f.redMask) !== red) continue;
+    if (channelMask(f.greenShift, f.greenMask) !== green) continue;
+    if (channelMask(f.blueShift, f.blueMask) !== blue) continue;
+    const hasAlpha = (f.alphaMask ?? 0) !== 0;
+    if (f.depth === depth) {
+      if (hasAlpha === wantAlpha) return f.id;
+      sameDepthAlt ??= f.id;
+    } else if (hasAlpha === wantAlpha) {
+      otherDepth ??= f.id;
+    } else {
+      otherDepthAlt ??= f.id;
+    }
+  }
+  return sameDepthAlt ?? otherDepth ?? otherDepthAlt;
+}
+
+/**
+ * visual id -> format id, from the reply's screens section where the server
+ * sent one, and matched on colour masks where it did not.
+ *
+ * Visual ids are unique across screens, so one flat map answers for all of
+ * them. The server's own table is the whole answer where it is there — it
+ * names indexed visuals too, which masks cannot — and mask matching then
+ * fills in only the visuals it left out.
+ *
+ * @param {object} display node-x11's display object
+ * @param {Array<object>} formats parsed formats list
+ * @param {object} [reply] the `QueryPictFormats` reply, for its `screens`
+ * @returns {Map<number, number>}
+ */
+export function visualFormats(display, formats, reply) {
+  const byVisual = new Map();
+  for (const screen of reply?.screens ?? []) {
+    for (const depth of screen?.depths ?? []) {
+      for (const { visual, format } of depth?.visuals ?? []) {
+        byVisual.set(visual >>> 0, format);
+      }
+    }
+  }
+  for (const screen of display?.screen ?? []) {
+    for (const depth in screen.depths ?? {}) {
+      for (const visual of Object.values(screen.depths[depth])) {
+        const vid = visual.vid >>> 0;
+        if (byVisual.has(vid)) continue;
+        const format = matchVisualFormat(visual, Number(depth), formats);
+        if (format != null) byVisual.set(vid, format);
+      }
+    }
+  }
+  return byVisual;
+}
+
+/**
+ * visual id -> the depth its pixels are, straight from the handshake.
+ *
+ * @param {object} display node-x11's display object
+ * @returns {Map<number, number>}
+ */
+export function visualDepths(display) {
+  const byVisual = new Map();
+  for (const screen of display?.screen ?? []) {
+    for (const depth in screen.depths ?? {}) {
+      for (const visual of Object.values(screen.depths[depth])) {
+        byVisual.set(visual.vid >>> 0, Number(depth));
+      }
+    }
+  }
+  return byVisual;
+}
+
+/**
+ * The format a drawable of this depth is read through when its visual is not
+ * available — a pixmap, which has no visual at all, or a window whose visual
+ * has not been asked for yet.
+ *
+ * The standard formats node-x11 picks out of the list by their masks. Right
+ * for the layouts an X client meets most of the time (8:8:8 colour, 8-bit
+ * coverage) and wrong for everything else, which is why it is the fallback
+ * and not the answer.
+ */
+export function formatForDepth(Render, depth) {
+  if (depth === 32) return Render.rgba32;
+  if (depth === 8) return Render.a8;
+  return Render.rgb24;
+}

package/lib/pixmap.js

@@ -1,15 +1,46 @@
 import { safeRelease } from './cleanup.js';
 import Drawable from './drawable.js';
+import { extensionEventNames } from './events_map.js';
 
 // GC fallback: free the server-side pixmap when the wrapper is collected
 // without an explicit destroy()
-const registry = new FinalizationRegistry(({ X, id }) => {
+const registry = new FinalizationRegistry(({ X, id, releaseId }) => {
   safeRelease(X, () => {
     X.FreePixmap(id);
-    X.ReleaseID(id);
+    if (releaseId) X.ReleaseID(id);
   });
 });
 
+/**
+ * A GetGeometry reply in ntk's spelling (window.js has the window-shaped
+ * twin). For a pixmap, `x`, `y` and `borderWidth` are always 0 — X reports
+ * them anyway, and returning the same shape as `wnd.getGeometry()` keeps the
+ * two interchangeable.
+ */
+function unpackGeometry(res) {
+  return {
+    x: res.xPos,
+    y: res.yPos,
+    width: res.width,
+    height: res.height,
+    depth: res.depth,
+    borderWidth: res.borderWidth,
+    root: res.windowid
+  };
+}
+
+/**
+ * Whether this connection's allocator handed out `id`. Owning an adopted
+ * pixmap does not always mean the id was ours: XCompositeNameWindowPixmap
+ * names a pixmap into an id the adopter allocated itself, but a pixmap made
+ * by another client carries an id from that client's range. Only an id of
+ * ours may go back into the pool on destroy — releasing a foreign one would
+ * eventually make AllocID hand out an id the server refuses as not ours.
+ */
+function ownAllocation(display, id) {
+  return ((id & ~display.resource_mask) >>> 0) === (display.resource_base >>> 0);
+}
+
 export default class Pixmap extends Drawable {
   constructor(app, args = {}) {
     super();
@@ -18,29 +49,157 @@ export default class Pixmap extends Drawable {
     this.X = X;
     this.display = app.display;
 
-    const parentId = args.parent ? args.parent.id : app.display.screen[0].root;
-    this.depth = args.depth || 24;
+    // A pixmap has no visual of its own — X gives it a depth and nothing
+    // else. What its pixels mean is decided by whoever put them there, so a
+    // pixmap holding a window's content (a backing store, a compositor's
+    // NameWindowPixmap) is told which visual that was: it is what names the
+    // picture format the pixels can be read through (issue #295). Left 0,
+    // the format is picked from the depth as before.
+    this.visualId = args.visual ?? 0;
+
+    // `pixmap.ready` (see the getter): resolved as soon as this wrapper
+    // knows its geometry — at the end of the constructor for a pixmap ntk
+    // created or one adopted with its geometry declared, when GetGeometry
+    // replies for one adopted by bare id
+    this._readyPromiseResolve = null;
+    this._readyPromise = new Promise((resolve) => {
+      this._readyPromiseResolve = resolve;
+    });
+    this._adoptError = null;
 
     if (!args.id) {
+      const parentId = args.parent ? args.parent.id : app.display.screen[0].root;
+      this.depth = args.depth || 24;
       this.id = X.AllocID();
       X.CreatePixmap(this.id, parentId, this.depth, args.width, args.height);
       this.width = args.width;
       this.height = args.height;
       this._owned = true;
-      registry.register(this, { X, id: this.id }, this);
+      this._releaseId = true;
+      registry.register(this, { X, id: this.id, releaseId: true }, this);
+      this._readyPromiseResolve(this);
     } else {
       this.id = args.id;
-      this._owned = false;
+      // Nothing is defaulted for an adopted pixmap: what the caller declared
+      // is recorded, and what they did not is asked of the server rather
+      // than guessed — a depth invented here would pick the picture format
+      // everything drawing on it reads the pixels through (issue #291).
+      this.width = args.width;
+      this.height = args.height;
+      this.depth = args.depth;
+      this._owned = !!args.own;
+      this._releaseId = this._owned && ownAllocation(this.display, this.id);
+      if (this._owned) {
+        registry.register(this, { X, id: this.id, releaseId: this._releaseId }, this);
+      }
+      if (this.width !== undefined && this.height !== undefined && this.depth !== undefined) {
+        this._readyPromiseResolve(this);
+      } else {
+        X.GetGeometry(this.id, (err, res) => {
+          // A pixmap freed between the id reaching us and this request
+          // reaching the server answers BadDrawable, and there is nothing to
+          // record. `ready` still resolves — a wait that never ends is worse
+          // than one that ends with `width` undefined — and `Pixmap.adopt`
+          // is the form that turns this into a rejection.
+          if (err) this._adoptError = err;
+          else this._applyGeometry(unpackGeometry(res));
+          this._readyPromiseResolve(this);
+        });
+      }
+    }
+
+    // Extension events name their drawable, and a DAMAGE object can watch a
+    // pixmap, so routing (see App#_routeExtensionEvents) looks the target up
+    // in `X.event_consumers` — where windows already live. A pixmap enrols
+    // only when someone listens, because the entry is a strong reference:
+    // enrolling every pixmap would pin them all past the GC fallback above.
+    // A listening pixmap therefore stays until destroy(), which is also what
+    // removes it from the table.
+    this.on('newListener', (name) => {
+      if (extensionEventNames.has(name) && X.event_consumers) {
+        X.event_consumers[this.id] = this;
+      }
+    });
+  }
+
+  /**
+   * Adopt an existing pixmap id: ask the server for its geometry and depth,
+   * and take responsibility for freeing it. This is the compositor's case —
+   * XCompositeNameWindowPixmap hands back a pixmap the adopting client must
+   * FreePixmap, and must re-adopt on every resize of the named window — but
+   * any handover of a pixmap id works the same way.
+   *
+   * Rejects if the pixmap does not exist (already freed — for a compositor,
+   * re-name the window and adopt the fresh id). Pass `own: false` to observe
+   * a pixmap that stays another client's to free, `visual` to name the
+   * visual its pixels are laid out in (see the constructor), and any of
+   * `width`/`height`/`depth` already known — with all three declared no
+   * round trip is made.
+   */
+  static async adopt(app, id, { own = true, ...args } = {}) {
+    const pixmap = new Pixmap(app, { ...args, id, own });
+    await pixmap.ready;
+    if (pixmap._adoptError) {
+      // there is nothing server-side to own, so the GC fallback must not
+      // send a FreePixmap of its own to fail the same way
+      pixmap._owned = false;
+      registry.unregister(pixmap);
+      throw new Error(
+        `Pixmap.adopt: pixmap 0x${id.toString(16)} does not exist — it was freed ` +
+          'between its id being obtained and this request. A compositor sees this ' +
+          'when the named window was resized or destroyed: name it again and adopt ' +
+          'the fresh id.',
+        { cause: pixmap._adoptError }
+      );
     }
+    return pixmap;
+  }
+
+  /**
+   * Resolves with this pixmap once its geometry and depth are known —
+   * immediately for a pixmap ntk created or one adopted with `width`,
+   * `height` and `depth` all declared, when the GetGeometry sent by the
+   * constructor replies for one adopted by bare id. Never rejects: a pixmap
+   * that was already gone resolves with `width` still `undefined`.
+   */
+  get ready() {
+    return this._readyPromise;
+  }
+
+  /**
+   * Ask the server about this pixmap now — `{ x, y, width, height, depth,
+   * borderWidth, root }`, the same shape `wnd.getGeometry()` resolves with
+   * (`x`, `y` and `borderWidth` are 0 for a pixmap). The reply is written
+   * back to `width`/`height`/`depth`, and resolves `ready` if it was still
+   * pending.
+   */
+  getGeometry() {
+    return new Promise((resolve, reject) => {
+      this.X.GetGeometry(this.id, (err, res) => {
+        if (err) return reject(err);
+        const geometry = unpackGeometry(res);
+        this._applyGeometry(geometry);
+        resolve(geometry);
+      });
+    });
+  }
+
+  /** Record a GetGeometry reply, and let anything waiting on it go. */
+  _applyGeometry({ width, height, depth }) {
+    this.width = width;
+    this.height = height;
+    this.depth = depth;
+    this._readyPromiseResolve(this);
   }
 
   destroy() {
+    if (this.X.event_consumers?.[this.id] === this) delete this.X.event_consumers[this.id];
     if (!this._owned) return;
     this._owned = false;
     registry.unregister(this);
     safeRelease(this.X, () => {
       this.X.FreePixmap(this.id);
-      this.X.ReleaseID(this.id);
+      if (this._releaseId) this.X.ReleaseID(this.id);
     });
   }
 

package/lib/region.js

@@ -0,0 +1,148 @@
+import { safeRelease } from './cleanup.js';
+
+export const REGION_DOCS = 'https://github.com/sidorares/ntk/blob/master/docs/context-2d.md#region-clips';
+
+const registry = new FinalizationRegistry(({ fixes, X, id }) => {
+  safeRelease(X, () => {
+    fixes.DestroyRegion(id);
+    X.ReleaseID(id);
+  });
+});
+
+/**
+ * One rectangle in the form XFIXES wants, from either spelling.
+ *
+ * ntk's own boxes are `{ x, y, w, h }` — that is what `_clipRect()` and the
+ * damage rectangles a window reports look like — and the protocol's are
+ * `{ x, y, width, height }`. Taking both means a region can be built out of
+ * boxes ntk handed the caller without a translation step whose only job is
+ * to rename two fields.
+ */
+function toRect(r) {
+  const width = r.width ?? r.w;
+  const height = r.height ?? r.h;
+  if (!Number.isFinite(r.x) || !Number.isFinite(r.y) || !Number.isFinite(width) || !Number.isFinite(height)) {
+    throw new TypeError(`ntk: region rectangle needs finite x/y/width/height, got ${JSON.stringify(r)}`);
+  }
+  return { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(width), height: Math.round(height) };
+}
+
+const toRects = (rects) => (rects || []).map(toRect);
+
+/**
+ * The id of an XFIXES region, given a `Region`, a raw id, or anything else
+ * carrying one (`{ id }`). Regions are ids on the wire, so a caller who made
+ * one through node-x11 directly can still hand it to `ctx.clipRegion()`.
+ */
+export function regionId(value) {
+  const id = typeof value === 'number' ? value : value?.id;
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new TypeError(
+      `ntk: expected an XFIXES region (app.createRegion(...)) or its id, got ${JSON.stringify(value)}`
+    );
+  }
+  return id;
+}
+
+/**
+ * A server-side XFIXES region: a set of rectangles the X server keeps and
+ * combines for you, with no round trip per operation.
+ *
+ * Regions are how X describes a non-rectangular area — damage from an
+ * expose, a window's SHAPE, the area a compositor has left to paint after
+ * subtracting the windows in front. `ctx.clipRegion(region)` clips a 2d
+ * context to one (docs/context-2d.md).
+ *
+ * Build one with `await app.createRegion(rects)`; the await is the XFIXES
+ * extension being loaded on first use, not a round trip per region.
+ * Everything after that is asynchronous in the X sense — requests go out and
+ * nothing waits — except `fetch()`, which is a reply.
+ */
+export default class Region {
+  /**
+   * Not called directly: `app.createRegion(rects)` loads XFIXES first and is
+   * the supported way in.
+   *
+   * @param {App} app
+   * @param {object} fixes the XFIXES extension, as `app.fixes()` resolves it
+   * @param {Array<object>} [rects] `{ x, y, width, height }` or `{ x, y, w, h }`
+   */
+  constructor(app, fixes, rects = []) {
+    this.app = app;
+    this.X = app.X;
+    this.fixes = fixes;
+    this.id = this.X.AllocID();
+    this.fixes.CreateRegion(this.id, toRects(rects));
+    this._owned = true;
+    registry.register(this, { fixes, X: this.X, id: this.id }, this);
+  }
+
+  /** Replace the contents with this rectangle list. */
+  set(rects) {
+    this.fixes.SetRegion(this.id, toRects(rects));
+    return this;
+  }
+
+  /** Replace the contents with another region's. */
+  copyFrom(other) {
+    this.fixes.CopyRegion(regionId(other), this.id);
+    return this;
+  }
+
+  /** Move by (dx, dy). */
+  translate(dx, dy) {
+    this.fixes.TranslateRegion(this.id, Math.round(dx), Math.round(dy));
+    return this;
+  }
+
+  /** Keep only what is also in `other`. In place. */
+  intersect(other) {
+    this.fixes.IntersectRegion(this.id, regionId(other), this.id);
+    return this;
+  }
+
+  /** Add everything in `other`. In place. */
+  union(other) {
+    this.fixes.UnionRegion(this.id, regionId(other), this.id);
+    return this;
+  }
+
+  /**
+   * Remove everything in `other`. In place — and the operation a compositor
+   * runs once per window, painting front to back and taking each window's
+   * shape out of what is left for the ones behind it.
+   */
+  subtract(other) {
+    this.fixes.SubtractRegion(this.id, regionId(other), this.id);
+    return this;
+  }
+
+  /**
+   * Read the region back: `{ extents, rectangles }`, each rectangle
+   * `{ x, y, width, height }`. The one round trip in the class — regions are
+   * meant to be combined server-side, so reach for this to inspect or to
+   * test, not inside a paint loop.
+   *
+   * @returns {Promise<{extents: object, rectangles: Array<object>}>}
+   */
+  fetch() {
+    return new Promise((resolve, reject) => {
+      this.fixes.FetchRegion(this.id, (err, region) => (err ? reject(err) : resolve(region)));
+    });
+  }
+
+  /** Free the region server-side. Idempotent. */
+  destroy() {
+    if (!this._owned) return;
+    this._owned = false;
+    registry.unregister(this);
+    safeRelease(this.X, () => {
+      this.fixes.DestroyRegion(this.id);
+      this.X.ReleaseID(this.id);
+    });
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}