@react-x11/components 0.9.0 → 0.11.0

package/dist/maps/gl/text.js

@@ -13,11 +13,31 @@
 // A label is rasterized **whole**, not glyph by glyph: placement sets every
 // line label on a straight stretch, so a label is one rigid piece of type —
 // one textured quad, rotated as a unit — and shaping, kerning and scripts
-// stay the text engine's business. What is stored is **coverage**, drawn in
-// white and read from the alpha channel; colour and halo are the shader's
-// (see `./shaders.ts`), so one raster serves every palette and a
-// light-to-dark switch re-rasterizes nothing.
+// stay the text engine's business.
+//
+// **One raster per string, at every size.** The engine sets a string once,
+// at the atlas's `base` size, as coverage; what is stored is its signed
+// distance field (`src/internal/sdf.ts`), one byte a texel. A name drawn at 11 pixels
+// and the same name at 20 are one raster scaled, so a zoom ramp that grows
+// the type asks for nothing new, and a halo of any width is a threshold on
+// the same distances. Colour and halo are the shader's (see `./shaders.ts`),
+// so one raster serves every palette and a light-to-dark switch
+// re-rasterizes nothing. What it costs is the engine's hinting — the text
+// is its outline, scaled — which at map-label sizes is the right trade:
+// one shaping and one readback per name for the life of the atlas.
+//
+// An icon's two pieces (`../icons.ts`) are fields here too, drawn as
+// coverage from the same paths the retained renderer fills, at the same
+// base size, and coloured by the same shader.
 import { Surface } from 'react-x11/ntk';
+import { traceGlyph, tracePlate } from '../icons.js';
+import { SDF_EDGE, distanceField } from '../../internal/sdf.js';
+/** Whether a context can fill a path — what an icon is drawn with. */
+function fills(ctx) {
+    return (typeof ctx.beginPath === 'function' &&
+        typeof ctx.arc === 'function' &&
+        typeof ctx.fill === 'function');
+}
 /** The offscreen surface a batch is set on, in device pixels. A readback
  *  has to stay inside it — X answers a GetImage past a pixmap's edge with
  *  BadMatch — so a batch is whatever fits. */
