@navaramap/three 0.0.0

package/src/core/SelectiveEffectRegistry.ts

@@ -0,0 +1,90 @@
+// ============================================================================
+// SelectiveEffectRegistry
+// ============================================================================
+
+const MAX_SLOTS = 11;
+
+/**
+ * Unified registry for selective effects.
+ *
+ * Manages effectId → slot bit mapping.
+ * Assigns bit positions in the EffectIds Buffer bitmask (R channel).
+ * Half-float preserves integer masks up to 2047 exactly, so up to 11 slots
+ * (2^11 - 1) can be represented losslessly in a single channel.
+ * Freed slots are reused by subsequent registrations.
+ */
+export class SelectiveEffectRegistry {
+  // effectId → slot bit mapping
+  private idToSlot = new Map<string, number>();
+  private freedSlots: number[] = [];
+  private nextSlot = 0;
+
+  constructor(
+    /** Called when slot assignments change (register/unregister). */
+    private onSlotsChanged: () => void,
+  ) {}
+
+  // ---------------------------------------------------------------------------
+  // Slot management
+  // ---------------------------------------------------------------------------
+
+  registerSlot(effectId: string): number {
+    const existing = this.idToSlot.get(effectId);
+    if (existing !== undefined) return existing;
+
+    let slot: number;
+    const freed = this.freedSlots.pop();
+    if (freed !== undefined) {
+      slot = freed;
+    } else {
+      if (this.nextSlot >= MAX_SLOTS) {
+        console.warn(
+          `SelectiveEffectRegistry: max ${MAX_SLOTS} slots reached, ignoring effectId "${effectId}"`,
+        );
+        return -1;
+      }
+      slot = this.nextSlot++;
+    }
+
+    this.idToSlot.set(effectId, slot);
+    this.onSlotsChanged?.();
+    return slot;
+  }
+
+  unregisterSlot(effectId: string): void {
+    const slot = this.idToSlot.get(effectId);
+    if (slot === undefined) return;
+    this.idToSlot.delete(effectId);
+    this.freedSlots.push(slot);
+    this.onSlotsChanged?.();
+  }
+
+  get slotCount(): number {
+    return this.idToSlot.size;
+  }
+
+  getSlot(effectId: string): number | undefined {
+    return this.idToSlot.get(effectId);
+  }
+
+  computeMask(effectIds: readonly string[]): number {
+    let mask = 0;
+    for (const id of effectIds) {
+      const slot = this.idToSlot.get(id);
+      if (slot !== undefined && slot >= 0) {
+        mask |= 1 << slot;
+      }
+    }
+    return mask;
+  }
+
+  /**
+   * Clear all slot assignments.
+   * Intended for teardown only; does not emit onSlotsChanged.
+   */
+  clear(): void {
+    this.idToSlot.clear();
+    this.freedSlots = [];
+    this.nextSlot = 0;
+  }
+}

package/src/core/ViewContext.ts

