ntk 6.3.0 → 6.4.0

package/lib/glx.js

@@ -1,10 +1,115 @@
-// GLX visual/fbconfig discovery.
+// GLX visual/fbconfig discovery, and the diagnosis of a failed setup.
 //
 // A GLX drawable has to use a visual the GL context was created for, so the
 // visual must be known *before* CreateWindow. This module asks the server
 // (GetFBConfigs, falling back to the GLX 1.2 GetVisualConfigs) instead of
 // shelling out to `glxinfo`, so it works headlessly and in CI.
 
+/**
+ * `err.code` on every error this module and the OpenGL context throw, so
+ * callers can branch on the cause instead of matching on message text.
+ *
+ * - `GLX_NO_EXTENSION` — the server does not have the GLX extension.
+ * - `GLX_INDIRECT_DISABLED` — it has GLX, but refuses indirect contexts,
+ *   which is the only kind that works over the wire. The default on Xorg
+ *   >= 1.17 and Xwayland, and by far the most common failure.
+ * - `GLX_NO_CONFIG` — no visual/fbconfig matches the requested attributes.
+ * - `GLX_CONTEXT_FAILED` — anything else that went wrong in setup.
+ */
+export const GLXError = {
+  NO_EXTENSION: 'GLX_NO_EXTENSION',
+  INDIRECT_DISABLED: 'GLX_INDIRECT_DISABLED',
+  NO_CONFIG: 'GLX_NO_CONFIG',
+  CONTEXT_FAILED: 'GLX_CONTEXT_FAILED'
+};
+
+// `message` says what is wrong in one line; `hint` is the multi-line
+// remedy, printed by the default warning and available to anyone rendering
+// their own fallback UI.
+function glxError(code, message, hint, cause) {
+  const err = new Error(message);
+  err.code = code;
+  if (hint) err.hint = hint;
+  if (cause) err.cause = cause;
+  return err;
+}
+
+const displayName = () => process.env.DISPLAY || 'the X server';
+
+const IGLX_HINT = `Indirect GLX is what ntk draws with: GL commands travel over the X
+connection, since there is no client-side GL library involved. Xorg >= 1.17
+and Xwayland ship with it disabled, and answer GLX CreateContext with
+BadValue. The extension is still present and still advertises GLX 1.4 with a
+full set of fbconfigs, which is why this looks like it should have worked.
+
+To get a server that allows it:
+  under Wayland:  Xwayland :5 +iglx &  then DISPLAY=:5
+  under X:        Xephyr :5 +iglx &    then DISPLAY=:5
+  Xorg:           +iglx on the command line, or
+                  Option "AllowIndirectGLX" "on" in xorg.conf
+  XQuartz:        defaults write org.xquartz.X11 enable_iglx -bool true
+
+Note that on current Linux distros the indirect GL *engine* behind those
+contexts is often gone even with +iglx on — contexts are created but nothing
+rasterizes. See docs/context-opengl.md.`;
+
+/** Turn a failed GLX CreateContext into an error that explains itself. */
+export function diagnoseCreateContext(err, cfg) {
+  // BadValue with value 0 from CreateContext (minor opcode 3) is how a
+  // server without +iglx says "no indirect contexts here" — every other
+  // rejection names the value it disliked
+  if (err?.error === 2 && err.badParam === 0) {
+    return glxError(
+      GLXError.INDIRECT_DISABLED,
+      `${displayName()} has GLX but refuses to create indirect GLX contexts, so there is no OpenGL context to draw with`,
+      IGLX_HINT,
+      err
+    );
+  }
+  const visual = cfg?.visual ? ` for visual 0x${cfg.visual.toString(16)}` : '';
+  return glxError(
+    GLXError.CONTEXT_FAILED,
+    `GLX CreateContext${visual} failed: ${err?.message ?? err}`,
+    null,
+    err
+  );
+}
+
+/**
+ * The console form of a failed GL setup: what went wrong, then how to fix
+ * it. Indented so the remedy reads as one block and not as unrelated log
+ * lines, and ending with the way to take over the handling.
+ */
+export function glxErrorReport(err) {
+  const lines = [`ntk: getContext('opengl') failed — ${err?.message ?? err}`];
+  if (err?.hint) lines.push('', ...err.hint.split('\n').map((l) => (l ? `  ${l}` : l)));
+  lines.push('', `  (await gl.ready to handle this yourself; err.code is ${err?.code ?? 'unset'})`);
+  return lines.join('\n');
+}
+
+/**
+ * Create a GLX context and find out whether it worked.
+ *
+ * CreateContext has no reply, so its failure would otherwise surface as an
+ * unattributed X error plus a misleading GLXBadContext from the MakeCurrent
+ * that follows. node-x11 >= 3.8 takes a callback here; older versions
+ * cannot report it at all, and this resolves optimistically rather than
+ * hanging.
+ */
+export function createContext(GLX, ctx, cfg) {
+  if (GLX.CreateContext.length < 6) {
+    GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0, (err) => {
+      if (err) reject(diagnoseCreateContext(err, cfg));
+      else resolve();
+      return true; // handled here; keep it away from the app's onXError
+    });
+  });
+}
+
 // defaults applied on top of the caller's spec; `null` means "don't care"
 const DEFAULT_SPEC = {
   DOUBLEBUFFER: true,
@@ -120,8 +225,12 @@ function matchLegacy(configs, spec) {
 export async function chooseGLXConfig(app, spec = {}) {
   const GLX = app.display.GLX;
   if (!GLX) {
-    throw new Error(
-      'GLX: extension not available on this display — indirect GLX is often disabled (X server flag +iglx / AllowIndirectGLX)'
+    throw glxError(
+      GLXError.NO_EXTENSION,
+      `${displayName()} does not have the GLX extension, so it cannot do OpenGL at all`,
+      'A server built without GLX, or started with -extension GLX. This is a\n' +
+        'different problem from indirect GLX being disabled, which is the usual\n' +
+        'one — there the extension is present and CreateContext is what fails.'
     );
   }
 
@@ -135,7 +244,11 @@ export async function chooseGLXConfig(app, spec = {}) {
 
   if (want.visual) {
     const info = visualInfo(screen, want.visual);
-    if (!info) throw new Error(`GLX: visual 0x${want.visual.toString(16)} is not on screen ${screenNum}`);
+    if (!info)
+      throw glxError(
+        GLXError.NO_CONFIG,
+        `GLX: visual 0x${want.visual.toString(16)} is not on screen ${screenNum}`
+      );
     return {
       visual: want.visual,
       depth: info.depth,
@@ -187,8 +300,10 @@ export async function chooseGLXConfig(app, spec = {}) {
   const legacyBest = pick(fromVisuals);
   if (legacyBest) return legacyBest;
 
-  throw new Error(
-    `GLX: no visual on screen ${screenNum} matches ${describe(want)} (server offered ${legacy.length} GLX visuals)`
+  throw glxError(
+    GLXError.NO_CONFIG,
+    `GLX: no visual on screen ${screenNum} matches ${describe(want)} (server offered ${legacy.length} GLX visuals)`,
+    'Relax the spec — DEPTH_SIZE and DOUBLEBUFFER are the usual culprits.'
   );
 }
 

package/lib/index.js

@@ -3,6 +3,7 @@ import x11 from 'x11';
 import App from './app.js';
 import Clipboard from './clipboard.js';
 import { BLANK_CURSOR, CursorCache, cursorNames, cursorShapes, resolveCursorShape } from './cursor.js';
+import { GLXError } from './glx.js';
 import Window from './window.js';
 import { loadLayout } from './yoga.js';
 import { decodeKey, groupForState } from './keyboard.js';
@@ -227,7 +228,9 @@ export {
   premultiply,
   cssLength,
   decodeKey,
-  groupForState
+  groupForState,
+  // the `code` on a failed GL setup: branch on it rather than on the message
+  GLXError
 };
 // The layout engine ntk lays HtmlView out with — downstream layout consumers
 // (e.g. the react-x11 renderer) must import it from here rather than from

package/lib/renderingcontext_opengl.js

@@ -1,5 +1,5 @@
 import Drawable from './drawable.js';
-import { chooseGLXConfig } from './glx.js';
+import { GLXError, chooseGLXConfig, createContext, glxErrorReport } from './glx.js';
 
 // Indirect GLX rendering context exposing an OpenGL 1.4-style api.
 // Note: many modern X servers ship with indirect GLX disabled — see README.
@@ -14,9 +14,11 @@ class RenderingContextOpenGL {
     const X = window.X;
     const GLX = window.display.GLX;
     if (!GLX) {
-      throw new Error(
-        "getContext('opengl'): the X server has no GLX extension — indirect GLX is often disabled (+iglx / AllowIndirectGLX)"
+      const err = new Error(
+        `getContext('opengl'): ${process.env.DISPLAY || 'the X server'} does not have the GLX extension, so it cannot do OpenGL at all`
       );
+      err.code = GLXError.NO_EXTENSION;
+      throw err;
     }
 
     this.window = window;
@@ -82,9 +84,21 @@ class RenderingContextOpenGL {
 
       const ctx = X.AllocID();
       this.contextId = ctx;
-      GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0);
+      // CreateContext first, and on its own: it is the request a server with
+      // indirect GLX disabled rejects, and going on to MakeCurrent would bury
+      // that under a GLXBadContext about the context that was never created
+      await createContext(GLX, ctx, cfg).catch((err) => {
+        this.contextId = 0; // nothing to destroy
+        throw err;
+      });
       const tag = await new Promise((resolve, reject) => {
-        GLX.MakeCurrent(window.id, ctx, 0, (err, contextTag) => (err ? reject(err) : resolve(contextTag)));
+        GLX.MakeCurrent(window.id, ctx, 0, (err, contextTag) => {
+          if (!err) return resolve(contextTag);
+          const failed = new Error(`GLX MakeCurrent failed: ${err.message}`);
+          failed.code = GLXError.CONTEXT_FAILED;
+          failed.cause = err;
+          reject(failed);
+        });
       });
 
       this.contextTag = tag;
@@ -97,9 +111,7 @@ class RenderingContextOpenGL {
     this.ready.catch((err) => {
       this.error = err;
       queue.length = 0;
-      console.warn(
-        `ntk: getContext('opengl') failed: ${err.message} (await gl.ready to handle this yourself)`
-      );
+      console.warn(glxErrorReport(err));
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "parse-color": "^1.0.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.23",
-    "x11": "^3.7.0",
+    "x11": "^3.8.0",
     "yoga-layout": "^3.2.1"
   },
   "scripts": {