@navaramap/three 0.0.0

package/src/material/overrideMaterialsForMRT.ts

@@ -0,0 +1,439 @@
+// Ref: https://github.com/takram-design-engineering/three-geospatial/blob/main/packages/effects/src/setupMaterialsForGeometryPass.ts
+
+import { packing } from "@takram/three-geospatial/shaders";
+import { ShaderLib, ShaderMaterial, type ShaderLibShader } from "three";
+import { LineMaterial } from "three-stdlib";
+
+import { createReplacer } from "../utils";
+
+const SETUP = Symbol("SETUP");
+
+declare module "three" {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface ShaderLibShader {
+    [SETUP]?: boolean;
+  }
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface ShaderMaterial {
+    [SETUP]?: boolean;
+  }
+}
+
+function injectNormal(shader: ShaderLibShader): ShaderLibShader {
+  const vertexShader = createReplacer(shader.vertexShader)
+    .replace(
+      /* glsl */ `#include <fog_pars_vertex>`,
+      /* glsl */ `
+        #include <fog_pars_vertex>
+        #include <normal_pars_vertex>
+      `,
+    )
+    .replace(
+      /* glsl */ `#include <defaultnormal_vertex>`,
+      /* glsl */ `
+        #include <defaultnormal_vertex>
+        #include <normal_vertex>
+      `,
+    )
+    .replace(
+      /* glsl */ `#if defined ( USE_ENVMAP ) || defined ( USE_SKINNING )`,
+      /* glsl */ `#if 1`,
+    )
+    .replace(
+      /* glsl */ `#include <clipping_planes_vertex>`,
+      /* glsl */ `
+        #include <clipping_planes_vertex>
+        vViewPosition = - mvPosition.xyz;
+      `,
+    ).source;
+  shader.vertexShader = /* glsl */ `
+    #undef FLAT_SHADED
+    varying vec3 vViewPosition;
+    ${vertexShader}
+  `;
+
+  const fragmentShader = createReplacer(shader.fragmentShader)
+    .replace(
+      /#ifndef FLAT_SHADED\s+varying vec3 vNormal;\s+#endif/m,
+      /* glsl */ `#include <normal_pars_fragment>`,
+    )
+    .replace(
+      /* glsl */ `#include <common>`,
+      /* glsl */ `
+        #include <common>
+        #include <packing>
+      `,
+    )
+    .replace(
+      /* glsl */ `#include <specularmap_fragment>`,
+      /* glsl */ `
+        #include <specularmap_fragment>
+        #include <normal_fragment_begin>
+        #include <normal_fragment_maps>
+      `,
+    ).source;
+  shader.fragmentShader = /* glsl */ `
+    #undef FLAT_SHADED
+    varying vec3 vViewPosition;
+    ${fragmentShader}
+  `;
+
+  return shader;
+}
+
+function injectGBuffer(
+  shader: ShaderLibShader,
+  { type }: { type?: "basic" | "physical" } = {},
+): ShaderLibShader {
+  if (shader[SETUP] === true) {
+    return shader;
+  }
+  if (type === "basic") {
+    injectNormal(shader);
+  }
+  const normalBufferWrite =
+    type === "physical"
+      ? /* glsl */ `
+          normalBuffer = vec4(packNormalToVec2(normal), metalnessFactor, roughnessFactor)
+        `
+      : /* glsl */ `
+          #ifdef USE_ROUGHNESS
+            float roughnessFactor = roughness;
+          #else
+            float roughnessFactor = 0.0;
+          #endif
+          normalBuffer = vec4(packNormalToVec2(normal), reflectivity, roughnessFactor);
+        `;
+  shader.fragmentShader = /* glsl */ `
+    // MRT layout:
+    //   location 0: gl_FragColor (color)
+    //   location 1: normalBuffer (normal + material props)
+    //   location 2: effectIdBuffer (effectIds: R=bitmask)       — SelectiveEffect only
+    //   location 3: emissiveBuffer (emissive: RGB=diffuseColor×intensity+emissive additive, A=unused) — SelectiveEffect only
+    #ifndef USE_SHADOWMAP_DEPTH
+      layout(location = 1) out vec4 normalBuffer;
+      layout(location = 2) out vec4 effectIdBuffer;
+      layout(location = 3) out vec4 emissiveBuffer;
+    #endif
+
+    #if !defined(USE_ENVMAP)
+      uniform float reflectivity;
+    #endif // !defined(USE_ENVMAP)
+
+    #ifdef USE_ROUGHNESS
+      uniform float roughness;
+    #endif // USE_ROUGHNESS
+
+    #ifdef USE_SELECTIVE_EFFECT
+      uniform float uEffectIdsMask;
+      uniform float uEmissiveIntensity;
+    #endif
+
+    ${packing}
+    ${
+      createReplacer(shader.fragmentShader).replace(
+        /}\s*$/, // Assume the last curly brace is of main()
+        /* glsl */ `
+          #ifndef USE_SHADOWMAP_DEPTH
+            ${normalBufferWrite};
+
+            #ifdef USE_SELECTIVE_EFFECT
+              effectIdBuffer = vec4(uEffectIdsMask, 0.0, 0.0, 1.0);
+              emissiveBuffer = vec4(diffuseColor.rgb * uEmissiveIntensity + emissive, 1.0);
+            #else
+              effectIdBuffer = vec4(0.0);
+              emissiveBuffer = vec4(0.0);
+            #endif
+          #endif
+        }
+      `,
+      ).source
+    }
+  `;
+  shader[SETUP] = true;
+  return shader;
+}
+
+function injectGBufferToSpriteMaterial(shader: ShaderLibShader) {
+  if (shader[SETUP] === true) {
+    return shader;
+  }
+
+  shader.vertexShader = /* glsl */ `
+    varying vec3 vViewPosition;
+    ${
+      createReplacer(shader.vertexShader).replace(
+        /}\s*$/,
+        `
+        vViewPosition = -mvPosition.xyz;
+      }
+    `,
+      ).source
+    }
+  `;
+
+  shader.fragmentShader = /* glsl */ `
+    layout(location = 1) out vec4 normalBuffer;
+    layout(location = 2) out vec4 effectIdBuffer;
+    layout(location = 3) out vec4 emissiveBuffer;
+
+    #ifdef USE_SELECTIVE_EFFECT
+      uniform float uEffectIdsMask;
+    #endif
+
+    varying vec3 vViewPosition;
+
+    ${packing}
+
+    ${
+      createReplacer(shader.fragmentShader).replace(
+        /}\s*$/, // Assume the last curly brace is of main()
+        /* glsl */ `
+          // Flat shading
+          vec3 fdx = dFdx( vViewPosition );
+          vec3 fdy = dFdy( vViewPosition );
+          vec3 normal = normalize( cross( fdx, fdy ) );
+          normalBuffer = vec4(
+            packNormalToVec2(normal),
+            0.0,
+            0.0
+          );
+
+          #ifdef USE_SELECTIVE_EFFECT
+            effectIdBuffer = vec4(uEffectIdsMask, 0.0, 0.0, 1.0);
+            emissiveBuffer = vec4(0.0);
+          #else
+            effectIdBuffer = vec4(0.0);
+            emissiveBuffer = vec4(0.0);
+          #endif
+        }
+      `,
+      ).source
+    }
+  `;
+
+  shader[SETUP] = true;
+
+  return shader;
+}
+
+/**
+ * @internal
+ * Patches all built-in Three.js `ShaderLib` materials (basic, lambert, phong,
+ * standard, physical, sprite, points) so they write to the MRT G-buffer.
+ * Called automatically when `@navaramap/three` is imported — application code
+ * never needs to call this. Custom `ShaderMaterial`/`LineMaterial` do not go
+ * through `ShaderLib`, so they must opt in via {@link setupMaterialForMRT}.
+ */
+export function overrideMaterialsForMRT(): void {
+  injectGBuffer(ShaderLib.lambert);
+  injectGBuffer(ShaderLib.phong);
+  injectGBuffer(ShaderLib.basic, { type: "basic" });
+  injectGBuffer(ShaderLib.standard, { type: "physical" });
+  injectGBuffer(ShaderLib.physical, { type: "physical" });
+  injectGBufferToSpriteMaterial(ShaderLib.sprite);
+  injectGBufferToSpriteMaterial(ShaderLib.points);
+}
+
+// TODO: Use a parser to handle this.
+function injectGBufferToShaderMaterial(
+  shader: ShaderMaterial,
+  normalVariableName = "normal",
+): ShaderLibShader {
+  if (shader[SETUP] === true) {
+    return shader;
+  }
+
+  // Vertex shader
+  const common = "#include <common>";
+
+  const logdepthParsVert = "#include <logdepthbuf_pars_vertex>";
+  const logdepthVert = "#include <logdepthbuf_vertex>";
+
+  shader.vertexShader = /* glsl */ `
+    ${shader.vertexShader.includes(common) ? "" : common}
+    ${shader.vertexShader.includes(logdepthParsVert) ? "" : logdepthParsVert}
+
+    ${
+      createReplacer(shader.vertexShader).replace(
+        /}\s*$/, // Assume the last curly brace is of main()
+        /* glsl */ `
+          ${shader.vertexShader.includes(logdepthVert) ? "" : logdepthVert}
+        }
+      `,
+      ).source
+    }
+  `;
+
+  // Fragment shader
+  const logdepthParsFrag = "#include <logdepthbuf_pars_fragment>";
+  const logdepthFrag = "#include <logdepthbuf_fragment>";
+  const normalBufferWrite = /* glsl */ `
+          vec4(
+            packNormalToVec2(${normalVariableName}),
+            0.0,
+            0.0
+          );
+        `;
+  shader.fragmentShader = /* glsl */ `
+    #ifndef USE_SHADOWMAP_DEPTH
+      layout(location = 1) out vec4 normalBuffer;
+      layout(location = 2) out vec4 effectIdBuffer;
+      layout(location = 3) out vec4 emissiveBuffer;
+
+      #ifdef USE_SELECTIVE_EFFECT
+        uniform float uEffectIdsMask;
+        uniform vec3 uEmissiveColor;
+        uniform float uEmissiveIntensity;
+      #endif
+    #endif
+
+    ${packing}
+
+    ${shader.fragmentShader.includes(logdepthParsFrag) ? "" : logdepthParsFrag}
+
+    ${
+      createReplacer(shader.fragmentShader).replace(
+        /}\s*$/, // Assume the last curly brace is of main()
+        /* glsl */ `
+          ${shader.fragmentShader.includes(logdepthFrag) ? "" : logdepthFrag}
+
+          #ifndef USE_SHADOWMAP_DEPTH
+            normalBuffer = ${normalBufferWrite};
+
+            #ifdef USE_SELECTIVE_EFFECT
+              effectIdBuffer = vec4(uEffectIdsMask, 0.0, 0.0, 1.0);
+              emissiveBuffer = vec4((gl_FragColor.rgb + uEmissiveColor) * uEmissiveIntensity, 1.0);
+            #else
+              effectIdBuffer = vec4(0.0);
+              emissiveBuffer = vec4(0.0);
+            #endif
+          #endif
+        }
+      `,
+      ).source
+    }
+  `;
+
+  shader[SETUP] = true;
+
+  return shader;
+}
+
+export type SetupMaterialForMRTOptions = {
+  /**
+   * Name of the GLSL variable holding the **view-space** normal in the
+   * fragment shader (it is packed with `packNormalToVec2`, which assumes
+   * view space). Defaults to `"normal"`. Shaders that expose their normal as
+   * a `varying vec3 vNormal` should pass `{ normal: "vNormal" }`.
+   *
+   * Ignored for `LineMaterial`, which derives a screen-space normal itself.
+   */
+  normal?: string;
+};
+
+// LineMaterial MRT Support. Injects normalBuffer, effectIdBuffer, emissiveBuffer outputs.
+// When USE_SELECTIVE_EFFECT is defined, outputs effectIdsMask (emissive not supported for LineMaterial).
+function injectGBufferToLineMaterial(lineMaterial: LineMaterial) {
+  if (lineMaterial[SETUP] === true) {
+    return lineMaterial;
+  }
+
+  // Check if this is actually a LineMaterial from three-stdlib
+  if (
+    !lineMaterial.fragmentShader ||
+    !lineMaterial.fragmentShader.includes("vLineDistance")
+  ) {
+    return lineMaterial;
+  }
+
+  // LineMaterial already has proper vertex shader setup, so we only modify fragment shader
+
+  lineMaterial.fragmentShader = /* glsl */ `
+    layout(location = 1) out vec4 normalBuffer;
+    layout(location = 2) out vec4 effectIdBuffer;
+    layout(location = 3) out vec4 emissiveBuffer;
+
+    #ifdef USE_SELECTIVE_EFFECT
+      uniform float uEffectIdsMask;
+    #endif
+
+    ${packing}
+
+    ${
+      createReplacer(lineMaterial.fragmentShader)
+        .replace(
+          "void main() {",
+          /* glsl */ `
+          void main() {
+            // Calculate screen-space normal for Line2 MRT compatibility
+            vec3 fdx = dFdx(gl_FragCoord.xyz);
+            vec3 fdy = dFdy(gl_FragCoord.xyz);
+            vec3 normal = normalize(cross(fdx, fdy));
+
+            // Ensure normal faces camera (positive Z in screen space)
+            if (normal.z < 0.0) normal = -normal;
+        `,
+        )
+        .replace(
+          /}\s*$/, // Assume the last curly brace is of main()
+          /* glsl */ `
+          normalBuffer = vec4(
+            packNormalToVec2(normal),
+            0.0,
+            0.0
+          );
+
+          #ifdef USE_SELECTIVE_EFFECT
+            effectIdBuffer = vec4(uEffectIdsMask, 0.0, 0.0, 1.0);
+            emissiveBuffer = vec4(0.0);
+          #else
+            effectIdBuffer = vec4(0.0);
+            emissiveBuffer = vec4(0.0);
+          #endif
+        }
+      `,
+        ).source
+    }
+  `;
+
+  lineMaterial[SETUP] = true;
+
+  return lineMaterial;
+}
+
+/**
+ * Wire a custom material into Navara's MRT G-buffer so depth/normal-based
+ * effects (SSAO, SSR, outline, aerial perspective, clouds) and SelectiveEffect
+ * (Bloom/Outline) work on the mesh that uses it.
+ *
+ * Built-in Three.js materials (`MeshStandardMaterial`, `MeshBasicMaterial`,
+ * `Sprite`, `Points`, …) are patched automatically on import and do **not**
+ * need this. Only custom `ShaderMaterial` and three-stdlib `LineMaterial`
+ * bypass `ShaderLib`, so they must opt in here.
+ *
+ * `LineMaterial` is detected and routed automatically; the `normal` option is
+ * only used for plain `ShaderMaterial`.
+ *
+ * Injects `normalBuffer` (location 1), `effectIdBuffer` (location 2), and
+ * `emissiveBuffer` (location 3). For `ShaderMaterial` it also injects the
+ * `logdepthbuf` modules; `LineMaterial` already has its own vertex setup, so
+ * those are not added. When `USE_SELECTIVE_EFFECT` is defined,
+ * `effectIdBuffer`/`emissiveBuffer` are populated (emissive is unsupported for
+ * `LineMaterial`). Idempotent — calling it more than once on the same material
+ * is a no-op.
+ *
+ * Requirements for `ShaderMaterial`: the fragment shader must expose a
+ * view-space normal (named by `options.normal`, default `"normal"`), and the
+ * last `}` in each shader is assumed to close `main()`.
+ */
+export function setupMaterialForMRT(
+  material: ShaderMaterial,
+  options?: SetupMaterialForMRTOptions,
+): void {
+  if (material instanceof LineMaterial) {
+    injectGBufferToLineMaterial(material);
+    return;
+  }
+  injectGBufferToShaderMaterial(material, options?.normal);
+}

