ntk 8.7.0 → 8.8.0

package/lib/app.js

@@ -1,7 +1,17 @@
 import { connectionGone } from './cleanup.js';
 import Clipboard from './clipboard.js';
 import { CursorCache } from './cursor.js';
-import { GLError, backendFor, glCapabilities, glError, nativeRefreshRate, resolveGLPolicy } from './gl.js';
+import {
+  DIRECT_SAMPLES,
+  GLError,
+  backendFor,
+  glCapabilities,
+  glError,
+  nativeRefreshRate,
+  requestedSamples,
+  resolveGLPolicy,
+  warnDirectSamples
+} from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
@@ -620,6 +630,13 @@ export default class App {
    * fbconfig with an alpha channel. Direct needs no round trip to answer —
    * there are no fbconfigs in it, only a window the GPU draws for.
    *
+   * What a backend cannot do, the answer says rather than drops: `samples`
+   * is the colour samples per pixel the returned config really has, which
+   * on the direct backend is 0 today whatever the spec asked for (issue
+   * #341, `DIRECT_SAMPLES` in lib/gl.js). A `SAMPLES`/`SAMPLE_BUFFERS`
+   * request that cannot be met also warns once per connection, because an
+   * aliased edge is otherwise found months later in a screenshot.
+   *
    * @param {object} [spec] GLX attributes, e.g. `{ DEPTH_SIZE: 24 }`
    */
   async chooseGLConfig(spec = {}) {
@@ -638,6 +655,11 @@ export default class App {
         `direct rendering: screen ${screenNum} has no 32-bit visual, so a GL window cannot have an alpha channel`
       );
     }
+    // asked for multisampling this backend cannot give? say so once, then
+    // answer honestly below rather than dropping the attribute (issue #341)
+    const wantSamples = requestedSamples(spec);
+    if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(this, caps.flavor, wantSamples);
+
     return {
       backend: 'direct',
       // which direct pipeline this connection runs: 'dri3' or 'appledri'
@@ -649,6 +671,9 @@ export default class App {
       class: 4, // TrueColor; the only class these buffers can be read as
       doubleBuffer: true, // a swap chain, always
       depthSize: spec.DEPTH_SIZE ?? 16,
+      // no flavor can allocate a multisampled window buffer yet; said out
+      // loud so a caller can supersample instead of assuming MSAA
+      samples: DIRECT_SAMPLES,
       screen: screenNum,
       fbconfig: null,
       device: caps.device,

package/lib/gl.js

@@ -467,6 +467,68 @@ export function glCapabilities(app) {
   return app._glCaps;
 }
 
+/**
+ * How many colour samples per pixel a direct-backend window has. Zero, on
+ * both flavors, and this is the one place that says so.
+ *
+ * Not because multisampling is exotic on a GPU — it is nearly free there —
+ * but because the sample count belongs to the pixel format the `x11-dri`
+ * addon builds one layer below ntk: `EGL_SAMPLES` on the EGLConfig behind
+ * the GBM surface (`dri3`), `kCGLPFASamples`/`kCGLPFASampleBuffers` on the
+ * CGL pixel format (`appledri`). Its `Gpu` and `apple.Context` take a depth
+ * size and no sample count, and its GL table has neither
+ * `renderbufferStorageMultisample` nor `blitFramebuffer`, so there is not a
+ * multisampled framebuffer for ntk to resolve by hand either. Nothing here
+ * can conjure one — what it can do is not pretend, which is why
+ * `chooseGLConfig` reports `samples` on every backend and says so out loud
+ * when the spec asked for more than it got (issue #341).
+ *
+ * When the addon grows the option this becomes what it reports, and the
+ * request travels the rest of the way without another change here.
+ */
+export const DIRECT_SAMPLES = 0;
+
+/**
+ * The sample count a GLX-vocabulary spec asks for: `SAMPLES` when it names
+ * one, 1 for a bare `SAMPLE_BUFFERS` (multisample, width up to the driver),
+ * and 0 when it asks for no multisampling at all — which is also what a
+ * config object from `chooseGLConfig` reads as, since it carries neither.
+ */
+export function requestedSamples(spec = {}) {
+  const samples = Number(spec.SAMPLES) || 0;
+  if (samples > 0) return samples;
+  return Number(spec.SAMPLE_BUFFERS) > 0 ? 1 : 0;
+}
+
+/**
+ * Say — once per connection, on the console — that a multisample request
+ * cannot be honoured here.
+ *
+ * A downgrade rather than a failure: the window renders, its edges alias.
+ * That is exactly the kind of thing an app finds out about six months later
+ * from a screenshot, so it is worth one warning and a `samples` field to
+ * branch on. Once per connection because every window would otherwise say
+ * it again.
+ */
+export function warnDirectSamples(app, flavor, wanted) {
+  if (app._warnedDirectSamples) return;
+  app._warnedDirectSamples = true;
+  console.warn(
+    `ntk: this GL request asks for SAMPLES=${wanted}, and the direct backend` +
+      `${flavor ? ` (${flavor} flavor)` : ''} cannot give a window a multisampled buffer, so it has ` +
+      'samples: 0 and its edges will alias.\n' +
+      '\n' +
+      '  The sample count belongs to the pixel format x11-dri builds one layer below\n' +
+      '  ntk (EGL_SAMPLES on dri3, kCGLPFASamples on appledri), and it takes no such\n' +
+      '  option yet — there is nothing here to ask with.\n' +
+      '\n' +
+      '  Branch on config.samples (or gl.samples) rather than on having asked. For\n' +
+      "  multisampling today: indirect GLX honours SAMPLES (glPolicy: 'indirect'),\n" +
+      '  where the server picks an fbconfig that has it — or supersample in your own\n' +
+      '  draw code. See docs/context-gles.md#multisampling.'
+  );
+}
+
 /**
  * The backend `getContext('opengl')` should use right now, synchronously.
  *

package/lib/glx.js

@@ -131,7 +131,15 @@ const legacyProps = {
   BLUE_SIZE: 'blueBits',
   ALPHA_SIZE: 'alphaBits',
   AUX_BUFFERS: 'numAuxBuffers',
-  LEVEL: 'level'
+  LEVEL: 'level',
+  // Not among GetVisualConfigs' fixed properties, but a server that has
+  // multisample visuals sends these as (tag, value) pairs after them, which
+  // x11 decodes under their attribute names. Mapped to themselves so a
+  // SAMPLES request is filtered on this path too rather than passing
+  // through unexamined — a spec that asks for multisampling and gets a
+  // visual without it is the failure this whole field exists to stop.
+  SAMPLE_BUFFERS: 'SAMPLE_BUFFERS',
+  SAMPLES: 'SAMPLES'
 };
 
 // attributes compared as "at least this much"; the rest must match exactly
@@ -219,8 +227,11 @@ function matchLegacy(configs, spec) {
  *   `null` means "don't care". `screen` picks the X screen (default 0),
  *   `visual` pins a specific visual id and skips the search.
  * @returns {Promise<{visual: number, depth: number, class: number,
- *   doubleBuffer: boolean, depthSize: number, fbconfig: number|null,
- *   config: object}>}
+ *   doubleBuffer: boolean, depthSize: number, samples: number|null,
+ *   fbconfig: number|null, config: object}>} `samples` is the colour
+ *   samples per pixel the chosen config has — 0 for no multisampling, and
+ *   `null` only in the pinned-`visual` case, where no fbconfig was looked
+ *   at to know.
  */
 export async function chooseGLXConfig(app, spec = {}) {
   const GLX = app.display.GLX;
@@ -255,6 +266,9 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!toNumber(want.DOUBLEBUFFER),
       depthSize: toNumber(want.DEPTH_SIZE) || 0,
+      // the caller pinned the visual, so nothing was chosen and no fbconfig
+      // was read: unknown, which is not the same claim as "none"
+      samples: null,
       screen: screenNum,
       fbconfig: null,
       config: {}
@@ -272,6 +286,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.DOUBLEBUFFER,
       depthSize: cfg.DEPTH_SIZE || 0,
+      samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: cfg.FBCONFIG_ID,
       config: cfg
@@ -292,6 +307,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.doubleBufferMode,
       depthSize: cfg.depthBits || 0,
+      samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: null,
       config: cfg

package/lib/renderingcontext_cgl.js

@@ -43,7 +43,15 @@
 
 import { connectionGone } from './cleanup.js';
 import Drawable from './drawable.js';
-import { GLError, backendFor, glError, loadDriAddon } from './gl.js';
+import {
+  DIRECT_SAMPLES,
+  GLError,
+  backendFor,
+  glError,
+  loadDriAddon,
+  requestedSamples,
+  warnDirectSamples
+} from './gl.js';
 
 /** pacing fallback where the display's rate is not known (see App#frameInterval) */
 const FALLBACK_FRAME_INTERVAL = 1000 / 60;
@@ -115,6 +123,17 @@ does not make it retroactive. Either:
       );
     }
     this.depth = depth;
+
+    /**
+     * Colour samples per pixel — 0 here, as on every direct flavor
+     * (`DIRECT_SAMPLES`). A config asking for more is a request this
+     * pipeline cannot pass on, so it is answered rather than dropped: the
+     * warning fires once per connection, and draw code branches on this.
+     */
+    this.samples = DIRECT_SAMPLES;
+    const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
+    if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, 'appledri', wantSamples);
+
     this._screen = config.screen ?? 0;
     this._clientId = caps.appleClientId ?? dri.apple.clientId();
 

package/lib/renderingcontext_gles.js

@@ -17,7 +17,15 @@
 // is proven.
 
 import Drawable from './drawable.js';
-import { GLError, backendFor, glError, loadDriAddon } from './gl.js';
+import {
+  DIRECT_SAMPLES,
+  GLError,
+  backendFor,
+  glError,
+  loadDriAddon,
+  requestedSamples,
+  warnDirectSamples
+} from './gl.js';
 import { GLSwapchain } from './glswapchain.js';
 
 /**
@@ -98,6 +106,16 @@ does not make it retroactive. Either:
     }
     this.depth = depth;
 
+    /**
+     * Colour samples per pixel — 0 here, as on every direct flavor
+     * (`DIRECT_SAMPLES`). A config asking for more is a request this
+     * pipeline cannot pass on, so it is answered rather than dropped: the
+     * warning fires once per connection, and draw code branches on this.
+     */
+    this.samples = DIRECT_SAMPLES;
+    const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
+    if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, caps.flavor, wantSamples);
+
     const policy = app.glPolicy;
     this.gpu = sharedGpu(app, dri, {
       format: depth === 32 ? dri.FORMAT.ARGB8888 : dri.FORMAT.XRGB8888,

package/lib/renderingcontext_opengl.js

@@ -30,6 +30,14 @@ class RenderingContextOpenGL {
     this.contextId = 0;
     /** the config chosen (or passed in), see app.chooseGLXConfig */
     this.config = null;
+    /**
+     * Colour samples per pixel the config in use has: 0 until the config is
+     * resolved, and 0 afterwards unless the spec asked for multisampling and
+     * the server had an fbconfig with it. The direct contexts carry the same
+     * field, so draw code can decide whether to antialias itself without
+     * knowing which backend it is on.
+     */
+    this.samples = 0;
     this.visual = 0;
     this.error = null;
 
@@ -75,6 +83,9 @@ class RenderingContextOpenGL {
     this.ready = (async () => {
       const cfg = await this._resolveConfig(config);
       this.config = cfg;
+      // a config passed in by hand may be the fbconfig itself rather than a
+      // chooseGLXConfig result, so read either shape
+      this.samples = cfg.samples ?? cfg.config?.SAMPLES ?? cfg.SAMPLES ?? 0;
       this.visual = cfg.visual;
       if (window.visual && window.visual !== cfg.visual) {
         console.warn(

package/lib/window.js

@@ -3719,6 +3719,9 @@ export default class Window extends Drawable {
    * connection selected and nothing else adds to it behind the caller's
    * back. It resolves rather than returning undefined because the promise is
    * the whole interface: an awaited no-op still has to mean "you have it".
+   *
+   * `deselectInput(mask)` is the inverse, and the only thing that lowers the
+   * mask again — `off()` drops the listener and leaves the selection.
    */
   selectInput(mask) {
     const added = mask & ~this.eventMask;
@@ -3736,6 +3739,92 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * The bits of the event mask something in this process still needs: the
+   * union over every event name with a live listener, plus what ntk's own
+   * machinery requires. `deselectInput` refuses exactly these, so
+   * `mask & wnd.heldEventMask` asks "would that be refused?" without making
+   * the request.
+   *
+   * Not a subset of `eventMask`. A listener implies a bit whether or not
+   * this connection ever selected it — an adopted window selects nothing
+   * (issue #322), and ntk's own map/unmap/destroy handlers listen without
+   * asking for anything.
+   */
+  get heldEventMask() {
+    let held = 0;
+    for (const name in xevents.mask) {
+      const bit = xevents.mask[name];
+      // 0 marks an event that arrives regardless of any selection
+      if (bit && this.listenerCount(name) > 0) held |= bit;
+    }
+    // the redraw cycle is driven by intercepting Expose, whether or not
+    // anyone listens for it: a double-buffered window that stops selecting
+    // Exposure stops repainting (see _enableBackingStore)
+    if (this._backing) held |= x11.eventMask.Exposure;
+    return held;
+  }
+
+  /**
+   * Stop selecting `mask` — the inverse of `selectInput`, and the only way a
+   * window's event mask ever goes down (issue #318).
+   *
+   * `on(name, fn)` raises the mask as a side effect and `off()` does not
+   * lower it again, so a window that stops needing an event goes on being
+   * sent it until it is destroyed. For most masks that is invisible; for
+   * PointerMotion it is 32 bytes per motion event — 2 KB/s at 60 Hz, and
+   * 8 KB/s where the motion is XI2's — for as long as the pointer is over
+   * the window. A viewer that hides its chrome, a toolbar that unmounts, a
+   * window that goes to a background tab: they know when they stop needing
+   * hover, and this is how they say so.
+   *
+   * Bits a live listener still needs are kept rather than cleared, because
+   * dropping PointerMotion out from under an `on('mousemove')` is the one
+   * bug this API can have. Several names share one bit — `map`, `unmap`,
+   * `resize`, `reparent`, `gravity`, `circulate` and `destroy` are all
+   * StructureNotify — so losing the last `map` listener does not make the
+   * bit free. It resolves with the bits it kept for that reason, `0` when it
+   * cleared everything it was asked to:
+   *
+   *   const kept = await wnd.deselectInput(x11.eventMask.PointerMotion);
+   *   if (kept) ... // something in this process is still listening
+   *
+   * Two selections it will therefore not clear: StructureNotify, held by
+   * ntk's own map/unmap/destroy bookkeeping on every window, and Exposure on
+   * a double-buffered one. XI2 is selected separately and keeps its own
+   * inverse — `selectXI2([])` (see lib/xi2.js).
+   */
+  deselectInput(mask) {
+    const clear = mask & this.eventMask & ~this.heldEventMask;
+    const kept = mask & this.eventMask & ~clear;
+    // asking to drop what is not selected, or only what is spoken for, is a
+    // request that would change nothing
+    if (clear === 0) return Promise.resolve(kept);
+    this.eventMask &= ~clear;
+    // no motion means no hints, so no frame owes the server the QueryPointer
+    // that re-arms one. A poll already in flight is left alone, as
+    // setMouseHintOnly leaves it: its answer is a real position.
+    if (clear & (x11.eventMask.PointerMotion | x11.eventMask.PointerMotionHint)) {
+      this._hintRearm = false;
+    }
+    // A window the server has already taken, or a connection on its way out:
+    // there is no selection left to lower, and node-x11 throws at a request
+    // from then on (issue #321). The tracked mask is lowered all the same —
+    // it says what this connection holds, and it holds nothing.
+    if (this._destroyed || connectionGone(this.X)) return Promise.resolve(kept);
+    return new Promise((resolve, reject) => {
+      this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, (err) => {
+        if (!err) return resolve(kept);
+        // the request failed as a whole, so the server kept the mask it had:
+        // take the bits back rather than leave `eventMask` denying a
+        // selection this connection still holds — the next on() reads it to
+        // decide whether a write can be skipped
+        this.eventMask |= clear;
+        reject(err);
+      });
+    });
+  }
+
   /**
    * Add this window to our save-set (X ChangeSaveSet). A window manager
    * reparents clients into frames it owns; without the save-set, the

package/package.json

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