@navaramap/three 0.0.0

package/src/input.ts

@@ -0,0 +1,144 @@
+import type { Core } from "@navaramap/engine";
+
+// TODO: Need to think about how to propagate these event to worker.
+export function registerInputEvents(
+  core: Core,
+  element: HTMLElement,
+  getTerrainDistance?: () => number | null,
+): () => void {
+  let mouseEvent:
+    | {
+        type: "mousedown" | "mouseup";
+        button: number;
+      }
+    | undefined;
+
+  let lastTerrainDistance: number | undefined;
+
+  const mousedown = (event: MouseEvent) => {
+    mouseEvent = {
+      type: "mousedown",
+      button: event.button,
+    };
+    const terrainDistance = getTerrainDistance?.() ?? undefined;
+    lastTerrainDistance = terrainDistance;
+    core.input({ ...mouseEvent, terrain_distance: terrainDistance });
+  };
+  const mouseup = () => {
+    core.input({
+      ...(mouseEvent ?? {}),
+      type: "mouseup",
+    });
+    mouseEvent = undefined;
+  };
+
+  const mousemove = (event: MouseEvent) => {
+    const width = element.clientWidth;
+    const height = element.clientHeight;
+    const aspectRatio = width / height;
+    core.input({
+      type: "mousemove",
+      x: (event.clientX / width) * aspectRatio,
+      y: event.clientY / height,
+    });
+  };
+
+  const touchstart = (event: TouchEvent) => {
+    event.preventDefault();
+
+    lastTerrainDistance = getTerrainDistance?.() ?? undefined;
+    for (const touch of event.changedTouches) {
+      core.input({
+        type: "touchstart",
+        x: touch.clientX,
+        y: touch.clientY,
+        id: touch.identifier,
+        terrain_distance: lastTerrainDistance,
+      });
+    }
+  };
+
+  const touchend = (event: TouchEvent) => {
+    event.preventDefault();
+
+    for (const touch of event.changedTouches) {
+      core.input({
+        type: "touchend",
+        x: touch.clientX,
+        y: touch.clientY,
+        id: touch.identifier,
+      });
+    }
+  };
+
+  const touchmove = (event: TouchEvent) => {
+    event.preventDefault();
+
+    for (const touch of event.changedTouches) {
+      core.input({
+        type: "touchmove",
+        x: touch.clientX,
+        y: touch.clientY,
+        id: touch.identifier,
+      });
+    }
+  };
+
+  const wheel = (event: WheelEvent) => {
+    lastTerrainDistance = getTerrainDistance?.() ?? undefined;
+    core.input({
+      type: "wheel",
+      x: event.deltaX,
+      y: event.deltaY,
+      terrain_distance: lastTerrainDistance,
+    });
+  };
+
+  const keydown = (event: KeyboardEvent) => {
+    core.input({
+      type: "keydown",
+      key_code: event.code,
+      key: event.key,
+    });
+  };
+
+  const keyup = (event: KeyboardEvent) => {
+    core.input({
+      type: "keyup",
+      key_code: event?.code,
+      key: event?.key,
+    });
+  };
+  // This is used to emit a key up event without any params.
+  const keyupEmpty = () => {
+    core.input({
+      type: "keyup",
+    });
+  };
+
+  element.addEventListener("mousedown", mousedown);
+  element.addEventListener("mouseup", mouseup);
+  element.addEventListener("mouseleave", mouseup);
+  element.addEventListener("mouseleave", keyupEmpty);
+  element.addEventListener("mousemove", mousemove);
+  element.addEventListener("touchstart", touchstart);
+  element.addEventListener("touchend", touchend);
+  element.addEventListener("touchmove", touchmove);
+  element.addEventListener("wheel", wheel);
+  document.addEventListener("keydown", keydown);
+  document.addEventListener("keyup", keyup);
+
+  return () => {
+    element.removeEventListener("mousedown", mousedown);
+    element.removeEventListener("mouseup", mouseup);
+    element.removeEventListener("mouseleave", mouseup);
+    element.removeEventListener("mouseleave", keyupEmpty);
+    element.removeEventListener("mousemove", mousemove);
+    element.removeEventListener("touchstart", touchstart);
+    element.removeEventListener("touchend", touchend);
+    element.removeEventListener("touchmove", touchmove);
+    element.removeEventListener("wheel", wheel);
+    document.removeEventListener("keydown", keydown);
+    document.removeEventListener("keyup", keyup);
+  };
+}

