@navaramap/three 0.0.0

package/src/mesh/polyline.ts

@@ -0,0 +1,523 @@
+import {
+  PolylineMesh as NavaraPolylineMesh,
+  PolylineMaterial,
+} from "@navaramap/engine";
+import {
+  BufferAttribute,
+  BufferGeometry,
+  Color,
+  Matrix4,
+  ShaderMaterial,
+  Vector2,
+} from "three";
+
+import type { EventContext } from "../event/context";
+import { createPolylineMaterialEnhancer } from "../material/enhancer";
+
+import {
+  BatchedFeatureMesh,
+  POLYLINE_BATCH_TEXTURE_ROWS,
+  type BatchedFeatureAttributes,
+} from "./batchedFeature";
+import type {
+  BatchedAttributeName,
+  BatchTextureRowKey,
+  DefaultBatchAttributeValues,
+} from "./batchTexture";
+import { releaseGeometryArraysAfterUpload } from "./releaseGeometryArrays";
+import { setupRTECallback } from "./rtcRteHelper";
+
+// Sentinel value for picking coordinate when not picking (reused to avoid allocations)
+const PICKING_COORD_SENTINEL = new Vector2(-1, -1);
+
+type Attributes = BatchedFeatureAttributes<{
+  position: BufferAttribute;
+  // RTE mode attributes (only present when useRTE=true)
+  position_3d_high?: BufferAttribute;
+  position_3d_low?: BufferAttribute;
+  start_3d_high?: BufferAttribute;
+  start_3d_low?: BufferAttribute;
+  end_3d_high?: BufferAttribute;
+  end_3d_low?: BufferAttribute;
+  // Non-RTE mode attributes (only present when useRTE=false)
+  start?: BufferAttribute;
+  forward_offset?: BufferAttribute;
+  // Common attributes (present for non-flat polylines)
+  start_normal?: BufferAttribute;
+  end_normal_and_texture_coordinate_normalization_x?: BufferAttribute;
+  // Always present
+  right_normal_and_texture_coordinate_normalization_y: BufferAttribute;
+  attrBatchId: BufferAttribute;
+}>;
+
+export class PolylineMesh extends BatchedFeatureMesh<
+  BufferGeometry<Attributes>,
+  ShaderMaterial
+> {
+  readonly ctx: EventContext;
+  /** Material enhancer for managing shader state */
+  private _enhancedMaterial?: ReturnType<typeof createPolylineMaterialEnhancer>;
+  /** Flag indicating geometry initialization failed - mesh should never be visible */
+  private _geometryInitFailed = false;
+
+  constructor(ctx: EventContext) {
+    super(new BufferGeometry<Attributes>(), new ShaderMaterial());
+    this.ctx = ctx;
+  }
+
+  init(mesh: NavaraPolylineMesh) {
+    this.batchLength = mesh.batch_length;
+    const geometryResult = this.initGeometry(mesh);
+
+    // If geometry init failed (missing required buffers), mark as permanently invisible
+    if (!geometryResult.success) {
+      console.warn(
+        "PolylineMesh: Failed to initialize geometry due to missing required buffers. Mesh will be permanently invisible.",
+      );
+      this._geometryInitFailed = true;
+      this.visible = false;
+    }
+
+    this.initMaterial(mesh, geometryResult.useRTE);
+
+    this.addEventListener("removedFromWorld", () => {
+      this.dispose();
+    });
+
+    return this;
+  }
+
+  private initGeometry(
+    mesh: NavaraPolylineMesh,
+  ): { success: true; useRTE: boolean } | { success: false; useRTE: false } {
+    const { buf } = this.ctx;
+    const g = mesh.geometry;
+    const position = buf.removeF32(g.position.data);
+    const position_high = g.position_high
+      ? buf.removeF32(g.position_high.data)
+      : null;
+    const position_low = g.position_low
+      ? buf.removeF32(g.position_low.data)
+      : null;
+    const start_high = g.start_high ? buf.removeF32(g.start_high.data) : null;
+    const start_low = g.start_low ? buf.removeF32(g.start_low.data) : null;
+    const end_high = g.end_high ? buf.removeF32(g.end_high.data) : null;
+    const end_low = g.end_low ? buf.removeF32(g.end_low.data) : null;
+    const start_normals = g.start_normals
+      ? buf.removeF32(g.start_normals.data)
+      : null;
+    const end_normal_and_texture_coordinate_normalization_x =
+      g.end_normal_and_texture_coordinate_normalization_x
+        ? buf.removeF32(
+            g.end_normal_and_texture_coordinate_normalization_x.data,
+          )
+        : null;
+    const right_normal_and_texture_coordinate_normalization_y = buf.removeF32(
+      g.right_normal_and_texture_coordinate_normalization_y.data,
+    );
+    const indices = buf.removeU32(g.indices);
+    const batchIds = g.batch_ids ? buf.removeF32(g.batch_ids.data) : undefined;
+    const batchIdSize = g.batch_ids ? g.batch_ids.size : 0;
+    const batchIndex = g.batch_index
+      ? buf.removeU32(g.batch_index.data)
+      : undefined;
+    const batchIndexSize = g.batch_index ? g.batch_index.size : 0;
+
+    if (
+      !position ||
+      !right_normal_and_texture_coordinate_normalization_y ||
+      !indices
+    ) {
+      return { success: false, useRTE: false };
+    }
+
+    const geometry = this.geometry;
+    const useRTE = !!(
+      position_high &&
+      position_low &&
+      start_high &&
+      start_low &&
+      end_high &&
+      end_low
+    );
+
+    geometry.setAttribute(
+      "position",
+      new BufferAttribute(position, g.position.size),
+    );
+
+    if (useRTE) {
+      // RTE attributes
+      if (position_high && position_low) {
+        geometry.setAttribute(
+          "position_3d_high",
+          new BufferAttribute(position_high, 3),
+        );
+        geometry.setAttribute(
+          "position_3d_low",
+          new BufferAttribute(position_low, 3),
+        );
+      }
+      if (start_high && start_low) {
+        geometry.setAttribute(
+          "start_3d_high",
+          new BufferAttribute(start_high, 3),
+        );
+        geometry.setAttribute(
+          "start_3d_low",
+          new BufferAttribute(start_low, 3),
+        );
+      }
+      if (end_high && end_low) {
+        geometry.setAttribute("end_3d_high", new BufferAttribute(end_high, 3));
+        geometry.setAttribute("end_3d_low", new BufferAttribute(end_low, 3));
+      }
+    } else if (g.start && g.forward_offset) {
+      const start = buf.removeF32(g.start.data);
+      const forward_offset = buf.removeF32(g.forward_offset.data);
+
+      if (!start || !forward_offset) {
+        return { success: false, useRTE: false };
+      }
+
+      // Non-RTE mode: use regular start attribute
+      geometry.setAttribute("start", new BufferAttribute(start, g.start.size));
+
+      geometry.setAttribute(
+        "forward_offset",
+        new BufferAttribute(forward_offset, g.forward_offset.size),
+      );
+    }
+
+    if (start_normals && g.start_normals) {
+      geometry.setAttribute(
+        "start_normal",
+        new BufferAttribute(start_normals, g.start_normals.size),
+      );
+    }
+    if (
+      end_normal_and_texture_coordinate_normalization_x &&
+      g.end_normal_and_texture_coordinate_normalization_x
+    ) {
+      geometry.setAttribute(
+        "end_normal_and_texture_coordinate_normalization_x",
+        new BufferAttribute(
+          end_normal_and_texture_coordinate_normalization_x,
+          g.end_normal_and_texture_coordinate_normalization_x.size,
+        ),
+      );
+    }
+    geometry.setAttribute(
+      "right_normal_and_texture_coordinate_normalization_y",
+      new BufferAttribute(
+        right_normal_and_texture_coordinate_normalization_y,
+        g.right_normal_and_texture_coordinate_normalization_y.size,
+      ),
+    );
+
+    if (batchIds) {
+      geometry.setAttribute(
+        "attrBatchId",
+        new BufferAttribute(batchIds, batchIdSize),
+      );
+    }
+
+    if (batchIndex) {
+      this._setBatchIndex(Float32Array.from(batchIndex), batchIndexSize);
+    }
+
+    geometry.setIndex(new BufferAttribute(indices, 1));
+    // geometry.computeVertexNormals();
+
+    // The renderer lazily calls computeBoundingSphere(), which reads
+    // position.array, for every polyline: non-RTE ones through frustum culling
+    // (RTE disables it below), and ALL of them through depth sorting —
+    // renderer.sortObjects reads geometry.boundingSphere even when
+    // frustumCulled is false. Compute it eagerly so that read happens before
+    // we drop the CPU arrays. In RTE mode `position` still holds the f32
+    // world-space coordinates, so the resulting sphere is valid.
+    geometry.computeBoundingSphere();
+
+    // With the bounding sphere resolved and batch-id data consumed on the GPU,
+    // no CPU read survives the first upload. Drop the JS-heap copies to keep a
+    // single resident (GPU) copy — see releaseGeometryArraysAfterUpload for the
+    // context-loss trade-off.
+    releaseGeometryArraysAfterUpload(geometry);
+
+    return { success: true, useRTE };
+  }
+
+  private initMaterial(mesh: NavaraPolylineMesh, useRTE: boolean) {
+    const { uniforms } = this.ctx;
+    const meshMaterial = mesh.material;
+
+    const [minHeight, maxHeight] = meshMaterial.__internal__?.minMaxHeights ?? [
+      0, 0,
+    ];
+
+    this.castShadow = !!meshMaterial.castShadow;
+    this.receiveShadow = !!meshMaterial.receiveShadow;
+
+    const isTexturized = mesh.should_be_texturized;
+
+    // Shader selection is handled by enhancer's transformShader
+    this.material.depthTest = false;
+
+    // Disable lighting for texturized rendering - the texture will be applied to the lit tile
+    this.material.lights = !isTexturized;
+    this.material.vertexColors = false;
+
+    // Ignored if it is cloned.
+    if (!this._enhancedMaterial) {
+      // Create enhanced material with encapsulated state
+      const enhancer = createPolylineMaterialEnhancer(this.material);
+      this._enhancedMaterial = enhancer;
+    }
+    const enhancer = this._enhancedMaterial;
+
+    enhancer.mount({
+      base: {
+        color: meshMaterial.color,
+        minMaxHeight: [minHeight, maxHeight],
+        addHeight: meshMaterial.height ?? 0,
+        width: meshMaterial.width,
+        maxWidth: meshMaterial.maxWidth,
+        isTexturized,
+        pickable: false,
+        useRTE,
+        transparent: meshMaterial.transparent,
+        opacity: meshMaterial.opacity,
+        depthWrite: meshMaterial.depthWrite,
+        // External shared uniforms from CommonUniforms
+        viewportAndPixelRatio: uniforms.viewportAndPixelRatio,
+        frustumNearFar: uniforms.frustumNearFar,
+        frustumRatio: uniforms.frustumRatio,
+      },
+    });
+
+    // Initialize enhancer uniforms early so they're available before onBeforeCompile
+    const mutates = enhancer.mutates();
+    mutates.updateUniforms(this.material.uniforms, enhancer.states());
+
+    // Set up RTE callback if needed
+    const state = enhancer.states();
+    if (state.useRTE) {
+      const mutates = enhancer.mutates();
+      const callback = setupRTECallback(
+        this,
+        (modelViewMatrixRTE, cameraPositionHigh, cameraPositionLow) =>
+          mutates.updateRteUniforms(
+            modelViewMatrixRTE,
+            cameraPositionHigh,
+            cameraPositionLow,
+            state,
+          ),
+        new Matrix4(),
+        new Matrix4(),
+      );
+      this.onBeforeRender = callback;
+      this.onBeforeShadow = callback;
+
+      // Disable frustum culling for RTE mode
+      this.frustumCulled = false;
+    }
+
+    // Set up custom program cache key based on config flags that affect shader defines
+    this.material.customProgramCacheKey = enhancer.programCacheKey;
+
+    // Set onBeforeCompile to use enhancer
+    this.material.onBeforeCompile = enhancer.transformShader;
+
+    this.ctx.viewContext.applyShadowMaterial(this.material);
+
+    this._initBatchedMaterial();
+
+    this._update(meshMaterial, mesh.active);
+  }
+
+  _getBatchTextureRows(): BatchTextureRowKey[] {
+    // No EXTRUDED_HEIGHT: the polyline shaders declare no receiver for it,
+    // so accepting the attribute would break shader compilation.
+    return POLYLINE_BATCH_TEXTURE_ROWS;
+  }
+
+  _initBatchDataTexture(): void {
+    // Call parent to create the texture
+    super._initBatchDataTexture();
+
+    // Update the enhancer with the new batchDataTexture
+    const texture = this._getBatchDataTexture();
+    if (texture) {
+      this.getEnhancer().update({
+        base: { useBatchTexture: true, batchDataTexture: { value: texture } },
+      });
+    }
+  }
+
+  /**
+   * Keep enhancer state in sync with batch-attribute usage so that
+   * customProgramCacheKey reflects the correct shader configuration.
+   *
+   * This mirrors PolygonMesh._updateBatchAttribute: when batch color
+   * is first enabled, also enable batchColorEnabled and set color to white.
+   */
+  _updateBatchAttribute(
+    batchId: number,
+    attribute: BatchedAttributeName,
+    value: number | number[] | boolean,
+  ): void {
+    switch (attribute) {
+      case "color": {
+        // When batch color is first used, enable batchColorEnabled and set material.color to white
+        if (!this.getEnhancer().states().batchColorEnabled) {
+          // Set material.color to white (multiplier identity) and enable batch color mode
+          this.getEnhancer().update({
+            base: { batchColorEnabled: true, color: 0xffffff },
+          });
+        }
+        this.getEnhancer().update({ base: { useBatchColorShow: true } });
+        break;
+      }
+      case "show": {
+        this.getEnhancer().update({ base: { useBatchColorShow: true } });
+        break;
+      }
+      case "height":
+        this.getEnhancer().update({ base: { useBatchHeight: true } });
+        break;
+      case "lineWidth":
+        this.getEnhancer().update({ base: { useBatchLineWidth: true } });
+        break;
+    }
+
+    // Call parent to update the batch texture
+    super._updateBatchAttribute(batchId, attribute, value);
+  }
+
+  _update(material: PolylineMaterial, active: boolean) {
+    // If geometry initialization failed, keep mesh permanently invisible
+    // to prevent WebGL errors from missing attributes/buffers
+    if (this._geometryInitFailed) {
+      this.visible = false;
+      return;
+    }
+
+    const enhancer = this.getEnhancer();
+
+    // Update mesh properties (not handled by enhancer)
+    this.visible = (material.show ?? true) && active;
+    this.castShadow = !!material.castShadow;
+    this.receiveShadow = !!material.receiveShadow;
+
+    const base = enhancer.states();
+
+    // Build update props from material
+    const minMaxHeights = material.__internal__?.minMaxHeights;
+    enhancer.update({
+      base: {
+        // `material.color` is used only when `batchColorEnabled` is `false`.
+        // Otherwise the color is updated via `_setFeatureColor` or the batch data texture.
+        color: base.batchColorEnabled ? undefined : material.color,
+        minMaxHeight:
+          minMaxHeights !== undefined
+            ? [minMaxHeights[0], minMaxHeights[1]]
+            : undefined,
+        addHeight: material.height,
+        width: material.width,
+        maxWidth: material.maxWidth,
+        transparent: material.transparent,
+        opacity: material.opacity,
+        depthWrite: material.depthWrite,
+        effectIdsMask:
+          this.ctx.viewContext.selectiveEffectRegistry?.computeMask(
+            material.effectIds ?? [],
+          ) ?? 0,
+        emissiveColor: material.emissiveColor ?? 0,
+        emissiveIntensity: material.emissiveIntensity ?? 0,
+      },
+    });
+
+    // Update material.lights flag based on isTexturized state
+    // (lighting should be disabled for texturized/draped polylines)
+    this.material.lights = !base.isTexturized;
+  }
+
+  /**
+   * Get the enhancer, throwing if not initialized.
+   * @throws Error if enhancer is not initialized
+   */
+  private getEnhancer(): NonNullable<typeof this._enhancedMaterial> {
+    if (!this._enhancedMaterial) {
+      throw new Error(
+        "PolylineMesh material enhancer is not initialized. This usually indicates a failure during construction or geometry/material setup.",
+      );
+    }
+    return this._enhancedMaterial;
+  }
+
+  get color() {
+    return this.material.uniforms.color.value;
+  }
+
+  get draped(): boolean {
+    return this.getEnhancer().states().isTexturized;
+  }
+
+  get emissiveColor(): number {
+    return this.getEnhancer().states().emissiveColor;
+  }
+  get emissiveIntensity(): number {
+    return this.getEnhancer().states().emissiveIntensity;
+  }
+  get effectIdsMask(): number {
+    return this.getEnhancer().states().effectIdsMask;
+  }
+
+  onBeforePicking(pickingCoord?: Vector2) {
+    this.getEnhancer().update({ base: { pickable: true } });
+    this.needsUpdate();
+
+    const mutates = this.getEnhancer().mutates();
+    if (pickingCoord) {
+      mutates.setPickingCoord(pickingCoord);
+    } else {
+      mutates.setPickingCoord(PICKING_COORD_SENTINEL);
+    }
+  }
+
+  onAfterPicking() {
+    this.getEnhancer().update({ base: { pickable: false } });
+    this.needsUpdate();
+    this.getEnhancer().mutates().setPickingCoord(PICKING_COORD_SENTINEL);
+  }
+
+  _getDefaultBatchAttributeValues(): DefaultBatchAttributeValues {
+    return {
+      color: this.color,
+    };
+  }
+
+  _setFeatureColor(color: Color): void {
+    // Called by evaluator to override feature color
+    // Set batchColorEnabled=true to prevent _update() from overwriting with material.color
+    this.getEnhancer().update({
+      base: { batchColorEnabled: true, color: color.getHex() },
+    });
+  }
+
+  _setFeatureShow(visible: boolean): void {
+    this.visible = visible;
+  }
+
+  clone() {
+    const cloned = new PolylineMesh(this.ctx) as this;
+    cloned.geometry = this.geometry;
+    cloned.material = this.material;
+    cloned._enhancedMaterial = this._enhancedMaterial;
+    return cloned;
+  }
+
+  dispose() {
+    this.ctx.viewContext.removeShadowMaterial(this.material);
+  }
+}

