@react-x11/components 0.8.0 → 0.10.0

package/src/maps/tiles.ts

@@ -18,6 +18,14 @@
 //    scaled. Only an integer zoom change, a style change or a display-scale
 //    change invalidates one.
 //
+// Both are filed under the **source object**, not under its `id`. An id is
+// only what a source is called, and two providers can share one — a source
+// without one is named for its slot in `sources`, and `osmRasterSource` is
+// `osm-raster` whichever server it points at — so filing by id handed a map
+// switched to another provider the old one's tiles wherever it had them,
+// until eviction got round to them. Filed by object, a new provider starts
+// empty, and an old one keeps its tiles for when it comes back.
+//
 // The surface is the expensive half — on the corpus in `scripts/bench/`, a
 // dense city tile is 50-140 ms to rasterize and about 0.05 ms to composite
 // — so the cache's job is to make sure that cost is paid once per tile per
@@ -25,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';
 
@@ -80,6 +88,14 @@ export interface TileRender {
   zoom: number;
   /** The cache generation it was drawn under. */
   generation: number;
+  /**
+   * Whether its pixels depend on the style. A vector tile's do — they are
+   * the style, rasterized — and a raster tile's do not: they are the
+   * provider's image, uploaded as it arrived. So an unstyled rendering
+   * belongs to every generation, and a restyle neither redraws it nor stops
+   * showing it.
+   */
+  styled: boolean;
   /** The next style run to draw, or `-1` when it is finished. */
   progress: number;
   /** …and how far into that run's active layers, because a run is not a
@@ -97,6 +113,12 @@ export interface TileRender {
  */
 export interface TileDataEntry {
   readonly key: string;
+  /** Who answers for it — and so which provider the bytes came from,
+   *  since tiles are filed under the source object. */
+  readonly source: MapSource;
+  /** What that source is called: the `sourceId` its `load` requests carry
+   *  and `onError` reports. */
+  readonly sourceId: string;
   readonly tile: TileId;
   status: TileStatus;
   error: unknown;
@@ -141,7 +163,15 @@ export class CachedTile {
    * keeps being composited until it is ready to be replaced.
    */
   shown: TileRender | null = null;
-  /** The rendering being drawn, or null when there is nothing to draw. */
+  /**
+   * The rendering being drawn, or null when there is nothing to draw.
+   *
+   * Finished ones do not usually stay: a draft is {@link TileCache.promote}d
+   * in the frame it is done. The exception is a restyle, which holds the
+   * previous style's whole picture up until the view is redrawn — so there
+   * a finished draft waits here until {@link TileCache.swap} puts every one
+   * on screen at once.
+   */
   drawing: TileRender | null = null;
   /** Frame counter of the last frame that wanted it — what eviction sorts
    *  on. */
@@ -207,12 +237,20 @@ export class TileCache {
   private readonly _entries = new Map<string, CachedTile>();
   /** The source's own tiles, shared by every rendering that draws one. */
   private readonly _data = new Map<string, TileDataEntry>();
+  /** The key prefix of each source object — per object and not per id,
+   *  for the reason at the top of this file. */
+  private readonly _prefixes = new WeakMap<MapSource, string>();
+  private _prefixCount = 0;
   private readonly _options: TileCacheOptions;
   private _frame = 0;
   private _surfaceBytes = 0;
   /** 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;
@@ -227,7 +265,16 @@ export class TileCache {
     return this._generation;
   }
 
-  /** Every rendered surface is stale — a new style, a new display scale. */
+  /**
+   * Every styled surface is stale: a new style, or `refresh()` after an
+   * edit to one. The data behind them stays, and so does a raster tile's
+   * rendering, which no style drew (see {@link TileRender.styled}).
+   *
+   * A new display scale needs none of this, because a rendering's size is
+   * already part of what makes it valid. And nothing on screen is thrown
+   * away here: each picture stays until its replacement is finished —
+   * {@link promote} for one tile, {@link swap} for the whole view at once.
+   */
   invalidateStyle(): void {
     this._generation++;
   }
@@ -241,21 +288,31 @@ export class TileCache {
     return this._entries.size;
   }
 
-  key(sourceId: string, tile: TileId): string {
-    return `${sourceId}:${tileKey(tile)}`;
+  /** What a source's tile is filed under: a prefix of the source object's
+   *  own, then `z/x/y`. The id is in the prefix only so that a key reads
+   *  well in a debugger; two objects with one id get two prefixes. */
+  key(source: MapSource, tile: TileId): string {
+    let prefix = this._prefixes.get(source);
+    if (prefix === undefined) {
+      prefix = `${source.id ?? 'source'}#${++this._prefixCount}`;
+      this._prefixes.set(source, prefix);
+    }
+    return `${prefix}:${tileKey(tile)}`;
   }
 
-  peek(sourceId: string, tile: TileId): CachedTile | undefined {
-    return this._entries.get(this.key(sourceId, tile));
+  peek(source: MapSource, tile: TileId): CachedTile | undefined {
+    return this._entries.get(this.key(source, tile));
   }
 
   /**
    * The entry for a tile the cover asked for, and the data behind it,
    * asking the source for that data if nothing has yet.
    *
-   * `dataTile` is the tile whose bytes serve this one — itself, until the
-   * cover goes deeper than the source cuts. Marks both used by the current
-   * frame, which is what keeps them out of the next eviction.
+   * Filed under `source`; `sourceId` is only what it is called. `dataTile`
+   * is the tile whose bytes serve this one — itself, until the cover goes
+   * deeper than the source cuts. Marks both used by the current frame,
+   * which is what keeps them out of the next eviction — and a load still
+   * in flight from being cancelled by {@link sweep}.
    */
   want(
     source: MapSource,
@@ -265,7 +322,7 @@ export class TileCache {
     sub: { x: number; y: number; span: number } = { x: 0, y: 0, span: 1 },
   ): CachedTile {
     const data = this._wantData(source, sourceId, dataTile);
-    const key = this.key(sourceId, tile);
+    const key = this.key(source, tile);
     let entry = this._entries.get(key);
     if (!entry) {
       entry = new CachedTile(key, sourceId, tile, data, sub);
@@ -280,11 +337,13 @@ export class TileCache {
     sourceId: string,
     tile: TileId,
   ): TileDataEntry {
-    const key = this.key(sourceId, tile);
+    const key = this.key(source, tile);
     let data = this._data.get(key);
     if (!data) {
       data = {
         key,
+        source,
+        sourceId,
         tile,
         status: 'idle',
         error: null,
@@ -299,23 +358,19 @@ export class TileCache {
     }
     data.lastUsed = this._frame;
     if (data.status === 'idle') {
-      this._load(source, sourceId, data);
+      this._load(data);
     } else if (data.status === 'error' && Date.now() >= data.retryAt) {
       // A failed tile is retried, but on a backoff rather than on every
       // frame. Without it a source that is down — or an application whose
       // `load` throws on the first call, which is how this was found — is
       // asked for every visible tile sixty times a second, which is a
       // retry storm pointed at somebody else's servers.
-      this._load(source, sourceId, data);
+      this._load(data);
     }
     return data;
   }
 
-  private _load(
-    source: MapSource,
-    sourceId: string,
-    entry: TileDataEntry,
-  ): void {
+  private _load(entry: TileDataEntry): void {
     entry.status = 'loading';
     entry.error = null;
     // A **real** `AbortController` where the runtime has one. A look-alike
@@ -365,7 +420,11 @@ export class TileCache {
     };
     let result: TileData | Promise<TileData>;
     try {
-      result = source.load({ ...entry.tile, sourceId, signal });
+      result = entry.source.load({
+        ...entry.tile,
+        sourceId: entry.sourceId,
+        signal,
+      });
     } catch (error) {
       settle(() => fail(error));
       return;
@@ -408,20 +467,24 @@ export class TileCache {
    * under the fine one until it arrives — which is the difference between a
    * map that fills in and a map that flashes empty. Bounded, because
    * scaling one tile over sixteen screenfuls is worse than the hole.
+   *
+   * With a `generation`, only a picture drawn in it counts: a map showing
+   * one style must not cover a hole with a tile drawn in another.
    */
   ancestorWithSurface(
-    sourceId: string,
+    source: MapSource,
     tile: TileId,
     levels = 5,
+    generation?: number,
   ): CachedTile | null {
     let z = tile.z - 1;
     let x = tile.x >> 1;
     let y = tile.y >> 1;
     for (let up = 0; up < levels && z >= 0; up++, z--, x >>= 1, y >>= 1) {
-      const entry = this._entries.get(this.key(sourceId, { z, x, y }));
+      const entry = this._entries.get(this.key(source, { z, x, y }));
       // `shown` is finished by construction, so an ancestor is never a
       // half-drawn picture.
-      if (entry?.shown) {
+      if (entry?.shown && drawnFor(entry.shown, generation)) {
         // Stamped, because for as long as it is covering a hole it is on
         // screen — and an unstamped entry is the *first* thing eviction
         // takes, which would drop the only picture the map is showing.
@@ -433,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
@@ -442,39 +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(
-    sourceId: string,
+    source: MapSource,
     tile: TileId,
-    depth = 2,
-  ): { 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(sourceId, {
-              z: tile.z + down,
-              x: (tile.x << down) + dx,
-              y: (tile.y << down) + dy,
-            }),
-          );
-          if (entry?.shown) {
-            entry.lastUsed = this._frame;
-            found.push({ entry, x: dx, y: dy, span });
-          }
-        }
+    generation?: number,
+  ): {
+    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;
   }
 
   /**
@@ -493,12 +582,19 @@ export class TileCache {
    * the tile is blank for the several frames it takes to redraw, which
    * above a source's `maxZoom` happens at every integer zoom — the same
    * z14 tile serves 15, 16, 17 and on.
+   *
+   * A draft that is finished but not yet promoted — a restyle holding the
+   * old style up until the whole view is ready — matches like any other and
+   * comes back as it is, so it is not drawn twice.
    */
   beginRender(
     entry: CachedTile,
     size: number,
     zoom: number,
     make: SurfaceFactory,
+    /** False for a raster tile, whose pixels are the provider's and no
+     *  style's — see {@link TileRender.styled}. */
+    styled = true,
   ): TileRender | null {
     if (this._matches(entry.shown, size, zoom)) return null;
     if (this._matches(entry.drawing, size, zoom)) return entry.drawing;
@@ -515,6 +611,7 @@ export class TileCache {
       size,
       zoom,
       generation: this._generation,
+      styled,
       progress: 0,
       progressLayer: 0,
     };
@@ -530,7 +627,7 @@ export class TileCache {
       render !== null &&
       render.size === size &&
       render.zoom === zoom &&
-      render.generation === this._generation
+      drawnFor(render, this._generation)
     );
   }
 
@@ -542,9 +639,38 @@ export class TileCache {
     if (entry.shown) this._release(entry.shown);
     entry.shown = entry.drawing;
     entry.drawing = null;
+    this._below = null;
     return true;
   }
 
+  /**
+   * Put the current generation on screen in one go: every finished draft
+   * becomes its tile's picture, and every picture and draft of an earlier
+   * generation is released — apart from a raster tile's, which no style
+   * drew.
+   *
+   * The other half of a restyle. While the element holds the previous style
+   * up it does not {@link promote}, so finished drafts wait in `drawing`,
+   * and this is the frame they all land in. What is released is more than
+   * what they replace: a tile off screen still holds whatever it was last
+   * drawn in, which is now a picture of a style the map has left — never
+   * 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);
+        entry.drawing = null;
+      }
+      if (this.promote(entry)) continue;
+      if (entry.shown && !drawnFor(entry.shown, this._generation)) {
+        this._release(entry.shown);
+        entry.shown = null;
+      }
+    }
+  }
+
   /** Note where a tile's rasterization stopped: at run `run`, having
    *  finished `layer` of its active layers (`-1` for all of them). */
   advance(
@@ -558,14 +684,18 @@ export class TileCache {
   }
 
   /**
-   * Drop what is no longer worth keeping.
+   * Drop what is no longer worth keeping. Called once a frame, after every
+   * tile the frame still needs has been through {@link want}.
    *
-   * Surfaces go first and by least-recently-wanted, because they are two
+   * A load the frame did not want is cancelled outright (see
+   * `_cancelUnwanted`). What has arrived is kept on budgets instead:
+   * surfaces first and by least-recently-wanted, because they are two
    * orders of magnitude larger than the data behind them and much cheaper
-   * to lose: a dropped surface is one re-rasterization, a dropped tile is a
-   * network request.
+   * to lose — a dropped surface is one re-rasterization, a dropped tile is
+   * a network request.
    */
   sweep(): void {
+    this._cancelUnwanted();
     if (
       this._surfaceBytes >
       (this._options.surfaceBudget ?? DEFAULT_SURFACE_BUDGET)
@@ -605,8 +735,50 @@ export class TileCache {
     }
   }
 
+  /**
+   * Cancel every load the frame just drawn did not ask for.
+   *
+   * A tile panned or zoomed out of the cover — or every tile of a source
+   * taken out of `sources` — would otherwise load to the end: a request
+   * nobody is waiting for, then a full-pane repaint when it lands, because
+   * a landing tile is an `onChange`. The cover is padded, so a tile just off
+   * screen is still wanted and keeps loading. That is also the contract on
+   * the element: it wants the whole cover on every frame, clipped and
+   * mid-gesture ones included, or what it skipped is aborted here and
+   * fetched again.
+   *
+   * Only loads: data that has arrived stays on the budgets above, and is
+   * what makes panning back, or switching back to a provider, free.
+   *
+   * And forgotten rather than parked. An aborted load never settles
+   * (`settle` ignores it), so an entry left in `_data` would say `'loading'`
+   * forever and never be asked for again; its renderings go with it, since
+   * each reads through to the same entry for life, and none has a surface to
+   * lose. The next frame that wants the tile starts over, with a new request
+   * and a new signal.
+   */
+  private _cancelUnwanted(): void {
+    let unwanted: Set<TileDataEntry> | null = null;
+    for (const data of this._data.values()) {
+      if (data.status === 'loading' && data.lastUsed < this._frame) {
+        (unwanted ??= new Set<TileDataEntry>()).add(data);
+      }
+    }
+    if (!unwanted) return;
+    for (const entry of [...this._entries.values()]) {
+      if (unwanted.has(entry.data)) this._drop(entry);
+    }
+    for (const data of unwanted) {
+      data.abort?.();
+      this._data.delete(data.key);
+    }
+  }
+
   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;
@@ -640,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. */
@@ -647,14 +820,32 @@ export class TileCache {
     return this._entries.values();
   }
 
-  /** Every source tile whose bytes are held. What labels are collected
-   *  from: a label belongs to the tile the data came from, and past a
-   *  source's depth many renderings share one of those. */
+  /** Every source tile whose bytes are held — including those of sources no
+   *  longer on the map, which is what makes switching back free and why a
+   *  reader filters on `source`. What labels are collected from: a label
+   *  belongs to the tile the data came from, and past a source's depth many
+   *  renderings share one of those. */
   dataEntries(): IterableIterator<TileDataEntry> {
     return this._data.values();
   }
 }
 
+/**
+ * Whether a rendering can be shown for `generation`: any can when none is
+ * given, which is `progressive`; one no style drew — a raster tile's — can
+ * in every generation; any other only in the one it was drawn under.
+ */
+export function drawnFor(
+  render: TileRender,
+  generation: number | undefined,
+): boolean {
+  return (
+    generation === undefined ||
+    !render.styled ||
+    render.generation === generation
+  );
+}
+
 /** A source's pyramid, memoized per source object so the defaults are not
  *  refilled per frame. */
 const pyramids = new WeakMap<