ntk 7.6.1 → 8.0.0

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 } = {}) {
@@ -1325,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();
@@ -1342,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;
   }
 
   /**
@@ -1463,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();
@@ -1684,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(),
@@ -2390,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,
@@ -2429,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"
     ) {
@@ -2444,7 +2667,7 @@ class RenderingContext2d {
     }
 
     const coverage = rasterizer.rasterize({
-      polys: flat,
+      polys: shapes,
       rule: entry.rule,
       dx: -bb.x,
       dy: -bb.y,
@@ -2748,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 =
@@ -2986,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);
   }
@@ -3478,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 };