ntk 8.18.1 → 8.20.0

package/README.md

@@ -136,7 +136,7 @@ parser, say — can import just that piece, and loads only what it needs:
 | `ntk/gl`            | `GLError`, `GL_MODES`, `DEFAULT_GL_POLICY`, …           | —                           |
 | `ntk/shadow-math`   | `shadowSigma`, `shadowReach`, `blurScale`, …            | —                           |
 | `ntk/shadow-tiles`  | `planShadowTiles`, `shadowTileAlpha`, …                 | —                           |
-| `ntk/image`         | `Image`, `decodeImage`, `loadImage`                     | `jpeg-js`, `pngjs`          |
+| `ntk/image`         | `Image`, `decodeImage`, `loadImage`, `exifOrientation`  | `jpeg-js`, `pngjs`          |
 | `ntk/svg`           | `SvgView` (default export)                              | `htmlparser2`, `domutils`   |
 | `ntk/font`          | `Font` (default export)                                 | `fontkit`                   |
 | `ntk/xembed`        | the XEmbed protocol ([docs/xembed.md](docs/xembed.md))  | `x11`                       |

package/lib/app.js

@@ -52,6 +52,39 @@ const DEFAULT_FRAME_INTERVAL = 16;
 const MIN_REFRESH_RATE = 20;
 const MAX_REFRESH_RATE = 1000;
 
