@navaramap/three 0.0.0

package/src/object3DEvent.ts

@@ -0,0 +1,6 @@
+import type { Object3DEventMap } from "three";
+
+export type CustomObject3DEventMap = Object3DEventMap & {
+  removedFromWorld: undefined;
+  needsUpdate: undefined;
+};

package/src/orchestrators/RenderPassOrchestrator.ts

@@ -0,0 +1,147 @@
+import { NamedIndexMap } from "@navaramap/core";
+import { EffectComposer, Pass as PostProcessingPass } from "postprocessing";
+import { HalfFloatType, Scene, WebGLRenderer, Group } from "three";
+
+export type RenderPassOrchestratorOptions = {
+  halfFloat?: boolean;
+  multisampling?: number;
+};
+
+export type NamedPass = {
+  name: string;
+  pass: PostProcessingPass;
+};
+
+// Implementation policy:
+// - Here we only manage Pass with an ordered Map mechanism.
+// - When a Layer inserts with insertBefore/After, it inserts in the appropriate place.
+// - If we render in order from the top, we can render while preserving dependencies.
+// - As a preliminary step to the Layer mechanism, we want to be able to just freely add Pass from the ThreeView to the RenderPassOrchestrator.
+// - Use NamedIndexMap for Pass management.
+
+/**
+ * Orchestrate rendering passes with ordered management and flexible insertion.
+ */
+export class RenderPassOrchestrator {
+  lights = new Group();
+  scenes = {
+    mrt: new Scene(),
+    globe: new Scene(),
+    draped: new Scene(),
+    opaque: new Scene(),
+    transparent: new Scene(),
+    skyEnvMap: new Scene(),
+  };
+  effectComposer: EffectComposer;
+
+  private passMap = new NamedIndexMap<NamedPass>();
+
+  constructor(renderer: WebGLRenderer, options: RenderPassOrchestratorOptions) {
+    // Setup render pass
+    this.effectComposer = new EffectComposer(renderer, {
+      stencilBuffer: true,
+      frameBufferType: (options.halfFloat ?? true) ? HalfFloatType : undefined,
+      multisampling: options.multisampling,
+    });
+  }
+
+  setSize(width: number, height: number) {
+    this.effectComposer.setSize(width, height);
+  }
+
+  render() {
+    this.effectComposer.render();
+  }
+
+  /**
+   * Add a named pass to the end of the pass list.
+   */
+  addPass(name: string, pass: PostProcessingPass): void {
+    const namedPass: NamedPass = { name, pass };
+    this.passMap.add(namedPass);
+    this.effectComposer.addPass(pass);
+  }
+
+  /**
+   * Insert a pass before the specified target pass.
+   */
+  insertPassBefore(
+    targetName: string,
+    name: string,
+    pass: PostProcessingPass,
+  ): void {
+    const namedPass: NamedPass = { name, pass };
+    const targetIndex = this.passMap.insertBefore(targetName, namedPass);
+    this.effectComposer.addPass(pass, targetIndex);
+  }
+
+  /**
+   * Insert a pass after the specified target pass.
+   */
+  insertPassAfter(
+    targetName: string,
+    name: string,
+    pass: PostProcessingPass,
+  ): void {
+    const namedPass: NamedPass = { name, pass };
+    const targetIndex = this.passMap.insertAfter(targetName, namedPass);
+    this.effectComposer.addPass(pass, targetIndex);
+  }
+
+  /**
+   * Remove a pass by name.
+   */
+  removePass(name: string): void {
+    const targetPass = this.passMap.list.find((p) => p.name === name);
+    if (!targetPass) {
+      throw new Error(`Pass not found: ${name}`);
+    }
+
+    this.effectComposer.removePass(targetPass.pass);
+    this.passMap.list = this.passMap.list.filter((p) => p.name !== name);
+    this.rebuildIndexMap();
+  }
+
+  /**
+   * Get a pass by name.
+   */
+  getPass(name: string): PostProcessingPass | undefined {
+    return this.passMap.list.find((p) => p.name === name)?.pass;
+  }
+
+  /**
+   * Get all pass names in order.
+   */
+  getPassNames(): string[] {
+    return this.passMap.list.map((p) => p.name);
+  }
+
+  /**
+   * Clear all passes.
+   */
+  clearPasses(): void {
+    for (const namedPass of this.passMap.list) {
+      this.effectComposer.removePass(namedPass.pass);
+    }
+    this.passMap.list = [];
+    this.passMap.indexMap = {};
+  }
+
+  /**
+   * Dispose all GPU resources held by the effect composer.
+   */
+  dispose(): void {
+    this.clearPasses();
+    this.effectComposer.dispose();
+  }
+
+  /**
+   * Rebuild the index map after manual list modification.
+   */
+  private rebuildIndexMap(): void {
+    this.passMap.indexMap = {};
+    for (let i = 0; i < this.passMap.list.length; i++) {
+      this.passMap.indexMap[this.passMap.list[i].name] = i;
+    }
+  }
+}

