@navaramap/three 0.0.6 → 0.0.7

package/src/mesh/sdfText/batchedSdfText.ts

@@ -34,11 +34,18 @@ import type { PickableMesh } from "../pickableMesh";
 import { GlyphBuffers } from "./glyphBuffers";
 import { GlyphSlotAllocator, type GlyphRun } from "./glyphSlots";
 import { LabelDataTexture, LabelRow } from "./labelData";
+import {
+  createAnchorVisibilityState,
+  isAnchorPotentiallyVisible,
+  syncAnchorVisibilityState,
+} from "./labelVisibility";
 import { ALIGN_FACTORS, buildLabelLayout, type LayoutOptions } from "./layout";
+import { PendingSettlement } from "./pendingSettlement";
 
 /** Reusable scratch to avoid per-frame / per-write allocations. */
 const _tmpSize = new Vector2();
 const _tmpColor = new Color();
+const _visibility = createAnchorVisibilityState();
 
 type PositionsInfoBase = {
   batchIDs: Float32Array<ArrayBufferLike> | null;
@@ -80,10 +87,19 @@ type LabelRecord = {
   text: string;
   /**
    * The most recent text asked for. Differs from {@link text} only while an
-   * async font preparation is in flight; the callback compares against it so a
+   * async font preparation is in flight or parked (see
+   * {@link prepareDeferred}); the prepare callback compares against it so a
    * slow prepare can't clobber a newer text that landed meanwhile.
    */
   requestedText: string;
+  /**
+   * True while {@link requestedText} awaits font preparation parked on anchor
+   * visibility: unprepared text is not shaped — and its font faces not
+   * fetched — until a placement pass finds the anchor potentially visible
+   * (inside the frustum and not behind the globe's horizon). See
+   * `prepareDeferredLabels`.
+   */
+  prepareDeferred: boolean;
   /** Glyph-instance slots this label owns, or null when it has no text. */
   run: GlyphRun | null;
   /** Unique atlas glyphs the current text renders. */
@@ -166,6 +182,9 @@ export class BatchedSdfTextMesh
   /** Sparse batchIndex → label; labels are created on first per-feature touch. */
   private _labelByIndex: (LabelRecord | undefined)[] = [];
 
+  /** In-flight per-feature text preparations; see {@link whenLabelsSettled}. */
+  private _pendingTextPrepares = new PendingSettlement();
+
   private _glyphs: GlyphBuffers;
   private _slots = new GlyphSlotAllocator();
   private _labelData: LabelDataTexture;
@@ -175,6 +194,10 @@ export class BatchedSdfTextMesh
   private _lineHeight: number;
   private _textAlign: number;
 
+  /** Labels currently parked in `prepareDeferred`, so the per-pass promotion
+   *  scan can bail without touching `_labels` when nothing is parked. */
+  private _deferredCount = 0;
+
   /** Layer-level declutter settings, mirrored from the material. */
   private _declutter: boolean;
   private _declutterPriority: number;
@@ -357,6 +380,7 @@ export class BatchedSdfTextMesh
       batchId: info.batchIDs ? info.batchIDs[batchIndex * info.batchIDSize] : 0,
       text: "",
       requestedText: "",
+      prepareDeferred: false,
       run: null,
       glyphKeys: [],
       retainedKeys: null,
@@ -539,8 +563,11 @@ export class BatchedSdfTextMesh
    * text is already prepared in the font worker.
    */
   private _applyText(record: LabelRecord, text: string): void {
+    // `requestedText` is deliberately not touched here: it belongs to the
+    // intent-setting paths (`setTextByBatchIndex`, the material-text update).
+    // A re-layout of the *current* text (font/layout change) must not clobber
+    // a newer intent that is still in flight or parked on visibility.
     record.text = text;
-    record.requestedText = text;
 
     if (!text) {
       this._releaseRun(record);
@@ -781,6 +808,7 @@ export class BatchedSdfTextMesh
         isShown: record.declutterTarget === 0,
         owner: this,
         handle: record.slot,
+        contentKey: record.text,
       });
     }
   }