+/**
+ * How many of the solids drawings make for themselves a connection keeps
+ * (`App#transientSolid`). A fade folds each new alpha into every colour it
+ * draws, so it makes a few a frame; a frame faded at one alpha draws with
+ * fewer than this, and finds them all again on the next.
+ */
+const TRANSIENT_SOLIDS = 256;
+
+/**
+ * How many of the solids contexts paint their colour styles with a
+ * connection keeps (`App#styleSolid`): `fillStyle`, `strokeStyle`, a
+ * `TextLayout` span's colour. An app's palette is far fewer; a colour
+ * animated through a transition or a tween is a new one every frame.
+ */
+const STYLE_SOLIDS = 1024;
+
+/** How many CSS colour strings it finds them by before starting over. */
+const STYLE_NAMES = 1024;
+
+// a solid, and on a server too old for CreateSolidFill the 1x1 pixmap it
+// repeats
+function freeSolid(picture) {
+  picture.destroy();
+  picture._sourcePixmap?.destroy();
+}
+
+// the value `key` names, taken out of `map`
+function take(map, key) {
+  const value = map.get(key);
+  if (value !== undefined) map.delete(key);
+  return value;
+}
+
 /**
  * A RandR mode's vertical refresh rate in Hz, or 0 when it does not describe
  * one.
@@ -147,9 +180,21 @@ export default class App {
     // client costs no I/O — discovery waits for the first page to bind.
     sharedGlyphsFor(this);
     this._cursors = null;
+    // the solids a caller holds for good (solidPicture)
     this._solidPictures = new Map();
-    // the same pictures by the CSS colour that asked for them (solidPictureOf)
+    // the solids contexts paint their colour styles with, least recently
+    // used first; a clock that ticks as they are made and moved up; and the
+    // same pictures by the CSS colour that asked for them (styleSolid)
+    this._styleSolids = new Map();
+    this._styleSolidLimit = STYLE_SOLIDS;
+    this._styleClock = 0;
     this._solidByName = new Map();
+    // style solids let go of in this job, freed once it has run
+    this._evictedSolids = [];
+    // the solids one drawing makes for itself, least recently used first
+    // (transientSolid)
+    this._transientSolids = new Map();
+    this._transientSolidLimit = TRANSIENT_SOLIDS;
     this._rasterizer = undefined;
     this._shm = undefined;
     this._extensionPromises = new Map();
@@ -959,14 +1004,18 @@ export default class App {
   }
 
   /**
-   * A repeating source Picture of one colour, for compositing. Components
-   * are 0..1 floats, premultiplied by alpha.
+   * A repeating source Picture of one colour, for compositing, held for as
+   * long as the connection is open. Components are 0..1 floats,
+   * premultiplied by alpha.
    *
-   * Cached per connection, not per context: colours a context uses are the
-   * app's palette, and `Surface.render` builds a context per call — a
-   * per-context cache made every render recreate its fill colours
-   * server-side. Nothing evicts; a solid is a few dozen bytes on the server
-   * and an app cycles through few colours. Freed in `close()`.
+   * Cached per connection, not per context: `Surface.render` builds a
+   * context per call, and a per-context cache made every render recreate
+   * its colours server-side. Nothing evicts: whoever asked may hold the
+   * picture as long as it likes — a caller what `createSolidPicture` handed
+   * back, a context its glyph source — so this is for the few colours an
+   * app holds. Freed in `close()`. A context's colour styles are
+   * `styleSolid`'s, and the colours a drawing makes for itself
+   * `transientSolid`'s: once a colour animates, neither is few.
    *
    * On RENDER >= 0.10 a solid is one CreateSolidFill request; an older
    * server (or a hand-built App that skipped the version handshake in
@@ -976,7 +1025,151 @@ export default class App {
     const key = `${r}|${g}|${b}|${a}`;
     let p = this._solidPictures.get(key);
     if (p) return p;
+    // one a style paints with, or a drawing made for itself, is held from
+    // here on: out of its LRU, rather than made a second time
+    p =
+      take(this._styleSolids, key) ??
+      take(this._transientSolids, key) ??
+      this._createSolid(key, r, g, b, a);
+    // and no LRU's clock ages it now (_usedStyle)
+    p._used = Infinity;
+    this._solidPictures.set(key, p);
+    return p;
+  }
 
+  /**
+   * The solid a context paints a colour style with — `fillStyle`,
+   * `strokeStyle`, a `TextLayout` span's colour: a CSS colour string, or a
+   * premultiplied `[r, g, b, a]`. A string that is not a colour throws, as
+   * `fillStyle` always has.
+   *
+   * Found by the string, where there is one: a UI sets the same few strings
+   * again on every paint — every box's background, every border — and the
+   * way to a solid is a parse, a premultiply and a key made of four numbers
+   * turned into text, where by the string it is one lookup.
+   *
+   * Not held for good, as `solidPicture`'s are: a colour animated through a
+   * transition or a tween is a new solid every frame, so the `STYLE_SOLIDS`
+   * most recently used are kept and the rest let go. One let go is marked
+   * `_evicted` at once, so that nothing hands it out again, and freed when
+   * the job that let it go has run. X runs a client's requests in order, so
+   * every request sent with it in that job reaches the server first: within
+   * a job, holding one is safe however many colours are asked for meanwhile
+   * — and a drawing does ask, taking its style before the shadow it paints
+   * first makes colours of its own. Past the job, whoever holds one keeps
+   * the style too, and asks again on finding the mark, as a context does
+   * for `fillStyle` and `strokeStyle` (its `_backgroundPicture`).
+   */
+  styleSolid(value) {
+    if (typeof value !== 'string') return this._styleSolid(value);
+    const p = this._solidByName.get(value);
+    if (p !== undefined && !p._evicted) return this._usedStyle(p);
+    const c = cssColor(value);
+    if (!c) throw new Error(`Not a color: ${JSON.stringify(value)}`);
+    const solid = this._styleSolid(c);
+    // spellings are unbounded too: an app animating a colour writes a new
+    // string every frame
+    if (this._solidByName.size >= STYLE_NAMES) this._solidByName.clear();
+    this._solidByName.set(value, solid);
+    return solid;
+  }
+
+  // styleSolid by the numbers: a premultiplied [r, g, b, a]
+  _styleSolid([r, g, b, a]) {
+    const key = `${r}|${g}|${b}|${a}`;
+    const held = this._solidPictures.get(key);
+    if (held) return held;
+    const lru = this._styleSolids;
+    let p = lru.get(key);
+    if (p) return this._usedStyle(p);
+    p = this._createSolid(key, r, g, b, a);
+    p._used = ++this._styleClock;
+    lru.set(key, p);
+    for (const [oldest, picture] of lru) {
+      if (lru.size <= this._styleSolidLimit || picture === p) break;
+      lru.delete(oldest);
+      this._evictStyle(picture);
+    }
+    return p;
+  }
+
+  /**
+   * A style solid asked for again: moved to the recent end of the LRU, but
+   * only once it has aged into the older half. Moved on every ask, a
+   * `fillStyle` set to a string it knows cost six times what the lookup
+   * does; this way it stays a lookup and a comparison, and a colour asked
+   * for every frame is still not the one let go.
+   */
+  _usedStyle(p) {
+    if (this._styleClock - p._used > this._styleSolidLimit / 2) {
+      const lru = this._styleSolids;
+      lru.delete(p._key);
+      lru.set(p._key, p);
+      p._used = ++this._styleClock;
+    }
+    return p;
+  }
+
+  // a style solid let go: marked, and freed once the job has run (styleSolid)
+  _evictStyle(picture) {
+    picture._evicted = true;
+    const evicted = this._evictedSolids;
+    evicted.push(picture);
+    if (evicted.length === 1) queueMicrotask(() => this._freeEvictedSolids());
+  }
+
+  _freeEvictedSolids() {
+    const evicted = this._evictedSolids;
+    this._evictedSolids = [];
+    for (const picture of evicted) freeSolid(picture);
+  }
+
+  /**
+   * A solid for the requests of one drawing call, and nothing after them:
+   * the colours a drawing makes for itself — a style with `globalAlpha`
+   * folded into it, or the alpha alone in a mask slot. A fade makes new ones
+   * nearly every frame; kept the way `solidPicture` keeps its own, every
+   * fade left frames × colours of them on the server until the connection
+   * closed. So these are kept apart: the `TRANSIENT_SOLIDS` most recently
+   * used, the least recent freed as the next is made. A drawing faded at
+   * one alpha frame after frame finds its few again each time.
+   *
+   * Freeing one is safe because X runs a client's requests in the order
+   * they were sent, so the FreePicture reaches the server after every
+   * request sent with the picture before it. What that cannot cover is a
+   * request sent after — hence the contract: use the solid in the requests
+   * of the call that asked for it, and drop it. Never keep one or hand it
+   * out. Once evicted its id goes back to the pool, and the next solid made
+   * can take it, in another colour.
+   *
+   * A colour the app keeps anyway, for a caller (`solidPicture`) or a style
+   * (`styleSolid`), is answered from there: at full opacity, a rounded
+   * box's corners paint with the style's own.
+   */
+  transientSolid(r, g, b, a) {
+    const key = `${r}|${g}|${b}|${a}`;
+    let p = this._solidPictures.get(key) ?? this._styleSolids.get(key);
+    if (p) return p;
+    const lru = this._transientSolids;
+    p = lru.get(key);
+    if (p) {
+      // Map iteration order is insertion order — re-insert to mark recent
+      lru.delete(key);
+      lru.set(key, p);
+      return p;
+    }
+    p = this._createSolid(key, r, g, b, a);
+    lru.set(key, p);
+    for (const [oldest, picture] of lru) {
+      if (lru.size <= this._transientSolidLimit || picture === p) break;
+      lru.delete(oldest);
+      freeSolid(picture);
+    }
+    return p;
+  }
+
+  _createSolid(key, r, g, b, a) {
+    let p;
     const Render = this.display.Render;
     const [major, minor] = Render.version || [0, 0];
     if (major > 0 || minor >= 10) {
@@ -994,27 +1187,10 @@ export default class App {
     // what it paints with, so a drawing can fold `globalAlpha` into it: glyphs
     // composite straight from their source, with no mask slot to carry one
     p._rgba = Object.freeze([r, g, b, a]);
-    this._solidPictures.set(key, p);
-    return p;
-  }
-
-  /**
-   * The solid picture a CSS colour string paints with. A UI sets the same few
-   * strings again on every paint — every box's background, every border —
-   * and the way to `solidPicture` is a parse, a premultiply and a key made of
-   * four numbers turned into text; by the string it is one lookup. Throws, as
-   * `fillStyle` always has, for a string that is not a colour.
-   */
-  solidPictureOf(value) {
-    let p = this._solidByName.get(value);
-    if (p !== undefined) return p;
-    const c = cssColor(value);
-    if (!c) throw new Error(`Not a color: ${JSON.stringify(value)}`);
-    p = this.solidPicture(c[0], c[1], c[2], c[3]);
-    // spellings are unbounded where solids are not: an app animating a
-    // colour writes a new string every frame
-    if (this._solidByName.size >= 1024) this._solidByName.clear();
-    this._solidByName.set(value, p);
+    // and what the style LRU needs of it (styleSolid)
+    p._key = key;
+    p._evicted = false;
+    p._used = 0;
     return p;
   }
 
@@ -1031,13 +1207,16 @@ export default class App {
     // shadow coverage is cached per connection for the same reason solids
     // are: the contexts that drew it are long gone (see lib/shadow.js)
     dropShadowSurfaces(this);
-    // shared by every context that ever asked (see solidPicture), so their
-    // lifetime is the connection's — context teardown must not free them
-    for (const picture of this._solidPictures.values()) {
-      picture.destroy();
-      picture._sourcePixmap?.destroy();
-    }
+    // shared by every context that ever asked (see solidPicture), so they are
+    // the app's to free, never a context's teardown; whatever is left goes
+    // with the connection, the style solids this job let go of included
+    for (const picture of this._solidPictures.values()) freeSolid(picture);
+    for (const picture of this._styleSolids.values()) freeSolid(picture);
+    for (const picture of this._transientSolids.values()) freeSolid(picture);
+    this._freeEvictedSolids();
     this._solidPictures.clear();
+    this._styleSolids.clear();
+    this._transientSolids.clear();
     this._solidByName.clear();
     // GPU contexts are shared by every direct GL surface on this connection
     // (see renderingcontext_gles.js), so they outlive individual contexts and

package/lib/image.js

@@ -107,13 +107,28 @@ export class Image {
 
 const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47];
 
+const ORIENTATIONS = ['from-image', 'none'];
+
 /**
  * Decode a PNG or JPEG buffer (sniffed by magic bytes) into an Image.
  *
+ * A JPEG comes out the way up its EXIF Orientation says, as a browser shows
+ * it (CSS `image-orientation: from-image`, the default since 2020) and as
+ * every phone photo expects: a camera held upright writes the sensor's rows
+ * as they were read, sideways, and records the turn in the tag rather than
+ * in the pixels. `{ imageOrientation: 'none' }` keeps the stored pixels, for
+ * an app that applies the turn itself — `exifOrientation()` says which.
+ *
  * @param {Buffer|Uint8Array} buffer encoded image bytes
+ * @param {{ imageOrientation?: 'from-image' | 'none' }} [options]
  * @returns {Image}
  */
-export function decodeImage(buffer) {
+export function decodeImage(buffer, { imageOrientation = 'from-image' } = {}) {
+  if (!ORIENTATIONS.includes(imageOrientation)) {
+    throw new Error(
+      `decodeImage: imageOrientation must be 'from-image' or 'none', not ${JSON.stringify(imageOrientation)}`
+    );
+  }
   const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
   if (buf.length > 4 && PNG_MAGIC.every((b, i) => buf[i] === b)) {
     const png = PNG.sync.read(buf);
@@ -121,6 +136,8 @@ export function decodeImage(buffer) {
   }
   if (buf.length > 2 && buf[0] === 0xff && buf[1] === 0xd8) {
     const img = jpeg.decode(buf, { useTArray: true, maxMemoryUsageInMB: 512 });
+    const orientation = imageOrientation === 'none' ? 1 : exifOrientation(buf);
+    if (orientation !== 1) return new Image(orientPixels(img, orientation));
     return new Image({ width: img.width, height: img.height, data: Buffer.from(img.data) });
   }
   throw new Error('decodeImage: unsupported image format (PNG and JPEG are supported)');
@@ -134,16 +151,120 @@ export function decodeImage(buffer) {
  *
  * @param {string|URL|Buffer|Uint8Array} source file path (or file URL), or
  *   an in-memory buffer of encoded bytes
+ * @param {{ imageOrientation?: 'from-image' | 'none' }} [options] as for
+ *   `decodeImage`
  * @returns {Promise<Image>}
  */
-export async function loadImage(source) {
+export async function loadImage(source, options) {
   if (typeof source === 'string' || source instanceof URL) {
     // lazy builtin lookup: browser bundles must not depend on node:fs
     const fsp = builtin('node:fs/promises');
     if (!fsp) {
       throw new Error('loadImage: file paths need node — pass the encoded bytes instead');
     }
-    return decodeImage(await fsp.readFile(source));
+    return decodeImage(await fsp.readFile(source), options);
+  }
+  return decodeImage(source, options);
+}
+
+const APP1 = 0xe1;
+const SOS = 0xda;
+const EOI = 0xd9;
+const ORIENTATION_TAG = 0x0112;
+const SHORT = 3;
+
+/**
+ * The EXIF Orientation of a JPEG, 1 to 8 — the TIFF numbering, where 1 is
+ * as stored, 2 to 4 mirror left to right, turn half way and mirror top to
+ * bottom, 6 and 8 turn a quarter clockwise and anticlockwise, and 5 and 7
+ * are those quarter turns mirrored. 1 for anything else: no Exif, no tag, a
+ * value out of range, a segment cut short, or bytes that are not a JPEG.
+ *
+ * Only the tag itself is read: the first APP1 segment that carries Exif,
+ * tag 0x0112 of its IFD0, and only as the one SHORT the standard defines it
+ * as. The segments before the scan are walked by their lengths, so the cost
+ * is a few reads whatever the size of the image.
+ *
+ * @param {Buffer|Uint8Array} buf encoded image bytes
+ * @returns {number}
+ */
+export function exifOrientation(buf) {
+  if (!(buf.length > 2 && buf[0] === 0xff && buf[1] === 0xd8)) return 1;
+  for (let at = 2; at + 4 <= buf.length; ) {
+    if (buf[at] !== 0xff) return 1;
+    const marker = buf[at + 1];
+    // a marker may follow any number of 0xff fill bytes
+    if (marker === 0xff) {
+      at++;
+      continue;
+    }
+    // the metadata segments all come before the scan
+    if (marker === SOS || marker === EOI) return 1;
+    const end = at + 2 + ((buf[at + 2] << 8) | buf[at + 3]);
+    if (end < at + 4 || end > buf.length) return 1;
+    // the payload opens with "Exif\0\0" and the TIFF header after it, 14 bytes
+    if (marker === APP1 && end - (at + 4) >= 14 && isExifHeader(buf, at + 4)) {
+      return ifd0Orientation(buf, at + 10, end);
+    }
+    at = end;
+  }
+  return 1;
+}
+
+/** "Exif\0\0", which tells Exif's APP1 from XMP's */
+function isExifHeader(buf, at) {
+  return (
+    buf[at] === 0x45 && buf[at + 1] === 0x78 && buf[at + 2] === 0x69 && buf[at + 3] === 0x66 &&
+    buf[at + 4] === 0 && buf[at + 5] === 0
+  );
+}
+
+/** The Orientation in the IFD0 of the TIFF structure from `tiff` to `end`. */
+function ifd0Orientation(buf, tiff, end) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  // 'II' is little-endian, 'MM' big; both are written, by cameras and by editors
+  const little = buf[tiff] === 0x49 && buf[tiff + 1] === 0x49;
+  if (!little && !(buf[tiff] === 0x4d && buf[tiff + 1] === 0x4d)) return 1;
+  if (view.getUint16(tiff + 2, little) !== 42) return 1;
+  const ifd = tiff + view.getUint32(tiff + 4, little);
+  if (ifd + 2 > end) return 1;
+  const count = view.getUint16(ifd, little);
+  for (let i = 0, entry = ifd + 2; i < count && entry + 12 <= end; i++, entry += 12) {
+    if (view.getUint16(entry, little) !== ORIENTATION_TAG) continue;
+    if (view.getUint16(entry + 2, little) !== SHORT || view.getUint32(entry + 4, little) !== 1) return 1;
+    // one SHORT sits in the first two bytes of the entry's value field
+    const value = view.getUint16(entry + 8, little);
+    return value >= 1 && value <= 8 ? value : 1;
+  }
+  return 1;
+}
+
+/**
+ * Stored RGBA pixels turned the way `orientation` says, into a new buffer:
+ * where stored pixel (x, y) lands is `start + x * dx + y * dy`, in pixels of
+ * the result, which is `height` wide for the four that turn a quarter. Each
+ * pixel moves as one 32-bit word, so the byte order is never looked at.
+ */
+function orientPixels({ width: w, height: h, data }, orientation) {
+  const n = w * h;
+  const [start, dx, dy] = [
+    null,
+    [0, 1, w], // as stored
+    [w - 1, -1, w], // mirrored left to right
+    [n - 1, -1, -w], // half turn
+    [n - w, 1, -w], // mirrored top to bottom
+    [0, h, 1], // transposed: mirrored, then a quarter turn anticlockwise
+    [h - 1, h, -1], // a quarter turn clockwise
+    [n - 1, -h, -1], // transversed: mirrored, then a quarter turn clockwise
+    [n - h, -h, 1] // a quarter turn anticlockwise
+  ][orientation];
+  // jpeg-js hands over a fresh array, so its offset is word-aligned
+  const from = new Uint32Array(data.buffer, data.byteOffset, n);
+  const out = Buffer.alloc(n * 4);
+  const to = new Uint32Array(out.buffer, out.byteOffset, n);
+  for (let y = 0, i = 0; y < h; y++) {
+    for (let x = 0, j = start + y * dy; x < w; x++, j += dx) to[j] = from[i++];
   }
-  return decodeImage(source);
+  const turned = orientation >= 5;
+  return { width: turned ? h : w, height: turned ? w : h, data: out };
 }

package/lib/index.js

@@ -20,7 +20,7 @@ import { decodeKey, groupForState } from './keyboard.js';
 import Pixmap from './pixmap.js';
 import Picture from './picture.js';
 import Region from './region.js';
-import { Image, decodeImage, loadImage } from './image.js';
+import { Image, decodeImage, exifOrientation, loadImage } from './image.js';
 import {
   ImageData,
   fromStraightRgba,
@@ -274,6 +274,7 @@ export {
   unpackIcons,
   decodeImage,
   loadImage,
+  exifOrientation,
   Path2D,
   parseSvgPath,
   Font,