ntk 8.5.0 → 8.6.0

package/lib/index.js

@@ -48,6 +48,13 @@ import {
   setDefaultRasterizer
 } from './rasterize.js';
 import { DEFAULT_MASK_POLICY } from './maskcluster.js';
+import {
+  DEFAULT_SHADOW_POLICY,
+  blurCoverage,
+  gaussianKernel1d,
+  shadowReach,
+  shadowSigma
+} from './shadow.js';
 import { DEFAULT_SHAPE_POLICY } from './shapeglyphs.js';
 import { DEFAULT_SHARED_GLYPHS_POLICY } from './glyphdirectory.js';
 import { warmSharedGlyphs } from './text/glyphs.js';
@@ -275,6 +282,16 @@ export {
   DEFAULT_RASTER_POLICY,
   DEFAULT_MASK_POLICY,
   DEFAULT_SHAPE_POLICY,
+  // the shadow blur as a primitive (docs/surface.md#baking-a-blur), for a
+  // caller drawing shapes ntk's shadow properties never see. `blurCoverage`
+  // *bakes* the two separable passes into a surface's pixels — unlike
+  // `picture().setBlurFilter()`, whose kernel the server re-runs on every
+  // composite, which a cached shadow pays for once per frame
+  DEFAULT_SHADOW_POLICY,
+  blurCoverage,
+  gaussianKernel1d,
+  shadowReach,
+  shadowSigma,
   // cross-process shared glyphs (docs/shared-glyphs.md): the directory-side
   // budget, and the prewarm that makes a first paint of already-shared text
   // rasterize and upload nothing

package/lib/picture.js

@@ -25,10 +25,35 @@ export default class Picture {
     registry.register(this, { Render: this.Render, X, id: this.id }, this);
   }
 
+  /**
+   * Set the picture's filter — a *property of the picture*, not an operation
+   * on its pixels. The server re-applies it every time the picture is
+   * sampled, so the cost is per composite and forever, not once.
+   *
+   * That is what makes it right for resampling (`'bilinear'` under a
+   * transform) and a trap for anything expensive: see `setBlurFilter`.
+   */
   setFilter(name, params) {
     this.Render.SetPictureFilter(this.id, name, params);
   }
 
+  /**
+   * Hang a k×k gaussian `convolution` on the picture.
+   *
+   * **This re-convolves on every composite** — it is a filter, so the server
+   * runs the whole kernel each time the picture is drawn, and the pixels
+   * never change on the client's side of the wire. A picture blurred once and
+   * then composited each frame pays k² multiply-accumulates per pixel per
+   * frame: at radius 61 over 489×134 that is 244M per draw, which is a 1.6s
+   * hover on XQuartz and a 9s window repaint (issue #335).
+   *
+   * Reach for it when the blur really is per-draw and small. To blur
+   * something *once* and composite the result cheaply afterwards — a drop
+   * shadow, a cached soft edge — bake it instead with `blurCoverage` from
+   * ntk's entry point: two separable 1d passes (2k multiplies per pixel, not
+   * k²), run once, leaving a surface with the blur in its pixels and no
+   * filter of its own. See docs/surface.md#baking-a-blur.
+   */
   setBlurFilter(radius, sigma) {
     if (radius === 0) {
       return this.setFilter('convolution', [1, 1, 1]);

package/lib/shadow.js

@@ -32,6 +32,19 @@
 // second pass leaves a surface with the blur already in its pixels, so the
 // cached copy composites as a plain mask rather than re-running a kernel on
 // every frame.
+//
+// ## What of this is public
+//
+// The bake and the maths around it — `blurCoverage`, `shadowSigma`,
+// `shadowReach`, `gaussianKernel1d` and `DEFAULT_SHADOW_POLICY` — are
+// re-exported from `lib/index.js` (issue #335). A toolkit that draws its own
+// shapes (react-x11 paints a `<box>`'s `boxShadow` itself, because the
+// rounded rect is a path it already has and the result goes through its own
+// paint cache) needs exactly this and nothing else: the alternative on the
+// public surface, `picture().setBlurFilter()`, sets a k×k filter that the
+// server re-runs on *every* composite, which is invisible until someone
+// profiles a real display. The surfaces and the cache below stay private —
+// they are the 2d context's bookkeeping, not a primitive.
 import { Surface } from './surface.js';
 
 /**
@@ -117,8 +130,31 @@ export function gaussianKernel1d(sigma, reach = shadowReach(sigma)) {
  * and leaving it alive would double what the cache is holding. The output
  * carries no filter of its own, so compositing it is an ordinary masked
  * composite no matter how wide the blur was.
+ *
+ * Public, and the reason is that half of it: a *filter* is re-applied by the
+ * server on every composite, so a caller who blurs a picture with
+ * `setBlurFilter` and then caches it re-runs the kernel per frame — 244M
+ * multiply-accumulates for one 489×134 shadow at σ 10 (issue #335). This
+ * bakes instead. `shape` must be a coverage surface with the blur's reach as
+ * padding on all four sides, or the result ends in a straight line where the
+ * kernel ran out of pixels; see docs/surface.md.
  */
 export function blurCoverage(shape, sigma) {
+  if (!(sigma > 0) || !Number.isFinite(sigma)) {
+    throw new Error(
+      `blurCoverage: sigma must be a finite number above 0, got ${sigma}. ` +
+        'A canvas blur radius is a diameter, not a sigma — pass ' +
+        'shadowSigma(blur), which halves it and applies the policy cap. ' +
+        'σ = 0 is no blur at all: composite the coverage as it is.'
+    );
+  }
+  if (shape.format !== 'a8') {
+    throw new Error(
+      `blurCoverage: needs a coverage surface, got format ${JSON.stringify(shape.format)}. ` +
+        "Draw the shape into new Surface(app, { width, height, format: 'a8' }) — " +
+        'the blur runs on alpha, so an argb32 surface would lose its colour.'
+    );
+  }
   const app = shape.app;
   const R = app.display.Render;
   const { width, height } = shape;

package/package.json

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