ntk 7.6.0 → 7.7.0

package/lib/image.js

@@ -79,6 +79,18 @@ export class Image {
     return picture;
   }
 
+  /**
+   * The Pixmap those pixels live in on `app` (uploading on first use, like
+   * `picture`). What it is for is building a *second* Picture over the same
+   * upload — `ctx.createPattern` needs a repeating one, and changing the
+   * cached picture's attributes instead would change how `drawImage` samples
+   * this image everywhere else.
+   */
+  pixmap(app) {
+    this.picture(app);
+    return this._uploads.get(app).pixmap;
+  }
+
   /** free server-side copies of this image (safe to draw again afterwards) */
   destroy() {
     for (const { pixmap, picture } of this._uploads.values()) {

package/lib/index.js

@@ -47,6 +47,7 @@ import {
   defaultRasterizer,
   setDefaultRasterizer
 } from './rasterize.js';
+import { DEFAULT_MASK_POLICY } from './maskcluster.js';
 import { DEFAULT_SHAPE_POLICY } from './shapeglyphs.js';
 import { TextLayout } from './text/layout.js';
 import HtmlView from './widgets/htmlview.js';
@@ -61,7 +62,7 @@ import { cssColor, cssLength } from './widgets/css.js';
 // comes last on purpose: it wraps the 'opengl' factory the indirect one just
 // registered, so that the backend-neutral name can dispatch on glPolicy.
 import './renderingcontext_x11.js';
-import './renderingcontext_2d.js';
+import { CanvasGradient, CanvasPattern } from './renderingcontext_2d.js';
 import './renderingcontext_opengl.js';
 import './renderingcontext_gles.js';
 
@@ -237,6 +238,10 @@ export {
   Pixmap,
   Picture,
   Surface,
+  // fill/stroke styles the 2d context hands back (docs/context-2d.md) —
+  // exported for `instanceof`, not to be constructed directly
+  CanvasGradient,
+  CanvasPattern,
   Image,
   ImageData,
   pixelLayout,
@@ -260,6 +265,7 @@ export {
   defaultRasterizer,
   setDefaultRasterizer,
   DEFAULT_RASTER_POLICY,
+  DEFAULT_MASK_POLICY,
   DEFAULT_SHAPE_POLICY,
   TextLayout,
   HtmlView,

package/lib/maskcluster.js

@@ -0,0 +1,191 @@
+// Splitting one drawing's coverage mask into a few, when its pieces are
+// scattered (issue #264).
+//
+// A fill or stroke rasterizes coverage into one a8 mask sized to the
+// drawing's ink bounding box, and that mask costs width x height whatever
+// the coverage inside it is. For one shape the bound is right. For a path
+// holding N disjoint subpaths the bound is their *union*, so batching N
+// draws into one path trades N small masks for one big one — which wins
+// when the pieces span the box anyway (long edges of a graph) and loses
+// badly when they do not (its handle dots): at 1100x700, 735 batched edge
+// strokes cost 3.9 MB -> 1.3 MB of mask and 53% less frame time, while 19
+// edges plus 40 small discs batched the same way cost ~0.75 MB *more* and
+// 40% more frame time than drawing them singly.
+//
+// Rather than leave that cliff to every caller, the boxes go through here
+// first and the mask is emitted once per cluster. The partition is by gaps
+// only: a cut is legal where nothing straddles it, which is what keeps
+// every cluster box disjoint from every other. Disjoint boxes are what make
+// the split invisible — no pixel is composited twice (a translucent colour
+// would blend twice at any overlap), and the winding number a fill asks for
+// is unchanged, because a closed subpath contributes nothing to the winding
+// of a point outside its own box.
+//
+// Cutting is not free: each extra mask is a few more requests. So a cut has
+// to pay for itself in mask area, and the cheapest useful unit of area is
+// the policy's `minSaving`. That single rule bounds the outcome from both
+// sides — every cut removes at least `minSaving` pixels of mask, so the
+// number of clusters can never exceed the union area divided by it.
+
+/**
+ * When one drawing's mask is worth splitting into several.
+ *
+ * - `minSaving` — mask pixels a cut has to remove to be worth the extra
+ *   mask pass it costs. 64x64 is the same "small enough not to think about"
+ *   box `DEFAULT_RASTER_POLICY.maxArea` uses: below it, an extra pass is
+ *   dearer than the area it would save.
+ * - `maxMasks` — hard cap on clusters per drawing, so a pathological path
+ *   (thousands of scattered dots) cannot turn one drawing into thousands of
+ *   request groups. Cuts are taken most-valuable-first, so the cap keeps the
+ *   ones that matter.
+ *
+ * `{ maxMasks: 1 }` — or `minSaving: Infinity` — disables the split, which
+ * is what a composite op that writes outside its coverage gets.
+ */
+export const DEFAULT_MASK_POLICY = {
+  minSaving: 64 * 64,
+  maxMasks: 32
+};
+
+/** the policy for one app, merged over the defaults */
+export function maskPolicyOf(app) {
+  return app.maskPolicy
+    ? { ...DEFAULT_MASK_POLICY, ...app.maskPolicy }
+    : DEFAULT_MASK_POLICY;
+}
+
+const area = (b) => b.w * b.h;
+
+/** The smallest {x, y, w, h} box holding both of two boxes. */
+export function unionBox(a, b) {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    w: Math.max(a.x + a.w, b.x + b.w) - x,
+    h: Math.max(a.y + a.h, b.y + b.h) - y
+  };
+}
+
+function unionOf(boxes, order) {
+  let out = { ...boxes[order[0]] };
+  for (let i = 1; i < order.length; ++i) out = unionBox(out, boxes[order[i]]);
+  return out;
+}
+
+/**
+ * The most valuable gap cut of one group along one axis, or null when the
+ * group has no gap on it.
+ *
+ * `order` is the group's members sorted by that axis' start. A cut between
+ * members i and i+1 is legal only where nothing straddles it — the next box
+ * has to start at or past the far edge of every box before it, which for a
+ * union box is just its own far edge. What the cut is worth is the mask area
+ * it removes: the parent box less the two halves.
+ */
+function bestGap(boxes, order, box, axis) {
+  const n = order.length;
+  const start = axis === 'x' ? 'x' : 'y';
+  const size = axis === 'x' ? 'w' : 'h';
+
+  // suffix[i] is the union box of order[i..n-1]; the prefix is carried
+  // along the scan below
+  const suffix = new Array(n);
+  suffix[n - 1] = { ...boxes[order[n - 1]] };
+  for (let i = n - 2; i >= 0; --i) {
+    suffix[i] = unionBox(boxes[order[i]], suffix[i + 1]);
+  }
+
+  let best = null;
+  let prefix = { ...boxes[order[0]] };
+  for (let i = 0; i + 1 < n; ++i) {
+    if (i > 0) prefix = unionBox(prefix, boxes[order[i]]);
+    const next = boxes[order[i + 1]];
+    if (next[start] < prefix[start] + prefix[size]) continue; // straddled
+    const saving = area(box) - area(prefix) - area(suffix[i + 1]);
+    if (!best || saving > best.saving) {
+      best = { axis, at: i, saving, left: prefix, right: suffix[i + 1] };
+    }
+  }
+  return best;
+}
+
+/** a group of pieces, its box, and the best cut available to it */
+function makeNode(boxes, byX, byY, box) {
+  const node = { box: box ?? unionOf(boxes, byX), byX, byY, split: null };
+  if (byX.length > 1) {
+    const x = bestGap(boxes, byX, node.box, 'x');
+    const y = bestGap(boxes, byY, node.box, 'y');
+    node.split = !x ? y : !y || x.saving >= y.saving ? x : y;
+  }
+  return node;
+}
+
+/** the two halves of `node`, each with its own next-best cut */
+function splitNode(boxes, node) {
+  const { axis, at, left, right } = node.split;
+  const cut = axis === 'x' ? node.byX : node.byY;
+  const other = axis === 'x' ? node.byY : node.byX;
+  const inLeft = new Set(cut.slice(0, at + 1));
+  // the other axis' order survives the filter, so neither half is re-sorted
+  const leftOther = other.filter((i) => inLeft.has(i));
+  const rightOther = other.filter((i) => !inLeft.has(i));
+  const leftCut = cut.slice(0, at + 1);
+  const rightCut = cut.slice(at + 1);
+  return axis === 'x'
+    ? [
+        makeNode(boxes, leftCut, leftOther, left),
+        makeNode(boxes, rightCut, rightOther, right)
+      ]
+    : [
+        makeNode(boxes, leftOther, leftCut, left),
+        makeNode(boxes, rightOther, rightCut, right)
+      ];
+}
+
+/**
+ * Partition one drawing's pieces into mask clusters.
+ *
+ * @param {Array<{x, y, w, h}>} boxes one integer box per piece — a fill's
+ *   subpaths, a stroke's islands of triangles — already clamped to the
+ *   surface. Boxes may overlap; overlapping ones always end up in the same
+ *   cluster.
+ * @param {{minSaving: number, maxMasks: number}} [policy]
+ * @returns {Array<{x, y, w, h, items: number[]}>} clusters, each with the
+ *   indices of the pieces it holds. Cluster boxes are pairwise disjoint,
+ *   and their union is the union of `boxes`.
+ */
+export function clusterBoxes(boxes, policy = DEFAULT_MASK_POLICY) {
+  const n = boxes.length;
+  if (!n) return [];
+  // merged here as well as in maskPolicyOf, so that a partial policy from a
+  // direct caller ({ maxMasks: 1 }) cannot silently zero the other field
+  const { minSaving, maxMasks: cap } = { ...DEFAULT_MASK_POLICY, ...policy };
+  const maxMasks = Math.max(1, cap | 0);
+  const all = boxes.map((_, i) => i);
+  if (n === 1 || maxMasks === 1 || !(minSaving < Infinity)) {
+    return [{ ...unionOf(boxes, all), items: all }];
+  }
+
+  const byX = all.slice().sort((a, b) => boxes[a].x - boxes[b].x || a - b);
+  const byY = all.slice().sort((a, b) => boxes[a].y - boxes[b].y || a - b);
+  const nodes = [makeNode(boxes, byX, byY)];
+  // most-valuable cut first, so a maxMasks cap keeps the cuts that matter
+  while (nodes.length < maxMasks) {
+    let pick = -1;
+    let best = minSaving;
+    for (let i = 0; i < nodes.length; ++i) {
+      const split = nodes[i].split;
+      if (split && split.saving >= best) {
+        best = split.saving;
+        pick = i;
+      }
+    }
+    if (pick < 0) break;
+    const [a, b] = splitNode(boxes, nodes[pick]);
+    nodes[pick] = a;
+    nodes.push(b);
+  }
+  return nodes.map((node) => ({ ...node.box, items: node.byX }));
+}

package/lib/renderingcontext_2d.js

@@ -11,6 +11,7 @@ import {
   pixelLayout,
   toStraightRgba,
 } from "./imagedata.js";
+import { clusterBoxes, maskPolicyOf, unionBox } from "./maskcluster.js";
 import {
   Path2D,
   arcSegmentCount,
@@ -26,6 +27,7 @@ import {
 import Picture from "./picture.js";
 import Pixmap from "./pixmap.js";
 import { routeRaster } from "./rasterize.js";
+import { Surface } from "./surface.js";
 import {
   BL,
   BR,
@@ -48,6 +50,22 @@ import { TextLayout } from "./text/layout.js";
 import { reorderRuns } from "./text/shape.js";
 import { trapezoidize } from "./trapezoid.js";
 
+/**
+ * The subpaths of a flattened path that can enclose area, as the flat
+ * `[x0, y0, …]` lists both the local rasterizer and the trapezoidizer take,
+ * with the edge count the routing policy asks for.
+ */
+function fillableShapes(polys) {
+  const shapes = [];
+  let edges = 0;
+  for (const p of polys) {
+    if (p.pts.length < 6) continue;
+    shapes.push(p.pts);
+    edges += p.pts.length / 2;
+  }
+  return { shapes, edges };
+}
+
 /** The overlap of two {x, y, w, h} boxes, or null when they have none. */
 function intersectBox(a, b) {
   const x = Math.max(a.x, b.x);
@@ -103,12 +121,92 @@ const gcRegistry = new FinalizationRegistry(({ X, gcs }) => {
  * the type. A `RenderingContext2d` deliberately does not match: its `picture`
  * is a property rather than a method, and it keeps its own branch below.
  */
-/** a fillStyle with a single colour behind it, as opposed to a gradient or a
- * caller-supplied Picture */
+/** a fillStyle with a single colour behind it, as opposed to a gradient, a
+ * pattern or a caller-supplied Picture */
 function isPlainColor(style) {
   return typeof style === "string" || Array.isArray(style);
 }
 
+// `createPattern` repetitions -> XRender Repeat modes. The canvas spec's
+// per-axis 'repeat-x'/'repeat-y' have no mode here (see createPattern);
+// 'pad' and 'reflect' are the two XRender modes the spec has no name for.
+const REPEAT_MODES = {
+  repeat: 1, // Repeat.Normal
+  "no-repeat": 0, // Repeat.None
+  pad: 2, // clamp to the edge pixels
+  reflect: 3, // mirror every other tile
+};
+
+const PATTERN_DOCS =
+  "https://github.com/sidorares/ntk/blob/master/docs/context-2d.md#patterns";
+
+/**
+ * What a pattern tiles: a drawable holding the tile plus the picture format
+ * to read it through. A repeating source Picture is created over it rather
+ * than the source's own picture being changed, so tiling a `Surface` leaves
+ * `drawImage` of that same surface exactly as it was.
+ */
+function patternSourceOf(app, source) {
+  const Render = app.display.Render;
+  const formatFor = (depth) =>
+    depth === 32 ? Render.rgba32 : depth === 8 ? "a8" : Render.rgb24;
+
+  let drawable = null;
+  let width;
+  let height;
+  let format;
+  if (source instanceof Surface) {
+    if (source.app !== app) {
+      throw new Error(
+        "createPattern: the Surface belongs to a different X connection",
+      );
+    }
+    drawable = source.pixmap;
+    format = source.format === "a8" ? "a8" : Render.rgba32;
+    ({ width, height } = source);
+  } else if (source instanceof Image) {
+    drawable = source.pixmap(app);
+    format = Render.rgba32;
+    ({ width, height } = source);
+  } else if (source && typeof source.id === "number") {
+    // a Drawable: a Pixmap, or a Window (through its backing pixmap, which
+    // is where a double-buffered window's current pixels actually are)
+    drawable = source._backing || source;
+    const depth = drawable.depth ?? source.depth;
+    if (!depth) {
+      throw new Error(
+        "createPattern: the drawable's depth is not known yet — await the window's geometry, or pass a Surface",
+      );
+    }
+    format = formatFor(depth);
+    width = drawable.width ?? source.width;
+    height = drawable.height ?? source.height;
+  } else {
+    throw new Error(
+      "createPattern: expected a Surface, an Image, a Pixmap or a Window as the tile, got " +
+        (source === null ? "null" : typeof source),
+    );
+  }
+  if (format === "a8") {
+    throw new Error(
+      "createPattern: a coverage (a8) tile has no colour to paint with — XRender would " +
+        "sample it as black. Draw the tile into an argb32 Surface and tile that, or keep " +
+        `the a8 one and use ctx.drawImage, which paints it in the current fillStyle. ${PATTERN_DOCS}`,
+    );
+  }
+  return { drawable, format, width, height };
+}
+
+/**
+ * Point a pattern's picture transform at the transform in force for this
+ * fill — patterns are painted in user space, so the CTM is part of the
+ * mapping. Returns false when nothing would be painted (a singular matrix),
+ * true for anything else, including every non-pattern style.
+ */
+function preparePattern(src, m) {
+  return src instanceof CanvasPattern ? src._sync(m) : true;
+}
+
 function isPictureSource(image) {
   return (
     image instanceof Image ||
@@ -136,6 +234,30 @@ const GCO_TO_PICTOP = {
   lighter: "Add",
 };
 
+// The ops whose result is the destination wherever the mask is zero. Only
+// those may have a drawing's mask split into several boxes (maskcluster.js):
+// what the split gives up is the gaps between the boxes, and for these ops
+// the single-box version would not have changed those pixels either. `copy`,
+// `source-in`, `destination-in`, `source-out` and `destination-atop` write
+// the source — or nothing — across the whole box, so they keep one.
+const MASK_BOUNDED_OPS = [
+  "Over",
+  "OverReverse",
+  "OutReverse",
+  "Atop",
+  "Xor",
+  "Add",
+];
+
+// and what they are clustered with instead: one mask, exactly as before
+const ONE_MASK = { minSaving: Infinity, maxMasks: 1 };
+
+// How far apart two of a stroke's triangles have to be to start a new piece
+// (_trisPieces). Two mask boxes a pixel or two apart are not worth
+// splitting — each carries a pixel of antialiasing slack of its own — so
+// this only has to be small next to anything `minSaving` would pay for.
+const PIECE_SLACK = 2;
+
 // extrude-polyline has no round caps/joins: 'round' extrudes as butt/bevel
 // and the missing coverage is unioned in afterwards as triangle-fan disks
 // (see _strokePolys)
@@ -284,6 +406,12 @@ class RenderingContext2d {
     // a silent perf cliff, so hits and misses-by-reason are always counted.
     // NTK_DEBUG_SHAPES=1 prints the process-wide aggregate at exit.
     this.shapeStats = { hits: 0, misses: {} };
+    // Mask cost, for the same reason (issue #264): a drawing whose pieces
+    // are scattered pays for the box around all of them unless the mask is
+    // split, and neither the pixels nor the split show up anywhere else.
+    // `masks` counts mask passes, `pixels` their total area, `split` the
+    // drawings that took more than one.
+    this.maskStats = { masks: 0, pixels: 0, split: 0 };
     this._stack = [];
     this._clips = []; // [{ polys, rule }] in device space, already stacked
     this._gco = "source-over";
@@ -458,7 +586,11 @@ class RenderingContext2d {
       const c = parseColor(value);
       return this.createSolidPicture(c[0], c[1], c[2], c[3]);
     }
-    if (value instanceof Picture || value instanceof CanvasGradient) {
+    if (
+      value instanceof Picture ||
+      value instanceof CanvasGradient ||
+      value instanceof CanvasPattern
+    ) {
       return value;
     }
     throw new Error("Unknown fill style");
@@ -763,11 +895,9 @@ class RenderingContext2d {
     });
   }
 
-  _rasterizePolys(picture, polys, rule, dx = 0, dy = 0) {
-    const flat = [];
-    for (const p of polys) if (p.pts.length >= 6) flat.push(p.pts);
-    if (!flat.length) return;
-    const traps = trapezoidize(flat, dx, dy, [], rule);
+  _rasterizePolys(picture, shapes, rule, dx = 0, dy = 0) {
+    if (!shapes.length) return;
+    const traps = trapezoidize(shapes, dx, dy, [], rule);
     // stay under the server's maximum request size
     const chunk = 4000 * 6;
     for (let i = 0; i < traps.length; i += chunk) {
@@ -840,46 +970,34 @@ class RenderingContext2d {
   }
 
   /**
-   * Core fill: rasterize device-space polys into the scratch a8 mask,
-   * scale by globalAlpha, intersect with the clip, composite the source.
-   */
-  /**
-   * Device-space bounding box of flattened polys, with a pixel of slack for
-   * the antialiased edge, clamped to the surface. Null when nothing lands
-   * on it.
+   * Device-space bounding box of one flat `[x0, y0, …]` point list, with a
+   * pixel of slack for the antialiased edge, clamped to the surface. Null
+   * when nothing lands on it.
    */
-  _polysBBox(polys) {
+  _pointsBBox(pts) {
     let minX = Infinity;
     let minY = Infinity;
     let maxX = -Infinity;
     let maxY = -Infinity;
-    for (const poly of polys) {
-      const pts = poly.pts;
-      for (let i = 0; i < pts.length; i += 2) {
-        if (pts[i] < minX) minX = pts[i];
-        if (pts[i] > maxX) maxX = pts[i];
-        if (pts[i + 1] < minY) minY = pts[i + 1];
-        if (pts[i + 1] > maxY) maxY = pts[i + 1];
-      }
+    for (let i = 0; i < pts.length; i += 2) {
+      if (pts[i] < minX) minX = pts[i];
+      if (pts[i] > maxX) maxX = pts[i];
+      if (pts[i + 1] < minY) minY = pts[i + 1];
+      if (pts[i + 1] > maxY) maxY = pts[i + 1];
     }
     if (maxX === -Infinity) return null;
     return this._clampBBox(minX, minY, maxX, maxY);
   }
 
-  /** the same, for a flat triangle soup (stroke geometry) */
-  _trisBBox(tris) {
-    let minX = Infinity;
-    let minY = Infinity;
-    let maxX = -Infinity;
-    let maxY = -Infinity;
-    for (let i = 0; i < tris.length; i += 2) {
-      if (tris[i] < minX) minX = tris[i];
-      if (tris[i] > maxX) maxX = tris[i];
-      if (tris[i + 1] < minY) minY = tris[i + 1];
-      if (tris[i + 1] > maxY) maxY = tris[i + 1];
+  /** the same over every subpath of a flattened path, as one box */
+  _polysBBox(polys) {
+    let out = null;
+    for (const poly of polys) {
+      const b = this._pointsBBox(poly.pts);
+      if (!b) continue;
+      out = out ? unionBox(out, b) : b;
     }
-    if (maxX === -Infinity) return null;
-    return this._clampBBox(minX, minY, maxX, maxY);
+    return out;
   }
 
   // a pixel of slack for the antialiased edge, clamped to the surface
@@ -892,57 +1010,74 @@ class RenderingContext2d {
     return { x, y, w, h };
   }
 
-  _fillPolys(polys, rule, { src = null, op = null, alpha = null } = {}) {
-    if (!polys.length) return;
-    src = src ?? this._backgroundPicture;
-    op = op ?? this._op();
-    alpha = alpha ?? this.globalAlpha;
-    if (alpha <= 0) return;
-
-    // Everything below is bounded to the shape's bounding box rather than
-    // the whole surface. On the wire it makes no difference — a Composite
-    // request is the same size either way — but it is the difference
-    // between the server touching a 34x34 box and a 400x400 one per fill.
-    // Stale mask content outside the box is never composited, so clearing
-    // only the box is safe.
-    const b = this._polysBBox(polys);
-    if (!b) return;
-    const R = this.Render;
+  /**
+   * The mask boxes one drawing's pieces are painted through: one per cluster
+   * of them, whose union is the drawing's bounding box.
+   *
+   * Everything the mask does is bounded to those boxes rather than to the
+   * whole surface. On the wire it makes no difference — a Composite request
+   * is the same size either way — but it is the difference between the
+   * server touching a 34x34 box and a 400x400 one per fill. Where the pieces
+   * are *scattered*, their union is a poor bound in the same way, and
+   * `clusterBoxes` cuts it into the few boxes the ink is actually in (see
+   * maskcluster.js). Stale mask content outside a box is never composited,
+   * so clearing only the boxes is safe.
+   */
+  _maskClusters(pieces, op) {
+    const clusters = clusterBoxes(
+      pieces,
+      this._maskBounded(op) ? maskPolicyOf(this.window.app) : ONE_MASK,
+    );
+    if (clusters.length > 1) this.maskStats.split++;
+    return clusters;
+  }
 
-    this._ensureFillMask();
-    const flat = [];
-    let edges = 0;
-    for (const p of polys) {
-      if (p.pts.length < 6) continue;
-      flat.push(p.pts);
-      edges += p.pts.length / 2;
-    }
-    if (
-      !this._uploadCoverage({ polys: flat, rule, dx: -b.x, dy: -b.y }, b, edges)
-    ) {
-      R.FillRectangles(
-        R.PictOp.Src,
-        this.fillMask.id,
-        [0, 0, 0, 0],
-        [b.x, b.y, b.w, b.h],
-      );
-      this._rasterizePolys(this.fillMask, polys, rule);
-    }
+  /** whether `op` leaves the destination alone where the mask is zero */
+  _maskBounded(op) {
+    this._boundedOps ??= new Set(
+      MASK_BOUNDED_OPS.map((name) => this.Render.PictOp[name]),
+    );
+    return this._boundedOps.has(op);
+  }
 
-    // a rectangular clip narrows where the coverage is *composited*; the
-    // mask content outside it is stale by the same argument as outside `b`.
-    // A stack whose mask was dropped by restore() may still hold a poly —
-    // _clipRect says null then, and the mask comes back on demand.
+  /**
+   * The tail every masked fill and stroke ends in: coverage for one box into
+   * the scratch a8 mask, scaled by `alpha`, intersected with the clip, and
+   * the source composited through it.
+   *
+   * `job` is what a Rasterizer takes minus the box (docs/context-2d.md) —
+   * `{ polys, rule }` or `{ triangles }`; `server` rasterizes the same
+   * geometry into the mask server-side, for when the local rasterizer is not
+   * the cheaper route or declines.
+   *
+   * @returns {boolean} whether anything was composited
+   */
+  _paintThroughMask(b, job, { edges, src, op, alpha, server }) {
+    const R = this.Render;
+    // A rectangular clip narrows where the coverage is *composited*; the
+    // mask content outside it is stale by the same argument as outside `b`,
+    // and a box the clip rejects outright needs no coverage at all. A stack
+    // whose mask was dropped by restore() may still hold a poly — _clipRect
+    // says null then, and the mask comes back on demand.
     let out = b;
     if (this._clips.length && !this.clipMask) {
       const cr = this._clipRect();
       if (cr) {
         out = intersectBox(b, cr);
-        if (!out) return;
+        if (!out) return false;
       } else {
         this._requireClipMask();
       }
     }
+    if (!this._uploadCoverage({ ...job, dx: -b.x, dy: -b.y }, b, edges)) {
+      R.FillRectangles(
+        R.PictOp.Src,
+        this.fillMask.id,
+        [0, 0, 0, 0],
+        [b.x, b.y, b.w, b.h],
+      );
+      server();
+    }
     if (alpha < 1) {
       // In with a constant color scales the a8 coverage by that alpha
       R.FillRectangles(
@@ -985,7 +1120,59 @@ class RenderingContext2d {
       out.w,
       out.h,
     );
-    this._markDirty();
+    this.maskStats.masks++;
+    this.maskStats.pixels += out.w * out.h;
+    return true;
+  }
+
+  /**
+   * Core fill: rasterize device-space polys into the scratch a8 mask,
+   * scale by globalAlpha, intersect with the clip, composite the source.
+   */
+  _fillPolys(polys, rule, { src = null, op = null, alpha = null } = {}) {
+    if (!polys.length) return;
+    src = src ?? this._backgroundPicture;
+    op = op ?? this._op();
+    alpha = alpha ?? this.globalAlpha;
+    if (alpha <= 0) return;
+    if (!preparePattern(src, this._m)) return;
+
+    // one box per subpath, so a path holding disjoint ones can be masked as
+    // the pieces it is rather than as the box around all of them
+    const shapes = [];
+    const pieces = [];
+    for (const p of polys) {
+      if (p.pts.length < 6) continue;
+      const b = this._pointsBBox(p.pts);
+      if (!b) continue;
+      shapes.push(p.pts);
+      pieces.push(b);
+    }
+    if (!shapes.length) return;
+
+    this._ensureFillMask();
+    let painted = false;
+    for (const cluster of this._maskClusters(pieces, op)) {
+      const flat = [];
+      let edges = 0;
+      for (const i of cluster.items) {
+        flat.push(shapes[i]);
+        edges += shapes[i].length / 2;
+      }
+      painted =
+        this._paintThroughMask(
+          cluster,
+          { polys: flat, rule },
+          {
+            edges,
+            src,
+            op,
+            alpha,
+            server: () => this._rasterizePolys(this.fillMask, flat, rule),
+          },
+        ) || painted;
+    }
+    if (painted) this._markDirty();
   }
 
   _strokePolys(polys, { src = null } = {}) {
@@ -1106,10 +1293,23 @@ class RenderingContext2d {
         // a segment that is already at least r long
         if (dot >= 0 && r * r <= shortest) continue;
         const cross = ax * by - ay * bx;
-        // r·tan(φ/2) > min(|a|, |b|), squared. A non-positive denominator is
-        // the reversal the tangent is infinite at.
-        const denom = Math.sqrt(la * lb) + dot;
-        if (denom <= 0 || (r * cross) ** 2 > shortest * denom * denom) {
+        // r·tan(φ/2) > min(|a|, |b|), squared. A non-positive denominator
+        // is the reversal the tangent is infinite at — but near one the
+        // denominator is pure cancellation (√(la·lb) and -dot agree to ~15
+        // digits), so an exact double-back lands a few ulps to either side
+        // of 0. The same-x bursts of issue #259 have cross exactly 0 too,
+        // so when denom rounded positive neither test here fired and the
+        // extruder met the reversal itself, normalizing a zero-length
+        // tangent into NaN join vertices. Below its own noise floor denom
+        // only means "within microradians of a reversal", where the true
+        // tangent exceeds a million and no segment can hold the join: cut
+        // unconditionally.
+        const ab = Math.sqrt(la * lb);
+        const denom = ab + dot;
+        if (
+          denom <= ab * 1e-12 ||
+          (r * cross) ** 2 > shortest * denom * denom
+        ) {
           (cuts ??= []).push(i);
         }
       }
@@ -1277,6 +1477,27 @@ class RenderingContext2d {
         for (const run of dashed.runs) extrudeRun(cleanRun(run), false);
       }
     }
+    // Nothing non-finite may reach the server: FIXED encoding turns NaN
+    // into 0, so one poisoned vertex renders as a wedge to the origin on a
+    // real display — while the in-process server quietly drops it, which
+    // is why no headless pixel test can see this for us (issue #259). The
+    // cuts above are meant to keep the extruder off that path; this keeps
+    // a future miss from being catastrophic. A sum is finite iff every
+    // term is.
+    let w = 0;
+    for (let i = 0; i < tris.length; i += 6) {
+      const sum =
+        tris[i] +
+        tris[i + 1] +
+        tris[i + 2] +
+        tris[i + 3] +
+        tris[i + 4] +
+        tris[i + 5];
+      if (!Number.isFinite(sum)) continue;
+      if (w < i) for (let k = 0; k < 6; k++) tris[w + k] = tris[i + k];
+      w += 6;
+    }
+    if (w < tris.length) tris.length = w;
     if (!tris.length) return;
 
     const op = this._op();
@@ -1291,14 +1512,22 @@ class RenderingContext2d {
     const chunk = 4000 * 6;
     if (direct) {
       for (let i = 0; i < tris.length; i += chunk) {
+        const batch = tris.slice(i, i + chunk);
+        // RENDER aligns the source with the *first triangle's first vertex*,
+        // not with the destination: the source is sampled at
+        // (srcX + x - floor(tris[0].x)). Passing that vertex back is what
+        // makes source coordinates equal destination coordinates, the same
+        // convention drawGlyphRuns and compositeTraps use — without it every
+        // non-constant stroke style (a gradient, a pattern) is offset by
+        // wherever the stroke happens to start, and shifts as it moves.
         this.Render.Triangles(
           op,
           src.id,
-          0,
-          0,
+          Math.floor(batch[0]),
+          Math.floor(batch[1]),
           this.picture.id,
           this.Render.a8,
-          tris.slice(i, i + chunk),
+          batch,
         );
       }
       this._markDirty();
@@ -1308,91 +1537,117 @@ class RenderingContext2d {
     // Render coverage into the scratch mask, then composite through it so
     // the stroke honors clip / globalAlpha / composite op.
     //
-    // Bounded to the stroke's bounding box, for the same reason _fillPolys
-    // is: on the wire a Composite is the same size either way, but this
-    // branch runs once per stroke, and a wall of 400 round-capped icons is
-    // 3200 of them. Clearing and compositing the whole surface each time was
-    // ~6 Gpx a frame and took 1.9 s on XQuartz where the bounded version
-    // takes 37 ms (react-x11#148). Stale mask content outside the box is
-    // never composited, so clearing only the box is safe.
+    // Bounded to the stroke's islands, for the same reason _fillPolys is: on
+    // the wire a Composite is the same size either way, but this branch runs
+    // once per stroke, and a wall of 400 round-capped icons is 3200 of them.
+    // Clearing and compositing the whole surface each time was ~6 Gpx a frame
+    // and took 1.9 s on XQuartz where the bounded version takes 37 ms
+    // (react-x11#148). Stale mask content outside the boxes is never
+    // composited, so clearing only them is safe.
     this._ensureFillMask();
-    const b = this._trisBBox(tris);
-    if (!b) return;
-    if (
-      !this._uploadCoverage(
-        { triangles: tris, dx: -b.x, dy: -b.y },
-        b,
-        tris.length / 2,
-      )
-    ) {
-      this.Render.FillRectangles(
-        this.Render.PictOp.Src,
-        this.fillMask.id,
-        [0, 0, 0, 0],
-        [b.x, b.y, b.w, b.h],
-      );
-      const opaque = this.createSolidPicture(0, 0, 0, 1);
-      for (let i = 0; i < tris.length; i += chunk) {
-        this.Render.Triangles(
-          this.Render.PictOp.Add,
-          opaque.id,
-          0,
-          0,
-          this.fillMask.id,
-          this.Render.a8,
-          tris.slice(i, i + chunk),
-        );
-      }
-    }
-    let out = b;
-    if (this._clips.length && !this.clipMask) {
-      const cr = this._clipRect();
-      if (cr) {
-        out = intersectBox(b, cr);
-        if (!out) return;
-      } else {
-        this._requireClipMask();
+    const pieces = this._trisPieces(tris);
+    if (!pieces.length) return;
+    // the soup itself when it is one piece holding every triangle — the
+    // common case (one polyline is one piece), and worth not copying
+    const whole =
+      pieces.length === 1 &&
+      pieces[0].start === 0 &&
+      pieces[0].end === tris.length;
+    let painted = false;
+    for (const cluster of this._maskClusters(pieces, op)) {
+      const batch = whole ? tris : this._trisOf(tris, pieces, cluster.items);
+      painted =
+        this._paintThroughMask(
+          cluster,
+          { triangles: batch },
+          {
+            edges: batch.length / 2,
+            src,
+            op,
+            alpha: this.globalAlpha,
+            server: () => {
+              const opaque = this.createSolidPicture(0, 0, 0, 1);
+              for (let i = 0; i < batch.length; i += chunk) {
+                this.Render.Triangles(
+                  this.Render.PictOp.Add,
+                  opaque.id,
+                  0,
+                  0,
+                  this.fillMask.id,
+                  this.Render.a8,
+                  batch.slice(i, i + chunk),
+                );
+              }
+            },
+          },
+        ) || painted;
+    }
+    if (painted) this._markDirty();
+  }
+
+  /**
+   * A stroke's triangle soup as the islands it is made of: consecutive
+   * triangles are coalesced while they stay within `PIECE_SLACK` of each
+   * other, which collapses a polyline — body, caps, join disks and all —
+   * into one piece and leaves a batch of separate strokes as one piece each.
+   * Each piece carries the `[start, end)` span of `tris` it owns.
+   *
+   * Coalescing is always safe: merging boxes can only widen a mask, while
+   * splitting overlapping coverage apart is what would double-blend it —
+   * and `clusterBoxes` cannot split overlapping boxes anyway. So this is a
+   * linear pre-pass whose only job is to hand the clustering a handful of
+   * boxes instead of thousands of triangles.
+   *
+   * A piece that misses the surface entirely is dropped, leaving a hole in
+   * the spans — which is why the caller gathers a batch from the spans it
+   * has rather than assuming they tile `tris`.
+   */
+  _trisPieces(tris) {
+    const pieces = [];
+    let open = null;
+    const close = () => {
+      if (!open) return;
+      const b = this._clampBBox(open.minX, open.minY, open.maxX, open.maxY);
+      if (b) pieces.push({ ...b, start: open.start, end: open.end });
+      open = null;
+    };
+    for (let i = 0; i < tris.length; i += 6) {
+      const minX = Math.min(tris[i], tris[i + 2], tris[i + 4]);
+      const maxX = Math.max(tris[i], tris[i + 2], tris[i + 4]);
+      const minY = Math.min(tris[i + 1], tris[i + 3], tris[i + 5]);
+      const maxY = Math.max(tris[i + 1], tris[i + 3], tris[i + 5]);
+      if (
+        open &&
+        minX - PIECE_SLACK <= open.maxX &&
+        open.minX - PIECE_SLACK <= maxX &&
+        minY - PIECE_SLACK <= open.maxY &&
+        open.minY - PIECE_SLACK <= maxY
+      ) {
+        if (minX < open.minX) open.minX = minX;
+        if (maxX > open.maxX) open.maxX = maxX;
+        if (minY < open.minY) open.minY = minY;
+        if (maxY > open.maxY) open.maxY = maxY;
+        open.end = i + 6;
+        continue;
       }
+      close();
+      open = { minX, minY, maxX, maxY, start: i, end: i + 6 };
     }
-    if (this.globalAlpha < 1) {
-      this.Render.FillRectangles(
-        this.Render.PictOp.In,
-        this.fillMask.id,
-        [0, 0, 0, this.globalAlpha],
-        [out.x, out.y, out.w, out.h],
-      );
-    }
-    if (this.clipMask) {
-      this.Render.Composite(
-        this.Render.PictOp.In,
-        this.clipMask.id,
-        0,
-        this.fillMask.id,
-        out.x,
-        out.y,
-        0,
-        0,
-        out.x,
-        out.y,
-        out.w,
-        out.h,
-      );
+    close();
+    return pieces;
+  }
+
+  /** the triangles of the given pieces, gathered into one soup */
+  _trisOf(tris, pieces, items) {
+    let n = 0;
+    for (const i of items) n += pieces[i].end - pieces[i].start;
+    const out = new Array(n);
+    let w = 0;
+    for (const i of items) {
+      const piece = pieces[i];
+      for (let k = piece.start; k < piece.end; ++k) out[w++] = tris[k];
     }
-    this.Render.Composite(
-      op,
-      src.id,
-      this.fillMask.id,
-      this.picture.id,
-      out.x,
-      out.y,
-      out.x,
-      out.y,
-      out.x,
-      out.y,
-      out.w,
-      out.h,
-    );
-    this._markDirty();
+    return out;
   }
 
   /**
@@ -1429,6 +1684,7 @@ class RenderingContext2d {
   drawGlyphs(op, src, positioned) {
     const app = this.window.app;
     const R = this.Render;
+    if (!preparePattern(src, this._m)) return;
     if (!this._clips.length) {
       drawGlyphRuns(app, op, src.id, this.picture.id, positioned);
       this._markDirty();
@@ -1650,6 +1906,7 @@ class RenderingContext2d {
 
   fillRect(x, y, w, h) {
     if (matIsIdentity(this._m)) {
+      if (!preparePattern(this._backgroundPicture, this._m)) return;
       const mask = this._compositeMask();
       this.Render.Composite(
         this._op(),
@@ -2356,7 +2613,13 @@ class RenderingContext2d {
         [0, 0, 0, 0],
         [0, 0, bb.w, bb.h],
       );
-      this._rasterizePolys(tmpMask, entry.polys, entry.rule, -bb.x, -bb.y);
+      this._rasterizePolys(
+        tmpMask,
+        fillableShapes(entry.polys).shapes,
+        entry.rule,
+        -bb.x,
+        -bb.y,
+      );
     }
     R.Composite(
       op,
@@ -2395,14 +2658,8 @@ class RenderingContext2d {
   _uploadClipCoverage(tmpPixmap, entry, bb) {
     const rasterizer = this.window.app.rasterizer;
     if (!rasterizer) return false;
-    const flat = [];
-    let edges = 0;
-    for (const p of entry.polys) {
-      if (p.pts.length < 6) continue;
-      flat.push(p.pts);
-      edges += p.pts.length / 2;
-    }
-    if (!flat.length) return false;
+    const { shapes, edges } = fillableShapes(entry.polys);
+    if (!shapes.length) return false;
     if (
       routeRaster(bb.w, bb.h, edges, this.window.app.rasterPolicy) !== "local"
     ) {
@@ -2410,7 +2667,7 @@ class RenderingContext2d {
     }
 
     const coverage = rasterizer.rasterize({
-      polys: flat,
+      polys: shapes,
       rule: entry.rule,
       dx: -bb.x,
       dy: -bb.y,
@@ -2714,6 +2971,35 @@ class RenderingContext2d {
     return new CanvasGradient("conical", this, x0, y0, angle);
   }
 
+  /**
+   * A tiled paint: `source` repeated across whatever it fills, by the server,
+   * in the one composite the fill already costs (issue #263).
+   *
+   *     const tile = new Surface(app, { width: 24, height: 24 });
+   *     tile.render((c) => { c.fillStyle = '#333'; c.fillRect(0, 0, 1, 1); });
+   *     ctx.fillStyle = ctx.createPattern(tile, 'repeat');
+   *     ctx.fillRect(0, 0, ctx.width, ctx.height);   // one request, no mask
+   *
+   * That is the difference between a background grid costing one repeating
+   * picture and costing a pane-sized coverage mask: drawn as thousands of
+   * tiny subpaths, a dot grid rasterizes client-side into an a8 mask the
+   * size of its own bounding box — which for a background *is* the pane —
+   * then uploads and composites it, every frame.
+   *
+   * `source` is a `Surface` (pixels the server drew), an `Image` (pixels
+   * uploaded from the client), a `Pixmap` or a `Window`.
+   *
+   * `repetition` is `'repeat'` (the default), `'no-repeat'`, or the two
+   * XRender modes the canvas spec has no name for: `'pad'` (clamp to the
+   * edge pixels) and `'reflect'` (mirror every other tile). The spec's
+   * per-axis `'repeat-x'`/`'repeat-y'` are not among them — XRender repeats
+   * a source picture on both axes or on neither — and asking for one throws
+   * with the clip-to-a-strip equivalent.
+   */
+  createPattern(source, repetition = "repeat") {
+    return new CanvasPattern(this.window.app, source, repetition);
+  }
+
   /** the pixel layout of whatever this context currently draws into */
   get _layout() {
     const depth =
@@ -2952,8 +3238,13 @@ class RenderingContext2d {
    * colour to fold into; `_drawCoverage` routes those through the scratch. */
   _coverageSource() {
     const style = this._fillStyle;
-    if (this.globalAlpha >= 1 || !isPlainColor(style))
-      return this._backgroundPicture;
+    if (this.globalAlpha >= 1 || !isPlainColor(style)) {
+      // a pattern whose transform collapsed paints nothing, and "nothing" as
+      // a source is transparent black — no call site here has to know
+      return preparePattern(this._backgroundPicture, this._m)
+        ? this._backgroundPicture
+        : this.createSolidPicture(0, 0, 0, 0);
+    }
     const c = parseColor(style);
     return this.createSolidPicture(c[0], c[1], c[2], c[3] * this.globalAlpha);
   }
@@ -3444,9 +3735,167 @@ class CanvasGradient {
   }
 }
 
+/**
+ * The fill/stroke style `ctx.createPattern` returns: a tile and how it
+ * repeats, backed by one repeating XRender source picture.
+ *
+ * The picture is created on first use and freed by `destroy()` (or by the
+ * GC, through `Picture`'s finalizer). The tile it reads is *not* the
+ * pattern's to free: destroying the `Surface`/`Image` it came from is safe
+ * while the pattern lives — X keeps pixmap storage alive as long as a
+ * picture references it — but the pixels stop tracking anything drawn after.
+ *
+ * A pattern is bound to the connection, not to the context that made it, so
+ * one grid tile serves every window on the app.
+ */
+class CanvasPattern {
+  constructor(app, source, repetition = "repeat") {
+    const name = repetition ?? "repeat";
+    const repeat = REPEAT_MODES[name];
+    if (repeat === undefined) {
+      const known = Object.keys(REPEAT_MODES)
+        .map((k) => `'${k}'`)
+        .join(", ");
+      const axis = name === "repeat-x" || name === "repeat-y";
+      throw new Error(
+        `createPattern: unsupported repetition ${JSON.stringify(name)}` +
+          (axis
+            ? " — XRender repeats a source picture on both axes or on neither, with no" +
+              " per-axis mode to map this one to. Tile with 'repeat' and bound the fill" +
+              " to the one row/column of tiles instead: ctx.fillRect(x, y, w, tile.height)" +
+              " repeats horizontally and nowhere else."
+            : "") +
+          `. Supported: ${known}. ${PATTERN_DOCS}`,
+      );
+    }
+    const { drawable, format, width, height } = patternSourceOf(app, source);
+
+    this.app = app;
+    this.Render = app.display.Render;
+    this.source = source;
+    this.repetition = name;
+    this.width = width;
+    this.height = height;
+    this._repeat = repeat;
+    this._drawable = drawable;
+    this._format = format;
+    // pattern space -> user space, the canvas `CanvasPattern.setTransform`
+    // matrix. The picture transform is its inverse, composed with the CTM.
+    this._m = [1, 0, 0, 1, 0, 0];
+    this._picture = null;
+    // what the server currently holds: a fresh picture is untransformed and
+    // filtered nearest, so an untransformed fill costs no extra request
+    this._applied = [1, 0, 0, 1, 0, 0];
+    this._filter = "nearest";
+  }
+
+  /**
+   * Position/scale/rotate the tile, canvas-style: `matrix` maps pattern
+   * space to user space, as `[a, b, c, d, e, f]` or a DOMMatrix-shaped
+   * `{a, b, c, d, e, f}`. Translating by the scroll offset is what keeps a
+   * grid glued to the content under it.
+   */
+  setTransform(matrix) {
+    const m = Array.isArray(matrix)
+      ? matrix
+      : [matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f];
+    if (m.length < 6 || m.some((v) => !Number.isFinite(Number(v)))) {
+      throw new Error(
+        "CanvasPattern.setTransform: expected [a, b, c, d, e, f] or {a, b, c, d, e, f} of finite numbers",
+      );
+    }
+    this._m = m.slice(0, 6).map(Number);
+    return this;
+  }
+
+  /** the repeating source Picture, created on first use */
+  get picture() {
+    if (!this._picture) {
+      this._picture = new Picture(this.app, {
+        drawable: this._drawable,
+        format: this._format,
+        repeat: this._repeat,
+      });
+    }
+    return this._picture;
+  }
+
+  /** the Picture id, which is all a fill needs of a style */
+  get id() {
+    return this.picture.id;
+  }
+
+  /**
+   * Make the server-side mapping match `ctm ∘ patternMatrix`. XRender's
+   * picture transform runs the other way — it takes a coordinate in the
+   * composite's source space (which every fill here keeps equal to device
+   * space) to a texel — so it is the inverse.
+   *
+   * Returns false when that composition collapses (a zero scale), which
+   * paints nothing, exactly as the canvas spec says.
+   */
+  _sync(ctm) {
+    const m = matMultiply(ctm, this._m);
+    const inv = matInvert(m);
+    if (!inv) return false;
+    const a = this._applied;
+    if (
+      inv[0] !== a[0] ||
+      inv[1] !== a[1] ||
+      inv[2] !== a[2] ||
+      inv[3] !== a[3] ||
+      inv[4] !== a[4] ||
+      inv[5] !== a[5]
+    ) {
+      this.Render.SetPictureTransform(this.id, [
+        inv[0],
+        inv[2],
+        inv[4],
+        inv[1],
+        inv[3],
+        inv[5],
+        0,
+        0,
+        1,
+      ]);
+      this._applied = inv;
+    }
+    // A tile landing on whole pixels wants its own pixels back, not a blend
+    // of them: nearest is both exact and cheaper. Anything else is resampled.
+    const filter =
+      m[0] === 1 &&
+      m[1] === 0 &&
+      m[2] === 0 &&
+      m[3] === 1 &&
+      Number.isInteger(m[4]) &&
+      Number.isInteger(m[5])
+        ? "nearest"
+        : "bilinear";
+    if (filter !== this._filter) {
+      this.picture.setFilter(filter);
+      this._filter = filter;
+    }
+    return true;
+  }
+
+  /** free the repeating picture; the tile it read is the caller's */
+  destroy() {
+    if (this._picture) {
+      this._picture.destroy();
+      this._picture = null;
+    }
+    this._applied = [1, 0, 0, 1, 0, 0];
+    this._filter = "nearest";
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}
+
 // register context
 Drawable.renderingContextFactory["2d"] = (window) =>
   new RenderingContext2d(window);
 
 export default RenderingContext2d;
-export { CanvasGradient };
+export { CanvasGradient, CanvasPattern };

package/package.json

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