react-x11 1.2.0 → 2.0.0

package/src/frames.js

@@ -0,0 +1,73 @@
+// Which windows owe a frame.
+//
+// Shared between the paint root (nodes.js — it records the debt in
+// `invalidate()` and pays it in `flush()`) and the event dispatcher
+// (events.js — it pays early, for discrete input). Its own module because
+// nodes.js already imports events.js, and the dispatcher cannot import the
+// node back without a cycle.
+//
+// The set answers "which windows have unpainted damage" in O(1) at event
+// time. A tree walk would answer it too, but it is walked once per discrete
+// event on a tree that can be thousands of nodes, to find the one or two
+// roots that a `Set.add` in `invalidate()` already knew about.
+
+const pending = new Set();
+
+/** `node` has damage and no paint yet. Idempotent. */
+export function addPendingFrame(node) {
+  pending.add(node);
+}
+
+/** `node` is painting (or has nothing left to paint). */
+export function clearPendingFrame(node) {
+  pending.delete(node);
+}
+
+/**
+ * Paint every window that owes a frame and whose server is caught up — the
+ * synchronous half of the frame clock (issue #141).
+ *
+ * A discrete input has exactly one visual response: a button darkens, a
+ * caret lands, focus moves. Scheduling that response through
+ * `requestAnimationFrame` charges it up to a frame interval plus a fence
+ * round trip before it reaches the wire, on top of a paint that measures in
+ * the hundreds of microseconds. So the dispatcher calls this when the
+ * handler unwinds, and the pixels go out with the handler's own requests
+ * instead.
+ *
+ * Two things make that safe to do unconditionally at the call site:
+ *
+ *  - **The frame gate.** A window whose last frame has not landed keeps the
+ *    frame it already scheduled. Painting it now would be work nobody sees:
+ *    ntk defers the present until the frame ends, where it coalesces with
+ *    the one already pending. This is what keeps a burst sane — spin a wheel
+ *    and the first notch paints immediately, the rest fold into one catch-up
+ *    frame. "Update instantly, then catch up", with the frame clock as the
+ *    backpressure.
+ *
+ *    On ntk >= 7 what ends a frame is the display: the server reports the
+ *    present it executed at a vertical blank, so the gate now means "the
+ *    display has not shown the last frame" rather than "the socket has not
+ *    acknowledged it". Same call, later and truer signal — and it is also
+ *    what keeps us off a backing pixmap the server is still copying from.
+ *  - **Every window answers for itself.** The set is app-wide, so a click
+ *    that dirtied both a menu and the window under it paints both, each
+ *    gated on its own window's frame clock.
+ *
+ * A window whose scheduled frame this pays off keeps that scheduled
+ * callback; it runs and finds `needsPaint` false, which is already a cheap
+ * no-op.
+ */
+export function flushPendingFrames() {
+  if (pending.size === 0) return;
+  for (const node of [...pending]) {
+    const wnd = node.window;
+    // ntk < 5.2.0 (sidorares/ntk#148) cannot say whether the frame has
+    // landed, and a missing answer is not a "no" — without the gate a burst
+    // would paint every event, so the paced frame stays the safe choice.
+    // Same for a headless mock window that models no frame clock at all.
+    if (typeof wnd?.frameInFlight !== 'function') continue;
+    if (wnd.frameInFlight()) continue;
+    node.flush();
+  }
+}

package/src/glbackend.js

