@react-x11/components 0.9.0 → 0.11.0

package/src/maps/tiles.ts

@@ -33,8 +33,8 @@
 import type { PreparedStyle } from './paint.js';
 import type { VectorTile } from './mvt.js';
 import { parseTile } from './mvt.js';
-import { tileKey } from './proj.js';
-import type { TileId } from './proj.js';
+import { BELOW, FILL_DEPTH, fillFromBelow, tileKey } from './proj.js';
+import type { TileCell, TileId } from './proj.js';
 import { pyramidOf } from './sources.js';
 import type { MapSource, TileData } from './sources.js';
 
@@ -247,6 +247,10 @@ export class TileCache {
   /** Bumped by a style change, which retires every surface without
    *  touching the data behind it. */
   private _generation = 0;
+  /** The key of every tile with a picture, and of its ancestors up to
+   *  `FILL_DEPTH` levels above it — see {@link descendantsWithSurface}.
+   *  Built when first asked, and dropped whenever a picture comes or goes. */
+  private _below: Set<string> | null = null;
 
   constructor(options: TileCacheOptions = {}) {
     this._options = options;
@@ -492,7 +496,8 @@ export class TileCache {
   }
 
   /**
-   * The finished **descendants** of a tile, and where each sits inside it.
+   * The finished **descendants** of a tile, where each sits inside it, and
+   * the gaps they leave.
    *
    * The mirror of {@link ancestorWithSurface}, and the half a map needs
    * when it zooms *out*: the tiles already in hand are then the target's
@@ -501,42 +506,64 @@ export class TileCache {
    * over it, which is exactly as odd as it sounds — until the coarser tile
    * has been fetched, rasterized and composited.
    *
-   * `depth` is how many levels down to look, and it is small on purpose: a
-   * level down is 4 tiles, two is 16, and beyond that the pieces are too
-   * small to be worth the composites.
+   * Each quarter of the square is taken from the nearest level that has it,
+   * down to `FILL_DEPTH` — see `fillFromBelow`. The first cut took one
+   * level for the whole square, the nearest with anything in it, and looked
+   * two down. Both left the view blank where a zoom out needs it most: the
+   * edges, where the level the map came from covers only part of a coarser
+   * tile and the rest is one level further down or nowhere; and a zoom out
+   * of more than two levels, which a flick of the wheel is.
+   *
+   * The search goes only where {@link _heldBelow} says there is something,
+   * so a hole with nothing under it — every tile of a zoom *in* — costs four
+   * lookups rather than three hundred.
    *
    * `generation` as for {@link ancestorWithSurface}.
    */
   descendantsWithSurface(
     source: MapSource,
     tile: TileId,
-    depth = 2,
     generation?: number,
-  ): { entry: CachedTile; x: number; y: number; span: number }[] {
-    for (let down = 1; down <= depth; down++) {
-      const span = 1 << down;
-      const found: { entry: CachedTile; x: number; y: number; span: number }[] =
-        [];
-      for (let dy = 0; dy < span; dy++) {
-        for (let dx = 0; dx < span; dx++) {
-          const entry = this._entries.get(
-            this.key(source, {
-              z: tile.z + down,
-              x: (tile.x << down) + dx,
-              y: (tile.y << down) + dy,
-            }),
-          );
-          if (entry?.shown && drawnFor(entry.shown, generation)) {
-            entry.lastUsed = this._frame;
-            found.push({ entry, x: dx, y: dy, span });
-          }
-        }
+  ): {
+    pieces: (TileCell & { tile: TileId; value: CachedTile })[];
+    gaps: TileCell[];
+  } {
+    const below = this._heldBelow();
+    const { pieces, gaps } = fillFromBelow(tile, FILL_DEPTH, (under) => {
+      const key = this.key(source, under);
+      if (!below.has(key)) return undefined;
+      const entry = this._entries.get(key);
+      if (entry?.shown && drawnFor(entry.shown, generation)) {
+        // Stamped, for the reason `ancestorWithSurface` gives.
+        entry.lastUsed = this._frame;
+        return entry;
+      }
+      return BELOW;
+    });
+    return { pieces, gaps };
+  }
+
+  /** The keys of every tile with a picture and of its ancestors up to
+   *  `FILL_DEPTH` levels above — so a search under a hole can tell where
+   *  there is nothing without asking for each tile there. A superset where
+   *  a picture is of another generation, which only costs the search a
+   *  level. */
+  private _heldBelow(): Set<string> {
+    if (this._below) return this._below;
+    const below = new Set<string>();
+    for (const entry of this._entries.values()) {
+      if (!entry.shown) continue;
+      below.add(entry.key);
+      let { z, x, y } = entry.tile;
+      for (let up = 1; up <= FILL_DEPTH && z > 0; up++) {
+        z--;
+        x >>= 1;
+        y >>= 1;
+        below.add(this.key(entry.data.source, { z, x, y }));
       }
-      // The nearest level that has anything wins: one level down is both
-      // the sharpest and the fewest composites.
-      if (found.length > 0) return found;
     }
-    return [];
+    this._below = below;
+    return below;
   }
 
   /**
@@ -612,6 +639,7 @@ export class TileCache {
     if (entry.shown) this._release(entry.shown);
     entry.shown = entry.drawing;
     entry.drawing = null;
+    this._below = null;
     return true;
   }
 
@@ -629,6 +657,7 @@ export class TileCache {
    * composited again, and otherwise kept until eviction got round to it.
    */
   swap(): void {
+    this._below = null;
     for (const entry of this._entries.values()) {
       if (entry.drawing && !drawnFor(entry.drawing, this._generation)) {
         this._release(entry.drawing);
@@ -746,7 +775,10 @@ export class TileCache {
   }
 
   private _dropSurface(entry: CachedTile): void {
-    if (entry.shown) this._release(entry.shown);
+    if (entry.shown) {
+      this._release(entry.shown);
+      this._below = null;
+    }
     if (entry.drawing) this._release(entry.drawing);
     entry.shown = null;
     entry.drawing = null;
@@ -780,6 +812,7 @@ export class TileCache {
     for (const data of this._data.values()) data.abort?.();
     this._data.clear();
     this._surfaceBytes = 0;
+    this._below = null;
   }
 
   /** Every entry — for a test, and for the `onTiles` diagnostic. */

package/src/maps/types.ts

@@ -26,6 +26,7 @@ export type {
   SymbolLayer,
   Zoomed,
 } from './style.js';
+export type { MapIcon } from './icons.js';
 
 /** Which renderer draws a map — see `<Map renderer>`. */
 export type MapRenderer = 'gl' | 'retained';
@@ -94,7 +95,9 @@ export interface MapFrameStats {
    *  What covers a hole while zooming *in*. */
   fromAncestor: number;
   /** …and how many from their finer descendants, scaled down. What covers
-   *  a hole while zooming *out*, where there is no ancestor to borrow. */
+   *  a hole while zooming *out*, where there is no ancestor to borrow.
+   *  Descendants cover what they can and an ancestor the gaps between them,
+   *  so a hole covered partly from each counts in both. */
   fromDescendant: number;
   /** Tiles still to rasterize (retained) or to build (GL) — non-zero means
    *  the map is still sharpening and another frame is already scheduled. */
@@ -369,11 +372,32 @@ export interface MapGlProps {
    */
   levelFade?: number;
   /**
-   * Trade detail for frame rate while the camera moves. `true` holds each
-   * moving frame to 12 ms; `{ budgetMs }` to another budget. When the camera
-   * settles the next frame draws everything again.
+   * Trade detail for frame rate while the camera moves. **On by default**,
+   * holding each moving frame to 12 ms; `{ budgetMs }` picks another budget
+   * and `false` turns it off. When the camera settles the next frame draws
+   * everything again.
+   *
+   * It is on by default because the alternative is a renderer that can take
+   * the whole thread: unbudgeted, a fly across ten zoom levels left the
+   * event loop unable to run a `setTimeout` for a second at a time, with
+   * nothing individually slow inside it. An app embedding a map should not
+   * have to know that to keep its own clock running.
    */
   adaptive?: boolean | { budgetMs?: number };
+  /**
+   * Place labels in every frame while the camera moves, and set a new
+   * name's text in the frame it is placed in, so the names always match
+   * the zoom on screen. Off by default: new names then wait until the zoom
+   * has been still for 120 ms, and arrive a readback later.
+   *
+   * What it costs: a zoom crosses several label sets, so names arrive and
+   * leave at every step of it (each fading, over 220 ms), and each new name
+   * is set on this thread in the frame that needs it — up to 8 ms a frame,
+   * the rest the frame after. Needs a text engine that sets a string
+   * synchronously (react-x11 2.21's layout coverage); on one that cannot,
+   * names still arrive a readback later, but are placed every frame.
+   */
+  labelsWhileMoving?: boolean;
   /** Build tiles' geometry on this many worker threads, so no frame pays
    *  for a tile arriving. `0` (the default) builds on this thread, a few
    *  milliseconds a frame. */