@@ -822,10 +850,52 @@ export class BatchedSdfTextMesh
   }
 
   override setActive(active: boolean) {
+    const activating = active && !this.active;
     super.setActive(active);
+    // Tile-swap handoff: this batch replaces another (its parent tile is
+    // hidden in the same swap), so any label whose content the previous
+    // declutter pass already showed nearby starts granted instead of fading
+    // in from hidden — otherwise every swap blinks the whole tile's labels
+    // out for a throttled pass plus a fade-in. Genuinely new labels keep the
+    // fade; the next pass re-places everything and corrects any misseed.
+    if (activating && this._declutter) {
+      const declutter = this.ctx.declutter;
+      if (declutter) {
+        for (const record of this._labels) {
+          if (!record.show || record.declutterHide === 0) continue;
+          const a = record.anchor;
+          if (declutter.wasRecentlyShown(record.text, a[0], a[1], a[2])) {
+            record.declutterHide = 0;
+            record.declutterTarget = 0;
+            this._writeDeclutterHide(record);
+          }
+        }
+      }
+    }
     this._markDeclutterDirty();
   }
 
+  /**
+   * Resolves once every per-feature text preparation currently in flight has
+   * landed (glyph runs written), bounded by `timeoutMs`.
+   *
+   * The tile-LOD swap on the Rust side hides a parent tile the moment its
+   * children report rendered, so the caller must not report this batch
+   * rendered while labels are still shaping — the swap would show a batch
+   * that draws nothing (a tile-shaped blank).
+   *
+   * Only preparations already started are awaited. With declutter enabled,
+   * `setTextByBatchIndex` parks unprepared text until a placement pass
+   * confirms the anchor is on screen, so those labels are not yet in flight
+   * and this resolves immediately — cached text (the common case for a child
+   * tile repeating its parent's strings) applies synchronously and needs no
+   * wait either. The gate therefore only bites on the non-decluttered path;
+   * decluttered swaps rely on the placement handoff in {@link setActive}.
+   */
+  whenLabelsSettled(timeoutMs: number): Promise<void> {
+    return this._pendingTextPrepares.whenSettled(timeoutMs);
+  }
+
   // --- Picking ---
 
   override onBeforePicking() {
@@ -906,6 +976,11 @@ export class BatchedSdfTextMesh
 
     const material = m.material;
     const text = material.text ?? "";
+    // Kept so _applyUpdate can tell which material fields actually changed:
+    // engine change events re-send the full material even when only geometry
+    // or activation moved, and only genuine changes may overwrite per-feature
+    // (evaluator-set) values.
+    const prevMaterial = this._material;
     this._material = material;
     this._transform = m.transform;
 
@@ -964,7 +1039,7 @@ export class BatchedSdfTextMesh
       this._fontManager
         .prepareText(this._fontIdentifier, text, q, this._loadedFaceUrls)
         .then(() => {
-          this._applyUpdate(material, needRender, needFontUpdate);
+          this._applyUpdate(material, prevMaterial, needRender, needFontUpdate);
         })
         .catch((err: unknown) => {
           console.error("Failed to prepare text:", err);
@@ -973,11 +1048,12 @@ export class BatchedSdfTextMesh
       return;
     }
 
-    this._applyUpdate(material, needRender, needFontUpdate);
+    this._applyUpdate(material, prevMaterial, needRender, needFontUpdate);
   }
 
   private _applyUpdate(
     material: NavaraTextMaterial,
+    prevMaterial: NavaraTextMaterial,
     needRender?: () => void,
     forceUpdate = false,
   ) {
@@ -1029,27 +1105,48 @@ export class BatchedSdfTextMesh
       },
     });
 