@@ -0,0 +1,114 @@
+// Which GL backend a connection got, asked synchronously.
+//
+// The question is about the **connection**, not the machine. ntk's
+// `glCapabilities()` answers the machine one — "could direct rendering work
+// here" — and consults `glPolicy` only far enough to honour `'off'`, so on a
+// DRI3-capable box it resolves `{ direct: true }` under the default
+// `'indirect'` policy too. What actually draws is what the policy asked for,
+// so that is what this module reports: the same rule ntk's own `backendFor()`
+// applies when `getContext` picks a backend, kept in step here because it is
+// not part of ntk's public API (issue #357).
+//
+// ntk settles the probe during its connection handshake — it runs it whenever
+// `glPolicy` could select direct — so by the time any element is created the
+// answer is a property read rather than a round trip. That is what lets
+// `<shaderMaterial>` fail at creation, with a reason, instead of rendering an
+// empty surface.
+//
+// A leaf module on purpose: it imports nothing of ours, so both
+// `appcontext.js` (for `useSupports('shaders')`) and the node layer can use
+// it without the two importing each other.
+
+import { GLError } from 'ntk';
+
+/** Does this connection's policy ever choose the direct backend? */
+const wantsDirect = (app) => {
+  const mode = app?.glPolicy?.mode;
+  return mode === 'auto' || mode === 'direct';
+};
+
+/** ntk's coded-error shape — `code` to branch on, `hint` for what to do. */
+function glError(code, message, hint) {
+  const err = new Error(message);
+  err.code = code;
+  if (hint) err.hint = hint;
+  return err;
+}
+
+/**
+ * Is the direct backend — the one with shaders — what this connection draws
+ * through?
+ *
+ * False under a policy that never asks for it, whatever the machine could do,
+ * because the policy is what decides which backend is built.
+ */
+export function hasDirectGL(app) {
+  return wantsDirect(app) && !!app._glCapsResolved?.direct;
+}
+
+/**
+ * Why it is not, as a coded error — or null when it is available, or when the
+ * probe that would say has not answered yet.
+ *
+ * Worth surfacing rather than describing: the reasons are genuinely different
+ * (a policy that never asked, no GPU addon, a connection that cannot pass
+ * descriptors, a server without DRI3) and only one of them is "turn the
+ * policy on". A message that guesses sends people to check the wrong thing.
+ *
+ * The policy reasons are minted here because ntk has none to give: its probe
+ * consults the mode only for `'off'`, so a connection left on the default
+ * `'indirect'` carries capabilities with no `reason` in them at all — and on
+ * a capable machine, with `direct: true` in them.
+ */
+export function directGLFailure(app) {
+  const mode = app?.glPolicy?.mode;
+  if (mode === 'off') {
+    return glError(
+      GLError.DISABLED,
+      "glPolicy is 'off' on this connection, so no GL context is created at all",
+      "No <glarea> draws under this policy. Pass glPolicy: 'auto'\n" +
+        'to createRoot(), or drop the option, to get a context back.',
+    );
+  }
+  if (!wantsDirect(app)) {
+    return glError(
+      'GL_POLICY_INDIRECT',
+      "glPolicy is 'indirect' — ntk's default — so this connection draws " +
+        'through indirect GLX, which has no shaders whatever this machine could do',
+      "createRoot({ glPolicy: 'auto' }) takes the direct backend where it is\n" +
+        'available and this one everywhere else, and NTK_GL_POLICY=auto switches\n' +
+        'a single run. app.glCapabilities() still answers what the machine can do.',
+    );
+  }
+  const caps = app._glCapsResolved;
+  return caps && !caps.direct ? (caps.reason ?? null) : null;
+}
+
+/**
+ * Call `onChange` when that answer settles, and hand back the unsubscribe —
+ * the subscribe half of `useSupports('shaders')`.
+ *
+ * It settles at most once and then holds still. Under a policy that could
+ * pick direct, `createRoot()` waits for ntk's probe before it hands the app
+ * back, so the first render already reads the final answer and there is
+ * nothing to watch; under one that could not, the answer is false and stays
+ * false. What is left is a policy raised after connecting, which has missed
+ * the handshake probe — `glCapabilities()` is idempotent and cached, and is
+ * the same call ntk makes lazily when a context is created, so asking it here
+ * settles the answer rather than leaving one component reading false and the
+ * next reading true.
+ */
+export function watchDirectGL(app, onChange) {
+  if (!wantsDirect(app) || app._glCapsResolved) return () => {};
+  if (typeof app.glCapabilities !== 'function') return () => {};
+  let live = true;
+  // a probe that throws is a probe that found nothing: the answer stays
+  // false, and re-reading a boolean that did not move costs a comparison
+  const settled = () => {
+    if (live) onChange();
+  };
+  app.glCapabilities().then(settled, settled);
+  return () => {
+    live = false;
+  };
+}

package/src/glnodes.js

@@ -5,40 +5,79 @@
 // (NEXT_STEPS §4), sized and positioned by the parent's yoga layout like any
 // other drawn node. Everything about the surface is here; the scene graph
 // that draws into it comes later (docs/glx-plan.md).
-import { cssColor } from 'ntk';
+import { cssColorStraight } from 'ntk';
+
+// re-exported so the GL element layer stays one import for consumers
+export { directGLFailure, hasDirectGL } from './glbackend.js';
 
 import { Node } from './nodes.js';
-import { ScenePointer, sceneWantsPointer } from './pointer3d.js';
-import { SceneRenderer } from './scene3d.js';
 
 // One visual query per (app, spec): GetFBConfigs is a round trip and every
 // <glarea> in an app wants the same answer.
 const configCache = new WeakMap();
 
