@navaramap/three 0.0.0

package/src/event/context.ts

@@ -0,0 +1,279 @@
+import type {
+  Color as CoreColor,
+  ColorMap,
+  EventHandler,
+  EventManager,
+} from "@navaramap/core";
+import type {
+  DelegatedWorkerTasksResult,
+  ElevationDecoder,
+  ReconstructableEntity,
+  ReturnedTransferablePolygonBatchedFeature,
+  ReturnedTransferablePolylineBatchedFeature,
+  TextureFragmentStatus,
+  TransferableMartini,
+  TransferableTile,
+  VectorTileState,
+} from "@navaramap/engine";
+import type { FontManager } from "@navaramap/font";
+import type { Texture } from "three";
+
+import type { ViewEvents } from "..";
+import type { ThreeViewCamera } from "../camera";
+import type { ViewContext } from "../core";
+import type { LayersManager } from "../layersManager";
+import type { TileMesh } from "../mesh/tile";
+import type { Scenes, TexturizedSceneByTileCoordinates } from "../scene";
+import type { TextureOptions } from "../textures";
+import type { TileTextureCompositor } from "../tileTexture";
+import type {
+  AbortControllers,
+  MeshCache,
+  WorkerPoolPromises,
+  RenderFlag,
+  TileMapByHandle,
+} from "../type";
+import type { CommonUniforms } from "../uniforms";
+import type { TextureSlot } from "../utils";
+
+import type { HillshadeContext } from "./HillshadeContext";
+
+export type BufferLoader = {
+  // The non-removing getters (u8/f32/f64/u32) return short-lived VIEWS into
+  // WASM linear memory: consume them immediately and `.slice()` to retain —
+  // any WASM call that allocates may grow the memory and detach the view.
+  // Never hand their `.buffer` (the whole WASM memory) to another consumer.
+  // Consecutive getter calls do not allocate, so earlier views stay valid.
+  u8: (handle: number) => Uint8Array | null;
+  f32: (handle: number) => Float32Array | null;
+  f64: (handle: number) => Float64Array | null;
+  u32: (handle: number) => Uint32Array | null;
+  // The remove* variants return owned copies (the WASM-side buffer is freed).
+  removeU8: (handle: number) => Uint8Array | null;
+  removeF32: (handle: number) => Float32Array | null;
+  removeF64: (handle: number) => Float64Array | null;
+  removeU32: (handle: number) => Uint32Array | null;
+  setU8: (handle: number, bits: bigint, bytes: Uint8Array) => void;
+  newU8: (bytes: Uint8Array) => number | undefined;
+  newU32: (bytes: Uint32Array) => number | undefined;
+  newF32: (bytes: Float32Array) => number | undefined;
+  newF64: (bytes: Float64Array) => number | undefined;
+  // The `adopt*` variants register a JS-owned array in the `InMemoryBufferStore`
+  // (zero-copy — the array is kept as-is) and hand WASM a byte-count-only
+  // `External` handle, so worker-built geometry never round-trips through WASM
+  // linear memory. The getters (u8/f32/...) return it directly; remove* takes it
+  // and clears the WASM-side accounting.
+  adoptU8: (array: Uint8Array) => number | undefined;
+  adoptU32: (array: Uint32Array) => number | undefined;
+  adoptF32: (array: Float32Array) => number | undefined;
+  adoptF64: (array: Float64Array) => number | undefined;
+  /** DataRequester mirror of `adoptU8`: registers an `External` entry under an
+   * existing handle and fires the loaded event. Guards on `hasDataRequester`.
+   * An `External` entry carries no element type, so this is not typed. */
+  setExternal: (handle: number, bits: bigint, array: Uint8Array) => void;
+  remove: (handle: number) => void;
+  /** Evict handles Rust removed from the WASM `BufferStore` out of the JS-side
+   * `InMemoryBufferStore`; called once per frame. */
+  drainRemovedExternalHandles: () => void;
+  triggerDataRequesterLoaded: (bits: bigint, handle: number) => void;
+  triggerDataRequesterFailed: (bits: bigint) => void;
+};
+
+export type TextureFragmentHandler = {
+  triggerTextureFragmentLoaded: (
+    bits: bigint,
+    status: TextureFragmentStatus,
+  ) => void;
+};
+
+export type WorkerTaskHandler = {
+  triggerWorkerTaskCompleted: (
+    bits: bigint,
+    result: DelegatedWorkerTasksResult,
+  ) => void;
+  /**
+   * Release the delegator of a task that ended without a deliverable result.
+   * Consumes `delegator_id`; a no-op for a task the engine already cancelled.
+   */
+  triggerWorkerTaskFailed: (delegator_id: ReconstructableEntity) => void;
+  hasWorkerTask: (bits: bigint) => boolean;
+};
+
+export type TileHandler = {
+  getMartini: (bits: ReconstructableEntity) => TransferableMartini | undefined;
+  getTile: (handle: bigint) => TransferableTile | undefined;
+  getParentTile: (handle: bigint) => TransferableTile | undefined;
+  getTileElevationDecoder: (handle: bigint) => ElevationDecoder | undefined;
+  getVectorTileStates: (handle: bigint) => VectorTileState[] | undefined;
+  vectorRevision: () => number;
+  /** Reports a terrain tile's drape render-target GPU footprint (bytes) so the
+   * memory ledger tracks clamp-to-ground vector bakes that scale with terrain
+   * subdivision past the vector `maxZoom`. Pass 0 to release on dispose. */
+  reportDrapeGpuBytes: (handle: bigint, bytes: number) => void;
+  calcMetersPerTexel: (
+    tileHandle: bigint,
+    textureZoom: number,
+    textureWidth: number,
+  ) => number;
+};
+
+/**
+ * Handler for accessing individual Globe properties from WASM.
+ * This provides a reference-based interface instead of copying the entire Globe object.
+ */
+export type GlobeHandler = {
+  getTransparent: () => boolean | undefined;
+  getMaxSse: () => number | undefined;
+  getSegments: () => number | undefined;
+  getColor: () => CoreColor | undefined;
+  getHideUnderground: () => boolean | undefined;
+  getUseNormal: () => boolean | undefined;
+  getOpacity: () => number | undefined;
+  getWireframe: () => boolean | undefined;
+  getElevationColormap: () => Float32Array | undefined;
+  setTransparent: (value: boolean) => void;
+  setMaxSse: (value: number) => void;
+  setSegments: (value: number) => void;
+  setColor: (value: CoreColor) => void;
+  setHideUnderground: (value: boolean) => void;
+  setUseNormal: (value: boolean) => void;
+  setOpacity: (value: number) => void;
+  setWireframe: (value: boolean) => void;
+  setElevationColormap: (value: ColorMap) => void;
+};
+
+export type FeatureHandler = {
+  getTransferablePolygonBatchedFeature: (
+    bits: bigint,
+  ) => ReturnedTransferablePolygonBatchedFeature | undefined;
+  getTransferablePolylineBatchedFeature: (
+    bits: bigint,
+  ) => ReturnedTransferablePolylineBatchedFeature | undefined;
+  markFeatureIsRendered: (
+    type: "point" | "polyline" | "polygon" | "model",
+    bits: bigint,
+  ) => void;
+  /** Reports a rendered feature's actual measured GPU byte size so the memory
+   * ledger replaces its payload-based estimate. Feature kinds the engine has
+   * no owner lookup for are a no-op (currently wired: 3D Tiles models, whose
+   * post-glTF/Draco-decode size undercounts otherwise). */
+  reportFeatureGpuBytes: (bits: bigint, bytes: number) => void;
+  readAllBatchedProperties(
+    bits: bigint,
+    callback: (
+      batchIdx: number,
+      batchId: number,
+      properties?: Record<string, unknown>,
+    ) => void,
+  ): void;
+  readFilteredBatchedProperties(
+    bits: bigint,
+    keys: string[],
+    callback: (batchIdx: number, batchId: number, filtered?: unknown[]) => void,
+  ): void;
+};
+
+export type MeshHandler = {
+  setTileMeshPrepared: (handle: bigint) => void;
+};
+
+export type LayerHandler = {
+  getLayerIndex: (layerId: string) => number | undefined;
+};
+
+type EventContextArgs = {
+  eventManager: EventManager;
+  scenes: Scenes;
+  camera: ThreeViewCamera;
+  meshes: MeshCache;
+  abortControllers: AbortControllers;
+  buf: BufferLoader;
+  texFragment: TextureFragmentHandler;
+  tileHandler: TileHandler;
+  workerTaskHandler: WorkerTaskHandler;
+  meshHandler: MeshHandler;
+  featureHandler: FeatureHandler;
+  loadedTexs: Map<string, Texture>;
+  workerPoolPromises: WorkerPoolPromises;
+  uniforms: CommonUniforms;
+  texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+  tileTextureCompositor: TileTextureCompositor;
+  tileMapByHandle: TileMapByHandle;
+  textureOptions: TextureOptions;
+  renderFlag: RenderFlag;
+  viewEvents: EventHandler<ViewEvents>;
+  layersManager: LayersManager;
+  viewContext: ViewContext;
+  layerHandler?: LayerHandler;
+  fontManager?: FontManager;
+  textureFragmentIndex?: Map<string, Set<TextureSlot>>;
+  tileMeshToFragmentIds?: Map<TileMesh, Set<string>>;
+  hillshadeContext?: HillshadeContext;
+};
+
+/**
+ * EventContext bundles all the shared state needed to process engine events
+ * and propagate them into each processor.
+ */
+export class EventContext {
+  readonly eventManager: EventManager;
+  readonly scenes: Scenes;
+  readonly camera: ThreeViewCamera;
+  readonly meshes: MeshCache;
+  readonly abortControllers: AbortControllers;
+  readonly buf: BufferLoader;
+  readonly texFragment: TextureFragmentHandler;
+  readonly tileHandler: TileHandler;
+  readonly workerTaskHandler: WorkerTaskHandler;
+  readonly meshHandler: MeshHandler;
+  readonly featureHandler: FeatureHandler;
+  readonly loadedTexs: Map<string, Texture>;
+  readonly workerPoolPromises: WorkerPoolPromises;
+  readonly uniforms: CommonUniforms;
+  readonly texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+  readonly tileTextureCompositor: TileTextureCompositor;
+  readonly tileMapByHandle: TileMapByHandle;
+  readonly textureOptions: TextureOptions;
+  readonly renderFlag: RenderFlag;
+  readonly viewEvents: EventHandler<ViewEvents>;
+  readonly layersManager: LayersManager;
+  readonly viewContext: ViewContext;
+  readonly layerHandler?: LayerHandler;
+  readonly fontManager?: FontManager;
+  readonly textureFragmentIndex?: Map<string, Set<TextureSlot>>;
+  readonly tileMeshToFragmentIds?: Map<TileMesh, Set<string>>;
+  readonly hillshadeContext?: HillshadeContext;
+
+  updatedAt = 0;
+
+  constructor(args: EventContextArgs) {
+    this.eventManager = args.eventManager;
+    this.scenes = args.scenes;
+    this.camera = args.camera;
+    this.meshes = args.meshes;
+    this.abortControllers = args.abortControllers;
+    this.buf = args.buf;
+    this.texFragment = args.texFragment;
+    this.tileHandler = args.tileHandler;
+    this.workerTaskHandler = args.workerTaskHandler;
+    this.meshHandler = args.meshHandler;
+    this.featureHandler = args.featureHandler;
+    this.loadedTexs = args.loadedTexs;
+    this.workerPoolPromises = args.workerPoolPromises;
+    this.uniforms = args.uniforms;
+    this.texturizedSceneByTileCoordinates =
+      args.texturizedSceneByTileCoordinates;
+    this.tileTextureCompositor = args.tileTextureCompositor;
+    this.tileMapByHandle = args.tileMapByHandle;
+    this.textureOptions = args.textureOptions;
+    this.renderFlag = args.renderFlag;
+    this.viewEvents = args.viewEvents;
+    this.layersManager = args.layersManager;
+    this.viewContext = args.viewContext;
+    this.layerHandler = args.layerHandler;
+    this.fontManager = args.fontManager;
+    this.textureFragmentIndex = args.textureFragmentIndex;
+    this.tileMeshToFragmentIds = args.tileMeshToFragmentIds;
+    this.hillshadeContext = args.hillshadeContext;
+  }
+}