-    // Per-label values the material supplies defaults for. This mirrors the
-    // pre-batching behaviour where a material update overwrote whatever the
-    // evaluator had set per feature.
+    // Per-label values the material supplies defaults for. A *changed*
+    // material value overwrites whatever the evaluator had set per feature
+    // (mirroring the pre-batching behaviour for real `layer.update` calls) —
+    // but engine change events re-send the whole material for geometry or
+    // activation updates too, and stomping evaluator values with an unchanged
+    // material made labels visibly pulse: every terrain-height event reset
+    // per-feature sizes to the default for a few frames until the app's
+    // evaluator ran again.
     const materialText = material.text;
     const materialShow = material.show ?? true;
     const colorHex = material.color ?? 0xffffff;
     const opacity = clamp01(material.opacity ?? 1.0);
     const fontSize = material.size ?? 16.0;
     const addHeight = material.height ?? 0;
+    const showChanged = materialShow !== (prevMaterial.show ?? true);
+    const styleChanged =
+      colorHex !== (prevMaterial.color ?? 0xffffff) ||
+      opacity !== clamp01(prevMaterial.opacity ?? 1.0);
+    const fontSizeChanged = fontSize !== (prevMaterial.size ?? 16.0);
+    const addHeightChanged = addHeight !== (prevMaterial.height ?? 0);
 
     for (const record of this._labels) {
-      record.colorHex = colorHex;
-      record.opacity = opacity;
-      record.fontSize = fontSize;
-      record.addHeight = addHeight;
-      this._writeStyle(record);
-      this._writeFontSize(record);
-      this._writeAddHeight(record);
-
-      record.requestedShow = materialShow;
+      if (styleChanged) {
+        record.colorHex = colorHex;
+        record.opacity = opacity;
+        this._writeStyle(record);
+      }
+      if (fontSizeChanged) {
+        record.fontSize = fontSize;
+        this._writeFontSize(record);
+      }
+      if (addHeightChanged) {
+        record.addHeight = addHeight;
+        this._writeAddHeight(record);
+      }
+
+      if (showChanged) record.requestedShow = materialShow;
       if (materialText !== undefined && materialText !== "") {
+        // The material text overrides whatever the evaluator asked for —
+        // including a prepare that is in flight or parked on visibility.
+        record.requestedText = materialText;
+        this._clearDeferred(record);
         this._applyText(record, materialText);
       } else if (forceUpdate || layoutChanged) {
         // Font or layout changed — re-lay-out existing text.
@@ -1085,6 +1182,43 @@ export class BatchedSdfTextMesh
         this._highQuality,
       )
     ) {
+      // Unprepared text costs a worker round-trip and possibly font-face
+      // fetches, and low-zoom tiles span far more world than the screen shows
+      // (a z0 tile carries every country's name). Park preparation until a
+      // placement pass confirms the anchor can actually appear on screen
+      // (`prepareDeferredLabels`). Deciding here instead would race camera
+      // initialization: early tiles evaluate before the first render commits
+      // the camera pose to `matrixWorld`, wrongly passing far-side labels.
+      // The pass runs with the render camera on the next frame, so visible
+      // labels start preparing at most one throttle window later.
+      if (this.ctx.declutter) {
+        if (!record.prepareDeferred) {
+          record.prepareDeferred = true;
+          this._deferredCount++;
+        }
+        this._markDeclutterDirty();
+        this._needRender?.();
+        return;
+      }
+      this._prepareAndApply(record, text);
+      return;
+    }
+
+    this._clearDeferred(record);
+    this._applyText(record, text);
+    this._markDeclutterDirty();
+    this._needRender?.();
+  }
+
+  /** Kick off async font preparation for `text`, then lay it out — unless a
+   *  newer text supersedes it while the fonts load. */
+  private _prepareAndApply(record: LabelRecord, text: string): void {
+    // Tracked so `whenLabelsSettled` can gate the tile's render-completion
+    // report on the glyphs actually being written (this chain ends after
+    // `_applyText`), not merely on the font round-trip finishing. This is the
+    // single point where preparation starts — both the inline path above and
+    // the promotion of a parked label in `prepareDeferredLabels` route here.
+    this._pendingTextPrepares.track(
       this._fontManager
         .prepareText(
           this._fontIdentifier,
@@ -1103,13 +1237,50 @@ export class BatchedSdfTextMesh
         .catch((err: unknown) => {
           console.error("Failed to prepare text:", err);
           this._needRender?.();
-        });
-      return;
+        }),
+    );
+  }
+
+  private _clearDeferred(record: LabelRecord): void {
+    if (record.prepareDeferred) {
+      record.prepareDeferred = false;
+      this._deferredCount--;
     }
+  }
 
