react-x11 2.13.0 → 2.15.0

package/src/wayland/shm.js

@@ -0,0 +1,226 @@
+// Shared-memory buffers: the CPU path to a `wl_buffer`, beside the dma-buf
+// one the swapchain takes.
+//
+// Not for frames — every window frame here is a dma-buf and no pixel crosses
+// the socket — but a screen capture has to land somewhere the client can
+// read, and a compositor fills a `wl_shm` buffer, which is memory both sides
+// map. On this side "map" is the problem: neither Node nor Bun has mmap. What
+// both have is pread/pwrite on a descriptor, and a pool's memory *is* a file
+// — a memfd (x11-dri's `memfdCreate`), or without the addon an unlinked file
+// under /dev/shm — so the pixels are read back with `fs.readSync` from offset
+// 0 once the compositor says the frame is ready. That is one copy of one
+// screen on a path nobody runs per frame; the mmap it stands in for would
+// have saved it and cost a native binding.
+//
+// Two descriptors per pool, on purpose. The transport closes a descriptor it
+// has sent — `wl_shm.create_pool` hands ownership to the compositor — so the
+// one that goes on the wire is a dup and the original stays ours.
+//
+// Pixel layouts are the DRM fourcc ones `wl_shm.format` names: a packed
+// little-endian 32-bit word, so `XRGB8888` is the bytes B, G, R, X in memory
+// and `XBGR8888` is R, G, B, X. This machine is little-endian, as is every
+// machine a Wayland compositor has shipped on.
+
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { closeFd } from './fdutil.js';
+
+const require = createRequire(import.meta.url);
+
+/** The `wl_shm.format` values this file reads and writes. */
+export const SHM_FORMAT = {
+  ARGB8888: 0,
+  XRGB8888: 1,
+  XBGR8888: 0x34324258,
+  ABGR8888: 0x34324241,
+};
+
+const BGRX = new Set([SHM_FORMAT.ARGB8888, SHM_FORMAT.XRGB8888]);
+const RGBX = new Set([SHM_FORMAT.XBGR8888, SHM_FORMAT.ABGR8888]);
+const WITH_ALPHA = new Set([SHM_FORMAT.ARGB8888, SHM_FORMAT.ABGR8888]);
+
+export function isSupportedShmFormat(format) {
+  return BGRX.has(format) || RGBX.has(format);
+}
+
+/**
+ * Shared memory of `size` bytes, as two descriptors on the same pages: `fd`
+ * to keep, `wire` to give to the compositor.
+ *
+ * @returns {{ fd: number, wire: number, size: number }}
+ */
+export function openSharedMemory(size, name = 'react-x11') {
+  try {
+    const dri = require('x11-dri');
+    if (
+      typeof dri.memfdCreate === 'function' &&
+      typeof dri.dup === 'function'
+    ) {
+      const fd = dri.memfdCreate(size, name);
+      return { fd, wire: dri.dup(fd), size };
+    }
+  } catch {
+    /* the addon is optional; the file below works without it */
+  }
+  // A file both ends open, gone from the namespace the moment both have.
+  const path = `/dev/shm/${name}-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  const { O_RDWR, O_CREAT, O_EXCL } = fs.constants;
+  const fd = fs.openSync(path, O_RDWR | O_CREAT | O_EXCL, 0o600);
+  let wire = -1;
+  try {
+    fs.ftruncateSync(fd, size);
+    wire = fs.openSync(path, O_RDWR);
+    return { fd, wire, size };
+  } catch (err) {
+    closeFd(fd);
+    throw err;
+  } finally {
+    try {
+      fs.unlinkSync(path);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+export class ShmBuffer extends EventEmitter {
+  /**
+   * A pool holding exactly one buffer.
+   *
+   * @param {object} opts
+   * @param {object} opts.shm the `wl_shm` proxy
+   * @param {number} opts.width in pixels
+   * @param {number} opts.height
+   * @param {number} [opts.stride=width*4] bytes per row
+   * @param {number} [opts.format=SHM_FORMAT.XRGB8888]
+   * @param {string} [opts.name] what the memfd is called in /proc
+   */
+  constructor({
+    shm,
+    width,
+    height,
+    stride = width * 4,
+    format = SHM_FORMAT.XRGB8888,
+    name = 'react-x11-shm',
+  }) {
+    super();
+    this.width = width;
+    this.height = height;
+    this.stride = stride;
+    this.format = format;
+    this.size = stride * height;
+    const mem = openSharedMemory(this.size, name);
+    this.fd = mem.fd;
+    this.pool = shm.$.create_pool(mem.wire, this.size);
+    /** the `wl_buffer` proxy */
+    this.buffer = this.pool.$.create_buffer(0, width, height, stride, format);
+    this.destroyed = false;
+    this.buffer.on('release', () => this.emit('release'));
+  }
+
+  /** Everything in the pool, read back. */
+  read() {
+    const out = Buffer.allocUnsafe(this.size);
+    let off = 0;
+    while (off < this.size) {
+      const n = fs.readSync(this.fd, out, off, this.size - off, off);
+      if (n <= 0) break;
+      off += n;
+    }
+    return out;
+  }
+
+  /** Overwrite the pool from offset 0. */
+  write(bytes) {
+    let off = 0;
+    while (off < bytes.length) {
+      off += fs.writeSync(this.fd, bytes, off, bytes.length - off, off);
+    }
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    try {
+      this.buffer.$.destroy();
+      this.pool.$.destroy();
+    } catch {
+      /* connection gone */
+    }
+    closeFd(this.fd);
+  }
+}
+
+/**
+ * One pixel of a pool, as 0–255 channels.
+ *
+ * @param {Buffer|Uint8Array} bytes the pool's contents
+ * @param {{ stride:number, format:number }} layout
+ */
+export function shmPixel(bytes, { stride, format }, x, y) {
+  const o = y * stride + x * 4;
+  if (BGRX.has(format)) {
+    return { r: bytes[o + 2], g: bytes[o + 1], b: bytes[o] };
+  }
+  if (RGBX.has(format)) {
+    return { r: bytes[o], g: bytes[o + 1], b: bytes[o + 2] };
+  }
+  throw new Error(`unsupported wl_shm format 0x${format.toString(16)}`);
+}
+
+/**
+ * A pool's contents as straight RGBA, top row first — the shape
+ * `readback.js`'s `encodePNG` takes.
+ *
+ * @param {object} frame
+ * @param {Buffer|Uint8Array} frame.bytes
+ * @param {boolean} [frame.yInvert] the rows are bottom-up (screencopy's flag)
+ */
+export function shmToRGBA({
+  bytes,
+  width,
+  height,
+  stride,
+  format,
+  yInvert = false,
+}) {
+  if (!isSupportedShmFormat(format)) {
+    throw new Error(`unsupported wl_shm format 0x${format.toString(16)}`);
+  }
+  const swap = BGRX.has(format);
+  const alpha = WITH_ALPHA.has(format);
+  const data = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const src = (yInvert ? height - 1 - y : y) * stride;
+    const dst = y * width * 4;
+    for (let x = 0; x < width; x++) {
+      const s = src + x * 4;
+      const d = dst + x * 4;
+      if (swap) {
+        data[d] = bytes[s + 2];
+        data[d + 1] = bytes[s + 1];
+        data[d + 2] = bytes[s];
+      } else {
+        data[d] = bytes[s];
+        data[d + 1] = bytes[s + 1];
+        data[d + 2] = bytes[s + 2];
+      }
+      data[d + 3] = alpha ? bytes[s + 3] : 255;
+    }
+  }
+  return { width, height, data };
+}
+
+/** Reverse the row order in place: a y-inverted frame the right way up. */
+export function flipRows(bytes, stride, height) {
+  const tmp = Buffer.allocUnsafe(stride);
+  for (let y = 0; y < height >> 1; y++) {
+    const a = y * stride;
+    const b = (height - 1 - y) * stride;
+    bytes.copy(tmp, 0, a, a + stride);
+    bytes.copy(bytes, a, b, b + stride);
+    tmp.copy(bytes, b, 0, stride);
+  }
+  return bytes;
+}

package/src/wayland/ssd.js

@@ -0,0 +1,234 @@
+// Server-side decorations: asking the compositor to draw the frame, and
+// falling back to drawing it ourselves only when nothing will.
+//
+// The compositor may draw the frame — wlroots compositors and KDE do, when
+// asked, and GNOME does not advertise the protocol at all — so "who draws the
+// titlebar" is negotiated per toplevel. The client creates a decoration
+// object *before the toplevel's first commit* and says which mode it would
+// prefer; the compositor answers with `configure(mode)`, which is part of
+// the surface's configure sequence and takes effect on the same ack as the
+// size and states it arrived with. A client prefers, it never insists: sway
+// grants server_side, and a compositor that will not draw frames answers
+// client_side — which is the state the backend was already in, so
+// `decorations.js` stays and is switched off rather than removed.
+//
+// ## Two protocols say the same thing
+//
+// `xdg-decoration-unstable-v1` is the one to ask with, and where it is
+// offered it is the only one used. But it arrived late (2018) and KDE had
+// shipped `org_kde_kwin_server_decoration` years before, so a compositor may
+// advertise only the older one — KWin still carries both, and a handful of
+// smaller compositors never picked up the xdg protocol. Asking with whatever
+// is there is the difference between a real titlebar and an imitation, so
+// `createServerDecoration` tries them in that order and only gives up on
+// server-side when neither global exists.
+//
+// The KDE protocol is the same conversation in different words: it hangs off
+// the `wl_surface` rather than the `xdg_toplevel`, its enum has a third value
+// (`none`, no frame at all), its destructor is `release`, and — the one
+// difference that matters — its `mode` event is not part of a configure
+// sequence. Nothing promises a configure will follow it, so that driver
+// flushes itself (`flushesOutsideConfigure`); the xdg one keeps the stricter
+// discipline below.
+//
+// The mode is adopted, not applied on arrival, for the reason the configure
+// ack is deferred (window.js): a mode change is a size change — the surface
+// loses or gains its own titlebar — and the frame that adopts it has to be
+// painted at the new insets. `adopt()` runs from the xdg_surface.configure
+// handler, so a window hears 'decorationmode' before it hears 'configure'.
+
+import { EventEmitter } from 'node:events';
+
+/** `zxdg_toplevel_decoration_v1.mode`. */
+export const DECORATION_MODE = { CLIENT_SIDE: 1, SERVER_SIDE: 2 };
+
+/**
+ * `org_kde_kwin_server_decoration.mode`. The two that overlap with
+ * xdg-decoration share its numbering; `NONE` — no frame from either side —
+ * has no xdg equivalent and is only ever received, never asked for. A window
+ * that wants no frame asks for `CLIENT` and then draws nothing, which is the
+ * same picture and one less thing for `decorationPolicy` to express.
+ */
+export const KDE_DECORATION_MODE = { NONE: 0, CLIENT: 1, SERVER: 2 };
+
+/**
+ * What `decorations` means, at the app (`createRoot({ decorations })`) and
+ * per window (`<window decorations={false}>`, the one value the tree passes):
+ *
+ *   undefined | true | 'server'  a frame — the compositor's where it offers
+ *                                one, this backend's own otherwise
+ *   'client'                     a frame, always this backend's own
+ *   false                        no frame at all
+ *
+ * The per-window `false` wins over whatever the app said. A window with no
+ * frame still gets a decoration object when the compositor has the protocol,
+ * to *decline* server-side: sway frames every toplevel that has not said
+ * client_side, and a frameless window would come up with a title bar.
+ *
+ * @returns {{ draw: boolean, prefer: 'server'|'client' }} whether the window
+ *   wants a frame at all, and which side should draw it if so
+ */
+export function decorationPolicy(appOption, windowOption) {
+  const draw = appOption !== false && windowOption !== false;
+  const prefer = draw && appOption !== 'client' ? 'server' : 'client';
+  return { draw, prefer };
+}
+
+/**
+ * What both protocols have in common: a mode that arrives from the
+ * compositor, is held until the frame that can paint it adopts it, and an
+ * object that has to be destroyed before the thing it decorates.
+ */
+class Decoration extends EventEmitter {
+  constructor() {
+    super();
+    /** the mode in effect: 'server' | 'client', null before the first answer */
+    this.mode = null;
+    /** a mode the compositor sent that the next configure adopts */
+    this.pending = null;
+    this.destroyed = false;
+  }
+
+  /**
+   * Whether an answer can arrive with no configure behind it, in which case
+   * whoever owns this has to flush it rather than wait (window.js). False
+   * for xdg-decoration, whose mode is part of the configure sequence.
+   */
+  get flushesOutsideConfigure() {
+    return false;
+  }
+
+  /** The compositor's answer, held until `adopt()`. */
+  _answer(mode) {
+    this.pending = mode;
+    if (this.flushesOutsideConfigure) this.emit('pending');
+  }
+
+  /**
+   * Adopt the pending mode, if there is one.
+   *
+   * @returns {boolean} whether the mode in effect changed
+   */
+  adopt() {
+    if (this.pending == null) return false;
+    const changed = this.pending !== this.mode;
+    this.mode = this.pending;
+    this.pending = null;
+    if (changed) this.emit('mode', this.mode);
+    return changed;
+  }
+
+  /** Before the toplevel: destroying them the other way round is a protocol error. */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    try {
+      this._release();
+    } catch {
+      /* the connection may already be gone */
+    }
+  }
+}
+
+export class ServerDecoration extends Decoration {
+  /**
+   * Create the decoration object and state a preference. Must run before
+   * the toplevel's first commit; `WaylandWindow.createSync` calls it there.
+   *
+   * @param {object} opts
+   * @param {object} opts.manager the `zxdg_decoration_manager_v1` proxy
+   * @param {object} opts.toplevel the `xdg_toplevel` proxy
+   * @param {'server'|'client'} [opts.prefer='server']
+   */
+  constructor({ manager, toplevel, prefer = 'server' }) {
+    super();
+    this.proxy = manager.$.get_toplevel_decoration(toplevel.id);
+    this.proxy.on('configure', (mode) => {
+      this._answer(mode === DECORATION_MODE.SERVER_SIDE ? 'server' : 'client');
+    });
+    this.prefer(prefer);
+  }
+
+  /** State (or restate) the preference; the compositor answers with a configure. */
+  prefer(prefer) {
+    if (this.destroyed) return;
+    this.proxy.$.set_mode(
+      prefer === 'client'
+        ? DECORATION_MODE.CLIENT_SIDE
+        : DECORATION_MODE.SERVER_SIDE,
+    );
+  }
+
+  _release() {
+    this.proxy.$.destroy();
+  }
+}
+
+/**
+ * The same conversation over `org_kde_kwin_server_decoration`, for the
+ * compositors that have only that one. It decorates the `wl_surface`, so it
+ * is created from the surface rather than the toplevel — but the ordering
+ * rule is the toplevel's all the same, since that is what carries the frame.
+ */
+export class KdeServerDecoration extends Decoration {
+  /**
+   * @param {object} opts
+   * @param {object} opts.manager the `org_kde_kwin_server_decoration_manager`
+   * @param {object} opts.surface the `wl_surface` proxy
+   * @param {'server'|'client'} [opts.prefer='server']
+   */
+  constructor({ manager, surface, prefer = 'server' }) {
+    super();
+    this.proxy = manager.$.create(surface.id);
+    this.proxy.on('mode', (mode) => {
+      // `none` is not server-side, and this side draws nothing for it: the
+      // window that asked for no frame is already drawing nothing.
+      this._answer(mode === KDE_DECORATION_MODE.SERVER ? 'server' : 'client');
+    });
+    this.prefer(prefer);
+  }
+
+  /** Nothing sequences this protocol's `mode` event; window.js flushes it. */
+  get flushesOutsideConfigure() {
+    return true;
+  }
+
+  prefer(prefer) {
+    if (this.destroyed) return;
+    this.proxy.$.request_mode(
+      prefer === 'client'
+        ? KDE_DECORATION_MODE.CLIENT
+        : KDE_DECORATION_MODE.SERVER,
+    );
+  }
+
+  _release() {
+    this.proxy.$.release();
+  }
+}
+
+/**
+ * Ask whichever protocol the compositor has, preferring the standard one.
+ * Returns null only when there is nobody to ask — the case where the frame
+ * has to be this backend's own (GNOME).
+ *
+ * @param {object} opts
+ * @param {object} [opts.manager] `zxdg_decoration_manager_v1`, if bound
+ * @param {object} [opts.kdeManager] `org_kde_kwin_server_decoration_manager`
+ * @param {object} opts.toplevel the `xdg_toplevel` proxy
+ * @param {object} opts.surface the `wl_surface` proxy
+ * @param {'server'|'client'} [opts.prefer='server']
+ * @returns {Decoration|null}
+ */
+export function createServerDecoration({
+  manager,
+  kdeManager,
+  toplevel,
+  surface,
+  prefer = 'server',
+}) {
+  if (manager) return new ServerDecoration({ manager, toplevel, prefer });
+  if (kdeManager)
+    return new KdeServerDecoration({ manager: kdeManager, surface, prefer });
+  return null;
+}

package/src/wayland/surface.js

@@ -0,0 +1,141 @@
+// An offscreen surface: pixels that persist, drawn into with a 2d context and
+// drawn from with `drawImage`.
+//
+// ntk's `Surface` is an X pixmap and a Picture; the Cocoa backend's is a CG
+// bitmap. Here it is a render target (target.js) — a texture with a
+// framebuffer in front of it — which is also what a window's backing store
+// is, so the paint cache, scroll blits and the window all go through one
+// piece of code. The contract is the one `src/ntk.js` documents: `width`/
+// `height`, `getContext('2d')`, `render(fn)`, `clear()`, `copyWithin(src,
+// dx, dy)`, `destroy()`, and being a valid `drawImage` source.
+//
+// One thing to know about GL: a context has to be *current* to draw, and
+// only one surface is current at a time. Every target here shares the app's
+// one EGL context, so `render()` asks the app to make it current before
+// binding the target — which normally costs nothing, because it already is.
+//
+// Sharing one device is also why `getContext('2d')` used to be a trap. ntk
+// tells callers who draw often to hold a context rather than take one per
+// frame, and a held context here drew wherever the device was last pointed
+// — which, outside `render()`, was the window: the draws went nowhere
+// visible and nothing said so (#566). The context now takes the device back
+// whenever it finds it in someone else's hands (device.js), so holding one
+// works as ntk documents, and a node that painted into a surface in the
+// middle of the window's frame no longer has to put the window's GL state
+// back by hand either.
+
+import { WaylandContext2D } from './context2d.js';
+import { GLTarget } from './target.js';
+
+export class WaylandSurface {
+  /**
+   * @param {import('./app.js').WaylandApp} app
+   * @param {object} opts
+   * @param {number} opts.width
+   * @param {number} opts.height
+   * @param {'argb32'|'a8'} [opts.format='argb32']
+   */
+  constructor(app, { width, height, format = 'argb32' } = {}) {
+    if (format !== 'argb32' && format !== 'a8') {
+      throw new Error(
+        `Surface: unknown format ${JSON.stringify(format)} (argb32 or a8)`,
+      );
+    }
+    this.app = app;
+    this.width = Math.max(1, Math.round(width));
+    this.height = Math.max(1, Math.round(height));
+    this.format = format;
+    this._destroyed = false;
+    app.makeCurrent();
+    this.target = new GLTarget(app.gl, {
+      width: this.width,
+      height: this.height,
+      stencil: true,
+      format,
+    });
+    this._ctx = null;
+  }
+
+  getContext(name = '2d') {
+    if (this._destroyed) throw new Error('Surface: destroyed');
+    if (name !== '2d') {
+      throw new Error(
+        `Surface: getContext(${JSON.stringify(name)}) — a surface has a '2d' context and nothing else.`,
+      );
+    }
+    if (!this._ctx) {
+      this._ctx = new WaylandContext2D(this.app.gl, {
+        fontManager: this.app.fonts,
+        target: this.target,
+        // A surface may be drawn into between frames, when the app's notion
+        // of a current GL surface is whatever it last was; the context asks
+        // for one before it re-takes the device, as `render()` does.
+        makeCurrent: () => this.app.makeCurrent(),
+      });
+      this.app.makeCurrent();
+      this._ctx.init();
+    }
+    return this._ctx;
+  }
+
+  /**
+   * Draw into the surface through a context that starts clean — identity
+   * transform, no clip — and is flushed when the callback returns.
+   *
+   * Drawing through `getContext('2d')` directly works too, and keeps the
+   * transform and clip it was left with; this is the scoped form, for a
+   * caller that wants a frame's worth of state rather than a canvas's.
+   */
+  render(fn) {
+    if (this._destroyed) return this;
+    const ctx = this.getContext('2d');
+    this.app.makeCurrent();
+    ctx.begin(this.width, this.height);
+    try {
+      fn(ctx);
+    } finally {
+      ctx.end();
+      this.app.rebindWindowTarget();
+    }
+    return this;
+  }
+
+  /** Reset every pixel to fully transparent. */
+  clear() {
+    if (this._destroyed) return this;
+    this.render((ctx) => ctx.clearRect(0, 0, this.width, this.height));
+    return this;
+  }
+
+  /**
+   * Scroll the pixels of `src` by (dx, dy) in place. True when a copy was
+   * made; false means nothing survives the shift and the caller repaints.
+   */
+  copyWithin(src, dx, dy) {
+    if (this._destroyed) return false;
+    this.app.makeCurrent();
+    const ok = this.target.copyWithin(src, dx, dy);
+    this.app.rebindWindowTarget();
+    return ok;
+  }
+
+  /** What `blurCoverage` and friends would want; not available on the GPU. */
+  get bytes() {
+    throw new Error(
+      'Surface.bytes: pixels live on the GPU; use getContext("2d").getImageData()',
+    );
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    this.app.makeCurrent();
+    this._ctx?.destroy();
+    this._ctx = null;
+    this.target.destroy();
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}