package/src/mesh/releaseGeometryArrays.ts

@@ -0,0 +1,57 @@
+import {
+  type BufferAttribute,
+  type BufferGeometry,
+  InterleavedBufferAttribute,
+} from "three";
+
+/**
+ * After the first GPU upload, drop the CPU-side typed array of a
+ * `BufferAttribute` so it is not kept resident on the JS heap alongside the GPU
+ * copy. This is the standard Three.js `onUpload` idiom (`this.array = null`).
+ *
+ * IMPORTANT: once released, the attribute can no longer be re-uploaded — a
+ * WebGL context loss will NOT be able to restore it. Our geometry is
+ * WASM-sourced and re-fetched on demand rather than re-uploaded, and the memory
+ * ledger (`GPU_GEOMETRY_RESIDENCY_FACTOR`) now assumes exactly one resident
+ * (GPU) copy, so this trade-off is intentional. Only apply it to attributes
+ * whose `.array` is not re-read on the CPU after upload (bounding volumes must
+ * already be computed/assigned; batch/feature-id arrays must be consumed at
+ * setup time, not lazily).
+ */
+function disposeArray(this: BufferAttribute) {
+  // Three.js types `array` as a readonly typed array; null is the documented
+  // sentinel that frees it after upload.
+  (this as unknown as { array: unknown }).array = null;
+}
+
+/**
+ * Attach {@link disposeArray} to a single attribute (idempotent).
+ *
+ * Interleaved attributes are skipped: an `InterleavedBufferAttribute` (produced
+ * by `GLTFLoader` for interleaved bufferViews) has no `onUpload` method — only
+ * its shared underlying `InterleavedBuffer` does — and multiple attributes
+ * share one buffer, so releasing through it is unsafe without per-buffer
+ * dedupe. Skipping them keeps interleaved glTF/3D Tiles models rendering
+ * correctly at the cost of the array-release optimization for those attributes.
+ */
+export function releaseAttributeAfterUpload(
+  attribute: BufferAttribute | InterleavedBufferAttribute | null | undefined,
+): void {
+  if (!attribute) return;
+  if (attribute instanceof InterleavedBufferAttribute) return;
+  attribute.onUpload(disposeArray);
+}
+
+/**
+ * Attach the post-upload CPU-array release to every attribute and the index of
+ * a geometry. Safe to call once per geometry after all CPU-side reads
+ * (bounding volumes, batch-id extraction) are done and before first render.
+ */
+export function releaseGeometryArraysAfterUpload(
+  geometry: BufferGeometry,
+): void {
+  for (const attribute of Object.values(geometry.attributes)) {
+    releaseAttributeAfterUpload(attribute);
+  }
+  releaseAttributeAfterUpload(geometry.index);
+}