package/src/layer.ts

@@ -0,0 +1,183 @@
+import { EventHandler, type FeatureSetId } from "@navaramap/core";
+import type { Core } from "@navaramap/engine";
+
+import { FeatureEvaluator } from "./evaluations";
+import { Source } from "./source";
+import type { LayerDescription } from "./type";
+
+export type FeatureCreatedParams = {
+  featureSetId: FeatureSetId;
+  evaluator: FeatureEvaluator;
+  credit?: string;
+};
+
+export type FeatureUpdatedParams = {
+  featureSetId: FeatureSetId;
+  evaluator: FeatureEvaluator;
+  updatedAt: number;
+};
+
+export type FeatureVisibilityChangedParams = {
+  featureSetId: FeatureSetId;
+  visible: boolean;
+};
+
+export type FeatureRemovedParams = {
+  featureSetId: FeatureSetId;
+};
+
+/**
+ * Events emitted by Layer. Subscribe using `layer.on(eventName, callback)`.
+ */
+export type LayerEvent = {
+  /** Emitted when a new feature is created in this layer. */
+  featureCreated: (params: FeatureCreatedParams) => void;
+  /** Emitted when a feature in this layer is updated. */
+  featureUpdated: (params: FeatureUpdatedParams) => void;
+  /** Emitted when a feature's visibility changes. */
+  featureVisibilityChanged: (params: FeatureVisibilityChangedParams) => void;
+  /** Emitted when a feature is removed from this layer. */
+  featureRemoved: (params: FeatureRemovedParams) => void;
+  /** Emitted when the layer is deleted. */
+  deleted: () => void;
+};
+
+/**
+ * A handle to control a resource layer (e.g., imagery, terrain, GeoJSON, 3D Tiles) after it has been added to the scene.
+ * Returned by `ThreeView.addLayer()` when adding resource layers (not mesh, light, or effect descriptors).
+ *
+ * Resource layers are data-driven layers that load and display geographic data from external sources.
+ * Use this handle to update layer configuration or delete the layer.
+ *
+ * @example
+ * ```typescript
+ * // Add a GeoJSON layer
+ * const geoJsonLayer = view.addLayer({
+ *   type: "geojson",
+ *   data: {
+ *     url: "https://example.com/data.geojson",
+ *   },
+ *   point: { color: 0xff0000 }
+ * });
+ *
+ * // Update the layer configuration
+ * geoJsonLayer.update({ point: { color: 0x00ff00 } });
+ *
+ * // Listen to feature events
+ * geoJsonLayer.on("featureCreated", ({ evaluator }) => {
+ *   console.log("Feature created:", evaluator);
+ * });
+ *
+ * // Delete the layer
+ * geoJsonLayer.delete();
+ * ```
+ */
+export class Layer extends EventHandler<LayerEvent> {
+  /** The unique identifier of this layer. */
+  id: string;
+  private core: Core;
+  private featureEvaluators: Map<FeatureSetId, FeatureEvaluator> = new Map<
+    FeatureSetId,
+    FeatureEvaluator
+  >();
+  private needUpdate = false;
+  private convertColors?: (obj: unknown) => unknown;
+
+  constructor(
+    id: string,
+    core: Core,
+    convertColors?: (obj: unknown) => unknown,
+  ) {
+    super();
+
+    this.id = id;
+    this.core = core;
+    this.convertColors = convertColors;
+  }
+
+  /**
+   * Register a feature evaluator with this layer
+   * @internal Used by the event system
+   */
+  _registerFeatureEvaluator(
+    featureSetId: FeatureSetId,
+    evaluator: FeatureEvaluator,
+  ) {
+    this.featureEvaluators.set(featureSetId, evaluator);
+  }
+
+  /**
+   * Get a feature evaluator by ID
+   * @internal Used by the event system
+   */
+  _getFeatureEvaluator(
+    featureSetId: FeatureSetId,
+  ): FeatureEvaluator | undefined {
+    return this.featureEvaluators.get(featureSetId);
+  }
+
+  /**
+   * Unregister a feature evaluator from this layer
+   * @internal Used by the event system
+   */
+  _unregisterFeatureEvaluator(featureSetId: FeatureSetId) {
+    this.featureEvaluators.delete(featureSetId);
+  }
+
+  /**
+   * Process feature updates for all registered features
+   * @internal Used by the animation loop
+   */
+  _processFeatureUpdates(updatedAt: number) {
+    if (!this.needUpdate) {
+      return false;
+    }
+    this.needUpdate = false;
+
+    // Process all evaluators with the registered callbacks
+    for (const evaluator of this.featureEvaluators.values()) {
+      this.emit("featureUpdated", {
+        featureSetId: evaluator.id,
+        evaluator,
+        updatedAt,
+      });
+    }
+
+    return true;
+  }
+
+  /**
+   * Marks the layer for update on the next frame.
+   * Call this when you need to trigger `featureUpdated` events.
+   */
+  forceUpdate() {
+    this.needUpdate = true;
+  }
+
+  /**
+   * Updates the layer configuration.
+   * The entire configuration is replaced with the new values.
+   * @param l - New layer configuration
+   */
+  update(l: LayerDescription) {
+    const normalized =
+      "source" in l && l.source instanceof Source
+        ? { ...l, source: l.source.id }
+        : l;
+    // Convert Color objects to numbers if converter is provided
+    const processedLayer = this.convertColors
+      ? (this.convertColors(normalized) as LayerDescription)
+      : normalized;
+    this.core.updateLayer(this.id, processedLayer);
+  }
+
+  /**
+   * Removes the layer from the scene and disposes its resources.
+   * Emits the "deleted" event before cleanup.
+   * After calling this, the layer should no longer be used.
+   */
+  delete() {
+    this.core.deleteLayer(this.id);
+    this.emit("deleted");
+  }
+}

