ntk 8.4.1 → 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/renderingcontext_2d.js

@@ -1057,6 +1057,7 @@ class RenderingContext2d {
       textStyle: this._textStyle,
       fontString: this._lastFontString,
       fontVariations: this._fontVariations,
+      fontOpticalSizing: this._fontOpticalSizing,
       textRendering: this._textRendering,
       textAlign: this.textAlign,
       textBaseline: this.textBaseline,
@@ -1086,6 +1087,7 @@ class RenderingContext2d {
     this._textStyle = s.textStyle;
     this._lastFontString = s.fontString;
     this._fontVariations = s.fontVariations;
+    this._fontOpticalSizing = s.fontOpticalSizing;
     this._textRendering = s.textRendering;
     this.textAlign = s.textAlign;
     this.textBaseline = s.textBaseline;
@@ -1249,6 +1251,7 @@ class RenderingContext2d {
     sctx._textStyle = this._textStyle;
     sctx._lastFontString = this._lastFontString;
     sctx._fontVariations = this._fontVariations;
+    sctx._fontOpticalSizing = this._fontOpticalSizing;
     sctx._textRendering = this._textRendering;
     sctx.textAlign = this.textAlign;
     sctx.textBaseline = this.textBaseline;
@@ -4029,6 +4032,7 @@ class RenderingContext2d {
       style: parsed.style,
       size: parsed.size,
       variations: this._fontVariations,
+      opticalSizing: this._fontOpticalSizing,
     };
     style.font = this.window.app.fonts.match(style.family, style);
     this._lastFontString = val;
@@ -4061,6 +4065,32 @@ class RenderingContext2d {
     return this._fontVariations ?? null;
   }
 
+  /**
+   * CSS's `font-optical-sizing`: `'auto'` (the default) sets a face's `opsz`
+   * axis at the size the text is drawn at, `'none'` leaves it wherever the
+   * font file's default is.
+   *
+   * `'auto'` is what the CSS initial value has always been and what a
+   * reader expects — small text set in the family's Text cut, headlines in
+   * its Display cut — so this is the escape hatch, not the switch that
+   * turns the feature on. Reach for it when the size the canvas is drawing
+   * at is not the size the text is *read* at (a canvas scaled up by a
+   * transform, glyphs measured for something else), and pin the axis with
+   * `fontVariationSettings = { opsz: … }` when the answer is a specific
+   * optical size rather than the file's default.
+   *
+   * Order-independent, like `fontVariationSettings`: setting it re-resolves
+   * the face already in force.
+   */
+  set fontOpticalSizing(val) {
+    this._fontOpticalSizing = val === "none" ? "none" : "auto";
+    if (this._textStyle) this.font = this._lastFontString;
+  }
+
+  get fontOpticalSizing() {
+    return this._fontOpticalSizing ?? "auto";
+  }
+
   /**
    * CSS's `text-rendering`: which glyph path this text takes, overriding the
    * size thresholds in `app.textPolicy`.

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/lib/text/fontmanager.js

@@ -20,26 +20,69 @@ function variationsKeyOf(variations) {
     .join(',');
 }
 
+/**
+ * The optical size a style is set at, or `undefined` for "leave `opsz`
+ * alone" — see `instantiate()`.
+ *
+ * `opsz` is the one axis whose coordinate is not a design choice but a
+ * consequence of the size, so it defaults from `size` and needs an escape
+ * hatch for each way that default can be wrong:
+ *
+ * - `opticalSizing: 'none'` is CSS's `font-optical-sizing: none` — the face
+ *   stays at its own default optical size;
+ * - `opticalSize` is the typographic size to use when it is not `size`.
+ *   `size` on this path is CSS px, and a caller that has already multiplied
+ *   by a device scale is holding device pixels: a 13px label on a 2×
+ *   display arrives here as 26 and would pick a display cut. Such a caller
+ *   passes the unscaled size as `opticalSize` and keeps the scaled one for
+ *   the glyphs.
+ */
+function opticalSizeFor(style) {
+  if (!style || style.opticalSizing === 'none') return undefined;
+  const size = style.opticalSize ?? style.size;
+  return typeof size === 'number' && Number.isFinite(size) ? size : undefined;
+}
+
+/** Cache-key fragment for the optical size, `''` when the axis is left alone. */
+function opticalKeyOf(style) {
+  return opticalSizeFor(style) ?? '';
+}
+
 /**
  * Put a resolved face at the point in its design space the style asked for.
  *
- * The interesting half is `weight`. CSS has said for years that
- * `font-weight: 460` on a variable font means the `wght` axis at 460, not
- * "the nearest face"; a face with a `wght` axis therefore takes the
- * requested weight as a coordinate, and an app that hands ntk a variable
- * file gets the weight it asked for without knowing an axis exists. An
- * explicit `variations.wght` wins, because a caller naming the axis
- * directly is being more specific than one naming a weight.
+ * Two axes get a coordinate from a style that never names them, because CSS
+ * says both are consequences of properties the style does name:
+ *
+ * - `weight`. `font-weight: 460` on a variable font means the `wght` axis at
+ *   460, not "the nearest face", so an app that hands ntk a variable file
+ *   gets the weight it asked for without knowing an axis exists.
+ * - `size`. `font-optical-sizing: auto` has been the initial value since
+ *   optical sizing was specified: `opsz` tracks `font-size` unless the
+ *   author says otherwise. Without this a face is drawn at whatever optical
+ *   size its file happens to default to — on macOS the only San Francisco
+ *   fontconfig can see is a variable file defaulting to `opsz` 28, a
+ *   *display* cut, so every 13px menu label was set in display-sized
+ *   letterforms. Clamping does the rest: 13 against SF's `17..96` lands on
+ *   17, which is exactly Apple's Text end.
+ *
+ * An explicit `variations.wght` / `variations.opsz` wins in both cases,
+ * because a caller naming the axis directly is being more specific than one
+ * naming a weight or a size — the same order CSS gives
+ * `font-variation-settings` over the properties it overlaps.
  *
  * Everything here is a no-op for a static face: `variation()` returns the
  * font unchanged when the settings do not apply, so this costs one property
  * read on the path every non-variable app is already on.
  */
-function instantiate(font, weight, variations) {
+function instantiate(font, weight, variations, opticalSize) {
   const axes = font.variationAxes;
-  if (!axes || (!axes.wght && !variations)) return font;
+  if (!axes || (!axes.wght && !axes.opsz && !variations)) return font;
   const settings = { ...variations };
   if (axes.wght && settings.wght === undefined) settings.wght = weight;
+  if (axes.opsz && settings.opsz === undefined && opticalSize !== undefined) {
+    settings.opsz = opticalSize;
+  }
   return font.variation(settings);
 }
 
@@ -151,19 +194,30 @@ export default class FontManager {
    * Resolve a family (or CSS-style comma-separated family list) to a Font.
    * Registered fonts are consulted first, then fontconfig.
    *
+   * What is cached here is the *face* the pattern resolved to — the
+   * expensive half, since it is an fc-match and a file parse — and not the
+   * instance `instantiate()` cuts out of it. Two things follow. The map
+   * stays one entry per family/weight/style however many points of an axis
+   * an app asks for, so a slider animating `wght`, or a tree of labels at a
+   * dozen sizes, walks a face's own bounded instance cache rather than
+   * evicting other families out of this one. And `size` can drive `opsz`
+   * without joining the key: the coordinate is applied per call, so the
+   * first size asked for does not become every later one's.
+   *
    * @param {string} family e.g. `'Ubuntu Mono', monospace`
-   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic' }
+   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic',
+   *   size, variations, opticalSize, opticalSizing: 'auto'|'none' }
    */
   match(family = 'sans-serif', opts = {}) {
     const weight = numWeight(opts.weight);
     const italic = !!(opts.style && opts.style.includes('italic'));
-    const cacheKey = `${family}|${weight}|${italic}|${variationsKeyOf(opts.variations)}`;
-    let font = this._matches.get(cacheKey);
-    if (font) {
+    const cacheKey = `${family}|${weight}|${italic}`;
+    let face = this._matches.get(cacheKey);
+    if (face) {
       // insertion order is LRU order; re-inserting a hit moves it to the tail
       this._matches.delete(cacheKey);
-      this._matches.set(cacheKey, font);
-      return font;
+      this._matches.set(cacheKey, face);
+      return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
     }
 
     const families = String(family)
@@ -171,26 +225,23 @@ export default class FontManager {
       .map((f) => f.trim().replace(/^["']|["']$/g, ''))
       .filter(Boolean);
 
-    font = this._matchRegistered(
+    face = this._matchRegistered(
       families.map((f) => f.toLowerCase()),
       weight,
       italic
     );
-    if (!font) {
+    if (!face) {
       // sources understand comma-separated family lists natively
       const candidates = this.source.matchSorted({
         family: families.join(','),
         weight,
         style: italic ? 'italic' : 'normal'
       });
-      font = this._open(candidates[0]);
+      face = this._open(candidates[0]);
     }
-    font = instantiate(font, weight, opts.variations);
-    this._matches.set(cacheKey, font);
-    // The key now carries a point in a continuous space rather than one of a
-    // handful of weights, so an app animating an axis walks this map instead
-    // of hitting it. Same sweep as the shaping memo: drop the stale half in
-    // one pass rather than one entry per insert.
+    this._matches.set(cacheKey, face);
+    // A long-lived app can name a lot of families. Same sweep as the shaping
+    // memo: drop the stale half in one pass rather than one entry per insert.
     if (this._matches.size > MAX_MATCHES) {
       let drop = this._matches.size >> 1;
       for (const key of this._matches.keys()) {
@@ -198,7 +249,7 @@ export default class FontManager {
         this._matches.delete(key);
       }
     }
-    return font;
+    return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
   }
 
   /**
@@ -292,14 +343,14 @@ export default class FontManager {
   _shapeCached(text, style, levelsKey = '0') {
     const font = style.font;
     // A resolved `font` already carries its coordinates in its key, so the
-    // variations fragment only earns its keep on the family path — where two
-    // points of one axis would otherwise share a shaped run, and the second
-    // would be drawn with the first's advances.
+    // variations and optical-size fragments only earn their keep on the
+    // family path — where two points of one axis would otherwise share a
+    // shaped run, and the second would be drawn with the first's advances.
     const key = font
       ? `${font.key}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`
       : `${style.family}|${style.size}|${style.weight}|${style.style}|${variationsKeyOf(
           style.variations
-        )}|${levelsKey}|${text}`;
+        )}|${opticalKeyOf(style)}|${levelsKey}|${text}`;
     let shaped = this._shapeCache.get(key);
     if (shaped) {
       // Map iterates in insertion order: re-inserting a hit moves it to the

package/lib/text/layout.js

@@ -67,6 +67,8 @@ export class TextLayout {
         weight: s.weight ?? style.weight,
         style: s.style ?? style.style,
         variations: s.variations ?? style.variations,
+        opticalSize: s.opticalSize ?? style.opticalSize,
+        opticalSizing: s.opticalSizing ?? style.opticalSizing,
         textRendering: s.textRendering ?? style.textRendering,
         features: s.features ?? style.features,
         language: s.language ?? style.language,

package/lib/text/shape.js

@@ -69,7 +69,10 @@ export function normalizedLevels(levels, start, end) {
 export function shapeText(fonts, text, style, levels) {
   const size = style.size ?? 16;
   const family = style.family ?? 'sans-serif';
-  const baseFont = style.font ?? fonts.match(family, style);
+  // `size` is what drives the `opsz` axis, so a style that leaves it out
+  // hands `match()` the size this actually sets at rather than nothing
+  const baseFont =
+    style.font ?? fonts.match(family, style.size === undefined ? { ...style, size } : style);
 
   let baseLevel = 0;
   if (!levels) {

package/package.json

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