@navaramap/three 0.0.0

package/src/material/enhancer/tileComposite/types.ts

@@ -0,0 +1,58 @@
+import type { Texture } from "three";
+
+import type {
+  CompositeGlobals,
+  CompositeLayer,
+} from "../../../tileTexture/types";
+
+import type {
+  CompositeShaderContributions,
+  CompositeSlotContext,
+  CompositeUniformTarget,
+} from "./tileCompositeBaseEnhancer";
+
+/**
+ * A composite layer enhancer owns one expression's contribution to the
+ * offscreen composite pass — both its GLSL fragments and its uniforms. The
+ * factory returns `undefined` when the expression is inactive, so the composed
+ * chain contains only active enhancers and the composer just concatenates what
+ * each one provides. Adding a new expression is a new enhancer module + one
+ * entry in `createCompositeLayerEnhancers`.
+ *
+ * Every hook is optional; an enhancer exposes only the ones it participates in.
+ */
+export type CompositeLayerEnhancer = {
+  /** Per-slot uniform declarations (sized at numTextures). */
+  slotUniformDecls?: (numTextures: number) => string;
+  /** Slot-independent uniform declarations. */
+  globalUniformDecls?: () => string;
+  /** GLSL chunks inlined before `main()`. */
+  includes?: () => string;
+  /** Overrides the per-slot sampler (only the active overrider sets it). */
+  sampleProducer?: CompositeShaderContributions["sampleProducer"];
+  /** Additive transform on `texColor${k}` after sampling. */
+  perSlotPostSample?: (ctx: CompositeSlotContext) => string;
+  /** Additive attr update when a slot wins the alpha-over blend. */
+  perSlotOnWinner?: (ctx: CompositeSlotContext) => string;
+  /** GLSL injected after the slot loop. */
+  postLoop?: (numTextures: number) => string;
+
+  // --- material defines + uniform ownership (active enhancers only) ---
+  /** Shader defines this enhancer needs (e.g. USE_ELEVATION_HEATMAP). */
+  defines?: Record<string, number>;
+  /**
+   * Create this enhancer's uniform refs (sized at numTextures) and assign them
+   * into the composite material's uniform dict. Refs are held in closure so
+   * `bindSlot`/`bindGlobal` mutate the same objects three.js owns. Defined only
+   * when the enhancer is active.
+   */
+  attachUniforms?: (
+    target: CompositeUniformTarget,
+    numTextures: number,
+    placeholder: Texture,
+  ) => void;
+  /** Sync per-slot refs from the layer occupying compact slot `compactSlot`. */
+  bindSlot?: (compactSlot: number, layer: CompositeLayer | undefined) => void;
+  /** Sync slot-independent refs from the tile globals. */
+  bindGlobal?: (globals: CompositeGlobals) => void;
+};

package/src/material/index.ts

@@ -0,0 +1,3 @@
+export * from "./enhancer";
+export * from "./macro";
+export * from "./overrideMaterialsForMRT";

package/src/material/macro/index.ts

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