@@ -34,6 +54,9 @@ export class SurfaceTextEngine {
     _layouts = new Map();
     _surface = null;
     _ctx = null;
+    /** Whether the layouts answer their own coverage: unknown until a string
+     *  asks, and false for good once one does not. */
+    _coverage = null;
     constructor(app, fonts, family) {
         this._app = app;
         this._fonts = fonts;
@@ -70,13 +93,65 @@ export class SurfaceTextEngine {
         const layout = this._layout(text, size);
         return { width: Math.ceil(layout.width), height: Math.ceil(layout.height) };
     }
+    /**
+     * Strings the layouts set themselves, where the engine answers a layout's
+     * coverage (react-x11#673): no staging surface and no readback. The rest —
+     * icons, which are paths, and every string on an engine that cannot — go
+     * through the surface.
+     */
+    /**
+     * A string the layout sets itself, synchronously, where the engine
+     * answers a layout's coverage — no surface, no readback, nothing to wait
+     * for. `undefined` for an icon, and for every string once the engine has
+     * shown it cannot.
+     */
+    rasterizeNow(item, pad) {
+        if (item.icon || this._coverage === false)
+            return undefined;
+        const coverage = this._layout(item.text, item.size).coverage?.({ pad }) ?? null;
+        if (!coverage) {
+            if (this._coverage === null)
+                this._coverage = false;
+            return undefined;
+        }
+        this._coverage = true;
+        return coverage.width > STAGING_WIDTH || coverage.height > STAGING_HEIGHT
+            ? null // wider than the surface could set: never drawn, as there
+            : {
+                width: coverage.width,
+                height: coverage.height,
+                pixels: coverage.data,
+                stride: 1,
+            };
+    }
     async rasterize(items, pad) {
+        if (this._coverage === false)
+            return this._stage(items, pad);
+        const out = new Array(items.length);
+        const rest = [];
+        items.forEach((item, i) => {
+            const raster = this.rasterizeNow(item, pad);
+            if (raster === undefined) {
+                rest.push(i);
+                return;
+            }
+            out[i] = raster;
+        });
+        if (rest.length === 0)
+            return out;
+        const staged = await this._stage(rest.map((i) => items[i]), pad);
+        rest.forEach((i, k) => (out[i] = staged[k]));
+        return out;
+    }
+    async _stage(items, pad) {
         const places = [];
         let x = 0;
         let y = 0;
         let row = 0;
         for (const item of items) {
-            const box = this.measure(item.text, item.size);
+            const box = item.icon
+                ? { width: Math.ceil(item.size), height: Math.ceil(item.size) }
+                : this.measure(item.text, item.size);
             const w = box.width + pad * 2;
             const h = box.height + pad * 2;
             if (w > STAGING_WIDTH || h > STAGING_HEIGHT) {
@@ -112,19 +187,48 @@ export class SurfaceTextEngine {
         const started = now();
         // The rows drawn into: what is read back, and no more.
         let used = 0;
+        let drawn = 0;
         items.forEach((item, i) => {
             const place = places[i];
             if (!place)
                 return;
             // Drawing is this thread's time; past the budget the rest wait for
-            // the next batch.
-            if (now() - started > DRAW_BUDGET_MS) {
+            // the next batch — all but the first. A pause before it, a collection
+            // or a slow runner, deferred every string: nothing drawn, a readback of
+            // no rows, and a throw out of the frame; and a machine that slow would
+            // never have set one.
+            if (drawn > 0 && now() - started > DRAW_BUDGET_MS) {
                 places[i] = undefined;
                 return;
             }
-            this._layout(item.text, item.size).draw(ctx, place.x + pad, place.y + pad);
+            if (item.icon) {
+                // White, like the strings: coverage, coloured by the shader.
+                if (!fills(ctx)) {
+                    places[i] = null;
+                    return;
+                }
+                const half = item.size / 2;
+                const cx = place.x + pad + half;
+                const cy = place.y + pad + half;
+                ctx.fillStyle = '#ffffff';
+                ctx.beginPath();
+                if (item.icon.part === 'plate')
+                    tracePlate(ctx, cx, cy, item.size);
+                else
+                    traceGlyph(ctx, item.icon.name, cx, cy, item.size);
+                ctx.fill();
+            }
+            else {
+                this._layout(item.text, item.size).draw(ctx, place.x + pad, place.y + pad);
+            }
             used = Math.max(used, place.y + place.h);
+            drawn += 1;
         });
+        // nothing drawn — every icon here had nothing to fill with — is nothing
+        // to read back
+        if (drawn === 0) {
+            return places.map((p) => (p === null ? null : undefined));
+        }
         const image = await ctx.getImageData(0, 0, STAGING_WIDTH, used);
         return places.map((place) => {
             if (!place)
@@ -148,15 +252,31 @@ export class SurfaceTextEngine {
         this._layouts.clear();
     }
 }
-const keyOf = (text, size) => `${size}|${text}`;
+/** A string's key: the text alone, because one field serves every size. */
+const keyOf = (text) => `|${text}`;
+/** An icon piece's key: `#` where a string's has `|`, so no string can
+ *  be taken for one. */
+const iconKey = (name, part) => `#${part}:${name}`;
+/**
+ * Texels the drawn quad leaves off each side of a field: bilinear samples
+ * at its edge then stay inside the field's own margin, never reaching the
+ * shelf's unwritten rows or a neighbour.
+ */
+export const QUAD_INSET = 1;
 /**
- * The widest halo a raster's margin holds, in pixels. The drawn quad sits
- * {@link quadInset} inside the margin and a halo samples up to this far
- * past the quad, so its samples stay a texel inside the raster's own clear
- * margin and never reach a neighbour's.
+ * How far past the glyphs' edge a field can see, in its own texels — the
+ * widest halo it holds, and the reach of its distances before they
+ * saturate — for a field set with `pad` texels of margin and `pad` of
+ * spread. Scale by the drawn size over the base for screen pixels.
  */
-export const haloReach = (pad) => Math.max(0, Math.floor((pad - 2) / 2));
-export const quadInset = (pad) => pad - haloReach(pad) - 1;
+export const fieldReach = (pad) => Math.max(0, Math.min(pad * SDF_EDGE, pad - QUAD_INSET) - 0.5);
+/** The base size a display scale sets fields at, in device pixels: 16 at
+ *  1x, 32 at 2x — the size most map labels are drawn at or just under, so
+ *  a field is mostly sampled down, where it is sharpest. */
+export const fieldBase = (scale) => Math.round(16 * Math.min(2, Math.max(1, scale)));
+/** A field's margin and spread at a base size: room for a halo of a
+ *  quarter of the type's height. */
+export const fieldPad = (base) => Math.ceil(base * 0.375);
 /** Strings a frame measures however little budget it has left, so a frame
  *  that starts late still makes progress. One: on X11 a string's first
  *  measurement can cost milliseconds, and a floor of several put a pan
@@ -189,8 +309,11 @@ const KEEP_FRAMES = 120;
  */
 export class LabelAtlas {
     size;
-    /** Clear margin rasterized around every string, in pixels — what a halo
-     *  grows into, and what keeps it from sampling a neighbour. */
+    /** The device-pixel size every string and icon is set at: a label drawn
+     *  at `size` scales its field by `size / base`. */
+    base;
+    /** The margin set around every field, in its texels, which is also the
+     *  distance its values span — what a halo grows into. */
     pad;
     /** A frame's measuring ran out of budget: there is more to place. */
     starved = false;
@@ -199,8 +322,15 @@ export class LabelAtlas {
     _entries = new Map();
     /** Entries the texture does not have where they are, oldest first. */
     _uploads = [];
+    /** Drawable entries a compaction moved: all of them go up in the next
+     *  frame, ahead of any cap, before it draws. */
+    _moved = [];
     _wanted = new Map();
     _failed = new Set();
+    /** Rasters read back and waiting for their fields, oldest first — asked
+     *  for as much as anything in `_wanted`, so a frame never asks again. */
+    _fieldQueue = [];
+    _queued = new Set();
     _measured = new Map();
     _busy = false;
     _shelves = [];
@@ -208,14 +338,16 @@ export class LabelAtlas {
     _frame = 0;
     _deadline = Infinity;
     _measures = 0;
-    constructor(engine, options) {
+    constructor(engine, options = {}) {
         this._engine = engine;
         this.size = options.size ?? 2048;
-        this.pad = options.pad;
+        this.base = options.base ?? fieldBase(1);
+        this.pad = options.pad ?? fieldPad(this.base);
     }
-    /** Strings asked for and not yet rasterized, or a batch in flight. */
+    /** Strings asked for and not yet set: waiting, being read back, or
+     *  waiting for their fields. */
     get pending() {
-        return this._busy || this._wanted.size > 0;
+        return this._busy || this._wanted.size > 0 || this._fieldQueue.length > 0;
     }
     /** Rasters waiting for the texture. */
     get uploading() {
@@ -231,47 +363,68 @@ export class LabelAtlas {
         this._measures = 0;
         this.starved = false;
     }
-    /** The box a string sets in, or null when this frame's budget is spent. */
+    /** The box a string sets in at `size`, or null when this frame's budget
+     *  is spent. Measured once, at the base size, and scaled — the same
+     *  arithmetic that scales its field, so the box placement collides and
+     *  the quad the frame draws are one size. */
     measure(text, size) {
-        const key = keyOf(text, size);
-        const hit = this._measured.get(key);
-        if (hit)
-            return hit;
-        const engine = this._engine;
-        if (!engine)
-            return null;
-        if (this._measures >= MIN_MEASURES && now() > this._deadline) {
-            this.starved = true;
-            return null;
+        const key = keyOf(text);
+        let box = this._measured.get(key);
+        if (!box) {
+            const engine = this._engine;
+            if (!engine)
+                return null;
+            if (this._measures >= MIN_MEASURES && now() > this._deadline) {
+                this.starved = true;
+                return null;
+            }
+            this._measures++;
+            box = engine.measure(text, this.base);
+            if (this._measured.size > 20000)
+                this._measured.clear();
+            this._measured.set(key, box);
         }
-        this._measures++;
-        const box = engine.measure(text, size);
-        if (this._measured.size > 20000)
-            this._measured.clear();
-        this._measured.set(key, box);
-        return box;
+        const k = size / this.base;
+        return { width: box.width * k, height: box.height * k };
+    }
+    /** The string's field, once the texture has it; null until then —
+     *  asking is what gets it set. One field whatever size it is drawn at. */
+    entry(text) {
+        return this._lookup(keyOf(text), text, null, 'plate');
     }
-    /** The string's raster, once the texture has it; null until then —
-     *  asking is what gets it rasterized. */
-    entry(text, size) {
-        const key = keyOf(text, size);
+    /** One piece of an icon, as {@link entry} answers for a string. */
+    icon(name, part) {
+        return this._lookup(iconKey(name, part), '', name, part);
+    }
+    _lookup(key, text, icon, part) {
         const entry = this._entries.get(key);
         if (entry) {
             entry.used = this._frame;
             return entry.ready ? entry : null;
         }
-        if (!this._failed.has(key) && !this._wanted.has(key)) {
-            this._wanted.set(key, { text, size });
+        if (!this._failed.has(key) &&
+            !this._wanted.has(key) &&
+            !this._queued.has(key)) {
+            const size = this.base;
+            this._wanted.set(key, icon ? { text, size, icon: { name: icon, part } } : { text, size });
         }
         return null;
     }
+    /** Whether an icon can never be drawn — the engine has no path to fill
+     *  it with. A name set beside it is then set alone. */
+    iconFailed(name) {
+        return (this._failed.has(iconKey(name, 'plate')) ||
+            this._failed.has(iconKey(name, 'glyph')));
+    }
     /** Start rasterizing what has been asked for, unless a batch is out. */
     pump() {
         const engine = this._engine;
         if (!engine || this._busy || this._wanted.size === 0)
             return;
+        const keys = [];
         const batch = [];
-        for (const item of this._wanted.values()) {
+        for (const [key, item] of this._wanted) {
+            keys.push(key);
             batch.push(item);
             if (batch.length >= BATCH)
                 break;
@@ -282,11 +435,23 @@ export class LabelAtlas {
             rasters.forEach((raster, i) => {
                 if (raster === undefined)
                     return;
-                const key = keyOf(batch[i].text, batch[i].size);
+                const key = keys[i];
                 this._wanted.delete(key);
-                if (raster === null || !this._add(key, raster))
+                // A string with no raster never will have one; a raster with no
+                // room is a fact about this moment, and the string is asked for
+                // again by the next frame that still shows it.
+                if (raster === null) {
                     this._failed.add(key);
+                }
+                else {
+                    this._fieldQueue.push({ key, raster });
+                    this._queued.add(key);
+                }
             });
+            // The staging surface is free again as soon as the pixels are
+            // copied out, so the next batch is read back while this one waits
+            // for its fields; and a frame is asked for, to make them.
+            this.pump();
             this.onChange?.();
         }, () => {
             // A readback that fails once fails every time (no surface, a
@@ -297,26 +462,108 @@ export class LabelAtlas {
             this.onChange?.();
         });
     }
-    /** Up to `max` rasters for the texture, oldest first. The renderer marks
-     *  each `ready` once it is uploaded. */
+    /** Rasters for the texture: every one a compaction moved, then up to
+     *  `max` new ones, oldest first. The renderer marks each `ready` once it
+     *  is uploaded — a moved one already is, because the frame that takes it
+     *  draws after taking it. */
     takeUploads(max) {
-        return this._uploads.splice(0, max);
+        const moved = this._moved;
+        this._moved = [];
+        return moved.length > 0
+            ? moved.concat(this._uploads.splice(0, max))
+            : this._uploads.splice(0, max);
     }
     /** The texture is new, and has none of it: everything goes up again. */
     restart() {
         for (const entry of this._entries.values())
             entry.ready = false;
         this._uploads = [...this._entries.values()];
+        this._moved = [];
     }
     dispose() {
         this._engine?.dispose();
         this._engine = null;
+        this._fieldQueue = [];
+        this._queued.clear();
+    }
+    /** Read back and waiting for their fields: another frame is worth
+     *  drawing, to make them. */
+    get fielding() {
+        return this._fieldQueue.length > 0;
+    }
+    /**
+     * Make fields for what has been read back until `deadline` — at least
+     * one — in the frame, whose own draw then takes them into the texture.
+     *
+     * A field is about 0.2 ms. A batch of them made as it landed was 4-9 ms
+     * beside the frames, measured as event-loop stalls on a jump to a view
+     * whose every name was new; slices on timers of their own each waited
+     * behind a frame, and names arrived late. In the frame, on a budget,
+     * they are made at a known cost and drawn the frame after.
+     */
+    /**
+     * Set what placement asked for, in the frame, until `deadline` (at least
+     * one): what was read back already, then every string the engine can set
+     * synchronously. What is set here is drawable in this frame — it goes
+     * into the texture ahead of any cap, before this frame draws (the
+     * `labelsWhileMoving` path, `view.ts`). Icons, and an engine with no
+     * synchronous path, still go through {@link pump}.
+     */
+    setNow(deadline) {
+        const engine = this._engine;
+        if (!engine)
+            return;
+        let made = 0;
+        while (this._fieldQueue.length > 0 && (made === 0 || now() < deadline)) {
+            const { key, raster } = this._fieldQueue.shift();
+            this._queued.delete(key);
+            this._add(key, raster.width, raster.height, this._field(raster), true);
+            made++;
+        }
+        if (!engine.rasterizeNow)
+            return;
+        for (const [key, item] of this._wanted) {
+            if (made > 0 && now() >= deadline) {
+                this.starved = true;
+                break;
+            }
+            const raster = engine.rasterizeNow(item, this.pad);
+            if (raster === undefined)
+                continue;
+            this._wanted.delete(key);
+            if (raster === null) {
+                this._failed.add(key);
+                continue;
+            }
+            this._add(key, raster.width, raster.height, this._field(raster), true);
+            made++;
+        }
+    }
+    makeFields(deadline) {
+        if (!this._engine)
+            return;
+        let made = 0;
+        while (this._fieldQueue.length > 0 && (made === 0 || now() < deadline)) {
+            const { key, raster } = this._fieldQueue.shift();
+            this._queued.delete(key);
+            this._add(key, raster.width, raster.height, this._field(raster));
+            made++;
+        }
+    }
+    /** A raster's coverage as its distance field. The coverage is the
+     *  readback's alpha; the field spans `pad` texels either side of the
+     *  edge, which is the margin the engine set it with. */
+    _field(raster) {
+        const stride = raster.stride ?? 4;
+        return distanceField(raster.pixels, raster.width, raster.height, this.pad, stride, stride === 4 ? 3 : 0);
     }
-    _add(key, raster) {
-        let place = this._allocate(raster.width, raster.height);
-        if (!place) {
+    _add(key, width, height, pixels, 
+    /** Drawable in this frame: uploaded ahead of any cap before it draws. */
+    immediate = false) {
+        let place = this._allocate(width, height) ?? this._reuseShelf(width, height);
+        if (!place && this._compactable()) {
             this._compact();
-            place = this._allocate(raster.width, raster.height);
+            place = this._allocate(width, height);
         }
         if (!place)
             return false;
@@ -324,14 +571,17 @@ export class LabelAtlas {
             key,
             x: place.x,
             y: place.y,
-            width: raster.width,
-            height: raster.height,
-            pixels: raster.pixels,
-            ready: false,
+            width,
+            height,
+            pixels,
+            ready: immediate,
             used: this._frame,
         };
         this._entries.set(key, entry);
-        this._uploads.push(entry);
+        if (immediate)
+            this._moved.push(entry);
+        else
+            this._uploads.push(entry);
         return true;
     }
     /** A shelf packer: rows of one height class (rounded up to 8 pixels),
@@ -354,9 +604,72 @@ export class LabelAtlas {
         this._top += height;
         return { x: 0, y: shelf.y };
     }
+    /**
+     * Room made in place: the shelf of this height whose rasters were drawn
+     * longest ago, emptied and filled again from its left.
+     *
+     * **Nothing that stays moves.** A compaction moves every raster it keeps,
+     * and a moved raster is not drawn until it is in the texture again — at
+     * {@link takeUploads}' pace, so every label on screen went out together
+     * and came back over the next few frames, at full opacity. A full atlas
+     * is the ordinary state of a session (a thousand strings at 1x, a quarter
+     * of that at 2x), so that was a flash of the whole label layer at the end
+     * of most settles. A shelf any label of the last two frames stands on is not
+     * taken: what is dropped is off screen, and asked for again if it
+     * returns.
+     */
+    _reuseShelf(w, h) {
+        if (w > this.size)
+            return null;
+        const height = Math.ceil(h / 8) * 8;
+        const newest = new Map();
+        for (const entry of this._entries.values()) {
+            const seen = newest.get(entry.y);
+            if (seen === undefined || entry.used > seen)
+                newest.set(entry.y, entry.used);
+        }
+        let shelf = null;
+        // Not a shelf any label of this frame or the last stands on: fields can
+        // be made before a frame's labels are batched (`setNow`), when a label
+        // still fading out has not been asked for yet.
+        let oldest = this._frame - 1;
+        for (const candidate of this._shelves) {
+            if (candidate.height !== height)
+                continue;
+            const used = newest.get(candidate.y) ?? -Infinity;
+            if (used < oldest) {
+                oldest = used;
+                shelf = candidate;
+            }
+        }
+        if (!shelf)
+            return null;
+        const y = shelf.y;
+        for (const [key, entry] of this._entries) {
+            if (entry.y === y)
+                this._entries.delete(key);
+        }
+        this._uploads = this._uploads.filter((entry) => entry.y !== y);
+        this._moved = this._moved.filter((entry) => entry.y !== y);
+        shelf.x = w;
+        return { x: 0, y };
+    }
+    /** Whether a compaction would free anything: something kept past its
+     *  last use. One that keeps everything only moves it — every label on
+     *  screen out of the texture for the frames its upload takes, for no
+     *  room at all. */
+    _compactable() {
+        for (const entry of this._entries.values()) {
+            if (entry.used < this._frame - KEEP_FRAMES)
+                return true;
+        }
+        return false;
+    }
     /** Drop what has not been drawn for a while and pack the rest again,
-     *  tallest first. Everything kept has moved, so none of it is drawn
-     *  until the renderer has uploaded it where it now is. */
+     *  tallest first — the last resort, when no shelf of the height wanted
+     *  can be taken in place. What was drawable stays drawable: it is
+     *  uploaded where it now is, all of it, by the next frame before that
+     *  frame draws ({@link takeUploads}); what was waiting still waits. */
     _compact() {
         const keep = [...this._entries.values()]
             .filter((e) => e.used >= this._frame - KEEP_FRAMES)
@@ -365,15 +678,18 @@ export class LabelAtlas {
         this._shelves = [];
         this._top = 0;
         this._uploads = [];
+        this._moved = [];
         for (const entry of keep) {
             const place = this._allocate(entry.width, entry.height);
             if (!place)
                 continue;
             entry.x = place.x;
             entry.y = place.y;
-            entry.ready = false;
             this._entries.set(entry.key, entry);
-            this._uploads.push(entry);
+            if (entry.ready)
+                this._moved.push(entry);
+            else
+                this._uploads.push(entry);
         }
     }
 }