ntk 8.8.1 → 8.8.2

package/lib/app.js

@@ -5,12 +5,15 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glCapabilities,
   glError,
   nativeRefreshRate,
   requestedSamples,
+  requestedStencil,
   resolveGLPolicy,
-  warnDirectSamples
+  warnDirectSamples,
+  warnDirectStencil
 } from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
@@ -637,6 +640,14 @@ export default class App {
    * request that cannot be met also warns once per connection, because an
    * aliased edge is otherwise found months later in a screenshot.
    *
+   * `stencilSize` is answered the same way, and matters more: a stencil test
+   * against a framebuffer with no stencil buffer passes everywhere, so
+   * stencil-based drawing renders wrong instead of failing. `STENCIL_SIZE`
+   * becomes the CGL context's stencil size on macOS (8 when the spec names
+   * none, as the Cocoa backend's surfaces have); the dri3 flavor has nothing
+   * to ask EGL with, so it answers 0 and a request for more warns once
+   * (`directStencilSize` in lib/gl.js).
+   *
    * @param {object} [spec] GLX attributes, e.g. `{ DEPTH_SIZE: 24 }`
    */
   async chooseGLConfig(spec = {}) {
@@ -659,6 +670,12 @@ export default class App {
     // answer honestly below rather than dropping the attribute (issue #341)
     const wantSamples = requestedSamples(spec);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(this, caps.flavor, wantSamples);
+    // the same for stencil, where it matters more: a flavor that cannot ask
+    // for a stencil buffer answers 0, because a stencil test against no
+    // buffer passes everywhere and the draw code would never find out
+    const wantStencil = requestedStencil(spec);
+    const stencilSize = directStencilSize(caps.flavor, wantStencil);
+    if (wantStencil > stencilSize) warnDirectStencil(this, caps.flavor, wantStencil);
 
     return {
       backend: 'direct',
@@ -671,6 +688,9 @@ export default class App {
       class: 4, // TrueColor; the only class these buffers can be read as
       doubleBuffer: true, // a swap chain, always
       depthSize: spec.DEPTH_SIZE ?? 16,
+      // what the context will ask for (8 on appledri unless the spec says),
+      // carried here so the spec reaches getContext with the rest of it
+      stencilSize,
       // no flavor can allocate a multisampled window buffer yet; said out
       // loud so a caller can supersample instead of assuming MSAA
       samples: DIRECT_SAMPLES,

package/lib/fontconfig.js

@@ -133,8 +133,67 @@ function fcMatchError(err) {
   return err;
 }
 
+/**
+ * macOS's own face for a CSS generic family that fontconfig answers there
+ * with the wrong script's face, keyed by the generic.
+ *
+ * Only `sans-serif` is here, because it is the only generic fontconfig
+ * resolves to a CJK face on a Mac (see `platformFamilies`). `serif` and
+ * `monospace` land on PT Serif and Andale Mono, both of which set Latin,
+ * Cyrillic and Greek at their own widths.
+ */
+const DARWIN_GENERICS = new Map([['sans-serif', 'Helvetica']]);
+
+/**
+ * A family list with macOS's own face for a generic named ahead of it — on
+ * macOS only, and only for the generics in `DARWIN_GENERICS`. Everywhere
+ * else the list goes to fc-match exactly as it came.
+ *
+ * Homebrew's fontconfig (2.18) ships 48-guessfamily.conf, which tags a query
+ * naming a generic with that generic, and under it a `sans-serif` query
+ * ranks every face with "Sans" in its name ahead of all of 60-latin.conf's
+ * preferences — Verdana, Arial and Helvetica come in past the hundredth
+ * candidate. So `fc-match sans-serif` answers with whichever "…Sans…" face
+ * ranks first, and on a Mac that is Hiragino Sans: a Japanese face whose
+ * Cyrillic, Greek, `…` and `—` are full-width. "Мост" set in it is four
+ * em-wide cells, and CoreText sets it the same way — the advances are the
+ * font's own, so what is wrong is the face, not the shaping. Without that
+ * one file (XQuartz's fontconfig ships without it) the same query answers
+ * Verdana.
+ *
+ * Browsers never ask fontconfig on macOS, and all of them give `sans-serif`
+ * Helvetica. Naming it first does the same here, and the generic stays
+ * after it, so a codepoint Helvetica lacks still falls back through
+ * fontconfig's sans-serif list — CJK to Hiragino, as before.
+ *
+ * @param {string} family CSS-style family list, as FontManager hands it over
+ * @param {string} [platform] `process.platform`; a parameter so that a test
+ *   can ask for either answer on any machine
+ * @returns {string} the family list to hand fc-match
+ */
+export function platformFamilies(family, platform = globalThis.process?.platform) {
+  if (platform !== 'darwin') return family;
+  const names = String(family)
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+  const lower = names.map((name) => name.replace(/^["']|["']$/g, '').toLowerCase());
+  const out = [];
+  let changed = false;
+  for (let i = 0; i < names.length; i++) {
+    const face = DARWIN_GENERICS.get(lower[i]);
+    // a list that already names the face ahead of the generic needs nothing
+    if (face && !lower.slice(0, i).includes(face.toLowerCase())) {
+      out.push(face);
+      changed = true;
+    }
+    out.push(names[i]);
+  }
+  return changed ? out.join(',') : family;
+}
+
 function patternFor({ family, weight, style }) {
-  let fc = family || 'sans-serif';
+  let fc = platformFamilies(family || 'sans-serif');
   const fcWeight = normalizeWeight(weight);
   if (fcWeight !== undefined) fc += `:weight=${fcWeight}`;
   if (style && style.includes('italic')) fc += ':slant=italic';

package/lib/gl.js

@@ -535,6 +535,78 @@ export function warnDirectSamples(app, flavor, wanted) {
   );
 }
 
+/**
+ * The stencil bits a CGL context asks for when the config names no size:
+ * eight, what the Cocoa backend's GL surfaces carry (DEPTH24_STENCIL8), so
+ * a window on the `appledri` flavor has the same buffers whichever of the
+ * two macOS paths draws it. A stencil buffer costs next to nothing, and the
+ * failure without one is silent: a stencil test with no buffer behind it
+ * passes everywhere, so a stencil-then-cover fill does not fail — it fills
+ * its whole cover quad.
+ */
+export const DEFAULT_STENCIL_SIZE = 8;
+
+/**
+ * The stencil size a spec or config asks for, read the way the depth size
+ * is: `stencilSize` (a config `chooseGLConfig` answered) before
+ * `STENCIL_SIZE` (GLX's vocabulary). `undefined` when it names neither,
+ * which means "the flavor's default" rather than 0 — an explicit 0 asks for
+ * no stencil buffer and is honoured as such. `null` is GLX's "don't care"
+ * and reads as unnamed too.
+ */
+export function requestedStencil(spec = {}) {
+  const bits = spec.stencilSize ?? spec.STENCIL_SIZE;
+  if (bits === undefined || bits === null) return undefined;
+  return Number(bits) || 0;
+}
+
+/**
+ * The stencil bits a direct-backend window gets for a request, per flavor —
+ * the one place that decides it, as `DIRECT_SAMPLES` is for samples.
+ *
+ * - `appledri`: what was asked, `DEFAULT_STENCIL_SIZE` when nothing was. It
+ *   travels to `kCGLPFAStencilSize` on the CGL pixel format, which CGL
+ *   treats as a minimum.
+ * - `dri3`: 0, whatever was asked. x11-dri's `Gpu` builds its EGLConfig from
+ *   the colour format and a depth size and takes no stencil size, so none is
+ *   asked for — and EGL sorts configs smallest stencil first, so assume
+ *   none. There is nothing here to ask with; what can be done is say so
+ *   (`warnDirectStencil`). When the addon grows the option, this becomes the
+ *   request.
+ */
+export function directStencilSize(flavor, wanted) {
+  if (flavor === 'appledri') return wanted ?? DEFAULT_STENCIL_SIZE;
+  return 0;
+}
+
+/**
+ * Say — once per connection, on the console — that a stencil request cannot
+ * be met on this flavor.
+ *
+ * Unlike a missing sample buffer this is not a downgrade that merely looks
+ * worse: a stencil test against a framebuffer with no stencil buffer passes
+ * everywhere, so draw code built on it renders wrong instead of failing, and
+ * this warning and the `stencilSize` field are the only signals it gets.
+ */
+export function warnDirectStencil(app, flavor, wanted) {
+  if (app._warnedDirectStencil) return;
+  app._warnedDirectStencil = true;
+  console.warn(
+    `ntk: this GL request asks for STENCIL_SIZE=${wanted}, and the direct backend` +
+      `${flavor ? ` (${flavor} flavor)` : ''} cannot give its window a stencil buffer, so it has ` +
+      'stencilSize: 0 — and a stencil test with no buffer behind it passes everywhere.\n' +
+      '\n' +
+      '  The stencil size belongs to the EGLConfig x11-dri builds one layer below\n' +
+      '  ntk, and its Gpu takes no such option yet — there is nothing here to ask with.\n' +
+      '\n' +
+      '  Branch on config.stencilSize (or gl.stencilSize) rather than on having asked.\n' +
+      '  For a stencil buffer today: draw into a framebuffer of your own with a\n' +
+      '  DEPTH24_STENCIL8 renderbuffer attached, or use indirect GLX, where\n' +
+      "  STENCIL_SIZE picks an fbconfig that has one (glPolicy: 'indirect').\n" +
+      '  See docs/context-gles.md#stencil.'
+  );
+}
+
 /**
  * The backend `getContext('opengl')` should use right now, synchronously.
  *

package/lib/glx.js

@@ -227,11 +227,12 @@ function matchLegacy(configs, spec) {
  *   `null` means "don't care". `screen` picks the X screen (default 0),
  *   `visual` pins a specific visual id and skips the search.
  * @returns {Promise<{visual: number, depth: number, class: number,
- *   doubleBuffer: boolean, depthSize: number, samples: number|null,
- *   fbconfig: number|null, config: object}>} `samples` is the colour
- *   samples per pixel the chosen config has — 0 for no multisampling, and
- *   `null` only in the pinned-`visual` case, where no fbconfig was looked
- *   at to know.
+ *   doubleBuffer: boolean, depthSize: number, stencilSize: number|null,
+ *   samples: number|null, fbconfig: number|null, config: object}>}
+ *   `samples` is the colour samples per pixel the chosen config has — 0 for
+ *   no multisampling — and `stencilSize` its stencil bits; both are `null`
+ *   only in the pinned-`visual` case, where no fbconfig was looked at to
+ *   know.
  */
 export async function chooseGLXConfig(app, spec = {}) {
   const GLX = app.display.GLX;
@@ -268,6 +269,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       depthSize: toNumber(want.DEPTH_SIZE) || 0,
       // the caller pinned the visual, so nothing was chosen and no fbconfig
       // was read: unknown, which is not the same claim as "none"
+      stencilSize: null,
       samples: null,
       screen: screenNum,
       fbconfig: null,
@@ -286,6 +288,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.DOUBLEBUFFER,
       depthSize: cfg.DEPTH_SIZE || 0,
+      stencilSize: cfg.STENCIL_SIZE || 0,
       samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: cfg.FBCONFIG_ID,
@@ -307,6 +310,7 @@ export async function chooseGLXConfig(app, spec = {}) {
       class: info.visual.class,
       doubleBuffer: !!cfg.doubleBufferMode,
       depthSize: cfg.depthBits || 0,
+      stencilSize: cfg.stencilBits || 0,
       samples: cfg.SAMPLES || 0,
       screen: screenNum,
       fbconfig: null,

package/lib/renderingcontext_cgl.js

@@ -47,9 +47,11 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glError,
   loadDriAddon,
   requestedSamples,
+  requestedStencil,
   warnDirectSamples
 } from './gl.js';
 
@@ -134,6 +136,13 @@ does not make it retroactive. Either:
     const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, 'appledri', wantSamples);
 
+    /**
+     * Stencil bits the context asked CGL for: the config's `stencilSize` /
+     * `STENCIL_SIZE`, and 8 when it names none (`directStencilSize`). CGL
+     * takes the size as a minimum, so the buffer has at least this many.
+     */
+    this.stencilSize = directStencilSize('appledri', requestedStencil(config));
+
     this._screen = config.screen ?? 0;
     this._clientId = caps.appleClientId ?? dri.apple.clientId();
 
@@ -145,7 +154,11 @@ does not make it retroactive. Either:
     // covered (docs/context-gles.md#macos).
     try {
       this.ctx = new dri.apple.Context({
-        depthSize: config.depthSize ?? config.DEPTH_SIZE ?? 16
+        depthSize: config.depthSize ?? config.DEPTH_SIZE ?? 16,
+        // Without this the pixel format has no stencil buffer at all, and GL
+        // raises no error over it: a stencil test against a missing buffer
+        // passes everywhere, so a stencil-then-cover fill covers its whole quad.
+        stencilSize: this.stencilSize
       });
     } catch (err) {
       throw glError(

package/lib/renderingcontext_gles.js

@@ -21,10 +21,13 @@ import {
   DIRECT_SAMPLES,
   GLError,
   backendFor,
+  directStencilSize,
   glError,
   loadDriAddon,
   requestedSamples,
-  warnDirectSamples
+  requestedStencil,
+  warnDirectSamples,
+  warnDirectStencil
 } from './gl.js';
 import { GLSwapchain } from './glswapchain.js';
 
@@ -116,6 +119,17 @@ does not make it retroactive. Either:
     const wantSamples = Math.max(requestedSamples(config), Number(config.samples) || 0);
     if (wantSamples > DIRECT_SAMPLES) warnDirectSamples(app, caps.flavor, wantSamples);
 
+    /**
+     * Stencil bits the window's buffers have: 0 on this flavor, whatever the
+     * config asks for, because x11-dri's `Gpu` takes no stencil size to pass
+     * on (`directStencilSize`). A request for one is answered the way a
+     * sample count is — once, out loud — because a stencil test with no
+     * buffer behind it passes everywhere rather than failing.
+     */
+    const wantStencil = requestedStencil(config);
+    this.stencilSize = directStencilSize('dri3', wantStencil);
+    if (wantStencil > this.stencilSize) warnDirectStencil(app, 'dri3', wantStencil);
+
     const policy = app.glPolicy;
     this.gpu = sharedGpu(app, dri, {
       format: depth === 32 ? dri.FORMAT.ARGB8888 : dri.FORMAT.XRGB8888,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.8.1",
+  "version": "8.8.2",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",