package/src/material/macro/tileShader.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  generateTileCommonInjection,
+  generateTileMapFragment,
+  generateTileNormalFragmentMaps,
+  TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT,
+  TILE_NORMAL_BUFFER_REPLACEMENT,
+  TILE_PICK_FRAGMENT_OVERRIDE,
+} from "./tileShader";
+
+describe("generateTileCommonInjection", () => {
+  it("declares the three atlas samplers", () => {
+    const src = generateTileCommonInjection(8);
+    expect(src).toContain("uniform sampler2D uColorAtlas;");
+    expect(src).toContain("uniform sampler2D uAttrAtlas;");
+    expect(src).toContain("uniform sampler2D uNormalAtlas;");
+  });
+
+  it("sizes per-slot uniform arrays to the requested slot count", () => {
+    const src = generateTileCommonInjection(16);
+    expect(src).toContain("uniform float uShininesses[16];");
+    expect(src).toContain("uniform vec3 uEmissiveColors[16];");
+    expect(src).toContain("uniform float uEffectIdsMasks[16];");
+  });
+});
+
+describe("generateTileMapFragment", () => {
+  const src = generateTileMapFragment(16);
+
+  it("samples each atlas exactly once", () => {
+    const colorMatches = src.match(/texture2D\(uColorAtlas/g) ?? [];
+    const attrMatches = src.match(/texture2D\(uAttrAtlas/g) ?? [];
+    expect(colorMatches.length).toBe(1);
+    expect(attrMatches.length).toBe(1);
+  });
+
+  it("decodes winning slot from attr.a as (n*255) - 1", () => {
+    expect(src).toContain("int winIdx = int(round(atlasAttr.a * 255.0)) - 1;");
+  });
+
+  it("masks colour by attr.g and snapshots into nvr_pickColor on picking pass", () => {
+    // Raster pixels contribute 0 (no entity); vector pixels keep the pick
+    // ID written into atlasColor by the per-layer RT pass. We snapshot the
+    // masked value BEFORE the diffuse merge so the dithering-stage override
+    // writes it straight to gl_FragColor without lighting/tonemapping/fog
+    // corruption.
+    expect(src).toContain("if (uPickable > 0.)");
+    expect(src).toContain("atlasColor.rgb *= atlasAttr.g;");
+    expect(src).toContain("vec3 nvr_pickColor = atlasColor.rgb;");
+  });
+
+  it("indexes per-slot uniforms with winIdx (no loop)", () => {
+    expect(src).toContain("uShininesses[winIdx]");
+    expect(src).toContain("uReflectivities[winIdx]");
+    // Should not loop over slots — the dynamic index is the whole point.
+    expect(src).not.toMatch(/for\s*\(/);
+  });
+
+  it("uses premultiplied 'over' blend so transparent atlas keeps base color", () => {
+    // src.rgb + dst * (1 - src.a) — NOT mix(dst, src.rgb, src.a). Mixing
+    // would double-apply alpha because the composite already premultiplies.
+    expect(src).toContain(
+      "diffuseColor.rgb = atlasColor.rgb + diffuseColor.rgb * (1.0 - atlasColor.a);",
+    );
+    expect(src).not.toMatch(/mix\(diffuseColor\.rgb,\s*atlasColor\.rgb/);
+  });
+});
+
+describe("generateTileNormalFragmentMaps", () => {
+  it("omits the hillshade lookup entirely when hasHillshade is off", () => {
+    const src = generateTileNormalFragmentMaps({
+      hasHillshade: false,
+      hasWater: false,
+    });
+    expect(src).not.toContain("uNormalAtlas");
+    expect(src).not.toContain("TBN");
+  });
+
+  it("samples uNormalAtlas exactly once when hasHillshade is on", () => {
+    const src = generateTileNormalFragmentMaps({
+      hasHillshade: true,
+      hasWater: false,
+    });
+    const matches = src.match(/texture2D\(uNormalAtlas/g) ?? [];
+    expect(matches.length).toBe(1);
+    expect(src).toContain("atlasNormalSample.a > 0.5");
+    expect(src).toContain("uHillshadeExaggeration");
+  });
+
+  it("omits water specular call when hasWater is off", () => {
+    const src = generateTileNormalFragmentMaps({
+      hasHillshade: false,
+      hasWater: false,
+    });
+    expect(src).not.toContain("computeWaterSpecular");
+    expect(src).toContain("computeSpecular(");
+  });
+
+  it("emits computeWaterSpecular when hasWater is on", () => {
+    const src = generateTileNormalFragmentMaps({
+      hasHillshade: false,
+      hasWater: true,
+    });
+    expect(src).toContain("computeWaterSpecular(");
+  });
+});
+
+describe("MRT buffer replacements", () => {
+  it("writes finalNormal into normalBuffer with reflectivity/roughness packed", () => {
+    expect(TILE_NORMAL_BUFFER_REPLACEMENT).toContain("normalBuffer = vec4(");
+    expect(TILE_NORMAL_BUFFER_REPLACEMENT).toContain("tileReflectivity");
+    expect(TILE_NORMAL_BUFFER_REPLACEMENT).toContain("tileRoughness");
+  });
+
+  it("gates emissive/effect on isTexturizedLayer", () => {
+    expect(TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT).toContain(
+      "if (isTexturizedLayer)",
+    );
+    expect(TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT).toContain(
+      "effectIdBuffer = vec4(0.0);",
+    );
+  });
+
+  it("pick override writes nvr_pickColor straight to gl_FragColor", () => {
+    // Output is the LAST write of the fragment shader so envmap/tonemapping/
+    // colorspace/fog can't pollute the pick buffer with lit colours. The
+    // value comes from the attr.g-masked atlas (see generateTileMapFragment)
+    // — raster pixels become batchId=0 (no entity); vector pixels carry the
+    // ID their own per-layer enhancer wrote during the per-layer RT pass.
+    expect(TILE_PICK_FRAGMENT_OVERRIDE).toContain("if (uPickable > 0.)");
+    expect(TILE_PICK_FRAGMENT_OVERRIDE).toContain(
+      "gl_FragColor = vec4(nvr_pickColor, 1.0);",
+    );
+  });
+});

package/src/material/macro/tileShader.ts

@@ -0,0 +1,287 @@
+/**
+ * Slim TileMesh fragment-shader fragments.
+ *
+ * The TileMesh main pass used to unroll an N-slot texture loop per fragment
+ * (`generateMixOverlaidTexturesMacro`). That cost N TMU fetches × screen
+ * pixels every frame, plus another N iterations for `generateHillshadeNormal`.
+ *
+ * After the refactor, TileTextureCompositor bakes all N source textures into
+ * a per-tile MRT atlas (color + attr + normal) only when something is dirty.
+ * The main pass then does **at most three** texture lookups per fragment and
+ * uses the attr atlas's encoded winning-slot index to dynamically index the
+ * per-slot uniform arrays for shininess/specular/emissive/effect/etc.
+ *
+ * Each function returns a snippet that's spliced into a chunk via the
+ * existing `createReplacer` machinery in mesh/tile.ts.
+ */
+
+export type TileShaderFeatures = {
+  /** Atlas has a hillshade normal that should override the default normal. */
+  hasHillshade: boolean;
+  /** Some layer uses Water material → emit the water specular branch. */
+  hasWater: boolean;
+};
+
+/**
+ * Goes after `#include <common>` in the fragment shader. Declares the three
+ * atlas samplers + the per-slot uniform arrays we still index by winning
+ * slot. Adds varying for the original UV.
+ */
+export function generateTileCommonInjection(numTextures: number): string {
+  return `
+  uniform sampler2D uColorAtlas;
+  uniform sampler2D uAttrAtlas;
+  uniform sampler2D uNormalAtlas;
+
+  // Per-slot uniforms retained because they need full float precision and are
+  // indexed once per fragment by the winning slot from attr.a.
+  uniform vec3 uColors[${numTextures}];
+  uniform float uReflectivities[${numTextures}];
+  uniform float uRoughnesses[${numTextures}];
+  uniform float uWaterScaleNormals[${numTextures}];
+  uniform float uWaterSpeeds[${numTextures}];
+  uniform float uShininesses[${numTextures}];
+  uniform float uSpecularStrengths[${numTextures}];
+  uniform float uApplyWaterNormals[${numTextures}];
+  uniform bool uSpeculars[${numTextures}];
+  uniform float uEmissiveIntensities[${numTextures}];
+  uniform vec3 uEmissiveColors[${numTextures}];
+  uniform float uEffectIdsMasks[${numTextures}];
+
+  uniform sampler2D uWaterNormalMap;
+  uniform float uHillshadeExaggeration;
+  uniform float uPickable;
+  uniform float uIor;
+  uniform float uTime;
+
+  varying vec2 vOrigUv;
+  // vPosition is declared by WaterParsFragment when useNormal=true; for the
+  // Basic-material path no fragment-side code reads it, so omitting the
+  // declaration here avoids a redefinition error when both are present.
+  `;
+}
+
+/**
+ * Goes in place of `#include <map_fragment>`. Reads the three atlas textures
+ * once, decodes the winning slot index, and (when present) pulls per-slot
+ * precision-sensitive attrs by dynamic indexing. Picking suppresses the
+ * raster contribution by masking colour with the attr's isTexturized flag.
+ *
+ * `texturizedSceneIndexFrom` is captured at material-build time (used by
+ * generateTileEmissiveBuffer below to decide what gets written to the
+ * emissive/effect MRT attachments).
+ */
+export function generateTileMapFragment(maxTextures: number): string {
+  return `
+  vec4 atlasColor = texture2D(uColorAtlas, vOrigUv);
+  vec4 atlasAttr  = texture2D(uAttrAtlas,  vOrigUv);
+
+  // attr.a encodes (winningSlot + 1) / 255 — 0 means no contributing slot.
+  int winIdx = int(round(atlasAttr.a * 255.0)) - 1;
+  // Bound + clamp the decoded index to the valid uniform-array range. A tile drawn
+  // BEFORE its composite atlas is initialized samples an undefined attr.a that can
+  // decode to an out-of-range winIdx. An out-of-bounds DYNAMIC array index
+  // is undefined behavior that HANGS the Apple/iOS GPU with no WebGL error —
+  bool hasWinner = winIdx >= 0 && winIdx < ${maxTextures};
+  winIdx = clamp(winIdx, 0, ${maxTextures - 1});
+
+  // Picking: only vector (texturized) layers carry a pickable entity.
+  // attr.g is 1.0 on a vector pixel, 0.0 on a raster pixel — masking by
+  // attr.g zeroes raster contribution and leaves the vector mesh's own
+  // pick-shader output (composited into atlasColor via the per-layer RT
+  // path) untouched. We snapshot the masked colour BEFORE the diffuse
+  // merge so the final gl_FragColor override (after dithering_fragment)
+  // can write the encoded batchId straight through, bypassing envmap,
+  // tonemapping, colorspace, and fog — all of which would corrupt the ID.
+  if (uPickable > 0.) {
+    atlasColor.rgb *= atlasAttr.g;
+  }
+  vec3 nvr_pickColor = atlasColor.rgb;
+
+  // atlasColor is premultiplied: the composite pass accumulates with
+  //   acc = mix(acc, vec4(rgb, 1.0), alpha)
+  // which gives acc.rgb = rgb*alpha + prev*(1-alpha) and acc.a tracks total
+  // coverage. The "over" operator for a premultiplied source is
+  //   out = src.rgb + dst * (1 - src.a)
+  // — this preserves the globe's base colour where no layer wrote (atlas.a=0)
+  // and matches the legacy per-slot mix(diffuse, color, alpha) semantics
+  // exactly (verified algebraically for 1 and 2 stacked layers).
+
+  bool useWater = atlasAttr.r > 0.5;
+  bool isTexturizedLayer = atlasAttr.g > 0.5;
+
+  // Per-slot uniforms indexed by the winner. Dynamic indexing of non-sampler
+  // arrays is well-defined in GLSL ES 3.00. Fallbacks keep the default
+  // lighting reasonable for fully-transparent pixels.
+  float tileReflectivity      = hasWinner ? uReflectivities[winIdx]      : 0.0;
+  float tileRoughness         = hasWinner ? uRoughnesses[winIdx]         : 0.0;
+
+  // TODO: Support water material
+  float waterScaleNormal      = hasWinner ? uWaterScaleNormals[winIdx]   : 0.0;
+  float waterSpeed            = hasWinner ? uWaterSpeeds[winIdx]         : 0.0;
+  // Per-slot water specular params only exist for vector (texturized) water
+  // layers. When useWater comes from the tile-wide quantized-mesh watermask
+  // instead, the winning slot is a raster imagery layer (attr.g == 0) that
+  // carries no water params — so fall back to the default water appearance,
+  // the same one the no-winner open-ocean path uses. Without this a raster tile
+  // draped over a watermask would index the raster slot's zeroed params and the
+  // water glint would vanish under the imagery.
+  bool hasSlotWaterParams     = hasWinner && isTexturizedLayer;
+  float waterShininess        = hasSlotWaterParams ? uShininesses[winIdx]       : 50.0;
+  float waterSpecularStrength = hasSlotWaterParams ? uSpecularStrengths[winIdx]  : 1.0;
+  float applyWaterNormals     = hasWinner ? uApplyWaterNormals[winIdx]   : 0.0;
+  // The watermask flags water independently of which slot wins the blend, so its
+  // specular must survive a (non-water) raster winner. OR it in rather than
+  // letting the winner's own specular flag gate it — otherwise a draped raster
+  // imagery slot (uSpeculars == false) suppresses the watermask water entirely.
+  bool  useSpecular           = (!isTexturizedLayer && useWater) || (hasWinner && uSpeculars[winIdx]);
+
+  float tileEmissiveIntensity = (hasWinner && isTexturizedLayer) ? uEmissiveIntensities[winIdx] : 0.0;
+  vec3  tileEmissiveColor     = (hasWinner && isTexturizedLayer) ? uEmissiveColors[winIdx]      : vec3(0.0);
+  float tileEffectIdsMask     = (hasWinner && isTexturizedLayer) ? uEffectIdsMasks[winIdx]      : 0.0;
+
+  diffuseColor.rgb = atlasColor.rgb + diffuseColor.rgb * (1.0 - atlasColor.a);
+  `;
+}
+
+/**
+ * Goes in place of `#include <normal_fragment_maps>`. When the atlas carries
+ * a hillshade normal, transform it tangent→view via TBN like the legacy
+ * unrolled loop did, but with a single normal-atlas read. Then optionally
+ * compute water/specular contribution.
+ */
+export function generateTileNormalFragmentMaps(
+  features: TileShaderFeatures,
+): string {
+  const hillshadeBlock = features.hasHillshade
+    ? `
+    // attr-atlas normal: .a flags whether a hillshade slot won this pixel.
+    vec4 atlasNormalSample = texture2D(uNormalAtlas, vOrigUv);
+    if (atlasNormalSample.a > 0.5) {
+      vec3 demNormal = atlasNormalSample.rgb * 2.0 - 1.0;
+      demNormal = normalize(demNormal);
+      demNormal.xy *= uHillshadeExaggeration;
+      demNormal = normalize(demNormal);
+
+      // Build tangent-space basis from the geometric normal (= N).
+      vec3 up = vec3(0.0, 0.0, 1.0);
+      vec3 T = normalize(cross(up, N));
+      if (length(T) < 0.001) T = vec3(1.0, 0.0, 0.0); // pole fallback
+      vec3 B = normalize(cross(N, T));
+      mat3 TBN = mat3(T, B, N);
+
+      vec3 worldDemNormal = normalize(TBN * demNormal);
+      normal = normalize(mat3(viewMatrix) * worldDemNormal);
+    }
+    `
+    : "";
+
+  const waterBlock = features.hasWater
+    ? `
+    if (useSpecular) {
+      specular = computeSpecular(
+        vViewPosition,
+        origNormal,
+        waterShininess,
+        waterSpecularStrength,
+        uIor
+      );
+    } else if (useWater) {
+      specular = computeWaterSpecular(
+        uWaterNormalMap,
+        (vPosition.xy + vPosition.zy + vPosition.xz) / 3.0 * waterScaleNormal,
+        uTime * waterSpeed,
+        vViewPosition,
+        normalMatrix,
+        origNormal,
+        waterShininess,
+        waterSpecularStrength,
+        diffuseColor.rgb,
+        normal
+      );
+    }
+    `
+    : `
+    if (useSpecular) {
+      specular = computeSpecular(
+        vViewPosition,
+        origNormal,
+        waterShininess,
+        waterSpecularStrength,
+        uIor
+      );
+    }
+    `;
+
+  return `
+  #if USE_VERTEX_NORMAL && !USE_HILLSHADE
+    // Keep the interpolated per-vertex normal (already in view space via three.js).
+  #else
+    vec3 N = normalize(vPosition);
+    normal = normalize(mat3(viewMatrix) * N);
+  #endif
+  ${hillshadeBlock}
+  vec3 origNormal = vec3(normal);
+  vec3 specular = vec3(0.0);
+  ${waterBlock}
+  `;
+}
+
+/**
+ * `normalBuffer = …` replacement for the MRT pass. Identical to legacy
+ * behaviour: applyWaterNormals mixes the perturbed normal into the geometric
+ * one before packing.
+ */
+export const TILE_NORMAL_BUFFER_REPLACEMENT = `
+vec3 finalNormal = mix(origNormal, normalize(origNormal * 0.7 + normal), applyWaterNormals);
+normalBuffer = vec4(packNormalToVec2(finalNormal), tileReflectivity, tileRoughness);
+`;
+
+/**
+ * `effectIdBuffer = …; emissiveBuffer = …;` replacement. Only the
+ * texturized-layer pixels write effect/emissive; raster pixels stay 0 so they
+ * don't perturb downstream effect-mask passes.
+ */
+export const TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT = `
+if (isTexturizedLayer) {
+  effectIdBuffer = vec4(tileEffectIdsMask, 0.0, 0.0, 1.0);
+  emissiveBuffer = vec4(diffuseColor.rgb * tileEmissiveIntensity + tileEmissiveColor, 1.0);
+} else {
+  effectIdBuffer = vec4(0.0);
+  emissiveBuffer = vec4(0.0);
+}
+`;
+
+/**
+ * Final-stage pick override. Injected immediately AFTER
+ * `#include <dithering_fragment>` (the last chunk in MeshLambert/Basic main()),
+ * so the assignment to `gl_FragColor` is the last write of the fragment shader
+ * — bypassing envmap, tonemapping, colorspace, and fog, all of which would
+ * otherwise corrupt the encoded batchId.
+ *
+ * Draped vector meshes stay in their TileScene during the pick pass (see
+ * PickHelper's TileScene guard) and render their own pick IDs into the
+ * per-layer RT in pick mode. The composite atlas then carries those IDs
+ * forward; here we write them straight through, masked by attr.g so raster
+ * pixels contribute batchId=0 (no entity) instead of polluting the pick
+ * buffer. `nvr_pickColor` is set up by `generateTileMapFragment`.
+ */
+export const TILE_PICK_FRAGMENT_OVERRIDE = `
+if (uPickable > 0.) {
+  gl_FragColor = vec4(nvr_pickColor, 1.0);
+}
+`;
+
+/** Vertex-shader injection: passes UV and world-space position through. */
+export const TILE_VERTEX_INJECTIONS = {
+  afterCommon: `
+varying vec2 vOrigUv;
+varying vec3 vPosition;
+`,
+  afterUvVertex: `
+vOrigUv = vUv;
+`,
+  afterEnvmapVertex: `
+vPosition = (modelMatrix * vec4(transformed, 1.0)).xyz;
+`,
+};