react-x11 2.52.0 → 2.54.0

package/src/win32/fonts.js

@@ -1,6 +1,6 @@
 // The Windows text engine: DirectWrite behind the same `app.fonts` contract
 // ntk's FontManager answers on X11 and CoreText answers on macOS. The renderer
-// touches exactly this surface (docs/windows.md §"Text"):
+// touches exactly this surface (design/windows.md §"Text"):
 //
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })

package/src/win32/glarea.js

@@ -1,6 +1,6 @@
 // `<glarea>` on Windows: a WGL core context, composited as a visual.
 //
-// docs/windows-gl.md is the report behind this, and the route is the X11
+// design/windows-gl.md is the report behind this, and the route is the X11
 // model rather than ANGLE — a GL surface covers its rect and the tree draws
 // under it, positioned from the parent's yoga rect. src/glnodes.js already
 // expects exactly that, including the rule that the surface selects no
@@ -58,7 +58,7 @@ export class Win32GlWindow {
    * vendor driver: opengl32.dll is then the 1.1 software rasterizer, with no
    * shaders and no framebuffer objects — which is not a degraded direct
    * backend but the indirect one's feature set without its portability, and
-   * is docs/windows-gl.md's rung 2 rather than this one.
+   * is design/windows-gl.md's rung 2 rather than this one.
    */
   _onReady(ok, why = 0) {
     if (!ok) {
@@ -79,7 +79,7 @@ export class Win32GlWindow {
         'error',
         new Error(
           `react-x11: no OpenGL surface — ${REASONS[why] ?? 'the bridge refused it'}. ` +
-            'docs/windows-gl.md rung 2 (ANGLE) covers this case and is not built yet.',
+            'design/windows-gl.md rung 2 (ANGLE) covers this case and is not built yet.',
         ),
       );
       return;
@@ -540,7 +540,7 @@ export function installGl(app) {
       throw new Error(
         'react-x11: <glarea> has no GL surface — this machine has no vendor ' +
           'OpenGL driver, so only the 1.1 software rasterizer is available, ' +
-          'which has no shaders. docs/windows-gl.md rung 2 (ANGLE) covers ' +
+          'which has no shaders. design/windows-gl.md rung 2 (ANGLE) covers ' +
           'this case and is not built yet.',
       );
     });

package/src/win32/overlay.js

@@ -13,7 +13,7 @@
 // leave transparent shows the GL frame, and a translucent fill, an
 // antialiased edge or a shadow blends with it. Text on it is grayscale
 // rather than ClearType, which Direct2D does on any surface with alpha
-// (docs/windows.md §Text).
+// (design/windows.md §Text).
 //
 // Drawn like the window it lives in (src/win32/window.js): a DirectComposition
 // surface hands out a context per `BeginDraw`, valid until `EndDraw`, so the

package/src/win32/panewindow.js

@@ -1,4 +1,4 @@
-// The pane process's "window" on the Windows backend — docs/frame.md's child
+// The pane process's "window" on the Windows backend — design/frame.md's child
 // half, with the composition engine standing in for the X server.
 //
 // On X11 a pane renders into a real window of its own and the host reparents
@@ -6,7 +6,7 @@
 // the pane makes a DirectComposition surface handle, hangs a composition
 // swapchain off it, and draws through the same verb table a window draws
 // through; the host opens that handle and gives it to a visual of its own
-// (src/win32/panehost.js). See docs/windows-embedding.md for why this rather
+// (src/win32/panehost.js). See design/windows-embedding.md for why this rather
 // than a shared DXGI texture — in one line, nothing here has to synchronise.
 //
 // **The present is the hand-off.** Once the host holds the handle the
@@ -360,7 +360,7 @@ export class Win32PaneWindow {
    * On X11 that is the window's own id, because an XID means the same thing
    * in every process on the display. Windows has no such number: a window
    * cannot be embedded at all, because a composition target stops presenting
-   * the moment its window becomes a child (docs/windows-embedding.md, with
+   * the moment its window becomes a child (design/windows-embedding.md, with
    * the measurements). What crosses instead is the **buffer** — the same
    * composition surface handle a `<Frame>` pane publishes — and the host
    * binds it to a visual of its own rather than reparenting anything.

package/src/win32/shell.js

@@ -236,7 +236,7 @@ async function badgePixels(app, label, accent) {
  * What this rung cannot do, and says so by not implementing it: actions,
  * replacing a notification in place, and an icon of the app's own. Those want
  * the Windows App SDK's notification manager and an AppUserModelID the system
- * knows — docs/windows.md §"The desktop around the app". Until then the
+ * knows — design/windows.md §"The desktop around the app". Until then the
  * balloon is shown by the shell in the same place, with the same sound, and
  * kept in the same action centre.
  */

package/src/win32/window.js

@@ -252,7 +252,7 @@ export class Win32Window {
   }
 
   /** The size limits Windows asks for synchronously in WM_GETMINMAXINFO, so
-   * they are pushed ahead rather than answered on demand — docs/windows.md
+   * they are pushed ahead rather than answered on demand — design/windows.md
    * "What Windows asks synchronously, and JS can know in advance". */
   setSizeHints(hints = {}) {
     this._native.setSizeHints?.(this.id, hints);
@@ -691,7 +691,7 @@ export class Win32Window {
   }
 
   /** A DirectComposition surface is write-only, so a window's pixels are not
-   * readable the way an IOSurface's or an X drawable's are. docs/windows.md
+   * readable the way an IOSurface's or an X drawable's are. design/windows.md
    * answers this with PrintWindow once the commit has completed; not bound
    * yet, and it says so rather than answering with something wrong. */
   /**

package/src/windowid.js

@@ -78,7 +78,7 @@ export function windowOf(target) {
  * - **Windows** — a **composition surface handle**, already valid in the
  *   host process. A window cannot be embedded here at all: a composition
  *   target stops presenting the moment its window becomes a child, measured
- *   in docs/windows-embedding.md. So what crosses is the buffer, and the
+ *   in design/windows-embedding.md. So what crosses is the buffer, and the
  *   host binds it to a visual of its own instead of reparenting. The host is
  *   the parent process by default — `createRoot({ win32: { paneHostPid } })`
  *   when it is not.

package/src/xvideo.js

@@ -0,0 +1,189 @@
+// `<video frames>` on X11 with the server doing the conversion: an XVideo
+// port where the display has an image adaptor (ntk/xv;
+// design/architecture/video.md §2.6).
+//
+// The drawn path converts each YCbCr frame in a JavaScript loop over every
+// pixel and puts four bytes a pixel on the wire. Through Xv the frame
+// crosses as the decoder made it — 1.5 bytes a pixel for NV12 and I420,
+// through shared memory on a local display — and the matrix is the server's
+// GPU's: glamor's textured adaptor, which Xorg's modesetting driver and
+// Xwayland both ship.
+//
+// Where the frame goes is the record's open question, answered by
+// measurement: an adaptor takes no pixmap (`BadWindow` into one on
+// Xwayland), so the frame goes into a `VideoTarget` — a manually redirected
+// child window outside the window it belongs to, shown nowhere — and from
+// there, in one RENDER copy, into the `<video>`'s own surface. Everything
+// after that is the drawn path unchanged: the surface is composited in paint
+// order, under the window's popups and inside its scroll panes, and painted
+// again from without a frame.
+//
+// Declined, and the frame goes the JavaScript way, where the server has no
+// image adaptor (Xvfb, XQuartz, most remote displays), where ntk predates
+// ntk/xv, for a full-range frame or a colour space the port cannot be told
+// (every adaptor reads video range; one without XV_COLORSPACE reads BT.601
+// alone), while the window is not on screen, and for the first frame of a
+// size, while the port says how it wants it laid out.
+//
+// Nothing is asked of the server until a sink or a `<video>` asks: an app
+// that shows no video grabs no port and pays no round trip.
+
+const writers = new WeakMap();
+
+/** The writer for `app`'s connection, made on first ask. */
+export function xvVideoFor(app) {
+  let writer = writers.get(app);
+  if (!writer) writers.set(app, (writer = new XvVideo(app)));
+  return writer;
+}
+
+const same = (planes) => planes;
+const swapChroma = (planes) => planes && [planes[0], planes[2], planes[1]];
+
+/** A sink's format, as the formats a port may take it in — the planes put
+ *  in the port's order — cheapest first. */
+const PORT_FORMATS = {
+  NV12: [['NV12', same]],
+  I420: [
+    ['I420', same],
+    ['YV12', swapChroma],
+  ],
+  BGRA: [['AR24', same]],
+};
+
+class XvVideo {
+  constructor(app) {
+    this.app = app;
+    /** `undefined` while it is being asked for, then a VideoPort or null */
+    this.port = undefined;
+    this._opening = null;
+    /** the sizes asked about before the port answered, to lay out once it does */
+    this._waiting = [];
+    /** surface -> { target, window }: where each `<video>`'s frames go */
+    this._targets = new Map();
+  }
+
+  /**
+   * Start asking for a port, and — for a sink — for the layout of its
+   * frames, so its first frame is the only one drawn the slow way. Cheap
+   * and idempotent: a sink calls it when it is made.
+   */
+  prepare(sink) {
+    if (this.port === undefined) {
+      if (sink) this._waiting.push(sink);
+      if (!this._opening) this._open();
+      return;
+    }
+    if (this.port && sink) this._layout(sink);
+  }
+
+  _open() {
+    this._opening = import('ntk/xv')
+      .then(({ openVideoPort }) => openVideoPort(this.app))
+      .catch(() => null)
+      .then((port) => {
+        // a port with nowhere to put a frame — no Composite, so no target —
+        // is no port: given back, and the formats are JavaScript's
+        if (port && !port.targets) {
+          port.close();
+          port = null;
+        }
+        this.port = port;
+        const waiting = this._waiting;
+        this._waiting = [];
+        if (port) for (const sink of waiting) this._layout(sink);
+      });
+  }
+
+  /** Ask the port how it lays out `sink`'s frames, if it takes them at all. */
+  _layout(sink) {
+    const choice = this._formatFor(sink);
+    if (choice) this.port.layout(choice[0], sink.width, sink.height);
+  }
+
+  /**
+   * `preferredFormats` on X11 (src/videoframes.js): `null` while the port is
+   * being asked for — an answer not to keep — then the YCbCr formats the
+   * port takes ahead of BGRA, or BGRA alone where there is no port and every
+   * frame is drawn in JavaScript.
+   */
+  videoFormats() {
+    if (this.port === undefined) {
+      this.prepare();
+      return null;
+    }
+    if (this.port === null) return ['BGRA'];
+    const takes = (name) =>
+      PORT_FORMATS[name].some(([format]) => this.port.formats.includes(format));
+    return [...['NV12', 'I420'].filter(takes), 'BGRA'];
+  }
+
+  /** The port's format for `sink` and how its planes go, or null where the
+   *  port cannot show it as the sink means it. */
+  _formatFor(sink) {
+    const port = this.port;
+    if (sink.format !== 'BGRA') {
+      if (sink.range !== 'video') return null;
+      if (!port.colorSpaces.includes(sink.colorSpace)) return null;
+    }
+    return (
+      PORT_FORMATS[sink.format]?.find(([format]) =>
+        port.formats.includes(format),
+      ) ?? null
+    );
+  }
+
+  /**
+   * A `<video>`'s frame into `surface`, its drawn presentation: through the
+   * port into the node's target, then copied into the surface. False — and
+   * the node converts the frame itself — wherever this cannot (see the top).
+   */
+  writeVideoFrame(surface, sink, frame, node) {
+    const port = this.port;
+    if (!port) {
+      if (port === undefined) this.prepare(sink);
+      return false;
+    }
+    if (port.closed) return false;
+    const choice = this._formatFor(sink);
+    const window = node?.root?.window;
+    if (!choice || !window || typeof window.id !== 'number') return false;
+    const [format, order] = choice;
+    const { width, height } = sink;
+    let kept = this._targets.get(surface);
+    if (kept && (kept.window !== window || kept.target.destroyed)) {
+      // the node is in another window now, or its window took the target
+      // with it
+      kept.target.destroy();
+      this._targets.delete(surface);
+      kept = undefined;
+    }
+    if (!kept) {
+      // the first frame of a size: asked, and drawn the other way meanwhile
+      if (!port.layout(format, width, height)) return false;
+      const target = port.createTarget(window, { width, height });
+      if (!target) return false;
+      kept = { target, window };
+      this._targets.set(surface, kept);
+    }
+    const sent = kept.target.put({
+      format,
+      width,
+      height,
+      planes: order(frame.planes),
+      strides: order(frame.strides),
+      colorSpace: sink.colorSpace,
+    });
+    if (!sent) return false;
+    kept.target.copyTo(surface);
+    return true;
+  }
+
+  /** The node let `surface` go: so does its target. */
+  releaseVideoFrame(surface) {
+    const kept = this._targets.get(surface);
+    if (!kept) return;
+    this._targets.delete(surface);
+    kept.target.destroy();
+  }
+}