-    this._applyText(record, text);
-    this._markDeclutterDirty();
-    this._needRender?.();
+  /**
+   * Promote parked labels whose anchor became potentially visible: start
+   * their font preparation and apply the text when it lands. Runs at the
+   * start of every placement pass (see {@link DeclutterParticipant}) — the
+   * cadence at which visibility can actually change.
+   */
+  prepareDeferredLabels(camera: PerspectiveCamera): void {
+    if (this._deferredCount === 0 || !this.visible) return;
+    const state = syncAnchorVisibilityState(camera, _visibility);
+    for (const record of this._labels) {
+      if (!record.prepareDeferred) continue;
+      const a = record.anchor;
+      if (!isAnchorPotentiallyVisible(state, a[0], a[1], a[2])) continue;
+      this._clearDeferred(record);
+
+      const text = record.requestedText;
+      // Parked intent may have gone stale: cleared, or applied via another
+      // path (e.g. a material-level text update).
+      if (!text || text === record.text) continue;
+      if (
+        this._fontManager.isTextPrepared(
+          this._fontIdentifier,
+          text,
+          this._highQuality,
+        )
+      ) {
+        this._applyText(record, text);
+        this._markDeclutterDirty();
+        this._needRender?.();
+        continue;
+      }
+      this._prepareAndApply(record, text);
+    }
   }
 
   override setFeatureColorByBatchIndex(batchIndex: number, color: Color) {

package/src/mesh/sdfText/labelVisibility.test.ts

@@ -0,0 +1,106 @@
+import { PerspectiveCamera } from "three";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createAnchorVisibilityState,
+  isAnchorPotentiallyVisible,
+  syncAnchorVisibilityState,
+} from "./labelVisibility";
+
+// The ellipsoid getters cross into WASM, which is only initialized by
+// `view.init()`. Stub them with the f32 values the engine returns (navara_core
+// `WGS84_32`) so the radius band is exercised without a live view.
+vi.mock("@navaramap/three-api", () => ({
+  getWGS84SemiMajorAxis: () => 6_378_137,
+  getWGS84SemiMinorAxis: () => 6_356_752.5,
+}));
+
+/** Equatorial Earth radius (m); anchors at this length get the horizon test. */
+const R = 6_378_137;
+
+function makeCamera(
+  x: number,
+  y: number,
+  z: number,
+  fov = 60,
+): PerspectiveCamera {
+  const cam = new PerspectiveCamera(fov, 1, 1, 1e9);
+  cam.position.set(x, y, z);
+  cam.lookAt(0, 0, 0);
+  cam.updateMatrixWorld(true);
+  cam.updateProjectionMatrix();
+  return cam;
+}
+
+function visible(
+  cam: PerspectiveCamera,
+  x: number,
+  y: number,
+  z: number,
+): boolean {
+  const state = syncAnchorVisibilityState(cam, createAnchorVisibilityState());
+  return isAnchorPotentiallyVisible(state, x, y, z);
+}
+
+/** Surface anchor at `deg` degrees (around +Z) away from the sub-camera
+ *  point of a camera on the +X axis. */
+const surfaceAnchor = (deg: number): [number, number, number] => {
+  const rad = (deg * Math.PI) / 180;
+  return [R * Math.cos(rad), R * Math.sin(rad), 0];
+};
+
+describe("isAnchorPotentiallyVisible", () => {
+  describe("globe horizon", () => {
+    // Camera at 2R from the center: the geometric horizon sits at
+    // acos(R / 2R) = 60° from the sub-camera point; HORIZON_MARGIN (0.95)
+    // relaxes the cutoff to acos(0.95 / 2) ≈ 61.7°.
+    const cam = makeCamera(2 * R, 0, 0);
+
+    it("keeps the sub-camera point", () => {
+      expect(visible(cam, ...surfaceAnchor(0))).toBe(true);
+    });
+
+    it("keeps anchors just past the horizon (margin)", () => {
+      expect(visible(cam, ...surfaceAnchor(61))).toBe(true);
+    });
+
+    it("culls anchors clearly beyond the horizon", () => {
+      expect(visible(cam, ...surfaceAnchor(63))).toBe(false);
+    });
+
+    it("culls the antipode", () => {
+      expect(visible(cam, -R, 0, 0)).toBe(false);
+    });
+
+    it("never applies the horizon test outside the Earth-surface band", () => {
+      // Same direction as the antipode but at non-globe scale: only the
+      // frustum decides, and this point sits in front of the camera.
+      expect(visible(cam, -1000, 0, 0)).toBe(true);
+    });
+  });
+
+  describe("frustum", () => {
+    // Camera at +Z looking at the origin; fov 60 and aspect 1 put the exact
+    // frustum edge at |NDC| = 1 and the NDC_MARGIN (1.4) cutoff beyond it.
+    const cam = makeCamera(0, 0, 1000);
+
+    it("keeps anchors in front of the camera", () => {
+      expect(visible(cam, 0, 0, 0)).toBe(true);
+    });
+
+    it("culls anchors behind the camera", () => {
+      expect(visible(cam, 0, 0, 2000)).toBe(false);
+    });
+
+    it("keeps anchors slightly outside the viewport (margin)", () => {
+      // At depth 1000 the frustum half-extent is tan(30°)·1000 ≈ 577; x=700
+      // is ~1.2 in NDC — outside the screen but inside the 1.4 margin.
+      expect(visible(cam, 700, 0, 0)).toBe(true);
+    });
+
+    it("culls anchors well outside the viewport", () => {
+      // x=900 is ~1.56 in NDC, past the 1.4 margin.
+      expect(visible(cam, 900, 0, 0)).toBe(false);
+    });
+  });
+});