package/src/event/feature.ts

@@ -0,0 +1,357 @@
+import type { TileHandle } from "@navaramap/core";
+import { generate_id_from_entity } from "@navaramap/core";
+import {
+  type RenderableFeatureAddedEvent,
+  type RenderableFeature,
+  RenderableFeatureChangedEvent,
+} from "@navaramap/engine";
+import { Mesh, Sprite, Object3D, Scene } from "three";
+
+import {
+  BatchedSdfTextMesh,
+  InstancedSpriteMesh,
+  ModelMesh,
+  PolygonMesh,
+  PolylineMesh,
+} from "../mesh";
+import { FEATURE_RENDER_ORDER } from "../renderOrder";
+import type { Scenes } from "../scene";
+
+import type { EventContext } from "./context";
+import {
+  handleFeatureCreatedEventByLayerId,
+  handleFeatureUpdatedEventByLayerId,
+  handleFeatureVisibilityChangedEventByLayerId,
+} from "./featureEvent";
+import { renderBillboard, processBillboardChanged } from "./features/billboard";
+import { renderModel, processModelChanged } from "./features/model";
+import { sumModelGpuBytes } from "./features/modelGpuBytes";
+import { renderPoint, processPointChanged } from "./features/point";
+import { renderPolygon, processPolygonChanged } from "./features/polygon";
+import {
+  renderPolygonOutline,
+  processPolygonOutlineChanged,
+} from "./features/polygonOutline";
+import { renderPolyline, processPolylineChanged } from "./features/polyline";
+import { renderText, processTextChanged } from "./features/text";
+
+import { setTransform } from ".";
+
+/**
+ * Choose the render scene for a non-draped feature based on its material.
+ *
+ * Sprites (billboards/points) and SDF text configured with `depthTest: false`
+ * are meant to render always-on-top. Left in the MRT scene they draw before the
+ * depth-based post-processing effects (aerial perspective, clouds, ssao,
+ * atmosphere), which sample the depth buffer — where these features wrote
+ * nothing — and composite over them, painting them out. Route them into the
+ * transparent scene, which TransparentPassEffectDesc renders (clear=false)
+ * after those effects. Every other non-draped feature stays in the MRT scene.
+ *
+ * The material comes straight from the engine event (the source of truth): text
+ * applies its Three material asynchronously (behind font preparation), so the
+ * live mesh material can lag behind the intended `depthTest`.
+ */
+function overlayScene(
+  material: { depthTest?: boolean } | undefined,
+  scenes: Scenes,
+): Scene {
+  return material?.depthTest === false ? scenes.transparent : scenes.mrt;
+}
+
+export function renderFeature(
+  ctx: EventContext,
+  f: RenderableFeature,
+  tileHandle: TileHandle | undefined,
+  layerId: string,
+): Promise<Mesh | Sprite | Object3D | undefined> | undefined {
+  if (f.point) {
+    return renderPoint(ctx, f.point);
+  }
+  if (f.billboard) {
+    return renderBillboard(ctx, f.billboard);
+  }
+  if (f.model) {
+    return renderModel(ctx, f.model);
+  }
+  if (f.polyline) {
+    return renderPolyline(ctx, f.polyline);
+  }
+  if (f.polygon) {
+    return renderPolygon(ctx, f.polygon, tileHandle, layerId);
+  }
+  if (f.text) {
+    return renderText(ctx, f.text, layerId);
+  }
+}
+
+// Define whether the feature uses web worker internally.
+// - `model` feature uses Web worker internally to parse glTF and its compression.
+export const checkFeatureParallel = (feature: RenderableFeature): boolean => {
+  const { model } = feature;
+  return !!model;
+};
+
+export async function processRenderableFeatureAdded(
+  ctx: EventContext,
+  ev: RenderableFeatureAddedEvent,
+) {
+  const {
+    scenes,
+    meshes,
+    texturizedSceneByTileCoordinates,
+    featureHandler,
+    viewEvents,
+    layersManager,
+    viewContext,
+    updatedAt,
+    layerHandler,
+  } = ctx;
+  const id = generate_id_from_entity(ev);
+  const feature = ev.feature;
+
+  const { point, billboard, text, polyline, polygon, model } = feature;
+
+  const overscaledTileHandle = ev.overscaled_tile_handle;
+
+  const tileHandle = overscaledTileHandle?.handle;
+
+  const featureLayerId = ev.layer_id;
+
+  const useParallel = checkFeatureParallel(feature);
+
+  if (useParallel) {
+    // Start parallel process
+    viewContext.concurrencyManager.increment();
+  }
+
+  const obj = await renderFeature(ctx, feature, tileHandle, featureLayerId)
+    ?.then((r) => {
+      const type = (() => {
+        if (point || billboard || text) return "point";
+        else if (model) return "model";
+        else if (polyline) return "polyline";
+        else if (polygon) return "polygon";
+      })();
+      if (type) {
+        featureHandler.markFeatureIsRendered(type, ev.bits);
+      }
+      // The glTF/Draco decode happened on the JS side, so report the actual
+      // decoded GPU size back to the ledger (its compressed-payload estimate
+      // undercounts Draco content). Draco decode inflates geometry markedly.
+      if (model && r) {
+        featureHandler.reportFeatureGpuBytes(ev.bits, sumModelGpuBytes(r));
+      }
+      // The billboard image atlas (CPU pixel buffer + GPU texture) is
+      // allocated and grown lazily on the JS side as images load, so the
+      // mesh reports its measured footprint whenever it changes; the ledger
+      // folds it into the owning vector tile's cost. Capture `bits` as a
+      // plain number now: the reporter fires long after this WASM event
+      // object is freed (async image packs), and a deferred `ev.bits` read
+      // would throw "null pointer passed to rust".
+      if (billboard && r instanceof InstancedSpriteMesh) {
+        const featureBits = ev.bits;
+        r.setAtlasBytesReporter((bytes) =>
+          featureHandler.reportFeatureGpuBytes(featureBits, bytes),
+        );
+      }
+      return r;
+    })
+    .finally(() => {
+      if (useParallel) {
+        // End parallel process
+        viewContext.concurrencyManager.decrement();
+      }
+    });
+
+  if (!obj) return;
+
+  // Sprite should be handled by mesh itself.
+  const transform = (polyline ?? polygon ?? model)?.transform;
+  if (transform) {
+    setTransform(obj, transform);
+  }
+
+  obj.renderOrder = FEATURE_RENDER_ORDER;
+
+  // Add to MRT scene if not draped (draped features render to texturized scene)
+  const isDraped =
+    (obj instanceof PolygonMesh && obj.clampToGround) ||
+    (obj instanceof PolylineMesh && obj.draped);
+  if (!isDraped) {
+    const material = point?.material ?? billboard?.material ?? text?.material;
+    overlayScene(material, scenes).add(obj);
+  }
+
+  meshes.set(id, obj);
+
+  if (isDraped && tileHandle) {
+    // Insert the bakeable draped mesh into the per-tile cache now (it is fully built at
+    // this point). Readiness/ancestor-fallback is decided entirely on the Rust side from
+    // the ECS lifecycle, so no `scene_ready` is reported. Insert even when invisible —
+    // the offscreen bake skips invisible meshes.
+    const layerIndex = layerHandler?.getLayerIndex(featureLayerId);
+    // Timing: the layer may have been removed before this event; skip the insert then (the
+    // mesh object still exists, it just won't be baked for this layer).
+    if (layerIndex != null) {
+      texturizedSceneByTileCoordinates.add(
+        tileHandle,
+        featureLayerId,
+        obj as Mesh,
+        layerIndex,
+      );
+    }
+    obj.addEventListener("removedFromWorld", () => {
+      texturizedSceneByTileCoordinates.removeMesh(
+        tileHandle,
+        featureLayerId,
+        obj as Mesh,
+      );
+    });
+    obj.addEventListener("needsUpdate", () => {
+      texturizedSceneByTileCoordinates.markDirty(tileHandle, featureLayerId);
+    });
+  }
+
+  if (obj instanceof PolygonMesh && polygon && polygon.outline_geometry) {
+    const outline = await renderPolygonOutline(ctx, polygon);
+    outline.renderOrder = FEATURE_RENDER_ORDER;
+    scenes.mrt.add(outline);
+
+    obj.outline = outline;
+
+    obj.addEventListener("removedFromWorld", () => {
+      obj.outline?.clear();
+      obj.outline?.removeFromParent();
+    });
+  }
+
+  handleFeatureCreatedEventByLayerId(
+    featureHandler,
+    obj,
+    viewEvents,
+    layersManager,
+    featureLayerId,
+    ev.bits,
+  );
+  if (obj.visible) {
+    handleFeatureUpdatedEventByLayerId(
+      viewEvents,
+      layersManager,
+      featureLayerId,
+      ev.bits,
+      updatedAt,
+    );
+  }
+}
+
+export async function processRenderableFeatureChanged(
+  ctx: EventContext,
+  ev: RenderableFeatureChangedEvent,
+) {
+  const {
+    scenes,
+    meshes,
+    texturizedSceneByTileCoordinates,
+    viewEvents,
+    layersManager,
+    updatedAt,
+  } = ctx;
+  const id = generate_id_from_entity(ev);
+  const obj = meshes.get(id);
+  if (!obj) return;
+
+  const layerId = ev.layer_id;
+
+  const overscaledTileHandle = ev.overscaled_tile_handle;
+  const tileHandle = overscaledTileHandle?.handle;
+
+  const { point, billboard, text, polyline, polygon, model } = ev.feature;
+
+  const active =
+    (point ?? billboard ?? text ?? polyline ?? polygon ?? model)?.active ??
+    true;
+
+  // Capture visibility before material updates to detect changes
+  const prevVisible = obj.visible;
+
+  if (obj instanceof InstancedSpriteMesh && point) {
+    processPointChanged(obj, point, active);
+  }
+  if (obj instanceof InstancedSpriteMesh && billboard) {
+    await processBillboardChanged(obj, billboard, active);
+  }
+
+  if (obj instanceof BatchedSdfTextMesh && text) {
+    await processTextChanged(obj, text, active);
+  }
+
+  // `depthTest` may have flipped at runtime, changing which scene a sprite or
+  // text feature belongs to (transparent for always-on-top overlays, MRT
+  // otherwise). Re-route based on the incoming material; Three's `add()`
+  // reparents safely, and the guard keeps draped/model/polygon/polyline
+  // features untouched.
+  if (obj instanceof InstancedSpriteMesh || obj instanceof BatchedSdfTextMesh) {
+    const material = point?.material ?? billboard?.material ?? text?.material;
+    const target = overlayScene(material, scenes);
+    if (obj.parent !== target) {
+      target.add(obj);
+      ctx.renderFlag.forceUpdate = true;
+    }
+  }
+  if (obj instanceof ModelMesh && model) {
+    processModelChanged(obj, model, active);
+  }
+  if (obj instanceof PolylineMesh && polyline) {
+    processPolylineChanged(obj, polyline, active);
+  }
+  if (obj instanceof PolygonMesh && polygon) {
+    processPolygonChanged(obj, polygon, active, tileHandle);
+
+    if (obj.outline) {
+      processPolygonOutlineChanged(obj.outline, polygon, active);
+    }
+  }
+
+  // A draped feature's material/visibility changed: bump the layer scene's revision so the
+  // consuming TileMesh re-bakes (invisible meshes stay in the scene and are skipped at bake).
+  // Cache membership is owned by CREATE / `removedFromWorld`; a runtime `clampToGround` flip
+  // is not handled here (rare — the flag is set once at mesh init).
+  if (
+    ((obj instanceof PolygonMesh && obj.clampToGround) ||
+      (obj instanceof PolylineMesh && obj.draped)) &&
+    tileHandle
+  ) {
+    texturizedSceneByTileCoordinates.markDirty(tileHandle, layerId);
+  }
+
+  // Emit visibility changed event if visibility actually changed after material updates
+  if (prevVisible !== obj.visible) {
+    handleFeatureVisibilityChangedEventByLayerId(
+      layersManager,
+      layerId,
+      ev.bits,
+      obj.visible,
+    );
+  }
+
+  // Point, billboard and text should be handled by their mesh.
+  const transform = (polyline ?? polygon ?? model)?.transform;
+
+  // This should be handled after the asynchronous process to avoid a conflict.
+  if (transform) {
+    setTransform(obj, transform);
+  }
+
+  obj.updateMatrix();
+
+  if (obj.visible) {
+    handleFeatureUpdatedEventByLayerId(
+      viewEvents,
+      layersManager,
+      layerId,
+      ev.bits,
+      updatedAt,
+    );
+  }
+}