package/src/orchestrators/index.ts

@@ -0,0 +1 @@
+export * from "./RenderPassOrchestrator";

package/src/passes/AllDepthCopyPass.ts

@@ -0,0 +1,165 @@
+import PostProcessingCommon from "@shaders/glsl/postprocessingCommon.vert.glsl";
+import { CopyPass, Pass } from "postprocessing";
+import {
+  BasicDepthPacking,
+  DepthTexture,
+  LinearFilter,
+  NoBlending,
+  RGBADepthPacking,
+  RGBAFormat,
+  ShaderMaterial,
+  Texture,
+  WebGLRenderTarget,
+  type DepthPackingStrategies,
+  type WebGLRenderer,
+} from "three";
+
+import { packing } from "../shaders";
+
+const fragmentShader = `
+#include <packing>
+
+${packing}
+
+uniform sampler2D tDepth;
+#ifdef MERGE_DEPTH
+uniform sampler2D tExistingDepth;
+#endif
+
+varying vec2 vUv;
+
+float readDepth() {
+  #if DEPTH_PACKING == 3201
+    return unpackRGBAToDepth(texture2D(tDepth, vUv));
+  #else
+      return texture2D(tDepth, vUv).r;
+  #endif
+}
+
+void main() {
+  float depth = readDepth();
+
+  #ifdef MERGE_DEPTH
+  float existingDepth = unpackRGBAToDepth(texture2D(tExistingDepth, vUv));
+  // Keep the minimum depth (closest to camera)
+  depth = min(depth, existingDepth);
+  #endif
+
+  gl_FragColor = packDepthToRGBA(depth);
+}
+`;
+
+/**
+ * A pass that copies and optionally merges depth buffers.
+ * This is used to accumulate depths from multiple render stages.
+ */
+export class AllDepthCopyPass extends Pass {
+  private _renderTarget: WebGLRenderTarget;
+  private _material: ShaderMaterial;
+  private _merge: boolean;
+
+  private _copyPassRenderTarget = new WebGLRenderTarget(1, 1, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    stencilBuffer: false,
+    depthBuffer: false,
+  });
+  private _copyPass = new CopyPass(this._copyPassRenderTarget);
+
+  constructor(renderTarget?: WebGLRenderTarget) {
+    super("AllDepthCopyPass");
+
+    this.needsSwap = false;
+
+    this._material = new ShaderMaterial({
+      uniforms: {
+        tDepth: { value: null },
+        tExistingDepth: { value: null },
+      },
+      vertexShader: PostProcessingCommon,
+      fragmentShader,
+      blending: NoBlending,
+      toneMapped: false,
+      depthWrite: false,
+      depthTest: false,
+      defines: {},
+    });
+
+    if (renderTarget) {
+      this._renderTarget = renderTarget;
+    } else {
+      this._renderTarget = new WebGLRenderTarget(1, 1, {
+        format: RGBAFormat,
+        minFilter: LinearFilter,
+        magFilter: LinearFilter,
+        generateMipmaps: false,
+        stencilBuffer: false,
+        depthBuffer: false,
+      });
+    }
+
+    this.fullscreenMaterial = this._material;
+    this._merge = false;
+  }
+
+  get texture(): Texture {
+    return this._renderTarget.texture;
+  }
+
+  get depthPacking(): DepthPackingStrategies {
+    return RGBADepthPacking; // This depth texture is always packed as RGBA.
+  }
+
+  /**
+   * Set the depth texture to copy from.
+   */
+  setDepthTexture(
+    texture: DepthTexture | Texture | null,
+    packing?: DepthPackingStrategies,
+  ): void {
+    this._material.uniforms.tDepth.value = texture;
+    this._material.defines.DEPTH_PACKING = packing ?? BasicDepthPacking;
+  }
+
+  /**
+   * Copy depth buffer, optionally merging with existing depth.
+   * @param merge - If true, merge with existing depth by keeping the minimum (closest) depth
+   */
+  copyDepth(merge = false): void {
+    this._merge = merge;
+    if (merge) {
+      // Store the current texture as the existing depth
+      this._material.uniforms.tExistingDepth.value = this._copyPass.texture;
+      this._material.defines.MERGE_DEPTH = "1";
+    } else {
+      delete this._material.defines.MERGE_DEPTH;
+      this._material.uniforms.tExistingDepth.value = null;
+    }
+    this._material.needsUpdate = true;
+  }
+
+  setSize(width: number, height: number): void {
+    this._renderTarget.setSize(width, height);
+    this._copyPass.setSize(width, height);
+  }
+
+  render(
+    renderer: WebGLRenderer,
+    _inputBuffer: WebGLRenderTarget | null,
+    _outputBuffer: WebGLRenderTarget | null,
+  ): void {
+    const renderTarget = this._renderTarget;
+
+    if (this._merge) {
+      this._copyPass.render(renderer, renderTarget, null);
+    }
+
+    renderer.setRenderTarget(renderTarget);
+    renderer.render(this.scene, this.camera);
+  }
+
+  dispose(): void {
+    this._renderTarget.dispose();
+    this._material.dispose();
+  }
+}

