@navaramap/three 0.0.0

package/src/event/HillshadeContext.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import { HillshadeContext } from "./HillshadeContext";
+import type { HillshadeConfig } from "./HillshadeContext";
+
+describe("HillshadeContext", () => {
+  let context: HillshadeContext;
+  const mockConfig: HillshadeConfig = {
+    rgbScaler: [1, 1, 1],
+    boundary: 0,
+    minOffset: 0,
+    maxOffset: 0,
+    epsilon: 1.0,
+    offset: 0,
+  };
+
+  beforeEach(() => {
+    context = new HillshadeContext();
+  });
+
+  describe("pendingEdges management", () => {
+    it("allows multiple edges for same entity", () => {
+      const entityId = "tile_1";
+      const edge0 = new Uint8Array([1, 2, 3, 4]);
+      const edge1 = new Uint8Array([5, 6, 7, 8]);
+
+      const pending = new Map<number, Uint8Array>();
+      pending.set(0, edge0);
+      pending.set(1, edge1);
+      context.pendingEdges.set(entityId, pending);
+
+      const stored = context.pendingEdges.get(entityId);
+      expect(stored).toBeDefined();
+      expect(stored?.size).toBe(2);
+      expect(stored?.get(0)).toBe(edge0);
+      expect(stored?.get(1)).toBe(edge1);
+    });
+
+    it("overwrites pending edge for same direction", () => {
+      const entityId = "tile_1";
+      const oldEdge = new Uint8Array([1, 2, 3, 4]);
+      const newEdge = new Uint8Array([5, 6, 7, 8]);
+
+      const pending = new Map<number, Uint8Array>();
+      pending.set(0, oldEdge);
+      context.pendingEdges.set(entityId, pending);
+
+      // Overwrite with new edge
+      pending.set(0, newEdge);
+
+      const stored = context.pendingEdges.get(entityId);
+      expect(stored).toBeDefined();
+      expect(stored?.get(0)).toBe(newEdge);
+      expect(stored?.get(0)).not.toBe(oldEdge);
+    });
+  });
+
+  describe("tempDemTextures lifecycle", () => {
+    it("stores and retrieves temp DEM entry", () => {
+      const entityId = "tile_1";
+      const originalHandle = 42;
+
+      context.storeTempDem(entityId, originalHandle, 6, 1.0, mockConfig);
+
+      const entry = context.getTempDem(entityId);
+      expect(entry).toBeDefined();
+      expect(entry?.originalHandle).toBe(originalHandle);
+      expect(entry?.paddedSize).toBe(6);
+      expect(entry?.metersPerTexel).toBe(1.0);
+      expect(entry?.receivedEdges.size).toBe(0);
+    });
+
+    it("initializes with empty receivedEdges set and receivedEdgeData map", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      const entry = context.getTempDem(entityId);
+      expect(entry).toBeDefined();
+      expect(entry?.receivedEdges).toBeInstanceOf(Set);
+      expect(entry?.receivedEdges.size).toBe(0);
+      expect(entry?.receivedEdgeData).toBeInstanceOf(Map);
+      expect(entry?.receivedEdgeData.size).toBe(0);
+    });
+
+    it("stores edge data via storeEdgeData", () => {
+      const entityId = "tile_1";
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      const edgeBytes = new Uint8Array([1, 2, 3, 4]);
+      context.storeEdgeData(entityId, 0, edgeBytes);
+
+      const entry = context.getTempDem(entityId);
+      expect(entry?.receivedEdgeData.get(0)).toBe(edgeBytes);
+    });
+
+    it("tracks edge reception", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      expect(context.markEdgeReceived(entityId, 0)).toBe(false); // 1/4
+      expect(context.markEdgeReceived(entityId, 1)).toBe(false); // 2/4
+      expect(context.markEdgeReceived(entityId, 2)).toBe(false); // 3/4
+      expect(context.markEdgeReceived(entityId, 3)).toBe(true); // 4/4 - all received
+
+      const entry = context.getTempDem(entityId);
+      expect(entry).toBeDefined();
+      expect(entry?.receivedEdges.size).toBe(4);
+    });
+
+    it("handles duplicate edge reception", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      expect(context.markEdgeReceived(entityId, 0)).toBe(false);
+      expect(context.markEdgeReceived(entityId, 0)).toBe(false); // Duplicate
+      expect(context.markEdgeReceived(entityId, 0)).toBe(false); // Duplicate
+
+      const entry = context.getTempDem(entityId);
+      expect(entry).toBeDefined();
+      expect(entry?.receivedEdges.size).toBe(1); // Still only 1 edge
+    });
+
+    it("clears temp DEM entry", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+      expect(context.getTempDem(entityId)).toBeDefined();
+
+      context.clearTempDem(entityId);
+
+      expect(context.getTempDem(entityId)).toBeUndefined();
+    });
+
+    it("replaces existing temp DEM when storing new one", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 10, 6, 1.0, mockConfig);
+      context.markEdgeReceived(entityId, 0);
+
+      // Store new DEM (replaces old one)
+      context.storeTempDem(entityId, 20, 6, 2.0, mockConfig);
+
+      const entry = context.getTempDem(entityId);
+      expect(entry).toBeDefined();
+      expect(entry?.originalHandle).toBe(20);
+      expect(entry?.metersPerTexel).toBe(2.0);
+      expect(entry?.receivedEdges.size).toBe(0); // Reset
+    });
+  });
+
+  describe("edge-driven lifecycle integration", () => {
+    it("scenario: all edges arrive before texture creation", () => {
+      const entityId = "tile_1";
+
+      const pending = new Map<number, Uint8Array>();
+      pending.set(0, new Uint8Array([1, 2, 3, 4]));
+      pending.set(1, new Uint8Array([5, 6, 7, 8]));
+      pending.set(2, new Uint8Array([9, 10, 11, 12]));
+      pending.set(3, new Uint8Array([13, 14, 15, 16]));
+      context.pendingEdges.set(entityId, pending);
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      context.markEdgeReceived(entityId, 0);
+      context.markEdgeReceived(entityId, 1);
+      context.markEdgeReceived(entityId, 2);
+      const allReceived = context.markEdgeReceived(entityId, 3);
+
+      expect(allReceived).toBe(true);
+      const finalEntry = context.getTempDem(entityId);
+      expect(finalEntry).toBeDefined();
+      expect(finalEntry?.receivedEdges.size).toBe(4);
+
+      context.clearTempDem(entityId);
+      expect(context.getTempDem(entityId)).toBeUndefined();
+    });
+
+    it("scenario: edges arrive after texture, then all cleared", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      expect(context.markEdgeReceived(entityId, 0)).toBe(false);
+      expect(context.markEdgeReceived(entityId, 1)).toBe(false);
+      expect(context.markEdgeReceived(entityId, 2)).toBe(false);
+      expect(context.markEdgeReceived(entityId, 3)).toBe(true);
+
+      context.clearTempDem(entityId);
+      expect(context.getTempDem(entityId)).toBeUndefined();
+    });
+
+    it("scenario: late edge arrives after temp DEM cleared", () => {
+      const entityId = "tile_1";
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      context.markEdgeReceived(entityId, 0);
+      context.markEdgeReceived(entityId, 1);
+      context.markEdgeReceived(entityId, 2);
+      context.markEdgeReceived(entityId, 3);
+
+      context.clearTempDem(entityId);
+
+      const result = context.markEdgeReceived(entityId, 0);
+      expect(result).toBe(false); // No temp DEM exists
+    });
+
+    it("scenario: mixed order (some pending, some after)", () => {
+      const entityId = "tile_1";
+
+      const pending = new Map<number, Uint8Array>();
+      pending.set(0, new Uint8Array([1, 2, 3, 4]));
+      pending.set(2, new Uint8Array([9, 10, 11, 12]));
+      context.pendingEdges.set(entityId, pending);
+
+      context.storeTempDem(entityId, 1, 6, 1.0, mockConfig);
+
+      context.markEdgeReceived(entityId, 0);
+      context.markEdgeReceived(entityId, 2);
+
+      expect(context.markEdgeReceived(entityId, 1)).toBe(false);
+      expect(context.markEdgeReceived(entityId, 3)).toBe(true);
+
+      const mixedEntry = context.getTempDem(entityId);
+      expect(mixedEntry).toBeDefined();
+      expect(mixedEntry?.receivedEdges.size).toBe(4);
+    });
+  });
+});