package/src/mesh/sdfText/labelVisibility.ts

@@ -0,0 +1,131 @@
+import {
+  getWGS84SemiMajorAxis,
+  getWGS84SemiMinorAxis,
+} from "@navaramap/three-api";
+import { Matrix4, type PerspectiveCamera } from "three";
+
+/**
+ * Camera-derived state for testing whether a label anchor could appear on
+ * screen. Snapshot it once per scan with {@link syncAnchorVisibilityState},
+ * then test any number of anchors with {@link isAnchorPotentiallyVisible}.
+ */
+export type AnchorVisibilityState = {
+  /** Column-major view-projection matrix. */
+  vp: Float64Array;
+  /** Camera world position (ECEF meters). */
+  camX: number;
+  camY: number;
+  camZ: number;
+};
+
+export const createAnchorVisibilityState = (): AnchorVisibilityState => ({
+  vp: new Float64Array(16),
+  camX: 0,
+  camY: 0,
+  camZ: 0,
+});
+
+/**
+ * Fractional tolerance on the Earth-surface radius band. An anchor whose
+ * distance from the origin lands within this fraction of the WGS84 radii is
+ * treated as sitting on the globe and gets the horizon test; anchors outside
+ * the band (planar/local scenes, points far above the surface) rely on the
+ * frustum test alone. 5% reaches from well below the polar radius up to the
+ * equatorial radius plus high terrain and label height offsets — the band is a
+ * "is this a globe anchor at all" filter, so it is deliberately loose.
+ */
+const EARTH_BAND_TOLERANCE = 0.05;
+
+/**
+ * Squared band bounds, derived from the engine's WGS84 ellipsoid (Rust side)
+ * rather than from literals, so the band follows the engine's definition.
+ * Resolved on first use, not at module scope: `@navaramap/three-api` only
+ * answers once `view.init()` has initialized the WASM module. Memoized because
+ * the bounds are tested once per anchor in the label scan.
+ */
+let bandMin2 = 0;
+let bandMax2 = 0;
+
+const resolveEarthBand = () => {
+  const min = getWGS84SemiMinorAxis() * (1 - EARTH_BAND_TOLERANCE);
+  const max = getWGS84SemiMajorAxis() * (1 + EARTH_BAND_TOLERANCE);
+  bandMin2 = min * min;
+  bandMax2 = max * max;
+};
+
+/**
+ * Relaxation factor for the horizon test. `1` is the exact tangent-plane
+ * cutoff; lowering it admits anchors slightly beyond the horizon so labels
+ * near the limb start preparing (fonts fetching, glyphs shaping) before the
+ * camera fully reveals them.
+ */
+const HORIZON_MARGIN = 0.95;
+
+/**
+ * Clip-space margin factor for the frustum test. `1` is the exact viewport;
+ * `1.4` treats anchors within 40% beyond each edge as potentially visible, so
+ * a label whose box pokes into view, or that is about to pan in, is prepared
+ * slightly ahead of need.
+ */
+const NDC_MARGIN = 1.4;
+
+const _view = new Matrix4();
+const _viewProj = new Matrix4();
+
+/**
+ * Snapshot the camera into `out`. Derives the view matrix from `matrixWorld`
+ * rather than trusting `matrixWorldInverse`, which can be stale outside the
+ * render pass (same reasoning as `DeclutterManager._run`).
+ */
+export function syncAnchorVisibilityState(
+  camera: PerspectiveCamera,
+  out: AnchorVisibilityState,
+): AnchorVisibilityState {
+  _view.copy(camera.matrixWorld).invert();
+  _viewProj.multiplyMatrices(camera.projectionMatrix, _view);
+  out.vp.set(_viewProj.elements);
+  const e = camera.matrixWorld.elements;
+  out.camX = e[12];
+  out.camY = e[13];
+  out.camZ = e[14];
+  return out;
+}
+
+/**
+ * Whether a world-space (ECEF meters) anchor could appear on screen —
+ * deliberately optimistic: `false` is only returned when the anchor is
+ * provably out of view (behind the globe's horizon or well outside the
+ * frustum), so callers can safely skip work for hidden anchors and never
+ * miss a visible one.
+ */
+export function isAnchorPotentiallyVisible(
+  state: AnchorVisibilityState,
+  x: number,
+  y: number,
+  z: number,
+): boolean {
+  // Horizon: an anchor on the globe is beyond the horizon when the camera
+  // sits below the anchor's tangent plane — dot(C, P) < |P|². Only applied
+  // inside the Earth-surface band so non-globe anchors are never culled by it.
+  if (bandMax2 === 0) resolveEarthBand();
+  const r2 = x * x + y * y + z * z;
+  if (
+    r2 > bandMin2 &&
+    r2 < bandMax2 &&
+    x * state.camX + y * state.camY + z * state.camZ < r2 * HORIZON_MARGIN
+  ) {
+    return false;
+  }
+
+  // Frustum with margin. Near/far are ignored on purpose: an anchor beyond
+  // the far plane is still "potentially visible" the moment the camera pulls
+  // back, and being optimistic there costs at most one early preparation.
+  const vp = state.vp;
+  const w = vp[3] * x + vp[7] * y + vp[11] * z + vp[15];
+  if (w <= 0) return false; // behind the camera
+  const m = w * NDC_MARGIN;
+  const cx = vp[0] * x + vp[4] * y + vp[8] * z + vp[12];
+  if (cx < -m || cx > m) return false;
+  const cy = vp[1] * x + vp[5] * y + vp[9] * z + vp[13];
+  return cy >= -m && cy <= m;
+}