ntk 8.9.0 → 8.10.0

package/README.md

@@ -120,6 +120,28 @@ Server-side resources support `using` / `await using` (Node 24+):
 } // pixmap freed, connection closed
 ```
 
+## Importing less
+
+`ntk` is the whole package: the X11 client, the font engine, the SVG parser
+and the image decoders all load with it. A program that needs one piece —
+a renderer drawing through something other than X11 that wants the colour
+parser, say — can import just that piece, and loads only what it needs:
+
+| Import              | What                                                    | Loads with it               |
+| ------------------- | ------------------------------------------------------- | --------------------------- |
+| `ntk/color`         | `cssColor`, `cssColorStraight`, `premultiply`           | `parse-color`               |
+| `ntk/imagedata`     | `ImageData`, `pixelLayout`, `toStraightRgba`, …         | —                           |
+| `ntk/path`          | `Path2D`, `parseSvgPath`                                | —                           |
+| `ntk/gl`            | `GLError`, `GL_MODES`, `DEFAULT_GL_POLICY`, …           | —                           |
+| `ntk/shadow-math`   | `shadowSigma`, `shadowReach`, `blurScale`, …            | —                           |
+| `ntk/image`         | `Image`, `decodeImage`, `loadImage`                     | `jpeg-js`, `pngjs`          |
+| `ntk/svg`           | `SvgView` (default export)                              | `htmlparser2`, `domutils`   |
+| `ntk/font`          | `Font` (default export)                                 | `fontkit`                   |
+| `ntk/xembed`        | the XEmbed protocol ([docs/xembed.md](docs/xembed.md))  | `x11`                       |
+
+Each is the same module the root re-exports, so importing a name both ways
+gives the same function or class: nothing is loaded, or instantiated, twice.
+
 ## 3d graphics
 
 Two backends, chosen by `glPolicy`

package/lib/glswapchain.js

@@ -108,23 +108,69 @@ export class GLSwapchain {
     const gen = this.generation;
     if (gen && gen.width === w && gen.height === h) return gen.surface;
     this._retire(gen);
-    // a generation that had to go linear keeps that layout: whatever made the
-    // server refuse the tiled buffer has not changed since
+    // a generation that had to go linear keeps that layout: whatever refused
+    // the tiled buffer — the server, or EGL itself — has not changed since
     return this._newGeneration(w, h, gen ? gen.linear : false);
   }
 
+  /** A GBM surface at this size, in the layout asked for. */
+  _createSurface(w, h, linear) {
+    return linear
+      ? this.gpu.createSurface(w, h, this.dri.GBM_USE.RENDERING | this.dri.GBM_USE.LINEAR)
+      : this.gpu.createSurface(w, h);
+  }
+
   _newGeneration(w, h, linear) {
-    const use = linear ? this.dri.GBM_USE.RENDERING | this.dri.GBM_USE.LINEAR : undefined;
     let surface;
     try {
-      surface = use === undefined ? this.gpu.createSurface(w, h) : this.gpu.createSurface(w, h, use);
+      surface = this._createSurface(w, h, linear);
     } catch (err) {
-      throw glError(GLError.CONTEXT_FAILED, `could not create a ${w}x${h} GPU surface: ${err.message}`, null, err);
+      // Some drivers will not give EGL a window surface over a render-only
+      // GBM buffer at all: NVIDIA's answers eglCreateWindowSurface with
+      // EGL_BAD_MATCH, and takes the very same size and format once the
+      // buffer is linear. That is the retry an import refusal gets below,
+      // one step earlier — there the server would not read the buffer, here
+      // EGL would not draw into it, and a linear layout is what both of them
+      // accept. Cheap to try: the alternative is no direct rendering at all.
+      if (linear || !this.policy.linearFallback) {
+        throw this._surfaceError(w, h, linear ? 'linear' : 'tiled', err.message, err);
+      }
+      try {
+        surface = this._createSurface(w, h, true);
+      } catch (retryErr) {
+        throw this._surfaceError(
+          w,
+          h,
+          'tiled or linear',
+          `${err.message}; linear: ${retryErr.message}`,
+          err
+        );
+      }
+      linear = true;
     }
     this.generation = new Generation(surface, w, h, linear);
     return surface;
   }
 
+  /** No surface, naming the layouts that were refused and what to change. */
+  _surfaceError(w, h, tried, detail, cause) {
+    const hint =
+      tried === 'tiled'
+        ? 'A driver that will not draw into a tiled buffer (NVIDIA) takes a linear one,\n' +
+          'which is the retry glPolicy: { linearFallback: true } — the default — makes.\n' +
+          'See docs/context-gles.md#buffer-layout.'
+        : 'No layout this device offers can back a window surface for this driver.\n' +
+          "Another render node may: glPolicy: { devicePath: '/dev/dri/renderD###' }.\n" +
+          "Failing that, glPolicy: 'indirect' draws with no GPU buffer at all.\n" +
+          'See docs/context-gles.md#buffer-layout.';
+    return glError(
+      GLError.CONTEXT_FAILED,
+      `could not create a ${w}x${h} GPU surface (${tried}): ${detail}`,
+      hint,
+      cause
+    );
+  }
+
   /** Can a frame be drawn and presented right now? */
   canRender() {
     if (this.destroyed || this.error) return false;

package/lib/shadow.js

@@ -61,129 +61,25 @@
 // they are the 2d context's bookkeeping, not a primitive.
 import { Surface } from './surface.js';
 
-/**
- * Shadow policy — the cost ceilings, per app via `app.shadowPolicy`
- * (partial objects are merged over the defaults). See docs/context-2d.md.
- *
- * - `cacheBytes` — LRU budget for retained shadow coverage per connection.
- *   Keyed by (text, font, blur) for text; least-recently-drawn surfaces are
- *   destroyed server-side once the total goes over.
- * - `maxSigma` — the widest gaussian actually run. The kernel is 6σ+1 wide,
- *   the request carries every tap, and the server multiplies each of them
- *   per pixel per pass, so an unbounded `shadowBlur` is an unbounded
- *   request and an unbounded stall. Past this the blur stops widening.
- * - `maxPixels` — the largest coverage surface built for one shadow. Beyond
- *   it the shadow is dropped rather than turning one drawing into a
- *   multi-megabyte allocation; the drawing itself is unaffected.
- * - `scaleSigma` — the σ a reduced-scale blur is not allowed to fall below.
- *   A gaussian carries no detail finer than about σ/2 px, so a wide one does
- *   not need full resolution to resolve it: past twice this, coverage is
- *   shrunk by the largest power of two that keeps σ/scale at or above it,
- *   blurred there, and resolved back — `scale` off the kernel and `scale²`
- *   off the area, which is where a first paint's time goes (issue #338).
- *   What the shrink costs is set by that reduced σ and not by the ratio: 4
- *   holds the difference from an exact blur inside three levels of 8-bit
- *   alpha, where 3 is worth four levels and 2 is worth seven.
- * - `maxScale` — how far the shrink may go whatever the floor allows, so a
- *   `maxSigma`-wide blur cannot resample its way down to a thumbnail.
- *   `maxScale: 1` blurs everything at full resolution, which is what 8.6
- *   did, and is the setting for a caller that needs the exact kernel.
- */
-export const DEFAULT_SHADOW_POLICY = {
-  cacheBytes: 4 << 20,
-  maxSigma: 32,
-  maxPixels: 8 << 20,
-  scaleSigma: 4,
-  maxScale: 4
-};
-
-/** the policy for one app, merged over the defaults */
-export function shadowPolicyOf(app) {
-  return app?.shadowPolicy
-    ? { ...DEFAULT_SHADOW_POLICY, ...app.shadowPolicy }
-    : DEFAULT_SHADOW_POLICY;
-}
-
-/**
- * The gaussian a `shadowBlur` asks for.
- *
- * `shadowBlur` is a **diameter**, not a radius: the canvas spec says a
- * shadow is blurred by a gaussian whose standard deviation is half of it.
- * Getting this wrong is invisible until someone compares against a browser,
- * so it is one line with a test on it — `shadowBlur: 8` must be σ = 4 here
- * exactly as it is in Chrome and Firefox.
- *
- * Clamped to the policy's `maxSigma`, which is the only place a shadow
- * silently stops matching a browser; the cap is chosen so that no shadow a
- * UI actually draws reaches it.
- */
-export function shadowSigma(blur, policy = DEFAULT_SHADOW_POLICY) {
-  const sigma = blur / 2;
-  return sigma > policy.maxSigma ? policy.maxSigma : sigma;
-}
+import {
+  DEFAULT_SHADOW_POLICY,
+  blurScale,
+  gaussianKernel1d,
+  shadowPolicyOf,
+  shadowReach,
+  shadowSigma
+} from './shadowmath.js';
 
-/**
- * How far the blur spreads coverage, in pixels — the kernel's half-width,
- * and therefore the padding every coverage surface needs on each side.
- *
- * Truncating a gaussian at 3σ leaves 0.3% of its weight outside, which is
- * below one step of the 8-bit coverage it is convolving.
- */
-export function shadowReach(sigma) {
-  return sigma > 0 ? Math.ceil(sigma * 3) : 0;
-}
-
-/**
- * A normalized 1d gaussian, `2 * reach + 1` taps wide.
- *
- * Normalizing the *truncated* kernel rather than the ideal one is what keeps
- * a flat interior at full coverage: a shadow under an opaque box must stay
- * opaque in the middle, and a kernel summing to 0.997 would leave it at 254.
- */
-export function gaussianKernel1d(sigma, reach = shadowReach(sigma)) {
-  const values = new Array(reach * 2 + 1);
-  let sum = 0;
-  for (let i = -reach; i <= reach; i++) {
-    const v = Math.exp(-(i * i) / (2 * sigma * sigma));
-    values[i + reach] = v;
-    sum += v;
-  }
-  for (let i = 0; i < values.length; i++) values[i] /= sum;
-  return values;
-}
-
-/**
- * The scale a blur of this sigma is run at: 1, 2 or 4 by default, meaning
- * "shrink the coverage by this much, blur at `sigma / scale`, resolve back".
- *
- * A gaussian is a low-pass filter — it carries nothing finer than about σ/2
- * px — so resolving a wide one at full resolution spends most of its time on
- * detail the result cannot hold. Shrinking first takes `scale` off the
- * kernel and `scale²` off the area it runs over: at σ 21 over 552×396, k = 4
- * turns 55.5M multiply-accumulates into 0.9M, which on a software-RENDER
- * server (XQuartz) is most of a first paint (issue #338).
- *
- * The scale is a power of two so that each shrink is an exact 2×2 average,
- * and it is capped both by `maxScale` and by the σ floor `scaleSigma`, which
- * is what keeps the reduced blur wide enough to still be a gaussian — the
- * difference from an exact blur is set by that reduced σ, and stays inside
- * three levels of 8-bit alpha at the 4 the policy defaults to. σ under
- * `2 * scaleSigma` gets 1: below that the two resampling composites cost
- * more than the kernel they save.
- *
- * Exported for a caller that draws its own shapes and can therefore skip the
- * shrink entirely: draw the shape into a surface `1 / scale` the size (its
- * padding scaled with it), blur at `sigma / scale`, and composite through a
- * `1 / scale` picture transform. See docs/surface.md#baking-a-blur.
- */
-export function blurScale(sigma, policy = DEFAULT_SHADOW_POLICY) {
-  const floor = policy.scaleSigma ?? DEFAULT_SHADOW_POLICY.scaleSigma;
-  const max = policy.maxScale ?? DEFAULT_SHADOW_POLICY.maxScale;
-  if (!(sigma > 0) || !(floor > 0) || !(max > 1)) return 1;
-  let scale = 1;
-  while (scale * 2 <= max && sigma / (scale * 2) >= floor) scale *= 2;
-  return scale;
-}
+// the arithmetic lives in shadowmath.js, which carries no surface; these
+// were defined here, and every name stays importable from here
+export {
+  DEFAULT_SHADOW_POLICY,
+  blurScale,
+  gaussianKernel1d,
+  shadowPolicyOf,
+  shadowReach,
+  shadowSigma
+};
 
 /**
  * The smallest a shrunk coverage surface is allowed to get on either side.

package/lib/shadowmath.js

@@ -0,0 +1,134 @@
+// The arithmetic of a drop shadow — the policy, the gaussian a `shadowBlur`
+// asks for, how far it reaches and the scale it is blurred at — with no
+// surface and no X connection in it (shadow.js has those).
+//
+// Its own module so that a renderer drawing shadows some other way can size
+// them the way this package does without loading the X11 client that the
+// surfaces need: react-x11's Cocoa, Windows and Wayland backends ask how far
+// a box shadow reaches here, and nothing else of ntk's. Exported as
+// `ntk/shadow-math`; shadow.js re-exports every name, so nothing that
+// imported them from there or from the package root changes.
+
+/**
+ * Shadow policy — the cost ceilings, per app via `app.shadowPolicy`
+ * (partial objects are merged over the defaults). See docs/context-2d.md.
+ *
+ * - `cacheBytes` — LRU budget for retained shadow coverage per connection.
+ *   Keyed by (text, font, blur) for text; least-recently-drawn surfaces are
+ *   destroyed server-side once the total goes over.
+ * - `maxSigma` — the widest gaussian actually run. The kernel is 6σ+1 wide,
+ *   the request carries every tap, and the server multiplies each of them
+ *   per pixel per pass, so an unbounded `shadowBlur` is an unbounded
+ *   request and an unbounded stall. Past this the blur stops widening.
+ * - `maxPixels` — the largest coverage surface built for one shadow. Beyond
+ *   it the shadow is dropped rather than turning one drawing into a
+ *   multi-megabyte allocation; the drawing itself is unaffected.
+ * - `scaleSigma` — the σ a reduced-scale blur is not allowed to fall below.
+ *   A gaussian carries no detail finer than about σ/2 px, so a wide one does
+ *   not need full resolution to resolve it: past twice this, coverage is
+ *   shrunk by the largest power of two that keeps σ/scale at or above it,
+ *   blurred there, and resolved back — `scale` off the kernel and `scale²`
+ *   off the area, which is where a first paint's time goes (issue #338).
+ *   What the shrink costs is set by that reduced σ and not by the ratio: 4
+ *   holds the difference from an exact blur inside three levels of 8-bit
+ *   alpha, where 3 is worth four levels and 2 is worth seven.
+ * - `maxScale` — how far the shrink may go whatever the floor allows, so a
+ *   `maxSigma`-wide blur cannot resample its way down to a thumbnail.
+ *   `maxScale: 1` blurs everything at full resolution, which is what 8.6
+ *   did, and is the setting for a caller that needs the exact kernel.
+ */
+export const DEFAULT_SHADOW_POLICY = {
+  cacheBytes: 4 << 20,
+  maxSigma: 32,
+  maxPixels: 8 << 20,
+  scaleSigma: 4,
+  maxScale: 4
+};
+
+/** the policy for one app, merged over the defaults */
+export function shadowPolicyOf(app) {
+  return app?.shadowPolicy
+    ? { ...DEFAULT_SHADOW_POLICY, ...app.shadowPolicy }
+    : DEFAULT_SHADOW_POLICY;
+}
+
+/**
+ * The gaussian a `shadowBlur` asks for.
+ *
+ * `shadowBlur` is a **diameter**, not a radius: the canvas spec says a
+ * shadow is blurred by a gaussian whose standard deviation is half of it.
+ * Getting this wrong is invisible until someone compares against a browser,
+ * so it is one line with a test on it — `shadowBlur: 8` must be σ = 4 here
+ * exactly as it is in Chrome and Firefox.
+ *
+ * Clamped to the policy's `maxSigma`, which is the only place a shadow
+ * silently stops matching a browser; the cap is chosen so that no shadow a
+ * UI actually draws reaches it.
+ */
+export function shadowSigma(blur, policy = DEFAULT_SHADOW_POLICY) {
+  const sigma = blur / 2;
+  return sigma > policy.maxSigma ? policy.maxSigma : sigma;
+}
+
+/**
+ * How far the blur spreads coverage, in pixels — the kernel's half-width,
+ * and therefore the padding every coverage surface needs on each side.
+ *
+ * Truncating a gaussian at 3σ leaves 0.3% of its weight outside, which is
+ * below one step of the 8-bit coverage it is convolving.
+ */
+export function shadowReach(sigma) {
+  return sigma > 0 ? Math.ceil(sigma * 3) : 0;
+}
+
+/**
+ * A normalized 1d gaussian, `2 * reach + 1` taps wide.
+ *
+ * Normalizing the *truncated* kernel rather than the ideal one is what keeps
+ * a flat interior at full coverage: a shadow under an opaque box must stay
+ * opaque in the middle, and a kernel summing to 0.997 would leave it at 254.
+ */
+export function gaussianKernel1d(sigma, reach = shadowReach(sigma)) {
+  const values = new Array(reach * 2 + 1);
+  let sum = 0;
+  for (let i = -reach; i <= reach; i++) {
+    const v = Math.exp(-(i * i) / (2 * sigma * sigma));
+    values[i + reach] = v;
+    sum += v;
+  }
+  for (let i = 0; i < values.length; i++) values[i] /= sum;
+  return values;
+}
+
+/**
+ * The scale a blur of this sigma is run at: 1, 2 or 4 by default, meaning
+ * "shrink the coverage by this much, blur at `sigma / scale`, resolve back".
+ *
+ * A gaussian is a low-pass filter — it carries nothing finer than about σ/2
+ * px — so resolving a wide one at full resolution spends most of its time on
+ * detail the result cannot hold. Shrinking first takes `scale` off the
+ * kernel and `scale²` off the area it runs over: at σ 21 over 552×396, k = 4
+ * turns 55.5M multiply-accumulates into 0.9M, which on a software-RENDER
+ * server (XQuartz) is most of a first paint (issue #338).
+ *
+ * The scale is a power of two so that each shrink is an exact 2×2 average,
+ * and it is capped both by `maxScale` and by the σ floor `scaleSigma`, which
+ * is what keeps the reduced blur wide enough to still be a gaussian — the
+ * difference from an exact blur is set by that reduced σ, and stays inside
+ * three levels of 8-bit alpha at the 4 the policy defaults to. σ under
+ * `2 * scaleSigma` gets 1: below that the two resampling composites cost
+ * more than the kernel they save.
+ *
+ * Exported for a caller that draws its own shapes and can therefore skip the
+ * shrink entirely: draw the shape into a surface `1 / scale` the size (its
+ * padding scaled with it), blur at `sigma / scale`, and composite through a
+ * `1 / scale` picture transform. See docs/surface.md#baking-a-blur.
+ */
+export function blurScale(sigma, policy = DEFAULT_SHADOW_POLICY) {
+  const floor = policy.scaleSigma ?? DEFAULT_SHADOW_POLICY.scaleSigma;
+  const max = policy.maxScale ?? DEFAULT_SHADOW_POLICY.maxScale;
+  if (!(sigma > 0) || !(floor > 0) || !(max > 1)) return 1;
+  let scale = 1;
+  while (scale * 2 <= max && sigma / (scale * 2) >= floor) scale *= 2;
+  return scale;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.9.0",
+  "version": "8.10.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -25,7 +25,15 @@
   "main": "./lib/index.js",
   "exports": {
     ".": "./lib/index.js",
-    "./xembed": "./lib/xembed.js"
+    "./xembed": "./lib/xembed.js",
+    "./color": "./lib/color.js",
+    "./imagedata": "./lib/imagedata.js",
+    "./path": "./lib/path.js",
+    "./gl": "./lib/gl.js",
+    "./shadow-math": "./lib/shadowmath.js",
+    "./image": "./lib/image.js",
+    "./svg": "./lib/widgets/svgview.js",
+    "./font": "./lib/text/font.js"
   },
   "files": [
     "lib"