package/src/material/selectiveEffectMaterialSetup.test.ts

@@ -0,0 +1,52 @@
+import { MeshLambertMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { setupSelectiveEffectUniforms } from "./selectiveEffectMaterialSetup";
+
+describe("setupSelectiveEffectUniforms", () => {
+  it("should link uEmissiveIntensity that auto-syncs with material.emissiveIntensity", () => {
+    const material = new MeshLambertMaterial();
+    material.emissiveIntensity = 0.5;
+    setupSelectiveEffectUniforms(material);
+
+    // Initial value should match material.emissiveIntensity
+    expect(material.userData.uEmissiveIntensity.value).toBe(0.5);
+
+    // Changing material.emissiveIntensity should be reflected via getter
+    material.emissiveIntensity = 0.8;
+    expect(material.userData.uEmissiveIntensity.value).toBe(0.8);
+  });
+
+  it("should link uEffectIdsMask uniform", () => {
+    const material = new MeshLambertMaterial();
+    setupSelectiveEffectUniforms(material);
+
+    expect(material.userData.uEffectIdsMask).toBeDefined();
+    expect(material.userData.uEffectIdsMask.value).toBe(0);
+  });
+
+  it("should set USE_SELECTIVE_EFFECT define", () => {
+    const material = new MeshLambertMaterial();
+    setupSelectiveEffectUniforms(material);
+
+    expect(material.defines?.USE_SELECTIVE_EFFECT).toBe(1);
+  });
+
+  it("should include SelectiveEffect in program cache key", () => {
+    const material = new MeshLambertMaterial();
+    setupSelectiveEffectUniforms(material);
+
+    const cacheKey = material.customProgramCacheKey();
+    expect(cacheKey).toContain("SelectiveEffect");
+  });
+
+  it("should be idempotent — second call is a no-op", () => {
+    const material = new MeshLambertMaterial();
+    setupSelectiveEffectUniforms(material);
+
+    const firstRef = material.userData.uEffectIdsMask;
+    setupSelectiveEffectUniforms(material);
+
+    expect(material.userData.uEffectIdsMask).toBe(firstRef);
+  });
+});

package/src/material/selectiveEffectMaterialSetup.ts

@@ -0,0 +1,53 @@
+import type { MeshLambertMaterial, MeshStandardMaterial } from "three";
+
+const SELECTIVE_EFFECT_SETUP = Symbol("SELECTIVE_EFFECT_SETUP");
+
+/**
+ * Set up Selective Effect defines and uniforms on a standard Three.js material.
+ * Sets USE_SELECTIVE_EFFECT define so the MRT shader writes effectIds + emissive.
+ * Emissive output uses additive blend: diffuseColor × emissiveIntensity + emissive.
+ * Used by non-enhancer meshes (Box, Sphere, etc.).
+ *
+ * Idempotent — calling multiple times on the same material is safe (no-op after first call).
+ */
+export function setupSelectiveEffectUniforms(
+  material: MeshLambertMaterial | MeshStandardMaterial,
+): void {
+  // Guard: only set up once per material
+  if ((material as unknown as Record<symbol, boolean>)[SELECTIVE_EFFECT_SETUP])
+    return;
+  (material as unknown as Record<symbol, boolean>)[SELECTIVE_EFFECT_SETUP] =
+    true;
+
+  material.userData.uEffectIdsMask = { value: 0 };
+  // Getter-based uniform: auto-syncs with material.emissiveIntensity without manual updates
+  material.userData.uEmissiveIntensity = {
+    get value() {
+      return material.emissiveIntensity;
+    },
+  };
+
+  // Set define on material.defines so Three.js includes it in program cache key.
+  // This ensures SelectiveEffect and non-SelectiveEffect materials get separate compiled programs.
+  material.defines = material.defines ?? {};
+  material.defines.USE_SELECTIVE_EFFECT = 1;
+
+  // Include SelectiveEffect token in program cache key to prevent program sharing
+  const prevCacheKey = material.customProgramCacheKey;
+  material.customProgramCacheKey = () => {
+    const base = prevCacheKey ? prevCacheKey.call(material) : "";
+    return `${base}_SelectiveEffect`;
+  };
+
+  const prevOnBeforeCompile = material.onBeforeCompile;
+  material.onBeforeCompile = (shader, renderer) => {
+    prevOnBeforeCompile?.call(material, shader, renderer);
+
+    // Link SelectiveEffect uniforms for runtime value updates
+    shader.uniforms.uEffectIdsMask = material.userData.uEffectIdsMask;
+    shader.uniforms.uEmissiveIntensity = material.userData.uEmissiveIntensity;
+  };
+
+  // Force recompile if the material was already rendered with the old program
+  material.needsUpdate = true;
+}

package/src/material/types/index.ts

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

package/src/material/types/uniform.ts

@@ -0,0 +1 @@
+export type UniformValue<T> = { value: T };

package/src/mesh/DrapedMesh.ts

@@ -0,0 +1,101 @@
+import {
+  AlwaysStencilFunc,
+  BackSide,
+  DecrementWrapStencilOp,
+  FrontSide,
+  IncrementWrapStencilOp,
+  KeepStencilOp,
+  Mesh,
+  NotEqualStencilFunc,
+  ZeroStencilOp,
+  type BufferGeometry,
+  type Material,
+  type NormalBufferAttributes,
+  type Object3DEventMap,
+} from "three";
+
+export class DrapedMesh<
+  TGeometry extends BufferGeometry = BufferGeometry<NormalBufferAttributes>,
+  TMaterial extends Material | Material[] = Material | Material[],
+  TEventMap extends Object3DEventMap = Object3DEventMap,
+> extends Mesh<TGeometry, TMaterial, TEventMap> {
+  drapedEnable: boolean;
+
+  constructor(geometry?: TGeometry, material?: TMaterial, enable = true) {
+    super(geometry, material);
+    this.drapedEnable = enable;
+  }
+
+  enabled() {
+    return this.drapedEnable && this.visible;
+  }
+
+  /**
+   * Run the stencil-test draping passes for this mesh.
+   * The caller supplies a `render` callback that performs the actual draw call
+   * (e.g. `renderer.render(scene, camera)`).
+   */
+  process(render: () => void): void {
+    if (!this.enabled()) return;
+
+    const run = (m: Material) => {
+      // Save original material state
+      const origStencilFunc = m.stencilFunc;
+      const origStencilFail = m.stencilFail;
+      const origStencilZPass = m.stencilZPass;
+      const origStencilZFail = m.stencilZFail;
+      const origSide = m.side;
+      const origColorWrite = m.colorWrite;
+      const origDepthWrite = m.depthWrite;
+      const origStencilWrite = m.stencilWrite;
+      const origDepthTest = m.depthTest;
+
+      // Back face pass
+      m.stencilFunc = AlwaysStencilFunc;
+      m.stencilFail = KeepStencilOp;
+      m.stencilZPass = KeepStencilOp;
+      m.stencilZFail = IncrementWrapStencilOp;
+      m.side = BackSide;
+      m.colorWrite = false;
+      m.depthWrite = false;
+      m.stencilWrite = true;
+      m.depthTest = true;
+
+      render();
+
+      // Front face pass
+      m.side = FrontSide;
+      m.stencilZFail = DecrementWrapStencilOp;
+
+      render();
+
+      // Final pass
+      m.stencilFunc = NotEqualStencilFunc;
+      m.stencilFail = ZeroStencilOp;
+      m.stencilZFail = ZeroStencilOp;
+      m.stencilZPass = ZeroStencilOp;
+      m.side = BackSide;
+      m.colorWrite = true;
+      m.depthTest = false;
+
+      render();
+
+      // Restore original material state
+      m.stencilFunc = origStencilFunc;
+      m.stencilFail = origStencilFail;
+      m.stencilZPass = origStencilZPass;
+      m.stencilZFail = origStencilZFail;
+      m.side = origSide;
+      m.colorWrite = origColorWrite;
+      m.depthWrite = origDepthWrite;
+      m.stencilWrite = origStencilWrite;
+      m.depthTest = origDepthTest;
+    };
+
+    if (Array.isArray(this.material)) {
+      this.material.map(run);
+    } else {
+      run(this.material);
+    }
+  }
+}