package/src/passes/CustomRenderPass.ts

@@ -0,0 +1,279 @@
+import { Globe } from "@navaramap/core";
+import { DepthCopyPass } from "postprocessing";
+import {
+  Color,
+  DepthTexture,
+  HalfFloatType,
+  NearestFilter,
+  RGBADepthPacking,
+  Scene,
+  WebGLRenderTarget,
+  type PerspectiveCamera,
+  type WebGLRenderer,
+} from "three";
+
+import { RenderPass } from "../effects";
+import { DrapedMesh } from "../mesh/DrapedMesh";
+import type { Scenes } from "../scene";
+
+import { AllDepthCopyPass, NormalCopyPass, RenderTargetCopyPass } from ".";
+
+// Scratch color reused when re-asserting the clear color each frame.
+const CLEAR_COLOR = new Color();
+
+/**
+ * Options for CustomRenderPass
+ */
+export type CustomRenderPassOptions = {
+  debugNormal?: boolean;
+  disableShadow?: boolean;
+  allowTransparent?: boolean;
+};
+
+export class CustomRenderPass extends RenderPass {
+  protected _camera: PerspectiveCamera;
+  protected _scenes: Scenes;
+  gbufferRenderTarget: WebGLRenderTarget;
+  private copyPass: RenderTargetCopyPass;
+  globeDepthCopyPass: DepthCopyPass;
+  globeNormalCopyPass: NormalCopyPass;
+  allDepthCopyPass: AllDepthCopyPass;
+  disableShadow: boolean;
+  private globe: Globe;
+  private combinedScene = new Scene();
+  private drapedTempScene = new Scene();
+
+  // Used to render only the shadow map
+  private shadowScene = new Scene();
+  private dummyShadowRenderTarget = new WebGLRenderTarget(1, 1, {
+    depthBuffer: true,
+    stencilBuffer: false,
+  });
+
+  private debugNormalCopyPass?: NormalCopyPass;
+  private allowTransparent: boolean;
+
+  constructor(
+    scenes: Scenes,
+    camera: PerspectiveCamera,
+    inputBuffer: WebGLRenderTarget,
+    globe: Globe,
+    options?: CustomRenderPassOptions,
+  ) {
+    super();
+
+    this.needsDepthTexture = true;
+
+    this.clearPass.setClearFlags(true, true, true);
+
+    this._scenes = scenes;
+    this._camera = camera;
+    this.globe = globe;
+
+    this.gbufferRenderTarget = inputBuffer.clone();
+    // attachment 1: normal buffer
+    this.gbufferRenderTarget.textures.push(
+      this.gbufferRenderTarget.texture.clone(),
+    );
+    // attachment 2: effectIds buffer
+    // HalfFloatType preserves integer masks up to 11 bits (0..2047) exactly.
+    // NearestFilter is required because this stores discrete bitmask data.
+    const effectIdsTexture = this.gbufferRenderTarget.texture.clone();
+    effectIdsTexture.type = HalfFloatType;
+    effectIdsTexture.minFilter = NearestFilter;
+    effectIdsTexture.magFilter = NearestFilter;
+    effectIdsTexture.generateMipmaps = false;
+    this.gbufferRenderTarget.textures.push(effectIdsTexture);
+    // attachment 3: emissive buffer (RGB=diffuseColor×intensity+emissive additive, A=unused)
+    // HalfFloatType preserves HDR emissive values for bloom extraction.
+    const emissiveTexture = this.gbufferRenderTarget.texture.clone();
+    emissiveTexture.type = HalfFloatType;
+    this.gbufferRenderTarget.textures.push(emissiveTexture);
+
+    this.copyPass = new RenderTargetCopyPass(this.gbufferRenderTarget);
+
+    this.globeDepthCopyPass = new DepthCopyPass({
+      depthPacking: RGBADepthPacking,
+    });
+
+    this.allDepthCopyPass = new AllDepthCopyPass();
+
+    this.disableShadow = !!options?.disableShadow;
+    this.allowTransparent = options?.allowTransparent ?? true;
+
+    this.globeNormalCopyPass = new NormalCopyPass();
+    this.globeNormalCopyPass.setNormalTexture(
+      this.gbufferRenderTarget.textures[1],
+    );
+    if (options?.debugNormal) {
+      this.debugNormalCopyPass = new NormalCopyPass();
+      this.debugNormalCopyPass.unpackNormal = true;
+      this.debugNormalCopyPass.setNormalTexture(
+        this.gbufferRenderTarget.textures[1],
+      );
+    }
+  }
+
+  // Render the scene with world scene that includes user setting object like a light.
+  protected _renderWithLight(renderer: WebGLRenderer, scene: Scene) {
+    if (this.disableShadow) {
+      renderer.render(scene, this._camera);
+      return;
+    }
+    scene.add(this._scenes.light);
+    renderer.render(scene, this._camera);
+    scene.remove(this._scenes.light);
+  }
+
+  render(
+    renderer: WebGLRenderer,
+    inputBuffer: WebGLRenderTarget | null,
+    _outputBuffer: WebGLRenderTarget | null,
+  ) {
+    const shouldDrapeByStencilTest = this._scenes.draped.children.length !== 0;
+
+    const renderTarget = this.gbufferRenderTarget;
+
+    if (this.clearPass.enabled) {
+      this.clearPass.render(renderer, inputBuffer, null);
+    }
+
+    // Render shadow map
+    if (renderer.shadowMap.enabled && !this.disableShadow) {
+      renderer.setRenderTarget(this.dummyShadowRenderTarget);
+      this.shadowScene.add(this._scenes.globe);
+      this.shadowScene.add(this._scenes.mrt);
+      this.shadowScene.add(this._scenes.opaque);
+      renderer.shadowMap.needsUpdate = true;
+      this._renderWithLight(renderer, this.shadowScene);
+      this.shadowScene.clear();
+    }
+
+    const clearDepth =
+      !this.globe.hideUnderground ||
+      // If transparent isn't allowed, show the underground. For example, the picking process doesn't need transparency.
+      // The underground should be shown when `transparent` is true to pick the underground object.
+      (!this.allowTransparent && this.globe.transparent);
+
+    renderer.setRenderTarget(renderTarget);
+    renderer.setClearColor(
+      renderer.getClearColor(CLEAR_COLOR),
+      renderer.getClearAlpha(),
+    );
+    renderer.clear();
+
+    this._renderWithLight(renderer, this._scenes.globe);
+
+    // Set normal texture for copy pass
+    this.globeNormalCopyPass.render(renderer, null, null);
+
+    this.globeDepthCopyPass.setDepthTexture(
+      renderTarget.depthTexture as DepthTexture,
+    );
+    this.globeDepthCopyPass.render(renderer, null, null);
+
+    if (clearDepth) {
+      // Copy globe depth to the all depth buffer
+      this.allDepthCopyPass.setDepthTexture(
+        this.globeDepthCopyPass.texture,
+        RGBADepthPacking,
+      );
+      this.allDepthCopyPass.copyDepth(false);
+      this.allDepthCopyPass.render(renderer, null, null);
+    }
+
+    // Set actual renderTarget again because it's changed in copy passes
+    renderer.setRenderTarget(renderTarget);
+
+    if (clearDepth) {
+      // Clear depth if hideUnderground is false.
+      renderer.clearDepth();
+    }
+
+    const shouldBlend =
+      !clearDepth &&
+      this.allowTransparent &&
+      this.globe.transparent &&
+      this.globe.hideUnderground;
+
+    if (shouldBlend) {
+      // Clear just color for blending.
+      // Also avoid to reset depth before draping by stencil buffer.
+      renderer.clearColor();
+    }
+
+    if (shouldDrapeByStencilTest) {
+      this._renderDrapedMesh(renderer);
+    }
+
+    if (shouldBlend) {
+      // Clear depth as well after stencil buffer draping.
+      renderer.clearDepth();
+    }
+
+    // If globe can be transparent, need to render all scene in same scene to blend them.
+    // Currently, blending is supported only with MRT scene.
+    if (shouldBlend) {
+      this.combinedScene.clear();
+      this.combinedScene.add(this._scenes.globe);
+      this.combinedScene.add(this._scenes.mrt);
+      this._renderWithLight(renderer, this.combinedScene);
+    } else {
+      this._renderWithLight(renderer, this._scenes.mrt);
+    }
+
+    this.debugNormalCopyPass?.render(renderer, null, null);
+
+    const finalTarget = this.renderToScreen ? null : inputBuffer;
+
+    if (this.debugNormalCopyPass) {
+      this.copyPass.setTexture(this.debugNormalCopyPass.texture);
+    }
+    this.copyPass.render(renderer, finalTarget, null);
+
+    this._renderWithLight(renderer, this._scenes.opaque);
+
+    // Copy all depth (globe + MRT + opaque) to the all depth buffer.
+    // The renderTarget's depth texture now contains all rendered depth.
+    this.allDepthCopyPass.setDepthTexture(finalTarget?.depthTexture ?? null);
+    this.allDepthCopyPass.copyDepth(clearDepth);
+    this.allDepthCopyPass.render(renderer, null, null);
+  }
+
+  setDepthTexture(depthTexture: DepthTexture): void {
+    this.gbufferRenderTarget.depthTexture = depthTexture;
+    this.globeDepthCopyPass.setDepthTexture(depthTexture.clone());
+    this.copyPass.setDepthTexture(depthTexture);
+  }
+
+  setSize(width: number, height: number) {
+    this.gbufferRenderTarget.setSize(width, height);
+    this.globeDepthCopyPass.setSize(width, height);
+    this.allDepthCopyPass.setSize(width, height);
+    this.globeNormalCopyPass.setSize(width, height);
+    this.debugNormalCopyPass?.setSize(width, height);
+  }
+
+  // Drape a feature on the terrain by stencil test.
+  // Refs
+  // - https://www.isprs.org/proceedings/XXXVII/congress/2_pdf/5_WG-II-5/06.pdf
+  // - http://wscg.zcu.cz/WSCG2007/Papers_2007/journal/B17-full.pdf
+  protected _renderDrapedMesh(renderer: WebGLRenderer) {
+    const drapedScene = this._scenes.draped;
+    const children = [...drapedScene.children];
+
+    for (const child of children) {
+      if (!(child instanceof DrapedMesh) || !child.enabled()) continue;
+
+      drapedScene.remove(child);
+      this.drapedTempScene.add(child);
+
+      child.process(() =>
+        this._renderWithLight(renderer, this.drapedTempScene),
+      );
+
+      this.drapedTempScene.remove(child);
+      drapedScene.add(child);
+    }
+  }
+}