package/src/layers/effect/FinalCopyEffectDesc.ts

@@ -0,0 +1,29 @@
+import {
+  EffectDesc,
+  type EffectConfig,
+  type EffectUpdate,
+} from "../../core/EffectDesc";
+import { CopyPass } from "../../effects";
+
+type Description = {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  final?: {};
+};
+
+export type FinalCopyPassConfig = Description & EffectConfig;
+
+export type FinalCopyPassUpdate = Description & EffectUpdate;
+
+export class FinalCopyEffectDesc extends EffectDesc<
+  FinalCopyPassConfig,
+  FinalCopyPassUpdate,
+  CopyPass
+> {
+  static key = "final";
+
+  createPass() {
+    const pass = new CopyPass();
+
+    return pass;
+  }
+}

package/src/layers/effect/MRTPassEffectDesc.ts

@@ -0,0 +1,105 @@
+import type { DepthPackingStrategies, Texture } from "three";
+import invariant from "tiny-invariant";
+
+import {
+  EffectDesc,
+  type EffectConfig,
+  type EffectUpdate,
+} from "../../core/EffectDesc";
+import type { ViewContext } from "../../core/ViewContext";
+import type ThreeView from "../../index";
+import { CustomRenderPass } from "../../passes";
+
+type Description = {
+  mrt?: {
+    debugNormal?: boolean;
+  };
+};
+
+export type MRTPassConfig = Description & EffectConfig;
+
+export type MRTPassUpdate = Description & EffectUpdate;
+
+export class MRTPassEffectDesc extends EffectDesc<
+  MRTPassConfig,
+  MRTPassUpdate,
+  CustomRenderPass
+> {
+  static key = "mrt";
+  // No insertAfter/Before - this is typically the first pass
+
+  private config: MRTPassConfig;
+
+  constructor(view: ThreeView, ctx: ViewContext, config: MRTPassConfig) {
+    super(view, ctx, config);
+    this.config = config;
+  }
+
+  createPass(): CustomRenderPass {
+    // Create render pass for MRT scene
+    const scenes = this.ctx.scenes;
+    const camera = this.view.camera.raw;
+
+    invariant(this.view.globe);
+
+    const pass = new CustomRenderPass(
+      scenes,
+      camera,
+      this.ctx.getInputBuffer(),
+      this.view.globe,
+      {
+        debugNormal: !!this.config.mrt?.debugNormal,
+      },
+    );
+
+    return pass;
+  }
+
+  get normalBuffer(): Texture | undefined {
+    return this.raw?.gbufferRenderTarget.textures[1];
+  }
+
+  get effectIdsBuffer(): Texture | undefined {
+    return this.raw?.gbufferRenderTarget.textures[2];
+  }
+
+  get emissiveBuffer(): Texture | undefined {
+    return this.raw?.gbufferRenderTarget.textures[3];
+  }
+
+  get depthBuffer(): Texture | undefined {
+    return this.raw?.allDepthCopyPass.texture;
+  }
+
+  get depthBufferPacking(): DepthPackingStrategies | undefined {
+    return this.raw?.allDepthCopyPass.depthPacking;
+  }
+
+  get globeNormalBuffer(): Texture | undefined {
+    return this.raw?.globeNormalCopyPass.texture;
+  }
+
+  get globeDepthBuffer(): Texture | undefined {
+    return this.raw?.globeDepthCopyPass.texture;
+  }
+
+  get globeDepthBufferPacking(): DepthPackingStrategies | undefined {
+    return this.raw?.globeDepthCopyPass.depthPacking;
+  }
+
+  onUpdateConfig(updates: MRTPassUpdate): void {
+    super.onUpdateConfig(updates);
+
+    if (!this._instance) return;
+
+    Object.assign(this.config, updates);
+
+    if (updates.mrt?.debugNormal !== undefined) {
+      // TODO: Support
+    }
+  }
+
+  onDestroy(): void {
+    super.onDestroy();
+  }
+}

