react-x11 2.4.0 → 2.6.0

package/src/cocoa/presenter.js

@@ -19,12 +19,19 @@
 //
 // Sibling order is zPosition, assigned from the node's own paintOrder() —
 // no sublayer-list surgery, ever. Dirt arrives on the invalidate channel
-// (`noteInvalidate`): a node means that node, null means everything (the
-// same "no bound named repaints everything" rule the X11 damage model has),
-// and geometry is re-diffed every frame because comparing four numbers is
-// cheaper than knowing.
+// (`noteInvalidate`): a node means that node, a bare rect means that part
+// of every raster it touches, null means everything (the same "no bound
+// named repaints everything" rule the X11 damage model has), and geometry
+// is re-diffed every frame because comparing four numbers is cheaper than
+// knowing.
 import { cssColorStraight } from 'ntk';
 
+import {
+  Node,
+  addDamageRect,
+  damageToPaint,
+  intersectRects,
+} from '../nodes.js';
 import { CocoaContext2D } from './context2d.js';
 
 const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
@@ -254,8 +261,27 @@ class ShapeRecorder {
   }
 }
 
-/** Paint everything a node draws itself — Node.paint minus the children. */
+/**
+ * Paint everything a node draws itself — Node.paint minus the children.
+ *
+ * An element that overrides `paint` (every drawing element in
+ * @react-x11/components does: `super.paint(ctx)` for the box, then the
+ * scene) has its content nowhere but in that override, so the override is
+ * what a raster replays — with the children held back by `_ownPaintOnly`,
+ * the one presenter-side flag `Node._paintChildren` honours, because they
+ * have visuals of their own. Everything else paints piecewise, which is
+ * what `Node.paint` would do minus the child walk.
+ */
 function paintSelf(node, ctx) {
+  if (node.paint !== Node.prototype.paint) {
+    node._ownPaintOnly = true;
+    try {
+      node.paint(ctx);
+    } finally {
+      node._ownPaintOnly = false;
+    }
+    return;
+  }
   node._paintShadow(ctx);
   node._paintBackground(ctx);
   node.paintContent(ctx);
@@ -263,6 +289,26 @@ function paintSelf(node, ctx) {
   node._paintOutline(ctx);
 }
 
+// Past this many bare-rect claims in one frame the overlap test costs more
+// than it saves, and the answer is the one a null claim gives: everything.
+const MAX_DIRTY_RECTS = 64;
+
+// The pass list of a raster that repaints in full: one pass, unbounded.
+const FULL_PASS = Object.freeze([null]);
+
+/** A rect grown outward to whole pixels — a pass clears and clips to its
+ * edges, and a fractional edge would antialias the clip into a seam. */
+function wholePixels(rect) {
+  const x = Math.floor(rect.x);
+  const y = Math.floor(rect.y);
+  return {
+    x,
+    y,
+    width: Math.ceil(rect.x + rect.width) - x,
+    height: Math.ceil(rect.y + rect.height) - y,
+  };
+}
+
 const EDGE_PROPS = [
   'borderTopColor',
   'borderRightColor',
@@ -354,6 +400,9 @@ class RasterState {
 
   ensure(presenter, width, height, scale) {
     if (!this.surface || this.width !== width || this.height !== height) {
+      // the layer holds its own copy of what it shows, so the bitmap a
+      // resize retires can go now rather than with the handle's finalizer
+      this.release(presenter.native);
       this.surface = presenter.native.createSurface(width, height, scale);
       this.width = width;
       this.height = height;
@@ -369,6 +418,16 @@ class RasterState {
     }
     return this.ctx;
   }
+
+  /** Free the bitmap now (bridge 0.4's `releaseSurface`); older bridges
+   * free it from the handle's finalizer, and this is then just the drop. */
+  release(native) {
+    const surface = this.surface;
+    this.surface = null;
+    if (surface && typeof native.releaseSurface === 'function') {
+      native.releaseSurface(surface);
+    }
+  }
 }
 
 export class CocoaLayerPresenter {
@@ -380,8 +439,14 @@ export class CocoaLayerPresenter {
     this.visuals = new Map(); // node -> Visual
     this.rasters = new Map(); // node -> RasterState
     this.bars = new Map(); // scroller node -> Map(axis -> { layer, raster })
-    this.dirty = new Set();
+    // Claims since the last frame — taken at the top of `frame()`, the way
+    // the X11 path takes its damage before painting, so a claim made from
+    // inside a paint lands in the next frame instead of being cleared with
+    // this one.
+    this.dirty = new Set(); // nodes
+    this.dirtyRects = []; // bare rects, window coordinates
     this.dirtyAll = true; // first frame rasters everything
+    this._claims = null; // the frame in progress: { all, nodes, rects }
     this.rootVisual = {
       layer: window._layer,
     };
@@ -402,12 +467,77 @@ export class CocoaLayerPresenter {
       // say which node that was. Everything re-rasters; a scroll names its
       // node and stays off this path.
       this.dirtyAll = true;
+    } else if (damage.width > 0 && damage.height > 0) {
+      // A bare rect with no layout behind it is a claim about pixels — an
+      // element's `invalidate(false, rect)` for the box a dragged node
+      // moved through, the region `scrollContents` shifts, the strip an
+      // animation ticks in — and it cannot name the node it came from
+      // either. The frame repaints that part of every raster visual whose
+      // ink the rect touches (the same conservative answer the damage model
+      // gives a rect: whatever draws there repaints, clipped to it);
+      // property boxes carry no raster and re-diff every frame regardless.
+      // Copied, because a caller's rect is very often a live `abs` about
+      // to be laid out.
+      if (this.dirtyRects.length >= MAX_DIRTY_RECTS) {
+        this.dirtyAll = true;
+      } else {
+        this.dirtyRects.push({
+          x: damage.x,
+          y: damage.y,
+          width: damage.width,
+          height: damage.height,
+        });
+      }
     }
   }
 
+  /** The claims a frame consumes, cleared for the next one. */
+  _takeClaims() {
+    const claims = {
+      all: this.dirtyAll,
+      nodes: this.dirty,
+      rects: this.dirtyAll ? [] : this.dirtyRects,
+    };
+    this.dirtyAll = false;
+    this.dirty = new Set();
+    this.dirtyRects = [];
+    return claims;
+  }
+
+  /**
+   * What this frame repaints of the raster covering `rect` for `node`: null
+   * for nothing, `FULL_PASS` for all of it, otherwise the window-space rects
+   * the frame's bare claims cover inside it, shaped exactly as the X11 path
+   * shapes its damage list: whole pixels, disjoint, at most a few of them,
+   * and one box instead of several when the several fill most of it —
+   * because a node painted in two overlapping passes blends translucent ink
+   * over itself, and because each pass is a full replay of the node's paint
+   * that only its own culling makes cheap. A pan's shifted region and the
+   * two strips beside it come out as the one pass they are.
+   */
+  _rasterPasses(node, rect, sizeChanged) {
+    const claims = this._claims;
+    if (sizeChanged || !claims || claims.all || claims.nodes.has(node)) {
+      return FULL_PASS;
+    }
+    let passes = null;
+    for (const claimed of claims.rects) {
+      const hit = intersectRects(wholePixels(claimed), rect);
+      if (hit) passes = addDamageRect(passes, hit);
+    }
+    return passes && damageToPaint(passes);
+  }
+
+  /** Does this frame re-raster the visual covering `rect` for `node`? */
+  _needsRaster(node, rect) {
+    return this._rasterPasses(node, rect, false) !== null;
+  }
+
   /** The whole frame: one walk, one transaction, property diffs only. */
   frame(windowNode) {
     const native = this.native;
+    const claims = (this._claims = this._takeClaims());
+    let presented = false;
     native.txBegin({ disableActions: true });
     try {
       this._syncWindowBackground(windowNode);
@@ -417,21 +547,42 @@ export class CocoaLayerPresenter {
         if (!seen.has(node)) {
           visual.destroy();
           this.visuals.delete(node);
-          this.rasters.delete(node);
+          this._dropRaster(node);
           const bars = this.bars.get(node);
           if (bars) {
             for (const entry of bars.values()) {
               native.removeFromSuperlayer(entry.layer);
+              entry.raster.release(native);
             }
             this.bars.delete(node);
           }
         }
       }
+      presented = true;
     } finally {
       native.txCommit();
+      this._claims = null;
+      // a frame that threw half-way presents what it got to; the claims it
+      // was answering are still owed, so the next frame answers them again
+      if (!presented) this._restoreClaims(claims);
     }
-    this.dirty.clear();
-    this.dirtyAll = false;
+  }
+
+  _restoreClaims(claims) {
+    this.dirtyAll ||= claims.all;
+    for (const node of claims.nodes) this.dirty.add(node);
+    if (this.dirtyRects.length + claims.rects.length > MAX_DIRTY_RECTS) {
+      this.dirtyAll = true;
+    } else {
+      this.dirtyRects.push(...claims.rects);
+    }
+  }
+
+  _dropRaster(node) {
+    const raster = this.rasters.get(node);
+    if (!raster) return;
+    raster.release(this.native);
+    this.rasters.delete(node);
   }
 
   _syncWindowBackground(windowNode) {
@@ -460,7 +611,7 @@ export class CocoaLayerPresenter {
     let visual = this.visuals.get(node);
     if (visual && visual.isRaster !== wantsRaster) {
       visual.destroy();
-      this.rasters.delete(node);
+      this._dropRaster(node);
       visual = null;
     }
     if (!visual) {
@@ -590,9 +741,8 @@ export class CocoaLayerPresenter {
     const s = this.scale;
     if (
       !sizeChanged &&
-      !this.dirtyAll &&
-      !this.dirty.has(node) &&
-      visual.shapeSignature
+      visual.shapeSignature &&
+      !this._needsRaster(node, rect)
     ) {
       return true; // shapes are current
     }
@@ -738,13 +888,38 @@ export class CocoaLayerPresenter {
       }
       this._dropSvgShapes(visual);
     }
-    if (!this.dirtyAll && !this.dirty.has(node) && !sizeChanged) return;
+    const passes = this._rasterPasses(node, rect, sizeChanged);
+    if (!passes) return;
     const ctx = raster.ensure(this, rect.width, rect.height, this.window.scale);
+    // The bitmap is this visual's composition cache, the way the window's
+    // backing store is the surface presenter's: a pass over part of it
+    // clears and clips to that part and leaves the rest as last frame drew
+    // it, and `paintDamage()` names the pass, so an element culls a drag
+    // step or an animation tick exactly as it does on X11 (docs/extending.md,
+    // "Drawing a scene into one node") instead of replaying its whole scene
+    // into a clip that throws almost all of it away. The full pass is the
+    // same loop with nothing to clip.
+    const root = node.root;
     ctx.save();
     try {
-      ctx.clearRect(0, 0, rect.width, rect.height);
       ctx.translate(-rect.x, -rect.y);
-      paintSelf(node, ctx);
+      for (const pass of passes) {
+        const area = pass ?? rect;
+        ctx.save();
+        try {
+          if (pass) {
+            ctx.beginPath();
+            ctx.rect(area.x, area.y, area.width, area.height);
+            ctx.clip();
+          }
+          ctx.clearRect(area.x, area.y, area.width, area.height);
+          if (root) root._paintDamage = pass;
+          paintSelf(node, ctx);
+        } finally {
+          if (root) root._paintDamage = null;
+          ctx.restore();
+        }
+      }
     } finally {
       ctx.restore();
     }

package/src/cocoa/surface.js

@@ -0,0 +1,235 @@
+// An offscreen drawing surface on the Cocoa backend — ntk's `Surface`
+// contract (draw once, composite many, and shift a retained band in place)
+// over one @windowkit/appkit CG bitmap. `react-x11/ntk`'s `Surface` hands
+// out one of these when the app it is given is a Cocoa app (the app's
+// `createSurface` seam, src/cocoa/app.js), so a component allocates its
+// buffer the same way on both backends and names neither:
+//
+//   const surface = new Surface(app, { width, height });   // device pixels
+//   const ctx = surface.getContext('2d');                    // a CocoaContext2D
+//   ctx.fillRect(0, 0, width, height);
+//   surface.copyWithin({ x: 0, y: 0, width, height }, 0, -rowHeight);
+//   windowCtx.drawImage(surface, x, y);                      // one composite
+//
+// What is the same as ntk's: the constructor, `width`/`height`/`format`/
+// `depth`/`bytes`, `getContext`, `render`, `clear`, `copyWithin` down to its
+// clamping (ntk#252 — integer deltas, the band that survives, false when
+// nothing does), `destroy`/`Symbol.dispose`, and `drawImage` taking the
+// surface as a source. What differs is stated here, because this is where
+// it lives:
+//
+// - **One graphics state per surface.** CoreGraphics keeps the CTM, the
+//   clip and the path in the bitmap context itself, where an X connection
+//   keeps them per Picture/GC. So `getContext('2d')` answers the same
+//   context every time — a JS object over that one state, nothing to free,
+//   and `destroy()` on it is a no-op — and `render()` brackets its callback
+//   in save/restore from the identity transform, so a one-shot draw leaves
+//   no residue for the next painter, which is what ntk gets from building a
+//   fresh context per call.
+// - **`format: 'a8'` is not here yet.** Coverage surfaces are what the paint
+//   cache's masks and the shadows use, and both stay on their X path; every
+//   consumer that allocates a surface of its own asks for argb32. Asking
+//   for a8 throws rather than answering a colour surface that would
+//   composite differently.
+// - **No Picture.** `picture()` is X's compositing handle; here a surface
+//   composites through `ctx.drawImage`, and asking for the picture says so.
+// - **Freed on `destroy()`.** The bridge's `releaseSurface` (0.4) frees the
+//   bitmap on the call and hands its bytes back to V8's account; the
+//   handle's finalizer stays as the safety net for a surface that is
+//   dropped without one. Under an older bridge the memory goes with the
+//   next GC, as it always did.
+//
+// Units are device pixels, like the window's backing store: a caller sizes
+// one from `contentBox()` numbers, which are device pixels already
+// (docs/scale.md). The bridge is told the app's scale so the bitmap carries
+// it — inert for a `drawImage` source, right for a layer's contents.
+import { CocoaContext2D } from './context2d.js';
+
+export class CocoaSurface {
+  constructor(app, { width, height, format = 'argb32' } = {}) {
+    if (
+      !Number.isInteger(width) ||
+      !Number.isInteger(height) ||
+      width <= 0 ||
+      height <= 0
+    ) {
+      throw new Error('Surface: width and height must be positive integers');
+    }
+    if (format === 'a8') {
+      throw new Error(
+        "Surface: format 'a8' (a coverage surface) is not on the cocoa " +
+          'backend yet — allocate argb32, which every backend has, and ' +
+          'tint through fillStyle/globalAlpha; track docs/macos.md ' +
+          '"Custom drawing on a layer tree".',
+      );
+    }
+    if (format !== 'argb32') {
+      throw new Error(
+        `Surface: unknown format ${JSON.stringify(format)} (argb32 or a8)`,
+      );
+    }
+    this.app = app;
+    this.width = width;
+    this.height = height;
+    this.format = format;
+    this.depth = 32;
+    this._native = app._native;
+    this._fonts = app.fonts ?? null;
+    this._ctx = null;
+    this._destroyed = false;
+    this._surfaceHandle = this._native.createSurface(
+      width,
+      height,
+      app.scale ?? 1,
+    );
+    // a fresh bitmap's contents are the allocator's; a surface that is only
+    // partly drawn must composite nothing where nothing was drawn
+    this.clear();
+  }
+
+  /** bytes of backing storage — what a cache budgets against */
+  get bytes() {
+    return this.width * this.height * 4;
+  }
+
+  /** X's compositing handle, which this backend does not have. */
+  picture() {
+    throw new Error(
+      'Surface: a surface on the cocoa backend has no XRender Picture — ' +
+        'composite it with ctx.drawImage(surface, x, y), which takes a ' +
+        'surface directly on both backends.',
+    );
+  }
+
+  _handle() {
+    if (this._destroyed) {
+      throw new Error(
+        'Surface: destroyed — a context on a destroyed surface cannot ' +
+          'draw; allocate a new Surface and draw into that.',
+      );
+    }
+    return this._surfaceHandle;
+  }
+
+  _context() {
+    if (!this._ctx) {
+      this._ctx = new CocoaContext2D(
+        this._native,
+        () => this._handle(),
+        () => 1,
+      );
+      this._ctx._fonts = this._fonts;
+    }
+    return this._ctx;
+  }
+
+  /**
+   * The 2d context on the bitmap — the same one every time, since the
+   * bitmap has one graphics state (see the header). ntk's contract has the
+   * caller owning it and owing it a `destroy()`; that call is honoured as a
+   * no-op, so a caller written against ntk needs no branch.
+   */
+  getContext(name = '2d') {
+    this._handle();
+    if (name !== '2d') {
+      throw new Error(
+        `Surface: getContext(${JSON.stringify(name)}) — a surface on the ` +
+          "cocoa backend has a '2d' context and nothing else.",
+      );
+    }
+    return this._context();
+  }
+
+  /**
+   * Draw into the surface through a context that starts clean — identity
+   * transform, the fill and line state as they were — and leaves the
+   * surface's state as it found it: the save/restore bracket stands in for
+   * the per-call context ntk builds and destroys.
+   */
+  render(fn) {
+    const ctx = this.getContext('2d');
+    ctx.save();
+    try {
+      ctx.resetTransform();
+      fn(ctx);
+    } finally {
+      ctx.restore();
+    }
+    return this;
+  }
+
+  /** Reset every pixel to fully transparent, whatever transform a live
+   * context holds — the clear is issued from the identity. */
+  clear() {
+    if (this._destroyed) return this;
+    const ctx = this._context();
+    ctx.save();
+    try {
+      ctx.resetTransform();
+      ctx.clearRect(0, 0, this.width, this.height);
+    } finally {
+      ctx.restore();
+    }
+    return this;
+  }
+
+  /**
+   * Scroll the pixels of `src` (surface coordinates, `{x, y, width,
+   * height}`) by (dx, dy) in place: one in-place copy of the band that
+   * survives the shift (the bridge's `scrollSurface`, a memmove per row), in
+   * place of redrawing everything that merely moved. True when the copy was
+   * issued; false means "nothing survives the shift here" and the caller
+   * repaints `src` exactly as it would have without this method.
+   *
+   * ntk#252's contract, clamp for clamp: refused when the delta is
+   * fractional (a sub-pixel shift changes every pixel), when it is zero,
+   * when nothing of `src` survives after clamping to the surface, or on a
+   * destroyed surface. The band is `clamped src ∩ (clamped src + delta)`,
+   * so nothing outside `src` is written; the overlap is safe because the
+   * copy walks rows in the direction that reads before it overwrites.
+   */
+  copyWithin(src, dx, dy) {
+    if (this._destroyed) return false;
+    if (!Number.isInteger(dx) || !Number.isInteger(dy)) return false;
+    if (dx === 0 && dy === 0) return false;
+    const x0 = Math.max(0, Math.floor(src.x));
+    const y0 = Math.max(0, Math.floor(src.y));
+    const x1 = Math.min(this.width, Math.ceil(src.x + src.width));
+    const y1 = Math.min(this.height, Math.ceil(src.y + src.height));
+    const dstX0 = Math.max(x0, x0 + dx);
+    const dstY0 = Math.max(y0, y0 + dy);
+    const dstX1 = Math.min(x1, x1 + dx);
+    const dstY1 = Math.min(y1, y1 + dy);
+    // written as the positive test so a NaN edge (a rect with no numbers
+    // in it) is a refusal too, never a native call with garbage
+    if (!(dstX1 > dstX0 && dstY1 > dstY0)) return false;
+    return Boolean(
+      this._native.scrollSurface(
+        this._surfaceHandle,
+        x0,
+        y0,
+        x1 - x0,
+        y1 - y0,
+        dx,
+        dy,
+      ),
+    );
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    const handle = this._surfaceHandle;
+    this._surfaceHandle = null;
+    this._ctx = null;
+    if (typeof this._native.releaseSurface === 'function') {
+      this._native.releaseSurface(handle);
+    }
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}
+
+export default CocoaSurface;