@react-x11/components 0.9.0 → 0.11.0

package/src/maps/gl/placement.ts

@@ -17,7 +17,7 @@
 //    fits its street at this zoom, it would be cut by the edge, or something
 //    that outranks it arrives.
 //  - **Labels fade**, in and out, over {@link FADE_MS}. A label never pops;
-//    one whose raster is still being set waits, invisibly, and fades in
+//    one whose field is still being set waits, invisibly, and fades in
 //    when it lands.
 //  - **Labels do not slide.** Anchors are fixed ground, so a label moves
 //    exactly with the map; when a street's label leaves the view another
@@ -42,8 +42,16 @@ import {
   estimateWidth,
 } from '../anchors.js';
 import type { GlLabelData } from '../anchors.js';
-import { haloReach } from './text.js';
+import { fieldReach } from './text.js';
 import type { AtlasEntry, LabelAtlas } from './text.js';
+import {
+  DEFAULT_ICON_COLOR,
+  DEFAULT_ICON_GLYPH_COLOR,
+  DEFAULT_ICON_SIZE,
+  ICON_GAP,
+  isMapIcon,
+} from '../icons.js';
+import type { MapIcon } from '../icons.js';
 
 /** A rectangle in device pixels. */
 interface Rect {
@@ -85,23 +93,25 @@ export interface PlacementFrame {
    *  must, and what the zoom uncovers is named once it stops — not labels
    *  arriving and leaving at every step of it. `true` by default. */
   admit?: boolean;
-  /** The camera is moving: a label keeps the raster it has, rather than
-   *  asking for one at each size its zoom ramp passes through. */
-  moving?: boolean;
 }
 
 /** Floats per label instance; the layout `renderer.ts` binds. */
-export const LABEL_INSTANCE = 18;
+export const LABEL_INSTANCE = 19;
 
 /** The frame's labels, ready to draw. */
 export interface LabelBatch {
   atlas: LabelAtlas;
   /** {@link LABEL_INSTANCE} floats per label: centre x, y (device
-   *  pixels); cos, sin of the baseline; the atlas rect x, y, w, h; ink
-   *  and halo colour, premultiplied and faded; halo radius; `1` to set
-   *  the label on whole pixels. */
+   *  pixels); cos, sin of the baseline; the field's rect in the atlas x,
+   *  y, w, h (texels); ink and halo colour, premultiplied and faded; halo
+   *  radius (device pixels); `1` to set the label on whole pixels; and
+   *  device pixels per field texel — the drawn size over the atlas's
+   *  base. */
   instances: Float32Array;
   count: number;
+  /** Labels drawn: fewer than `count` where an icon is two instances of
+   *  its own beside its name's. `count` where absent. */
+  labels?: number;
 }
 
 export interface PlacementStats {
@@ -130,12 +140,23 @@ const CELL = 64;
 interface LayerLabels {
   id: string;
   rank: number;
-  /** Device pixels, whole — the raster's size. */
+  /** Device pixels — not rounded: one field draws any size. */
   size: number;
   repeat: number;
   ink: Rgba;
   halo: Rgba | null;
   haloPx: number;
+  icon: LayerIcon | null;
+}
+
+/** A layer's icon at a zoom: device pixels across, the gap to the name,
+ *  and its two colours. */
+interface LayerIcon {
+  name: MapIcon;
+  size: number;
+  gap: number;
+  plate: Rgba;
+  glyph: Rgba;
 }
 
 /** A label on screen, or fading. Its ground is mercator, so it outlives
@@ -158,8 +179,6 @@ interface Shown {
   priority: number;
   opacity: number;
   placed: boolean;
-  /** The size it has a raster at — drawn until the current size's lands. */
-  drawn: number;
 }
 
 interface Candidate {
@@ -172,6 +191,9 @@ interface Candidate {
   point: boolean;
   sx: number;
   sy: number;
+  /** How far right of `sx` its box's centre is: an icon's name is set
+   *  beside it. Device pixels; set once the box is measured. */
+  ox: number;
   angle: number;
   cos: number;
   sin: number;
@@ -226,7 +248,7 @@ export class LabelPlacer {
 
   /**
    * Choose the frame's labels. Asks `atlas` for each contender's box, as
-   * the frame's budget allows, and for each winner's raster.
+   * the frame's budget allows, and for each winner's field.
    */
   place(frame: PlacementFrame, atlas: LabelAtlas): void {
     const started = now();
@@ -372,18 +394,28 @@ export class LabelPlacer {
       }
       const box = atlas.measure(c.text, c.size);
       if (!box || box.width === 0) continue;
-      const w = box.width;
-      const h = box.height;
+      let w = box.width;
+      let h = box.height;
       if (!c.point) {
         const need = w / 2 + h * LINE_MARGIN;
         if (c.avail < (c.shown ? need * 0.9 : need)) continue;
       }
+      // An icon on the point and the name beside it are one box, placed
+      // and given way as one.
+      const icon = this._icon(layers[c.layer], c.point, atlas);
+      if (icon) {
+        const full = icon.size + icon.gap + w;
+        c.ox = (full - icon.size) / 2;
+        w = full;
+        h = Math.max(h, icon.size);
+      }
+      const bx = c.sx + c.ox;
       const hw = (Math.abs(c.cos) * w + Math.abs(c.sin) * h) / 2;
       const hh = (Math.abs(c.sin) * w + Math.abs(c.cos) * h) / 2;
       if (
-        c.sx - hw < inset ||
+        bx - hw < inset ||
         c.sy - hh < inset ||
-        c.sx + hw > width - inset ||
+        bx + hw > width - inset ||
         c.sy + hh > height - inset
       ) {
         continue;
@@ -425,7 +457,6 @@ export class LabelPlacer {
               size: c.size,
               opacity: 0,
               placed: false,
-              drawn: 0,
             } as Shown);
           fresh.mx = c.mx;
           fresh.my = c.my;
@@ -442,8 +473,12 @@ export class LabelPlacer {
       }
       shown.placed = true;
       shown.size = c.size;
-      if (!frame.moving || shown.drawn === 0)
-        atlas.entry(shown.text, shown.size);
+      atlas.entry(shown.text);
+      const icon = this._icon(layers[shown.layer], shown.point, atlas);
+      if (icon) {
+        atlas.icon(icon.name, 'plate');
+        atlas.icon(icon.name, 'glyph');
+      }
     }
 
     this.stats = {
@@ -464,24 +499,27 @@ export class LabelPlacer {
     this._last = frame.now;
     const step = dt / FADE_MS;
     const layers = this._layersAt(frame.style, frame.zoom, frame.scale);
-    const reach = haloReach(atlas.pad);
+    // How far past its glyphs a field sees, in its own texels: the widest
+    // halo it can draw, times the label's scale.
+    const reach = fieldReach(atlas.pad);
     const halfW = frame.width / 2;
     const halfH = frame.height / 2;
     let count = 0;
+    let labels = 0;
     for (const shown of [...this._shown]) {
       const layer = layers[shown.layer];
-      let entry: AtlasEntry | null;
-      if (frame.moving && shown.drawn > 0 && shown.drawn !== shown.size) {
-        // Its zoom ramp has moved on; the size it has serves until the
-        // view is still.
-        entry = atlas.entry(shown.text, shown.drawn);
-      } else {
-        entry = atlas.entry(shown.text, shown.size);
-        if (entry) shown.drawn = shown.size;
-        else if (shown.drawn > 0) entry = atlas.entry(shown.text, shown.drawn);
-      }
+      // One field for every size: a zoom ramp that grows the type draws the
+      // same raster larger, the frame it changes.
+      const entry = atlas.entry(shown.text);
+      // A name set beside an icon waits for the icon as well: the name
+      // alone is what the icon is there to explain.
+      const icon = this._icon(layer, shown.point, atlas);
+      const plate = icon ? atlas.icon(icon.name, 'plate') : null;
+      const glyph = icon ? atlas.icon(icon.name, 'glyph') : null;
+      const ready =
+        entry !== null && (!icon || (plate !== null && glyph !== null));
       // Nothing to show yet: wait at zero rather than fade in unseen.
-      if (entry && layer) {
+      if (ready && layer) {
         shown.opacity = shown.placed
           ? Math.min(1, shown.opacity + step)
           : Math.max(0, shown.opacity - step);
@@ -492,44 +530,111 @@ export class LabelPlacer {
         this._shown.delete(shown);
         continue;
       }
-      if (!entry || !layer || shown.opacity <= 0) continue;
+      if (!ready || !entry || !layer || shown.opacity <= 0) continue;
       let dx = shown.mx - frame.centerX;
       dx -= Math.round(dx);
       const sx = halfW + dx * frame.world;
       const sy = halfH + (shown.my - frame.centerY) * frame.world;
       const eased = shown.opacity * shown.opacity * (3 - 2 * shown.opacity);
-      if (this._instances.length < (count + 1) * LABEL_INSTANCE) {
-        const grown = new Float32Array(this._instances.length * 2);
-        grown.set(this._instances);
-        this._instances = grown;
-      }
-      const d = this._instances;
-      const at = count * LABEL_INSTANCE;
-      const level = shown.angle === 0;
-      d[at] = sx;
-      d[at + 1] = sy;
-      d[at + 2] = level ? 1 : Math.cos(shown.angle);
-      d[at + 3] = level ? 0 : Math.sin(shown.angle);
-      d[at + 4] = entry.x;
-      d[at + 5] = entry.y;
-      d[at + 6] = entry.width;
-      d[at + 7] = entry.height;
       const ink = premultiplied(layer.ink, eased);
-      d[at + 8] = ink[0];
-      d[at + 9] = ink[1];
-      d[at + 10] = ink[2];
-      d[at + 11] = ink[3];
       const halo = layer.halo ? premultiplied(layer.halo, eased) : ZERO;
-      d[at + 12] = halo[0];
-      d[at + 13] = halo[1];
-      d[at + 14] = halo[2];
-      d[at + 15] = halo[3];
-      d[at + 16] = layer.halo ? Math.min(layer.haloPx, reach) : 0;
-      d[at + 17] = level ? 1 : 0;
-      count++;
+      const k = shown.size / atlas.base;
+      const haloPx = layer.halo ? Math.min(layer.haloPx, reach * k) : 0;
+      if (icon && plate && glyph) {
+        // The plate under its halo, the glyph on it, and the name level
+        // beside it: the string is its field less the margin, and its
+        // left edge goes the gap past the plate's right.
+        const ki = icon.size / atlas.base;
+        const plateHalo = layer.halo ? Math.min(layer.haloPx, reach * ki) : 0;
+        count = this._put(
+          count,
+          sx,
+          sy,
+          0,
+          plate,
+          premultiplied(icon.plate, eased),
+          halo,
+          plateHalo,
+          ki,
+        );
+        count = this._put(
+          count,
+          sx,
+          sy,
+          0,
+          glyph,
+          premultiplied(icon.glyph, eased),
+          ZERO,
+          0,
+          ki,
+        );
+        const tx =
+          sx +
+          icon.size / 2 +
+          icon.gap +
+          ((entry.width - 2 * atlas.pad) * k) / 2;
+        count = this._put(count, tx, sy, 0, entry, ink, halo, haloPx, k);
+      } else {
+        count = this._put(
+          count,
+          sx,
+          sy,
+          shown.angle,
+          entry,
+          ink,
+          halo,
+          haloPx,
+          k,
+        );
+      }
+      labels++;
     }
-    this.stats.drawn = count;
-    return { atlas, instances: this._instances, count };
+    this.stats.drawn = labels;
+    return { atlas, instances: this._instances, count, labels };
+  }
+
+  /** One instance — a label's string, or a piece of its icon — written at
+   *  `count`: answers the count after it. Level (`angle` 0) is set on
+   *  whole pixels. */
+  private _put(
+    count: number,
+    x: number,
+    y: number,
+    angle: number,
+    entry: AtlasEntry,
+    ink: Rgba,
+    halo: Rgba,
+    haloPx: number,
+    scale: number,
+  ): number {
+    if (this._instances.length < (count + 1) * LABEL_INSTANCE) {
+      const grown = new Float32Array(this._instances.length * 2);
+      grown.set(this._instances);
+      this._instances = grown;
+    }
+    const d = this._instances;
+    const at = count * LABEL_INSTANCE;
+    const level = angle === 0;
+    d[at] = x;
+    d[at + 1] = y;
+    d[at + 2] = level ? 1 : Math.cos(angle);
+    d[at + 3] = level ? 0 : Math.sin(angle);
+    d[at + 4] = entry.x;
+    d[at + 5] = entry.y;
+    d[at + 6] = entry.width;
+    d[at + 7] = entry.height;
+    d[at + 8] = ink[0];
+    d[at + 9] = ink[1];
+    d[at + 10] = ink[2];
+    d[at + 11] = ink[3];
+    d[at + 12] = halo[0];
+    d[at + 13] = halo[1];
+    d[at + 14] = halo[2];
+    d[at + 15] = halo[3];
+    d[at + 16] = haloPx;
+    d[at + 17] = level ? 1 : 0;
+    d[at + 18] = scale;
+    return count + 1;
   }
 
   // --- internals -------------------------------------------------------------
@@ -587,6 +692,7 @@ export class LabelPlacer {
       point,
       sx,
       sy,
+      ox: 0,
       angle: a,
       cos: Math.cos(a),
       sin: Math.sin(a),
@@ -607,6 +713,18 @@ export class LabelPlacer {
     };
   }
 
+  /** The icon a label of `layer` is set with: none for a name along a
+   *  street, and none where the atlas cannot draw it — the name is then set
+   *  alone rather than not at all. */
+  private _icon(
+    layer: LayerLabels | null | undefined,
+    point: boolean,
+    atlas: LabelAtlas,
+  ): LayerIcon | null {
+    const icon = point ? (layer?.icon ?? null) : null;
+    return icon && !atlas.iconFailed(icon.name) ? icon : null;
+  }
+
   /** Each symbol layer's labelling at this zoom, by layer index — null
    *  where it does not label. */
   private _layersAt(
@@ -630,13 +748,13 @@ export class LabelPlacer {
         symbol.textHaloWidth === undefined
           ? 1
           : resolveZoomed(symbol.textHaloWidth, zoom);
+      // Not rounded: a field draws any size, so a ramp grows the type
+      // continuously rather than a whole pixel at a time.
       const size = Math.max(
         1,
-        Math.round(
-          (symbol.textSize === undefined
-            ? 12
-            : resolveZoomed(symbol.textSize, zoom)) * scale,
-        ),
+        (symbol.textSize === undefined
+          ? 12
+          : resolveZoomed(symbol.textSize, zoom)) * scale,
       );
       return {
         id: layer.id,
@@ -646,10 +764,43 @@ export class LabelPlacer {
         ink,
         halo: halo && haloWidth > 0 ? halo : null,
         haloPx: haloWidth * scale,
+        icon: this._iconOf(symbol, zoom, scale),
       };
     });
   }
 
+  /** A layer's icon at this zoom, or null where it sets none — or names
+   *  one this version does not draw, or a colour that does not parse. */
+  private _iconOf(
+    symbol: SymbolLayer,
+    zoom: number,
+    scale: number,
+  ): LayerIcon | null {
+    if (!isMapIcon(symbol.icon)) return null;
+    const plate = this._color(
+      symbol.iconColor
+        ? resolveZoomed(symbol.iconColor, zoom)
+        : DEFAULT_ICON_COLOR,
+    );
+    const glyph = this._color(
+      symbol.iconGlyphColor
+        ? resolveZoomed(symbol.iconGlyphColor, zoom)
+        : DEFAULT_ICON_GLYPH_COLOR,
+    );
+    if (!plate || !glyph) return null;
+    const size =
+      symbol.iconSize === undefined
+        ? DEFAULT_ICON_SIZE
+        : resolveZoomed(symbol.iconSize, zoom);
+    return {
+      name: symbol.icon,
+      size: Math.max(1, Math.round(size * scale)),
+      gap: ICON_GAP * scale,
+      plate,
+      glyph,
+    };
+  }
+
   private _color(value: string): Rgba | null {
     let color = this._colors.get(value);
     if (color === undefined) {
@@ -743,11 +894,12 @@ class CollisionGrid {
     const out = this._scratch;
     out.length = 0;
     if (c.angle === 0) {
+      const x = c.sx + c.ox;
       out.push(
         0,
-        c.sx - w / 2 - pad,
+        x - w / 2 - pad,
         c.sy - h / 2 - pad,
-        c.sx + w / 2 + pad,
+        x + w / 2 + pad,
         c.sy + h / 2 + pad,
       );
       return out;