+// Whether GL setup has already been found impossible on this connection.
+// Every reason it fails — no GLX extension, indirect GLX disabled, no
+// matching visual — is a property of the X server, not of one surface, so
+// the first <glarea> to find out saves the rest from asking, so a second
+// surface can report `onError` on its first frame instead of showing an
+// empty box for the round trip it would otherwise take.
+const glxFailures = new WeakMap();
+
+/** The error that made GL unavailable on `app`, or null if all is well (or
+ * not yet known). Carries ntk's `code` — see `GLXError`. */
+export function glxFailure(app) {
+  return (app && glxFailures.get(app)) || null;
+}
+
+function recordGlxFailure(app, err) {
+  if (app && err && !glxFailures.has(app)) glxFailures.set(app, err);
+}
+
+/**
+ * The visual and depth to create the GL child window with.
+ *
+ * `chooseGLConfig` answers for whichever backend ntk's `glPolicy` selected
+ * and tags the result with `backend`; it is the newer name and the one to
+ * prefer, because asking the older `chooseGLXConfig` would pin the surface to
+ * indirect GLX no matter what the policy says. The fallback keeps `<glarea>`
+ * working on an ntk that predates the direct backend.
+ */
 export function glxConfig(app, spec) {
   const key = JSON.stringify(spec ?? null);
   let perApp = configCache.get(app);
   if (!perApp) configCache.set(app, (perApp = new Map()));
   let promise = perApp.get(key);
   if (!promise) {
-    promise =
-      typeof app.chooseGLXConfig === 'function'
-        ? app.chooseGLXConfig(spec)
-        : Promise.reject(
-            new Error(
-              'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLXConfig)',
-            ),
-          );
+    if (typeof app.chooseGLConfig === 'function') {
+      promise = app.chooseGLConfig(spec);
+    } else if (typeof app.chooseGLXConfig === 'function') {
+      promise = app
+        .chooseGLXConfig(spec)
+        .then((config) => ({ backend: 'indirect', ...config }));
+    } else {
+      promise = Promise.reject(
+        new Error(
+          'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',
+        ),
+      );
+    }
     perApp.set(key, promise);
   }
   return promise;
 }
 
-/** clearColor as a CSS string or an [r, g, b, a] float tuple. */
+/**
+ * clearColor as a CSS string or an [r, g, b, a] float tuple.
+ *
+ * Straight alpha, not premultiplied: this goes to `glClearColor`, and GL
+ * takes unassociated components. ntk's `cssColor` premultiplies for XRender,
+ * which would darken any translucent clear colour.
+ */
 function clearColorOf(props) {
   const value = props.clearColor ?? 'black';
   if (Array.isArray(value)) return value.length === 4 ? value : [...value, 1];
-  const parsed = cssColor(value);
+  const parsed = cssColorStraight(value);
   return parsed ?? [0, 0, 0, 1];
 }
 
@@ -74,8 +113,6 @@ export class GlAreaNode extends Node {
     this._realizing = false;
     this._frameScheduled = false;
     this._created = false;
-    this.scene = new SceneRenderer(this);
-    this.pointer = new ScenePointer(this);
     this._pointerDirty = true;
   }
 
@@ -95,24 +132,55 @@ export class GlAreaNode extends Node {
     if (this.window || this.destroyed || this._realizing) return;
     const parent = this.root?.window;
     if (!parent || typeof this.app?.createWindow !== 'function') return;
+    // asked and answered — and whoever asked first already reported it
+    const known = glxFailure(this.app);
+    if (known) return this._failed(known, { reported: true });
     this._realizing = true;
     glxConfig(this.app, this.props.glx).then(
       (config) => {
         this._realizing = false;
         if (this.destroyed || this.window) return;
-        this._create(config, parent);
+        // getContext() throws rather than rejects when the display has no
+        // GLX at all, and a throw in here would escape as an unhandled
+        // rejection instead of reaching onError
+        try {
+          this._create(config, parent);
+        } catch (err) {
+          this._failed(err);
+        }
       },
       (err) => {
         this._realizing = false;
-        this.error = err;
-        this.props.onError?.(err);
-        if (!this.props.onError) {
-          console.warn(`react-x11: <glarea> has no GL surface: ${err.message}`);
-        }
+        this._failed(err);
       },
     );
   }
 
