@react-x11/components 0.9.0 → 0.11.0

package/dist/maps/gl/view.js

@@ -35,9 +35,9 @@ import { MarkerBatcher } from './markers.js';
 import { buildOverlayBucket, overlayRegion, regionHolds, regionPlacement, } from './overlays.js';
 import { GL_PANE } from './pane.js';
 import { LABEL_INSTANCE, LabelPlacer } from './placement.js';
-import { GlMapRenderer } from './renderer.js';
+import { GlMapRenderer, gatesAt } from './renderer.js';
 import { GlTileStore } from './store.js';
-import { LabelAtlas, SurfaceTextEngine } from './text.js';
+import { LabelAtlas, SurfaceTextEngine, fieldBase } from './text.js';
 const h = React.createElement;
 /**
  * Adaptive quality's rungs, cheapest last. Each leaves out more than the
@@ -109,6 +109,12 @@ const BUILD_BUDGET_MS = 6;
  *  — the one label cost that can be large (the first strings on X11 load
  *  fonts and rasterize glyphs in JS). Placement's remainder waits a frame. */
 const TEXT_BUDGET_MOVING_MS = 1;
+/** Milliseconds a frame may spend making label fields (`text.ts`), about
+ *  0.2 ms each, when there are any to make. */
+const FIELD_BUDGET_MS = 4;
+/** With `labelsWhileMoving`: milliseconds a frame may spend setting the
+ *  text of names it has just placed, so they draw in it. */
+const LIVE_TEXT_BUDGET_MS = 8;
 const TEXT_BUDGET_SETTLED_MS = 4;
 /**
  * How often a moving view is placed again, in milliseconds — every other
@@ -150,7 +156,140 @@ const EMPTY_COVER = {
     descendants: 0,
     inView: [],
 };
-class GlMapDriver {
+/**
+ * The level fade: which level the frame is drawn from, and the one fading
+ * in over it.
+ *
+ * A new level is waited for — briefly, until every tile of it in view has
+ * answered — so the fade shows it arriving rather than a stand-in for it;
+ * then it fades in over the level it replaces, with an ease at both ends.
+ * A level more than one step away is not faded (the view it would fade
+ * from is sixteen times the tiles), and a change of target halfway
+ * through a fade takes the half-shown level as the one it fades from.
+ *
+ * What it cannot carry is a layer the style starts or stops drawing, which
+ * is {@link GateFader}'s: see there for why that is a separate thing and
+ * not a scene of its own.
+ */
+export class LevelFader {
+    /** The level the frame is drawn from, once one has been drawn. */
+    shown = null;
+    _fade = null;
+    /** Whether a fade is running or waiting to start. */
+    get fading() {
+        return this._fade !== null;
+    }
+    plan(target, cover, options) {
+        const { at, fadeMs } = options;
+        const to = target.level;
+        const plain = { base: target, next: null, alpha: 0 };
+        if (fadeMs <= 0 || this.shown === null || Math.abs(to - this.shown) > 1) {
+            this.shown = to;
+            this._fade = null;
+            return plain;
+        }
+        if (to === this.shown) {
+            this._fade = null;
+            return plain;
+        }
+        let fade = this._fade;
+        if (!fade || fade.to !== to) {
+            if (fade && fade.start !== null && (at - fade.start) / fadeMs >= 0.5) {
+                this.shown = fade.to;
+            }
+            if (this.shown === to) {
+                this._fade = null;
+                return plain;
+            }
+            fade = this._fade = { to, start: null, waitSince: at };
+        }
+        const base = cover(this.shown);
+        if (fade.start === null) {
+            if (target.missing.length > 0 && at - fade.waitSince < FADE_WAIT_MS) {
+                return { base, next: null, alpha: 0 };
+            }
+            fade.start = at;
+        }
+        const p = (at - fade.start) / fadeMs;
+        if (p >= 1) {
+            this.shown = to;
+            this._fade = null;
+            return plain;
+        }
+        return { base, next: target, alpha: p * p * (3 - 2 * p) };
+    }
+}
+/**
+ * The zoom gate's fade: how much of each style layer to draw, as the camera
+ * zooms past the `minZoom` and `maxZoom` the style gives them.
+ *
+ * **Why this is not a scene.** A level fade cross-fades two whole pictures,
+ * and a picture is the natural unit for a change of level. A layer ending
+ * is not: `minZoom` is a zoom, the pyramid changes level at a different
+ * zoom, and the two flips land on different frames — so carrying the gate
+ * as a second scene means a fade retargeted in the middle of another one,
+ * which can only either snap to the arriving scene or restart from the
+ * outgoing one. Both are a step in the picture, and stepping is what the
+ * fade is for. That is what made buildings vanish for one wheel notch and
+ * come back for the next. An opacity per layer has no such conflict: each
+ * layer's number moves on its own, through any number of level fades, and
+ * both scenes of a level fade draw with the same numbers — so the one
+ * thing an opacity ramp is bad at, a map dissolving layer by layer, cannot
+ * happen here, because only the layers actually crossing a gate move.
+ */
+export class GateFader {
+    /** Per style layer, in the prepared style's order. */
+    _alpha = [];
+    _at = null;
+    _fading = false;
+    /** Whether any layer is between the gate's ends — a frame to ask for. */
+    get fading() {
+        return this._fading;
+    }
+    /**
+     * The frame's `layerAlpha`, or null for "what the gate says" — which is
+     * every frame where nothing is crossing one, and every frame at all with
+     * the fade turned off.
+     */
+    step(style, options) {
+        const { at, fadeMs, zoom, detail } = options;
+        const targets = gatesAt(style, zoom, detail);
+        // The first frame, a restyle that changes the layer count, and the fade
+        // turned off: the gate, with nothing to advance.
+        const first = this._at === null || this._alpha.length !== targets.length;
+        if (fadeMs <= 0 || first) {
+            this._alpha = targets;
+            this._at = at;
+            this._fading = false;
+            return null;
+        }
+        const step = (at - (this._at ?? at)) / fadeMs;
+        this._at = at;
+        let fading = false;
+        let moved = false;
+        for (let i = 0; i < targets.length; i++) {
+            const to = targets[i];
+            const from = this._alpha[i];
+            if (from !== to) {
+                const next = to > from ? Math.min(to, from + step) : Math.max(to, from - step);
+                this._alpha[i] = next;
+                if (next !== to)
+                    fading = true;
+            }
+            if (this._alpha[i] !== to)
+                moved = true;
+        }
+        this._fading = fading;
+        return moved ? this._alpha : null;
+    }
+}
+/**
+ * The driver: everything a frame is, between the controller's camera and
+ * the renderer. Exported for the tests that drive it against a recording
+ * GL table — there is no other way to see a whole frame's decisions, and
+ * this host cannot render one (indirect GLX has no shaders).
+ */
+export class GlMapDriver {
     props;
     theme = null;
     _controller;
@@ -173,9 +312,18 @@ class GlMapDriver {
     _zoomedAt = -Infinity;
     _rung = 0;
     _cost = new CostModel();
-    _shown = null;
-    _fade = null;
+    _fader = new LevelFader();
+    _gates = new GateFader();
     _placer = new LabelPlacer();
+    /** Places the labels of the view a glide stops at, and shows nothing:
+     *  what it asks the atlas for is measured and set while the glide is
+     *  still being drawn. */
+    _scout = new LabelPlacer();
+    /** The destination the scout last placed, and whether that placement
+     *  measured everything it offered — a frame's text budget can run out
+     *  first, and then the next frame places it again. */
+    _scoutedFor = '';
+    _scoutDone = false;
     _markers = new MarkerBatcher();
     /** The overlays' bucket, and what it was built from. */
     _overlay = null;
@@ -187,7 +335,7 @@ class GlMapDriver {
     /** The attribution's one instance. */
     _attributionText = new Float32Array(LABEL_INSTANCE);
     /** An attribution a frame could not draw yet — its string not measured,
-     *  or its raster not in the texture — and the size it is set at. */
+     *  or its field not in the texture — and the size it is drawn at. */
     _attributionWanted = null;
     /** When labels were last placed. */
     _placedAt = -Infinity;
@@ -378,6 +526,9 @@ class GlMapDriver {
             }
             finally {
                 controller.painting = false;
+                // `onFrame` ran inside that, and a camera animation drives itself
+                // from it — so whatever it asked for is scheduled here.
+                controller.paintEnded();
             }
         }
         catch (error) {
@@ -433,64 +584,30 @@ class GlMapDriver {
         }
         return out;
     }
+    /**
+     * How long a moving frame may take, or null for "as long as it likes".
+     *
+     * **On unless turned off.** A renderer with no budget spends whatever a
+     * frame costs and asks for the next one on the following compositor tick
+     * regardless, so at the expensive end of a zoom sweep it takes the whole
+     * thread — and the app around it stops getting its timers. Measured on a
+     * fly across ten levels: without a budget the loop went a second at a time
+     * without running a `setTimeout`, and nothing inside it was slow, because
+     * the cost was spread over a hundred frames rather than spent in one call.
+     * With the budget, none. An embedding app should not have to know that to
+     * keep its own clock.
+     *
+     * What it costs is detail while the camera moves, and only while it moves:
+     * the frame after it settles draws everything again.
+     */
     _budget() {
         const adaptive = this.props.map.adaptive;
-        if (!adaptive)
+        if (adaptive === false)
             return null;
         return typeof adaptive === 'object'
             ? (adaptive.budgetMs ?? DEFAULT_BUDGET_MS)
             : DEFAULT_BUDGET_MS;
     }
-    /**
-     * The level fade: which level the frame is drawn from, and the one fading
-     * in over it.
-     *
-     * A new level is waited for — briefly, until every tile of it in view has
-     * answered — so the fade shows it arriving rather than a stand-in for it;
-     * then it fades in over the level it replaces, with an ease at both ends.
-     * A level more than one step away is not faded (the view it would fade
-     * from is sixteen times the tiles), and a change of target halfway
-     * through a fade takes the half-shown level as the one it fades from.
-     */
-    _planLevels(target, cover, at) {
-        const fadeMs = this.props.map.levelFade ?? 0;
-        const to = target.level;
-        const plain = { base: target, next: null, alpha: 0 };
-        if (fadeMs <= 0 || this._shown === null || Math.abs(to - this._shown) > 1) {
-            this._shown = to;
-            this._fade = null;
-            return plain;
-        }
-        if (to === this._shown) {
-            this._fade = null;
-            return plain;
-        }
-        let fade = this._fade;
-        if (!fade || fade.to !== to) {
-            if (fade && fade.start !== null && (at - fade.start) / fadeMs >= 0.5) {
-                this._shown = fade.to;
-            }
-            if (this._shown === to) {
-                this._fade = null;
-                return plain;
-            }
-            fade = this._fade = { to, start: null, waitSince: at };
-        }
-        const base = cover(this._shown);
-        if (fade.start === null) {
-            if (target.missing.length > 0 && at - fade.waitSince < FADE_WAIT_MS) {
-                return { base, next: null, alpha: 0 };
-            }
-            fade.start = at;
-        }
-        const p = (at - fade.start) / fadeMs;
-        if (p >= 1) {
-            this._shown = to;
-            this._fade = null;
-            return plain;
-        }
-        return { base, next: target, alpha: p * p * (3 - 2 * p) };
-    }
     _frame(gl, info) {
         const map = this.props.map;
         const controller = this._controller;
@@ -539,6 +656,17 @@ class GlMapDriver {
             store.want(target.missing);
             return { source, store, pyramid, target };
         });
+        // Where a wheel's glide stops, while one is running: its tiles are
+        // asked for after the view's own, so the view the glide lands on is
+        // loaded — and its labels set, below — by the time it gets there.
+        const destination = moving ? controller.destination() : null;
+        const ahead = destination
+            ? covers.map((c) => {
+                const cover = renderCover(destination, pane, scale, c.pyramid, c.store);
+                c.store.want(cover.missing);
+                return cover;
+            })
+            : null;
         // The level fade and adaptive quality are the first source's — the
         // basemap's; a pyramid over it is drawn at its own level throughout.
         const primary = covers[0] ?? null;
@@ -547,8 +675,9 @@ class GlMapDriver {
                 level,
             })
             : EMPTY_COVER;
+        const fadeMs = map.levelFade ?? 0;
         const plan = primary
-            ? this._planLevels(primary.target, coverAt, at)
+            ? this._fader.plan(primary.target, coverAt, { at, fadeMs })
             : { base: EMPTY_COVER, next: null, alpha: 0 };
         if (primary && plan.base !== primary.target) {
             primary.store.want(plan.base.missing);
@@ -589,11 +718,24 @@ class GlMapDriver {
         };
         let rung = 0;
         let predictedMs = 0;
+        // An overview of the view: its ancestors every other level up to the
+        // pyramid's root, asked for after the view's own tiles and looked up
+        // every frame, so they stay loaded. A view is a speck at those levels,
+        // so this is a tile or two a level. It is what a fast zoom out lands
+        // on: a trackpad's momentum can cross fifteen levels in a quarter of a
+        // second, and every level it passes that has no tile draws the style's
+        // background alone — a frame of one flat colour, labels gone with the
+        // tiles, where a coarser tile would have drawn the place, blurred. With
+        // one level of it in reach two levels up, a hole is always filled from
+        // above (`renderCover`'s ancestors reach eight). The level just above
+        // the view comes first: it is also what the ladder's last rungs draw.
+        if (primary) {
+            const top = primary.pyramid.minZoom;
+            for (let level = primary.target.level - 1; level >= top; level = level - 2 < top && level > top ? top : level - 2) {
+                primary.store.want(coverAt(level).missing);
+            }
+        }
         if (budget !== null && moving && primary) {
-            // The coarser level is what the ladder's last rungs draw, so ask for
-            // it too — after the view's own tiles, which come first.
-            primary.store.want(coverAt(Math.max(primary.pyramid.minZoom, primary.target.level - 1))
-                .missing);
             const predict = (r) => {
                 const built = build(r);
                 const work = renderer.estimate(built.frame) +
@@ -605,6 +747,24 @@ class GlMapDriver {
         }
         this._rung = rung;
         const { frame, fade } = build(rung);
+        // A layer crossing a gate — the style's `minZoom`, or this rung's
+        // `detail` — is ramped rather than cut, and both of a level fade's
+        // scenes draw it at the same ramp. Decided after the rung, because the
+        // rung is one of the gates: a moving frame that drops the style's
+        // newest layers to make its budget would otherwise take them out in
+        // one frame and hand them back in one more when the camera settled,
+        // which is a flicker on exactly the layers a zoom is looking at.
+        const layerAlpha = this._gates.step(prepared, {
+            at,
+            fadeMs,
+            zoom: camera.zoom,
+            detail: QUALITY_LADDER[rung].detail,
+        });
+        if (layerAlpha) {
+            frame.layerAlpha = layerAlpha;
+            if (fade)
+                fade.frame.layerAlpha = layerAlpha;
+        }
         // The text: the labels, and the attribution, set in the same atlas.
         let labels = null;
         let attribution = null;
@@ -614,12 +774,31 @@ class GlMapDriver {
             try {
                 const atlas = this._atlasFor(info.node, style, scale);
                 if (atlas) {
-                    atlas.beginFrame(now() + (moving ? TEXT_BUDGET_MOVING_MS : TEXT_BUDGET_SETTLED_MS));
+                    // Live labels measure at the settled budget while moving too:
+                    // what they admit mid-zoom has to be measured mid-zoom.
+                    const live = map.labelsWhileMoving === true;
+                    const textDeadline = now() +
+                        (moving && !live ? TEXT_BUDGET_MOVING_MS : TEXT_BUDGET_SETTLED_MS);
+                    atlas.beginFrame(textDeadline);
                     // The attribution before the names: it is one string, measured
                     // once, and a frame whose budget went on names would leave it
                     // for a later one — for as long as names keep arriving.
                     attribution = this._attributionFor(atlas, frame);
                     labels = this._labelsFor(atlas, frame, fade, at, moving);
+                    if (destination && ahead) {
+                        this._scoutFor(atlas, frame, destination, ahead, at);
+                    }
+                    else if (this._scoutedFor !== '') {
+                        this._scout.reset();
+                        this._scoutedFor = '';
+                    }
+                    // The fields of strings already read back, on a budget of their
+                    // own: the text budget moving is 1 ms, five fields, and a jump
+                    // somewhere new reads back sixty names at once — they came in
+                    // over two hundred milliseconds that way, against none for the
+                    // coverage rasters fields replaced. This frame's draw uploads
+                    // what it makes.
+                    atlas.makeFields(Math.max(textDeadline, now() + FIELD_BUDGET_MS));
                     this._pumpSoon();
                 }
             }
@@ -727,7 +906,7 @@ class GlMapDriver {
                 uploadBytes: stats.uploadBytes,
                 offscreen: stats.offscreen,
                 level,
-                shownLevel: this._shown ?? level,
+                shownLevel: this._fader.shown ?? level,
                 fade: stats.fade,
                 quality: rung,
                 predictedMs,
@@ -739,19 +918,24 @@ class GlMapDriver {
                 textPending: this._atlas?.pending ?? false,
             },
         };
-        // A label still fading, strings this frame had no budget to measure, or
-        // rasters still to go into the texture want the next frame; a raster
-        // in flight asks for one itself when it lands.
+        // A label still fading, strings this frame had no budget to measure,
+        // fields still to be made, or fields still to go into the texture want
+        // the next frame; a batch in flight asks for one itself when it lands.
         const labelling = labels !== null &&
             (this._placer.animating ||
                 this._atlas?.starved === true ||
+                this._atlas?.fielding === true ||
                 this._atlas?.uploading === true);
         // An attribution this frame could not draw may have gone into the
         // texture during it — the upload happens as the labels draw, after the
         // frame chose what to draw — and then it is the next frame's.
         const wanted = this._attributionWanted;
-        const attributing = wanted !== null && this._atlas?.entry(wanted.text, wanted.size) != null;
-        if (more || this._fade || labelling || attributing)
+        const attributing = wanted !== null && this._atlas?.entry(wanted.text) != null;
+        if (more ||
+            this._fader.fading ||
+            this._gates.fading ||
+            labelling ||
+            attributing)
             this.request();
         if (!this._announced) {
             this._announced = true;
@@ -813,9 +997,9 @@ class GlMapDriver {
             this._noText = true;
             return null;
         }
-        // Margin for a halo of two logical pixels, and the texel either side
-        // that keeps its samples inside it (see `quadInset`).
-        this._atlas = new LabelAtlas(engine, { pad: 2 * Math.ceil(2 * scale) + 2 });
+        // Fields set at a base size that follows the display's scale, so a
+        // label on a 2x panel is sampled from a field twice as fine.
+        this._atlas = new LabelAtlas(engine, { base: fieldBase(scale) });
         this._atlas.onChange = this.request;
         this._atlasKey = key;
         this._placer.reset();
@@ -827,6 +1011,7 @@ class GlMapDriver {
      * renderer.
      */
     _labelsFor(atlas, frame, fade, at, moving) {
+        const live = this.props.map.labelsWhileMoving === true;
         const from = fade && fade.alpha >= 0.5 ? fade.frame : frame;
         const centre = project(this._controller.camera().center);
         const placement = {
@@ -841,20 +1026,68 @@ class GlMapDriver {
             // The projection's world, which the cover lays every source out on.
             world: worldSize(frame.zoom, DEFAULT_TILE_SIZE) * frame.scale,
             now: at,
-            admit: at - this._zoomedAt >= ZOOM_QUIET_MS,
-            moving,
+            // Live: every name the view offers, at every step of a zoom.
+            admit: live || at - this._zoomedAt >= ZOOM_QUIET_MS,
         };
-        if (!moving || at - this._placedAt >= PLACE_INTERVAL_MS) {
+        if (live || !moving || at - this._placedAt >= PLACE_INTERVAL_MS) {
             this._placer.place(placement, atlas);
             this._placedAt = at;
         }
+        // Live: what placement asked for is set now, before the batch, so a
+        // name placed in this frame is drawn in it — its field goes into the
+        // texture ahead of the cap, before this frame's labels draw.
+        if (live)
+            atlas.setNow(now() + LIVE_TEXT_BUDGET_MS);
         return this._placer.batch(placement, atlas);
     }
+    /**
+     * Render ahead: place the labels of the view a glide stops at, so that
+     * every string it will show is measured and asked of the atlas while the
+     * glide's own frames are drawn. Nothing it places is drawn — the frame's
+     * placer places the destination again when it gets there, and finds every
+     * box measured and every field in the texture, so the labels fade in
+     * when the view settles rather than a readback and an upload after.
+     *
+     * A fresh placement each time (the scout keeps no labels between runs;
+     * holding a place is for what is on screen), and not every frame: when
+     * the destination moves — another notch — or more of its tiles land, or
+     * the last placement ran out of the frame's text budget before it had
+     * measured everything. It measures out of that budget, after the frame's
+     * own labels.
+     */
+    _scoutFor(atlas, frame, destination, covers, at) {
+        // The destination is recomputed from each frame's camera, so its last
+        // digits wander; to a millionth of a degree it is the same place. And
+        // it is a different question once more of its tiles are in hand.
+        let held = 0;
+        for (const c of covers)
+            held += c.own;
+        const key = `${destination.zoom}|${destination.center.lon.toFixed(6)}|${destination.center.lat.toFixed(6)}|${held}`;
+        if (key === this._scoutedFor && this._scoutDone)
+            return;
+        this._scoutedFor = key;
+        const centre = project(destination.center);
+        this._scout.reset();
+        this._scout.place({
+            width: frame.width,
+            height: frame.height,
+            scale: frame.scale,
+            zoom: destination.zoom,
+            style: frame.style,
+            tiles: covers.flatMap((c) => c.tiles),
+            centerX: centre.x,
+            centerY: centre.y,
+            world: worldSize(destination.zoom, DEFAULT_TILE_SIZE) * frame.scale,
+            now: at,
+            admit: true,
+        }, atlas);
+        this._scoutDone = !atlas.starved;
+    }
     /**
      * The attribution, as the retained renderer draws it: the same box on the
      * same pixels (`attributionLayout`), the text in the labels' face, from
      * the labels' atlas. Null while there is none to draw — `attribution=""`,
-     * or no source that names one — and until its raster is in the texture,
+     * or no source that names one — and until its field is in the texture,
      * so the box and its text arrive together.
      */
     _attributionFor(atlas, frame) {
@@ -866,19 +1099,20 @@ class GlMapDriver {
         const s = frame.scale;
         const size = ATTRIBUTION_SIZE * s;
         const box = atlas.measure(text, size);
-        const entry = box ? atlas.entry(text, size) : null;
+        const entry = box ? atlas.entry(text) : null;
         if (!box || !entry) {
             this._attributionWanted = { text, size };
             return null;
         }
         const at = attributionLayout({ width: box.width / s, height: box.height / s }, { x: 0, y: 0, width: frame.width / s, height: frame.height / s }, s);
         const palette = overlayPalette(this.theme);
-        // The string sits `pad` inside its raster, and a level label's quad is
-        // centred on its anchor and set on whole pixels: this anchor puts the
-        // string's corner on the layout's.
+        // The string sits `pad` texels inside its field, the field is drawn
+        // `k` device pixels a texel, and a level label's quad is centred on its
+        // anchor: this anchor puts the string's corner on the layout's.
+        const k = size / atlas.base;
         const d = this._attributionText;
-        d[0] = at.x - atlas.pad + entry.width / 2;
-        d[1] = at.y - atlas.pad + entry.height / 2;
+        d[0] = at.x + (entry.width / 2 - atlas.pad) * k;
+        d[1] = at.y + (entry.height / 2 - atlas.pad) * k;
         d[2] = 1;
         d[3] = 0;
         d[4] = entry.x;
@@ -888,6 +1122,7 @@ class GlMapDriver {
         d.set(premultiplied(parseColor(palette.text) ?? BLACK), 8);
         d.fill(0, 12, 17); // no halo: the box is what it reads against
         d[17] = 1;
+        d[18] = k;
         return {
             box: at.box,
             boxColor: premultiplied(parseColor(palette.background) ?? WHITE, ATTRIBUTION_OPACITY),