@@ -0,0 +1,235 @@
+import { EventHandler } from "@navaramap/core";
+import type { Core } from "@navaramap/engine";
+import type { ConcurrencyManager } from "@navaramap/worker";
+import type { Pass as PostProcessingPass } from "postprocessing";
+import type { Material, Object3D, WebGLRenderer } from "three";
+import invariant from "tiny-invariant";
+
+import type { LayersManager } from "../layersManager";
+import type { PickableMesh } from "../mesh/pickableMesh";
+import type { RenderPassOrchestrator } from "../orchestrators";
+import type { CustomRenderPass } from "../passes";
+import type { Scenes } from "../scene";
+import type { MeshCache } from "../type";
+
+import type { EffectHandle } from "./BaseHandle";
+import { SelectiveEffectRegistry } from "./SelectiveEffectRegistry";
+
+type ViewContextEvents = {
+  /**
+   * Emitted when a material is registered for CSM shadow rendering.
+   * @experimental This event may change or be removed in future versions.
+   */
+  shadowApplied: (material: Material) => void;
+  /**
+   * Emitted when a material is unregistered from CSM shadow rendering.
+   * @experimental This event may change or be removed in future versions.
+   */
+  shadowRemoved: (material: Material) => void;
+  /**
+   * Emitted when effect slot assignments change in SelectiveEffectRegistry.
+   * Listeners should recompute effectIdsMask to stay in sync.
+   */
+  effectSlotsChanged: () => void;
+};
+
+/**
+ * ViewContext is the shared context object passed to every custom descriptor and plugin.
+ *
+ * The public properties and methods defined here form the **public API surface**
+ * exposed to user-authored descriptors and plugins. Any addition, removal, or
+ * signature change to a public member is a **breaking change** for consumers.
+ *
+ * When extending this class, keep the public surface minimal and intentional:
+ * - Prefer methods over exposing internal objects directly — this allows the
+ *   implementation to change without breaking downstream code.
+ * - Mark internal dependencies as `private` so they are not accessible from
+ *   descriptor/plugin code.
+ */
+export class ViewContext extends EventHandler<ViewContextEvents> {
+  private _selectiveEffectRegistry: SelectiveEffectRegistry;
+  private _renderPass?: CustomRenderPass;
+
+  constructor(
+    /** Scene containers for different rendering passes. */
+    private _scenes: Scenes,
+    private layersManager: LayersManager,
+    private renderPassOrchestrator: RenderPassOrchestrator,
+    /** Manager for scheduling work on Web Workers. */
+    private _concurrencyManager: ConcurrencyManager,
+    private _core: Core,
+    private _meshes: MeshCache,
+  ) {
+    super();
+
+    this._selectiveEffectRegistry = new SelectiveEffectRegistry(() =>
+      this.emit("effectSlotsChanged"),
+    );
+  }
+
+  /** Scene containers for different rendering passes. */
+  get scenes(): Scenes {
+    return this._scenes;
+  }
+
+  /** Manager for scheduling work on Web Workers. */
+  get concurrencyManager(): ConcurrencyManager {
+    return this._concurrencyManager;
+  }
+
+  get selectiveEffectRegistry(): SelectiveEffectRegistry {
+    return this._selectiveEffectRegistry;
+  }
+
+  // --- Pass management ---
+
+  /** Get a post-processing pass by name. */
+  getPass(name: string): PostProcessingPass | undefined {
+    return this.renderPassOrchestrator.getPass(name);
+  }
+
+  /** Add a post-processing pass to the end of the pipeline. */
+  addPass(name: string, pass: PostProcessingPass): void {
+    this.renderPassOrchestrator.addPass(name, pass);
+  }
+
+  /** Insert a post-processing pass before the pass identified by `targetName`. */
+  insertPassBefore(
+    targetName: string,
+    name: string,
+    pass: PostProcessingPass,
+  ): void {
+    this.renderPassOrchestrator.insertPassBefore(targetName, name, pass);
+  }
+
+  /** Insert a post-processing pass after the pass identified by `targetName`. */
+  insertPassAfter(
+    targetName: string,
+    name: string,
+    pass: PostProcessingPass,
+  ): void {
+    this.renderPassOrchestrator.insertPassAfter(targetName, name, pass);
+  }
+
+  /** Remove a post-processing pass by name. */
+  removePass(name: string): void {
+    this.renderPassOrchestrator.removePass(name);
+  }
+
+  // --- Renderer/buffer access ---
+
+  /** Get the underlying WebGLRenderer instance. */
+  getRenderer(): WebGLRenderer {
+    return this.renderPassOrchestrator.effectComposer.getRenderer();
+  }
+
+  /** Get the input buffer from the effect composer. */
+  getInputBuffer() {
+    return this.renderPassOrchestrator.effectComposer.inputBuffer;
+  }
+
+  /** @internal */
+  _setRenderPass(renderPass: CustomRenderPass) {
+    this._renderPass = renderPass;
+  }
+
+  /**
+   * Gets the globe depth texture for post-processing effects.
+   */
+  getGlobeDepthTexture() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.globeDepthCopyPass.texture;
+  }
+
+  /**
+   * Gets the globe normal texture for post-processing effects.
+   */
+  getGlobeNormalTexture() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.globeNormalCopyPass.texture;
+  }
+
+  /**
+   * Gets the main render target which includes G-buffer.
+   */
+  getRenderTarget() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.gbufferRenderTarget;
+  }
+
+  /**
+   * Gets the scene normal texture from the G-buffer.
+   */
+  getNormalTexture() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.gbufferRenderTarget.textures[1];
+  }
+
+  /**
+   * Gets the effect IDs texture from the G-buffer.
+   */
+  getEffectIdsTexture() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.gbufferRenderTarget.textures[2];
+  }
+
+  /**
+   * Gets the emissive texture from the G-buffer.
+   */
+  getEmissiveTexture() {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    return this._renderPass.gbufferRenderTarget.textures[3];
+  }
+
+  // --- Descriptor query ---
+
+  /** @internal Iterate over all registered effect descriptors. */
+  _getEffects(): Generator<EffectHandle> {
+    return this.layersManager.getEffectDescs();
+  }
+
+  /**
+   * Register a material for CSM shadow rendering.
+   * @experimental This API may change or be removed in future versions.
+   */
+  applyShadowMaterial(material: Material): void {
+    this.emit("shadowApplied", material);
+  }
+
+  /**
+   * Unregister a material from CSM shadow rendering.
+   * @experimental This API may change or be removed in future versions.
+   */
+  removeShadowMaterial(material: Material): void {
+    this.emit("shadowRemoved", material);
+  }
+
+  // --- Picking registration ---
+
+  /**
+   * Generate a new unique global batch ID for picking.
+   * The returned ID is in the 24-bit RGB color range (1..0xffffff).
+   */
+  genGlobalBatchId(): number | undefined {
+    return this._core?.genGlobalBatchId();
+  }
+
+  /**
+   * Register a pickable mesh so the picking system can discover it.
+   * @param key - Unique key (typically the descriptor ID).
+   * @param mesh - Any {@link PickableMesh} implementation. Implementers
+   *   must also be an `Object3D` so the pick pass can re-parent the
+   *   renderable into its dedicated scene.
+   */
+  registerPickableMesh(key: string, mesh: PickableMesh & Object3D): void {
+    this._meshes?.set(key, mesh);
+  }
+
+  /**
+   * Unregister a pickable mesh from the picking system.
+   * @param key - The key used during registration.
+   */
+  unregisterPickableMesh(key: string): void {
+    this._meshes?.delete(key);
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,16 @@
+import { getExcludedKeys } from "../utils/object";
+
+import type { EffectConfig } from "./EffectDesc";
+import type { LightConfig } from "./LightDesc";
+import type { MeshConfig } from "./MeshDesc";
+
+export class UnknownTypeError extends Error {
+  constructor(
+    type: Exclude<(EffectConfig | MeshConfig | LightConfig)["type"], undefined>,
+    config: EffectConfig | MeshConfig | LightConfig,
+  ) {
+    super(
+      `Unknown ${type} type specified in configuration: ${getExcludedKeys(config, ["type"]).join(", ")}`,
+    );
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,50 @@
+export { DescRegistry } from "./DescRegistry";
+export { Registries } from "./Registries";
+export * from "./errors";
+export {
+  BaseDesc,
+  type BaseDescConfig,
+  type BaseDescConfigUpdate,
+} from "./BaseDesc";
+export {
+  MeshDesc,
+  type MeshUpdate,
+  type MeshConfig,
+  type PassKey,
+} from "./MeshDesc";
+export {
+  MeshDescWithSelectiveEffect,
+  type MeshUpdateWithSelectiveEffect,
+  type MeshConfigWithSelectiveEffect,
+} from "./MeshDescWithSelectiveEffect";
+export {
+  InstancedMeshDesc,
+  type InstancedMeshConfig,
+  type InstancedMeshUpdate,
+  type InstancedChildConfig,
+} from "./InstancedMeshDesc";
+export {
+  MeshDescRegistry,
+  type MeshDescConstructor,
+  type AnyMeshConfig,
+} from "./MeshDescRegistry";
+export { type AnyMeshDesc } from "./BaseHandle";
+export { LightDesc, type LightUpdate, type LightConfig } from "./LightDesc";
+export {
+  LightDescRegistry,
+  type LightDescConstructor,
+} from "./LightDescRegistry";
+export { EffectDesc, type EffectUpdate, type EffectConfig } from "./EffectDesc";
+export {
+  EffectDescRegistry,
+  type EffectDescConstructor,
+} from "./EffectDescRegistry";
+export {
+  BaseHandle,
+  MeshHandle,
+  LightHandle,
+  EffectHandle,
+} from "./BaseHandle";
+export * from "./ViewContext";
+export { SelectiveEffectRegistry } from "./SelectiveEffectRegistry";
+export { setupSelectiveEffectUniforms } from "../material/selectiveEffectMaterialSetup";