package/src/event/HillshadeContext.ts

@@ -0,0 +1,299 @@
+import type { Texture } from "three";
+import {
+  ClampToEdgeWrapping,
+  DataTexture,
+  LinearFilter,
+  NearestFilter,
+  NoColorSpace,
+  RGBAFormat,
+  RGBFormat,
+  UnsignedByteType,
+  WebGLRenderTarget,
+} from "three";
+
+import type { ViewContext } from "../core";
+import { HillshadeNormalMapGenerator } from "../utils/hillshadeNormalMapGenerator";
+
+import type { TileHandler } from "./context";
+
+/**
+ * Hillshade decoder configuration from Rust
+ */
+export type HillshadeConfig = {
+  rgbScaler: [number, number, number]; // vec3: [R, G, B] scalers
+  boundary: number;
+  minOffset: number;
+  maxOffset: number;
+  epsilon: number;
+  offset: number;
+};
+
+/**
+ * Temporary DEM state while waiting for edge updates.
+ * Stores only the WASM buffer handle and received edge strips — NOT the full padded DEM.
+ * The padded DEM is reconstructed transiently on each edge arrival, then discarded.
+ */
+type TempDemEntry = {
+  originalHandle: number;
+  paddedSize: number;
+  receivedEdges: Set<number>;
+  receivedEdgeData: Map<number, Uint8Array>;
+  metersPerTexel: number;
+  hillshadeConfig: HillshadeConfig;
+};
+
+/**
+ * Context for managing hillshade-related state and resources
+ * Centralizes all hillshade processing state to avoid scattered global variables
+ */
+export class HillshadeContext {
+  /** Shared normal map generator for offline rendering */
+  private normalMapGenerator: HillshadeNormalMapGenerator | null = null;
+
+  /** Scale factor for normal map RenderTarget dimensions (1.0 = full res, 0.5 = half res for mobile) */
+  normalMapScale = 1.0;
+
+  /** Pending edge updates that arrived before the main texture was created */
+  readonly pendingEdges = new Map<string, Map<number, Uint8Array>>();
+
+  /**
+   * Temporary storage for DEM reconstruction state while waiting for edge updates.
+   * entityId → { originalHandle, paddedSize, receivedEdges, receivedEdgeData, ... }
+   */
+  readonly tempDemTextures = new Map<string, TempDemEntry>();
+
+  /**
+   * RenderTarget pool for normal map generation
+   * One RenderTarget per entity to avoid GPU→CPU→GPU round-trip
+   * Similar to texturizedSceneRenderTargets in tile.ts
+   */
+  private renderTargets = new Map<string, WebGLRenderTarget>();
+
+  /**
+   * Get or create the normal map generator
+   * @param viewContext - ViewContext to get the renderer from
+   */
+  getOrCreateGenerator(viewContext: ViewContext): HillshadeNormalMapGenerator {
+    if (!this.normalMapGenerator) {
+      const renderer = viewContext.getRenderer();
+      this.normalMapGenerator = new HillshadeNormalMapGenerator(renderer);
+    }
+    return this.normalMapGenerator;
+  }
+
+  /**
+   * Get hillshade decoder config from tile
+   * @param tileHandler - TileHandler to query WASM
+   * @param tileHandle - Tile handle to get elevation decoder from
+   */
+  getHillshadeConfig(
+    tileHandler: TileHandler,
+    tileHandle: bigint,
+  ): HillshadeConfig {
+    const decoder = tileHandler.getTileElevationDecoder(tileHandle);
+
+    if (decoder) {
+      return {
+        rgbScaler: [decoder.r_scaler, decoder.g_scaler, decoder.b_scaler],
+        boundary: decoder.boundary,
+        minOffset: decoder.min_offset,
+        maxOffset: decoder.max_offset,
+        epsilon: decoder.epsilon,
+        offset: decoder.offset,
+      };
+    } else {
+      // Fallback to Terrarium defaults if no decoder found
+      return {
+        rgbScaler: [256, 1, 1 / 256],
+        boundary: 0,
+        minOffset: 0,
+        maxOffset: 0,
+        epsilon: 1.0,
+        offset: -32768,
+      };
+    }
+  }
+
+  /**
+   * Get or create a RenderTarget for the given entity
+   * Reuses existing RenderTarget if size matches, creates new one otherwise
+   * @private
+   */
+  private getOrCreateRenderTarget(
+    entityId: string,
+    width: number,
+    height: number,
+  ): WebGLRenderTarget {
+    let rt = this.renderTargets.get(entityId);
+
+    // Check if size matches (different zoom levels may have different sizes)
+    if (rt && (rt.width !== width || rt.height !== height)) {
+      rt.dispose();
+      rt = undefined;
+    }
+
+    if (!rt) {
+      rt = new WebGLRenderTarget(width, height, {
+        format: RGBFormat,
+        type: UnsignedByteType,
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        wrapS: ClampToEdgeWrapping,
+        wrapT: ClampToEdgeWrapping,
+        colorSpace: NoColorSpace,
+        generateMipmaps: false,
+      });
+      this.renderTargets.set(entityId, rt);
+    }
+
+    return rt;
+  }
+
+  /**
+   * Generate normal map texture from DEM data
+   * Creates a transient DataTexture for GPU upload, renders to RenderTarget, then frees the DEM texture.
+   * @param entityId - Entity ID for RenderTarget lookup/creation
+   * @param viewContext - ViewContext to get the renderer from
+   * @param demData - Padded DEM pixel data (CPU only, not GPU-resident)
+   * @param paddedSize - Width/height of the padded DEM (square)
+   * @param metersPerTexel - Meters per texel for normal calculation
+   * @param hillshadeConfig - Hillshade decoder configuration
+   * @param contentWidth - Content width (without padding)
+   * @param contentHeight - Content height (without padding)
+   * @returns Normal map texture (references RenderTarget.texture directly)
+   */
+  generateNormalMap(
+    entityId: string,
+    viewContext: ViewContext,
+    demData: Uint8Array,
+    paddedSize: number,
+    metersPerTexel: number,
+    hillshadeConfig: HillshadeConfig,
+    contentWidth: number,
+    contentHeight: number,
+  ): Texture {
+    const renderTarget = this.getOrCreateRenderTarget(
+      entityId,
+      Math.max(1, Math.round(contentWidth * this.normalMapScale)),
+      Math.max(1, Math.round(contentHeight * this.normalMapScale)),
+    );
+
+    // Create a transient DataTexture for GPU upload, render, then dispose immediately
+    const demTexture = new DataTexture(
+      demData,
+      paddedSize,
+      paddedSize,
+      RGBAFormat,
+      UnsignedByteType,
+    );
+    demTexture.colorSpace = NoColorSpace;
+    demTexture.minFilter = NearestFilter;
+    demTexture.magFilter = NearestFilter;
+    demTexture.needsUpdate = true;
+
+    const generator = this.getOrCreateGenerator(viewContext);
+    generator.renderToTarget(
+      renderTarget,
+      demTexture,
+      metersPerTexel,
+      hillshadeConfig,
+    );
+
+    demTexture.dispose();
+
+    return renderTarget.texture;
+  }
+
+  /**
+   * Clear RenderTarget for the given entity
+   */
+  clearRenderTarget(entityId: string): void {
+    const rt = this.renderTargets.get(entityId);
+    if (rt) {
+      rt.dispose();
+      this.renderTargets.delete(entityId);
+    }
+  }
+
+  /**
+   * Store temporary DEM entry (WASM handle + metadata) for edge updates.
+   * Does NOT store the full padded DEM — only the handle needed to re-read on demand.
+   */
+  storeTempDem(
+    entityId: string,
+    originalHandle: number,
+    paddedSize: number,
+    metersPerTexel: number,
+    hillshadeConfig: HillshadeConfig,
+  ): void {
+    this.tempDemTextures.set(entityId, {
+      originalHandle,
+      paddedSize,
+      receivedEdges: new Set(),
+      receivedEdgeData: new Map(),
+      metersPerTexel,
+      hillshadeConfig,
+    });
+  }
+
+  /**
+   * Store an edge pixel strip for later padded DEM reconstruction.
+   */
+  storeEdgeData(
+    entityId: string,
+    edgeDirection: number,
+    edgeBytes: Uint8Array,
+  ): void {
+    const entry = this.tempDemTextures.get(entityId);
+    if (entry) {
+      entry.receivedEdgeData.set(edgeDirection, edgeBytes);
+    }
+  }
+
+  /**
+   * Get temporary DEM texture entry
+   */
+  getTempDem(entityId: string): TempDemEntry | undefined {
+    return this.tempDemTextures.get(entityId);
+  }
+
+  /**
+   * Mark an edge as received for a temporary DEM
+   * @returns true if all 4 edges have been received
+   */
+  markEdgeReceived(entityId: string, edgeDirection: number): boolean {
+    const entry = this.tempDemTextures.get(entityId);
+    if (!entry) return false;
+
+    entry.receivedEdges.add(edgeDirection);
+    return entry.receivedEdges.size >= 4; // All 4 edges received
+  }
+
+  /**
+   * Clear temporary DEM data
+   */
+  clearTempDem(entityId: string): void {
+    this.tempDemTextures.delete(entityId);
+  }
+
+  /**
+   * Cleanup all resources
+   * Should be called on view disposal
+   */
+  dispose(): void {
+    this.tempDemTextures.clear();
+    this.pendingEdges.clear();
+
+    // Dispose all RenderTargets
+    for (const rt of this.renderTargets.values()) {
+      rt.dispose();
+    }
+    this.renderTargets.clear();
+
+    // Dispose generator
+    if (this.normalMapGenerator) {
+      this.normalMapGenerator.dispose();
+      this.normalMapGenerator = null;
+    }
+  }
+}