react-x11 2.13.0 → 2.14.0

package/src/wayland/glcontext.js

@@ -0,0 +1,415 @@
+// Tier D: a GLES rendering context whose frames reach the compositor as
+// dma-buf, with no pixels on the socket and no CPU rasterisation anywhere.
+//
+// The addon this leans on is misnamed by history. `x11-dri`'s `Gpu` is GBM +
+// EGL + GLES on a DRM render node and never touches X — the X part of the
+// package is the *presentation* half, DRI3 and Present, which is exactly the
+// half Wayland replaces. So the accelerated backend costs a swapchain and
+// nothing else; the GL context, the device selection and the buffer export
+// are already there and already shared with the X11 backend.
+//
+// A frame here has three parts, and the middle one is the renderer's:
+//
+//   beginFrame()   bind the backing target at the window's buffer size
+//   …the 2d context paints into it, partially, as it would into a pixmap…
+//   endFrame()     copy what changed into the swapchain buffer, swap, and
+//                  commit — with the configure ack and the frame request in
+//                  that same commit
+//
+// The backing target (target.js) is what makes partial repaints correct on a
+// rotating swapchain; see swapchain.js for why the copy is sized the way it
+// is. It also means the window's EGL config needs no stencil bits of its own
+// — the target carries them — though they are still requested, cheaply, for
+// anything that draws straight at the swapchain (a `<glarea>`).
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { WaylandSwapchain } from './swapchain.js';
+import { GLTarget } from './target.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * One GPU context per pixel format, not one per surface.
+ *
+ * An EGL context is expensive — a device, a GBM device, a display, a config
+ * scan — and every surface in an app wants the same one; sharing it also
+ * means textures and programs are shared between surfaces, as they are
+ * between canvases in a browser tab. The cost is that exactly one surface is
+ * current at a time, which `beginFrame` takes care of.
+ *
+ * Kept per x11-dri module, which is one object in practice and a fresh fake
+ * in each test.
+ */
+const gpuCaches = new WeakMap();
+
+function cacheFor(dri) {
+  let cache = gpuCaches.get(dri);
+  if (!cache) gpuCaches.set(dri, (cache = new Map()));
+  return cache;
+}
+
+/** `/dev/dri/card*`, in numeric order. */
+export function listCardNodes(readdir = fs.readdirSync) {
+  let names;
+  try {
+    names = readdir('/dev/dri');
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => /^card(\d+)$/.exec(name))
+    .filter(Boolean)
+    .sort((a, b) => Number(a[1]) - Number(b[1]))
+    .map((m) => `/dev/dri/${m[0]}`);
+}
+
+/**
+ * The DRM nodes to try for the shared context, in order; `undefined` is
+ * x11-dri's own choice, the first render node.
+ *
+ * A named device is the only one tried: asking for a device and getting
+ * another would be a worse surprise than the error. Otherwise the render
+ * node, as ever. A machine with no render node at all — a GitHub-hosted
+ * runner, a Hyper-V or VirtualBox guest — can still have a card node Mesa
+ * renders on in software, through kms_swrast, so those are tried in turn.
+ * With neither, x11-dri's default once more, so its own reason is the one
+ * reported.
+ */
+export function gpuCandidates({ requested, renderNodes, cardNodes }) {
+  if (requested) return [requested];
+  if (renderNodes.length) return [undefined];
+  return cardNodes.length ? cardNodes : [undefined];
+}
+
+function requireDri() {
+  try {
+    return require('x11-dri');
+  } catch (err) {
+    throw new Error(
+      'the accelerated backend needs the optional x11-dri addon, which is not installed',
+      { cause: err },
+    );
+  }
+}
+
+/**
+ * The GPU context for a pixel format, made once and shared.
+ *
+ * The device is `devicePath` (`glPolicy.devicePath`), else
+ * `REACT_X11_GL_DEVICE`, else whatever {@link gpuCandidates} finds. The
+ * cache is keyed by what was asked for rather than what was found, so the
+ * app's context and every window's resolve to the same one.
+ *
+ * @param {object} [seams] for the tests: the environment, and the card nodes
+ */
+export function sharedGpu(
+  dri,
+  { format, depthSize, stencilSize, devicePath },
+  { env = process.env, cardNodes = listCardNodes } = {},
+) {
+  const requested = devicePath || env.REACT_X11_GL_DEVICE || null;
+  const cache = cacheFor(dri);
+  const key = `${format}|${depthSize}|${stencilSize}|${requested ?? ''}`;
+  const existing = cache.get(key);
+  if (existing) return existing;
+  const candidates = gpuCandidates({
+    requested,
+    renderNodes: requested ? [] : dri.listRenderNodes(),
+    cardNodes: requested ? [] : cardNodes(),
+  });
+  const failures = [];
+  for (const path of candidates) {
+    try {
+      const gpu = new dri.Gpu({
+        format,
+        depthSize,
+        stencilSize,
+        ...(path ? { devicePath: path } : {}),
+      });
+      cache.set(key, gpu);
+      return gpu;
+    } catch (err) {
+      failures.push({ path, err });
+    }
+  }
+  const tried = failures
+    .map(
+      ({ path, err }) => `${path ?? 'the default render node'}: ${err.message}`,
+    )
+    .join('; ');
+  throw new Error(`could not create a GPU context on ${tried}`, {
+    cause: failures.at(-1).err,
+  });
+}
+
+export class WaylandGLContext {
+  /**
+   * Build the context with nothing to await.
+   *
+   * Only `zwp_linux_dmabuf_v1` had to be bound asynchronously, and an app
+   * binds it once at startup; the GPU context itself never needed the
+   * compositor. React's commit phase cannot await, and that is where windows
+   * are made.
+   */
+  static createSync({ conn, window, dmabuf, policy = {} }) {
+    const dri = requireDri();
+    const probe = dri.probe();
+    if (probe.gbm !== true || probe.egl !== true || probe.gles !== true) {
+      throw new Error(
+        `this machine cannot render on the GPU: gbm=${probe.gbm}, egl=${probe.egl}, gles=${probe.gles}`,
+      );
+    }
+    if (!dmabuf) {
+      throw new Error(
+        'this compositor does not advertise zwp_linux_dmabuf_v1, so GPU buffers cannot be handed to it',
+      );
+    }
+    // Alpha by default: client-side decorations want rounded corners, and a
+    // fully opaque window says so with `set_opaque_region` instead, which is
+    // the cheaper signal anyway.
+    const alpha = policy.alpha ?? true;
+    const format = alpha ? dri.FORMAT.ARGB8888 : dri.FORMAT.XRGB8888;
+    const gpu = sharedGpu(dri, {
+      format,
+      depthSize: policy.depthSize ?? 16,
+      stencilSize: policy.stencilSize ?? 8,
+      devicePath: policy.devicePath,
+    });
+    const chain = new WaylandSwapchain({
+      surface: window.surface,
+      dmabuf,
+      gpu,
+      dri,
+      format,
+      policy,
+    });
+    return new WaylandGLContext({
+      conn,
+      window,
+      dri,
+      gpu,
+      chain,
+      format,
+      policy,
+    });
+  }
+
+  /** The asynchronous form, for scripts that are not inside a React commit. */
+  static async create({ conn, window, policy = {} }) {
+    const dmabuf = await conn.bind('zwp_linux_dmabuf_v1');
+    return WaylandGLContext.createSync({ conn, window, dmabuf, policy });
+  }
+
+  constructor({ conn, window, dri, gpu, chain, format, policy = {} }) {
+    this.conn = conn;
+    this.window = window;
+    this.dri = dri;
+    this.gpu = gpu;
+    this.chain = chain;
+    this.format = format;
+    this.policy = policy;
+    /** The GL entry points — WebGL-shaped and camelCase. */
+    this.gl = gpu.gl;
+    this.destroyed = false;
+    /** the persistent pixels the renderer paints into */
+    this.backing = null;
+    this._surface = null;
+    this._inFrame = false;
+    this.lastFramePresented = false;
+
+    chain.onError = (err) => {
+      this.destroyed = true;
+      window.emit('error', err);
+    };
+  }
+
+  /** What the driver actually gave us, which can exceed what was asked for. */
+  get glVersion() {
+    return this.gpu.glVersion;
+  }
+
+  get features() {
+    return this.gpu.features;
+  }
+
+  get width() {
+    return this.backing?.width ?? 0;
+  }
+
+  get height() {
+    return this.backing?.height ?? 0;
+  }
+
+  /**
+   * Make the context current, size the swapchain and the backing target to
+   * the window's buffer size, and bind the target for drawing.
+   *
+   * The size is taken from the window rather than passed in because the
+   * compositor owns it: a configure may have landed between two frames, and
+   * drawing at the old size would produce a buffer the compositor stretches.
+   *
+   * @returns {{width:number, height:number, resized:boolean}|null}
+   */
+  beginFrame() {
+    if (this.destroyed) return null;
+    const w = this.window.bufferWidth;
+    const h = this.window.bufferHeight;
+    const surface = this.chain.surfaceFor(w, h);
+    this._surface = surface;
+    this.gpu.makeCurrent(surface);
+    let resized = false;
+    if (!this.backing) {
+      this.backing = new GLTarget(this.gl, {
+        width: w,
+        height: h,
+        stencil: true,
+      });
+      resized = true;
+    } else if (this.backing.width !== w || this.backing.height !== h) {
+      // Contents are dropped: a resize relayouts and repaints everything
+      // upstairs (listeners.js: `invalidate(true, null, 'resize')`).
+      this.backing.resize(w, h);
+      resized = true;
+    }
+    this.backing.bind();
+    this._inFrame = true;
+    return { width: w, height: h, resized };
+  }
+
+  /**
+   * Route GL draws at the backing target again — for a `<glarea>` that bound
+   * its own framebuffer in between, or anything else that touched the
+   * binding.
+   */
+  bindBacking() {
+    this.backing?.bind();
+  }
+
+  /**
+   * Finish the frame, hand it over, and hand back the frame clock.
+   *
+   * Pacing is owned here rather than by the caller because the two have to be
+   * atomic and the failure is silent if they are not. A `wl_surface.frame`
+   * request is only *delivered* by a commit, so a loop that asks for the
+   * callback and then discovers it has nothing to present — every buffer
+   * still held by the compositor, which is a normal thing to happen — waits
+   * forever on a callback the compositor was never told to schedule. That
+   * deadlock is what this method exists to make unrepresentable: the request
+   * goes out with the commit, and when there is no frame to show, an empty
+   * commit delivers it anyway so the clock keeps ticking and the next frame
+   * gets its turn.
+   *
+   * @param {Array<{x,y,width,height}>|'all'} [damage] what the frame changed,
+   *   in buffer coordinates. Defaults to everything.
+   * @returns {Promise<number>} the frame callback's timestamp, once the
+   *   compositor says it is time to draw again. An async function cannot
+   *   hand back a promise unsettled — returning `vsync` makes the caller's
+   *   `await` wait for it — which is what keeps one present in flight in
+   *   `_present`, and why a connection closing mid-frame rejects there.
+   */
+  async endFrame(damage = 'all') {
+    // Always a promise for the frame clock, even when there is no frame:
+    // callers chain off it unconditionally.
+    if (this.destroyed || !this._inFrame)
+      return Promise.resolve(Promise.resolve(0));
+    this._inFrame = false;
+    const gl = this.gl;
+    const win = this.window;
+
+    // The copy: backing -> the swapchain's back buffer, sized by what the
+    // next buffer might be missing. Then the GPU work is settled (optionally
+    // through a fence rather than a stall) before the swap hands it over.
+    const rects = this.chain.blitHint(damage);
+    this.backing.blitTo(
+      null,
+      rects === 'all' ? null : rects,
+      this.chain.width,
+      this.chain.height,
+    );
+    await this._settleGpu();
+
+    // Queued before anything that commits, so one commit carries the frame
+    // request, the configure ack, and the buffer.
+    const vsync = win.scheduleFrame();
+    win.ackPending();
+    // Another window's frame may have run in the await above and made its
+    // own surface current. eglSwapBuffers on a surface that is not current
+    // is EGL_BAD_SURFACE (0x300d): the second window of examples/windows.jsx.
+    this.gpu.makeCurrent(this._surface);
+    const presented = await this.chain.swap(damage);
+    // `swap` attached and damaged but did not commit; and when nothing went
+    // out — every buffer busy — the frame request still needs a commit to be
+    // delivered. Either way, exactly one commit.
+    if (!this.destroyed) win.surface.$.commit();
+    if (presented) win.mapped = true;
+    this.lastFramePresented = presented;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    return vsync;
+  }
+
+  /**
+   * Wait for the GPU to finish this frame *without* blocking the thread.
+   *
+   * `eglSwapBuffers` inside `Surface.swap()` waits for the frame's commands
+   * to complete, and that wait is a hard stall of the JS thread — measured at
+   * ~10ms per frame on this machine's virtio-gpu, and size-independent, so it
+   * is round-trip latency to the host rather than fill rate. A stalled thread
+   * is a thread not reading input or protocol events.
+   *
+   * A fence turns that stall into something the event loop can interleave
+   * with: signal after the draw commands, then poll with a zero timeout,
+   * yielding between polls so input and Wayland events get their turn. The
+   * work takes just as long — this trades a blocked thread for a busy one
+   * (measured: −0.9% frame rate) — so it is off by default and
+   * `glPolicy: { fence: true }` turns it on where responsiveness matters more
+   * than a core.
+   */
+  async _settleGpu() {
+    if (!this.policy?.fence) return;
+    const gl = this.gl;
+    if (!this.gpu.features?.sync) return;
+    let sync;
+    try {
+      sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    } catch {
+      return;
+    }
+    if (!sync) return;
+    gl.flush();
+    try {
+      for (let spins = 0; spins < 10000; spins++) {
+        const r = gl.clientWaitSync(sync, 0, 0);
+        if (r === gl.ALREADY_SIGNALED || r === gl.CONDITION_SATISFIED) return;
+        if (r !== gl.TIMEOUT_EXPIRED) return;
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+    } finally {
+      gl.deleteSync(sync);
+    }
+  }
+
+  canRender() {
+    return this.chain.canRender();
+  }
+
+  set onReady(fn) {
+    this.chain.onReady = fn;
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this._surface) {
+      try {
+        this.gpu.makeCurrent(this._surface);
+        this.backing?.destroy();
+      } catch {
+        /* context already gone */
+      }
+    }
+    this.backing = null;
+    this.chain.destroy();
+    // The Gpu is shared; it outlives any one context.
+  }
+}