package/src/layers/effect/README.md

@@ -0,0 +1,9 @@
+# Core Effect Descriptors
+
+This module contains only core effect descriptors that are tightly coupled with the
+internal rendering pipeline (MRT passes, transparent pass, final copy, selective
+effects).
+
+Independent, self-contained effect descriptors should be implemented as external
+packages (e.g., `@navaramap/three_default_descs`) using the public
+`EffectDesc` API and registered via plugins.

package/src/layers/effect/SelectiveEffectDesc.ts

@@ -0,0 +1,113 @@
+import { OrthographicCamera, PlaneGeometry, type Texture } from "three";
+
+import {
+  EffectDesc,
+  type EffectConfig,
+  type EffectUpdate,
+} from "../../core/EffectDesc";
+import type { ViewContext } from "../../core/ViewContext";
+import type ThreeView from "../../index";
+
+import type { MRTPassEffectDesc } from "./MRTPassEffectDesc";
+
+// Base configuration for selective effect descriptors
+export type SelectiveEffectConfig = {
+  selectiveEffect?: true;
+} & EffectConfig;
+
+export type SelectiveEffectUpdate = EffectUpdate;
+
+/**
+ * Create fullscreen rendering infrastructure for selective effect passes.
+ */
+export function createFullscreenQuad(): {
+  camera: OrthographicCamera;
+  geometry: PlaneGeometry;
+} {
+  return {
+    camera: new OrthographicCamera(-1, 1, 1, -1, 0, 1),
+    geometry: new PlaneGeometry(2, 2),
+  };
+}
+
+/**
+ * Base class for buffer-based selective effect descriptors (Bloom, Outline, etc.).
+ *
+ * Manages effect key registration, EffectIds Buffer slot allocation, and
+ * provides MRT buffer accessors for subclass passes.
+ *
+ * Subclasses implement {@link createPass}.
+ */
+export abstract class SelectiveEffectDesc<
+  Config extends SelectiveEffectConfig = SelectiveEffectConfig,
+  UpdateConfig extends SelectiveEffectUpdate = SelectiveEffectUpdate,
+> extends EffectDesc<Config, UpdateConfig> {
+  protected config: Config;
+
+  constructor(view: ThreeView, ctx: ViewContext, config: Config) {
+    super(view, ctx, config);
+    this.config = config;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API for Pass classes
+  // ---------------------------------------------------------------------------
+
+  /** ViewContext for accessing scenes, renderer, registry, etc. */
+  public get viewContext(): ViewContext {
+    return this.ctx;
+  }
+
+  /** Layer configuration (typed per subclass). */
+  public get layerConfig(): Config {
+    return this.config;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  onCreate(): void {
+    const registry = this.ctx.selectiveEffectRegistry;
+    if (!registry) {
+      throw new Error(
+        "SelectiveEffectRegistry not initialized. Ensure MRTPassEffectDesc is added before selective effect descriptors.",
+      );
+    }
+
+    // Allocate a slot bit in the EffectIds Buffer
+    registry.registerSlot(this.id);
+
+    super.onCreate();
+  }
+
+  onDestroy(): void {
+    const registry = this.ctx.selectiveEffectRegistry;
+
+    // Release slot bit in the EffectIds Buffer
+    registry?.unregisterSlot(this.id);
+
+    super.onDestroy();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Buffer accessors — used by subclass passes to read MRT data
+  // ---------------------------------------------------------------------------
+
+  /** Emissive RGB buffer (MRT attachment[3]). */
+  public getEmissiveBuffer(): Texture | null {
+    const mrtDesc = this.find<MRTPassEffectDesc>("mrt");
+    return mrtDesc?.emissiveBuffer ?? null;
+  }
+
+  /** EffectIds bitmask buffer (MRT attachment[2]). NearestFilter, discrete data. */
+  public getEffectIdsBuffer(): Texture | null {
+    const mrtDesc = this.find<MRTPassEffectDesc>("mrt");
+    return mrtDesc?.effectIdsBuffer ?? null;
+  }
+
+  /** Slot bit index for this effect instance in the EffectIds Buffer. -1 if unregistered. */
+  public getEffectSlot(): number {
+    return this.ctx.selectiveEffectRegistry?.getSlot(this.id) ?? -1;
+  }
+}

package/src/layers/effect/SkyEnvMapEffectDesc.ts

@@ -0,0 +1,58 @@
+import {
+  EffectDesc,
+  type EffectConfig,
+  type EffectUpdate,
+} from "../../core/EffectDesc";
+import type { ViewContext } from "../../core/ViewContext";
+import type ThreeView from "../../index";
+import { SkyEnvMapPass } from "../../passes";
+
+type Description = {
+  skyEnvMap?: {
+    resolution?: number;
+  };
+};
+
+export type SkyEnvMapPassConfig = Description & EffectConfig;
+
+export type SkyEnvMapPassUpdate = Description & EffectUpdate;
+
+export class SkyEnvMapEffectDesc extends EffectDesc<
+  SkyEnvMapPassConfig,
+  SkyEnvMapPassUpdate,
+  SkyEnvMapPass
+> {
+  static key = "skyEnvMap";
+  static insertBefore = ["mrt"];
+
+  private config: SkyEnvMapPassConfig;
+
+  constructor(view: ThreeView, ctx: ViewContext, config: SkyEnvMapPassConfig) {
+    super(view, ctx, config);
+    this.config = config;
+  }
+
+  createPass(): SkyEnvMapPass {
+    const scenes = this.ctx.scenes;
+    const camera = this.view.camera.raw;
+
+    const resolution = this.config.skyEnvMap?.resolution ?? 256;
+
+    const pass = new SkyEnvMapPass(scenes, camera, resolution);
+
+    return pass;
+  }
+
+  onUpdateConfig(updates: SkyEnvMapPassUpdate): void {
+    super.onUpdateConfig(updates);
+
+    if (!this._instance) return;
+
+    Object.assign(this.config, updates);
+
+    if (updates.skyEnvMap?.resolution !== undefined) {
+      // Would need to recreate the pass to change resolution
+      // For now, resolution is set at creation time only
+    }
+  }
+}

package/src/layers/effect/TransparentPassEffectDesc.ts

@@ -0,0 +1,62 @@
+import { Group, Scene } from "three";
+
+import {
+  EffectDesc,
+  type EffectConfig,
+  type EffectUpdate,
+} from "../../core/EffectDesc";
+import { RenderPass } from "../../effects";
+
+type Description = {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  transparent?: {};
+};
+
+export type TransparentPassConfig = Description & EffectConfig;
+
+export type TransparentPassUpdate = Description & EffectUpdate;
+
+export class TransparentPassEffectDesc extends EffectDesc<
+  TransparentPassConfig,
+  TransparentPassUpdate,
+  RenderPass
+> {
+  static key = "transparent";
+  static insertAfter = ["ssao", "clouds", "atmosphere", "mrt"];
+
+  light = new Group();
+  lightsSyncMap = new Map();
+
+  createPass(): RenderPass {
+    // Create render pass for transparent objects
+    const scene = new Scene();
+    scene.add(this.light);
+    scene.add(this.ctx.scenes.transparent);
+
+    const camera = this.view.camera.raw;
+
+    const pass = new RenderPass(scene, camera);
+    pass.clear = false;
+
+    this.ctx.scenes.light.addEventListener("childadded", ({ child }) => {
+      const cloned = child.clone(true);
+      this.lightsSyncMap.set(child.id, cloned);
+      this.light.add(cloned);
+    });
+    this.ctx.scenes.light.addEventListener("childremoved", ({ child }) => {
+      this.light.remove(this.lightsSyncMap.get(child.id));
+      this.lightsSyncMap.delete(child.id);
+    });
+
+    return pass;
+  }
+
+  update(_time: number): void {
+    // Sync lights
+    let i = 0;
+    for (const child of this.ctx.scenes.light.children) {
+      this.light.children[i].copy(child, true);
+      i++;
+    }
+  }
+}