+  /**
+   * GL is not available: report it once, and give up the X child window if
+   * one was created. It would otherwise sit over this rect as an unpainted
+   * hole, hiding whatever the fallback draws in its place.
+   *
+   * `reported` means ntk has already written the diagnosis to the console —
+   * it does that for a failed context, and its message is the better one.
+   */
+  _failed(err, { reported = false } = {}) {
+    this._realizing = false;
+    if (this.error) return;
+    this.error = err;
+    recordGlxFailure(this.app, err);
+    this.gl = null;
+    if (this.window) {
+      this.window.destroy?.();
+      this.window = null;
+      this.rect = null;
+    }
+    if (this.props.onError) this.props.onError(err);
+    else if (!reported) {
+      console.warn(`react-x11: <glarea> has no GL surface: ${err.message}`);
+    }
+  }
+
   _create(config, parent) {
     const rect = this._geometry();
     const wnd = this.app.createWindow({
@@ -132,6 +200,17 @@ export class GlAreaNode extends Node {
     this.config = config;
     wnd._reactX11Node = this;
     this.gl = wnd.getContext('opengl', config);
+    // a buffer freed by the display is a frame that can be drawn again
+    if (typeof this.gl?.onFrameAvailable !== 'undefined') {
+      this.gl.onFrameAvailable = () => this.requestFrame();
+    }
+    // The context is only usable once MakeCurrent has answered, and that is
+    // where a server refusing indirect GLX says so (ntk gives the rejection
+    // an err.code — see GLXError). Nothing here awaits it: GL calls queue
+    // until the tag arrives, so this only has to catch the failure.
+    this.gl?.ready?.catch((err) => {
+      if (!this.destroyed) this._failed(err, { reported: true });
+    });
     wnd.on?.('expose', () => this.requestFrame());
     wnd.map?.();
     this.requestFrame();
@@ -191,18 +270,37 @@ export class GlAreaNode extends Node {
   _drawFrame() {
     const gl = this.gl;
     if (!gl || this.destroyed) return;
+    const direct = gl.backend === 'direct';
+    // On the direct backend every buffer may still be held by the display,
+    // and drawing into one before it comes back would paint what is on
+    // screen. `onFrameAvailable` asks for this frame again when one frees.
+    if (direct && gl.canRender && !gl.canRender()) return;
+    // binds this surface — the GPU context is shared between every <glarea>
+    // on the connection — and picks up a resize
+    gl.makeCurrent?.();
+
     const { width, height } = this.rect;
-    const info = { width, height, node: this };
+    // x/y are where the node's origin sits in the drawable being drawn
+    // into (DrawInfo's contract) — a <glarea> draws into its own X window,
+    // so that is the origin.
+    const info = { width, height, x: 0, y: 0, node: this };
     if (!this._created) {
       this._created = true;
       this.props.onCreated?.(gl, info);
     }
-    this._syncPointerListeners();
-    gl.Viewport(0, 0, width, height);
     const [r, g, b, a] = clearColorOf(this.props);
-    gl.ClearColor(r, g, b, a);
-    gl.Clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
-    this.scene.render(gl, info);
+    // The two backends spell GL differently — PascalCase OpenGL 1.x against
+    // camelCase ES 2 — and neither pretends to be the other, so the handful
+    // of calls this element makes itself are written both ways.
+    if (direct) {
+      gl.viewport(0, 0, width, height);
+      gl.clearColor(r, g, b, a);
+      gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+    } else {
+      gl.Viewport(0, 0, width, height);
+      gl.ClearColor(r, g, b, a);
+      gl.Clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+    }
     this.props.onDraw?.(gl, info);
     gl.SwapBuffers();
     if (this.props.frameLoop === 'always') this.requestFrame();
@@ -220,45 +318,6 @@ export class GlAreaNode extends Node {
     else this.window?.map?.();
   }
 
-  /**
-   * X pointer events are only worth selecting when something in the scene
-   * listens for them — the r3f rule that only handler-bearing objects take
-   * part in picking, applied one level up, to the wire.
-   */
-  _syncPointerListeners() {
-    if (!this._pointerDirty || !this.window || this.pointer.attached) return;
-    this._pointerDirty = false;
-    if (!sceneWantsPointer(this.children)) return;
-    this.pointer.attach(this.window);
-  }
-
-  /** A scene node was added, removed, or gained/lost pointer handlers. */
-  _sceneChanged() {
-    this._pointerDirty = true;
-    this.requestFrame();
-  }
-
-  /** scene children (<mesh>, <group>, …) attach to this surface. */
-  insertBefore(child, beforeChild) {
-    super.insertBefore(child, beforeChild);
-    child._setSurface?.(this);
-    this._sceneChanged();
-  }
-
-  removeChild(child) {
-    super.removeChild(child);
-    this.invalidateGeometry(child);
-    this.pointer.forget(child);
-    this._sceneChanged();
-  }
-
-  /** A removed geometry's display list is no longer needed server-side. */
-  invalidateGeometry(node) {
-    if (!node) return;
-    if (node.isGeometry) this.scene.forget(this.gl, node);
-    for (const child of node.children ?? []) this.invalidateGeometry(child);
-  }
-
   // the child window covers this rect: nothing to paint into the parent's
   // 2d context, and no drawn children are allowed under it
   paint() {}
@@ -266,7 +325,6 @@ export class GlAreaNode extends Node {
   destroySubtree() {
     if (this.destroyed) return;
     super.destroySubtree();
-    this.scene.dispose(this.gl);
     this.gl?.destroy?.();
     this.gl = null;
     this.window?.destroy?.();