package/src/wayland/glyphatlas.js

@@ -0,0 +1,237 @@
+// The client-side glyph cache — the thing XRender's `GlyphSet` used to be.
+//
+// On X11 a glyph is uploaded once into a server-resident glyph set and then
+// named by id in a `CompositeGlyphs` request; the server owns the pixels and
+// the client never sees them again. There is no such thing here. A Wayland
+// client rasterises its own glyphs and composites them itself, so the cache
+// has to live on this side of the socket — and for Tier D specifically, in
+// GPU memory, as a texture that quads sample from.
+//
+// The rasteriser is ntk's own (`Font.rasterize` -> A8 coverage), which is the
+// part of the text stack most worth keeping: shaping, bidi and line breaking
+// stay exactly as they are on X11, and only the final composite changes.
+//
+// Packing is a shelf: glyphs arrive in no useful order and are never freed
+// individually, so the classic row-by-row placement wastes little and costs
+// nothing to maintain. When a shelf will not take the glyph the atlas grows
+// by doubling, which invalidates every entry — the context is told first, so
+// quads already buffered against the old layout are drawn before it changes
+// under them (see `onBeforeGrow`).
+//
+// Uploads are deferred and partial: new glyphs land in a CPU copy and the
+// dirty rectangle goes up with one `texSubImage2D` when the texture is next
+// bound. The first version of this file re-uploaded the whole atlas per new
+// glyph, which at 4096² is 16MB per character of a paragraph's first paint.
+
+const INITIAL_SIZE = 512;
+const MAX_SIZE = 4096;
+/** Keep glyphs from bleeding into each other under linear filtering. */
+const PAD = 1;
+
+export class GlyphAtlas {
+  constructor(gl, { size = INITIAL_SIZE } = {}) {
+    this.gl = gl;
+    this.size = size;
+    /** key -> { x, y, w, h, left, top, u0, v0, u1, v1 } */
+    this.entries = new Map();
+    this._shelfY = PAD;
+    this._shelfH = 0;
+    this._shelfX = PAD;
+    this._pixels = new Uint8Array(size * size);
+    this.texture = null;
+    /** dirty rectangle of the CPU copy not yet uploaded, or null */
+    this._dirty = null;
+    this._fresh = true; // the GPU texture needs a full upload
+    this.generation = 0;
+    /** called before the atlas grows, so pending quads can be flushed */
+    this.onBeforeGrow = null;
+  }
+
+  /**
+   * Find or make room for one rasterised glyph.
+   *
+   * @param {string} key identifies the glyph *and* the size it was rasterised
+   *   at — a 12px 'a' and a 24px 'a' are different pixels and share nothing.
+   * @param {() => {width,height,left,top,data}} raster called only on a miss,
+   *   so a hit never touches the font machinery
+   */
+  get(key, raster) {
+    const hit = this.entries.get(key);
+    if (hit) return hit;
+
+    const g = raster();
+    // A space has no ink. Cache the absence so the miss is paid once.
+    if (!g || g.width <= 0 || g.height <= 0) {
+      const empty = { empty: true, left: g?.left ?? 0, top: g?.top ?? 0 };
+      this.entries.set(key, empty);
+      return empty;
+    }
+
+    const spot = this._place(g.width, g.height);
+    if (!spot) return { empty: true, left: g.left, top: g.top };
+
+    for (let row = 0; row < g.height; row++) {
+      const src = row * g.width;
+      const dst = (spot.y + row) * this.size + spot.x;
+      this._pixels.set(g.data.subarray(src, src + g.width), dst);
+    }
+    this._markDirty(spot.x, spot.y, g.width, g.height);
+
+    const inv = 1 / this.size;
+    const entry = {
+      empty: false,
+      x: spot.x,
+      y: spot.y,
+      w: g.width,
+      h: g.height,
+      left: g.left,
+      top: g.top,
+      u0: spot.x * inv,
+      v0: spot.y * inv,
+      u1: (spot.x + g.width) * inv,
+      v1: (spot.y + g.height) * inv,
+    };
+    this.entries.set(key, entry);
+    return entry;
+  }
+
+  _markDirty(x, y, w, h) {
+    const d = this._dirty;
+    if (!d) {
+      this._dirty = { x0: x, y0: y, x1: x + w, y1: y + h };
+      return;
+    }
+    d.x0 = Math.min(d.x0, x);
+    d.y0 = Math.min(d.y0, y);
+    d.x1 = Math.max(d.x1, x + w);
+    d.y1 = Math.max(d.y1, y + h);
+  }
+
+  _place(w, h) {
+    if (w + PAD * 2 > this.size || h + PAD * 2 > this.size) {
+      return this._grow() ? this._place(w, h) : null;
+    }
+    if (this._shelfX + w + PAD > this.size) {
+      this._shelfY += this._shelfH + PAD;
+      this._shelfH = 0;
+      this._shelfX = PAD;
+    }
+    if (this._shelfY + h + PAD > this.size) {
+      return this._grow() ? this._place(w, h) : null;
+    }
+    const spot = { x: this._shelfX, y: this._shelfY };
+    this._shelfX += w + PAD;
+    if (h > this._shelfH) this._shelfH = h;
+    return spot;
+  }
+
+  /**
+   * Double the atlas and start over.
+   *
+   * Entries are dropped rather than copied: they only remember where their
+   * pixels went, and a repack at this frequency is not worth keeping a second
+   * copy of every glyph. Anyone holding an entry across this call has a
+   * stale one, which is why `onBeforeGrow` exists.
+   */
+  _grow() {
+    if (this.size >= MAX_SIZE) return false;
+    this.onBeforeGrow?.();
+    this.size *= 2;
+    this._pixels = new Uint8Array(this.size * this.size);
+    this.entries.clear();
+    this._shelfX = PAD;
+    this._shelfY = PAD;
+    this._shelfH = 0;
+    this._dirty = null;
+    this._fresh = true;
+    this.generation++;
+    if (this.texture) {
+      this.gl.deleteTexture(this.texture);
+      this.texture = null;
+    }
+    return true;
+  }
+
+  /**
+   * Forget every entry, keeping the texture and its size — for an atlas of
+   * transient masks, emptied at the start of each frame. Old pixels stay in
+   * the CPU copy until new entries overwrite them; nothing names them.
+   */
+  reset() {
+    if (this.entries.size === 0) return;
+    this.entries.clear();
+    this._shelfX = PAD;
+    this._shelfY = PAD;
+    this._shelfH = 0;
+    this._dirty = null;
+    this.generation++;
+  }
+
+  /** Make the atlas current on the active texture unit, uploading anything new. */
+  bind() {
+    const gl = this.gl;
+    if (!this.texture) {
+      this.texture = gl.createTexture();
+      gl.bindTexture(gl.TEXTURE_2D, this.texture);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      this._fresh = true;
+    } else {
+      gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    }
+    // One byte of coverage per texel, as R8 — GLES 3's own single-channel
+    // format — rather than the legacy ALPHA, which drivers emulate. On
+    // virgl the emulation let an upload into the mask atlas reach what the
+    // glyph atlas sampled: text drawn after a frame's coverage masks showed
+    // pieces of them (a select's chevron where a title's "R" belonged).
+    // A8 rows are tightly packed and almost never a multiple of 4.
+    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+    if (this._fresh) {
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.R8,
+        this.size,
+        this.size,
+        0,
+        gl.RED,
+        gl.UNSIGNED_BYTE,
+        this._pixels,
+      );
+      this._fresh = false;
+      this._dirty = null;
+    } else if (this._dirty) {
+      const { x0, y0, x1, y1 } = this._dirty;
+      const w = x1 - x0;
+      const h = y1 - y0;
+      // texSubImage2D wants the rows contiguous; a sub-rectangle of the CPU
+      // copy is not, so gather them. Small — a frame's worth of new glyphs.
+      const rows = new Uint8Array(w * h);
+      for (let r = 0; r < h; r++) {
+        const src = (y0 + r) * this.size + x0;
+        rows.set(this._pixels.subarray(src, src + w), r * w);
+      }
+      gl.texSubImage2D(
+        gl.TEXTURE_2D,
+        0,
+        x0,
+        y0,
+        w,
+        h,
+        gl.RED,
+        gl.UNSIGNED_BYTE,
+        rows,
+      );
+      this._dirty = null;
+    }
+    return this.texture;
+  }
+
+  destroy() {
+    if (this.texture) this.gl.deleteTexture(this.texture);
+    this.texture = null;
+    this.entries.clear();
+  }
+}