@navaramap/three 0.0.5 → 0.0.6

package/src/material/gbufferLayout.ts

@@ -0,0 +1,298 @@
+import GBufferParsFragmentChunk from "@shaders/glsl/chunks/gbuffer_pars_fragment.glsl";
+import {
+  HalfFloatType,
+  NearestFilter,
+  UnsignedByteType,
+  type WebGLRenderTarget,
+} from "three";
+
+/**
+ * TS side of the screen G-buffer (MRT) layout. Everything that touches the
+ * layout goes through this module so a change stays a single-file edit; the
+ * GLSL mirror is `shaders/glsl/chunks/gbuffer_pars_fragment.glsl`.
+ */
+
+/** The only attachment that always exists. The rest are packed after it. */
+export const GBUFFER_TEXTURE_INDEX = {
+  color: 0,
+} as const;
+
+/** Names an effect can declare in `requiredBuffers`. */
+export type GBufferName =
+  "normal" | "selectiveEffect" | "emissive" | "shadow" | "globeNormal";
+
+/**
+ * The subset backed by an MRT attachment. `globeNormal` is not one of them —
+ * it is a separate copy target — so it must not take an attachment slot, a
+ * `*_LOCATION` define, or a `MAX_DRAW_BUFFERS` slot.
+ */
+export const GBUFFER_ATTACHMENT_NAMES = [
+  "normal",
+  "selectiveEffect",
+  "emissive",
+  "shadow",
+] as const satisfies readonly GBufferName[];
+
+/**
+ * Per-view buffer configuration. Not set by the user - derived as the union
+ * of the active effects' `requiredBuffers`. A disabled buffer costs nothing:
+ * neither the storage nor the shader-side writes exist. Only
+ * {@link GBUFFER_ATTACHMENT_NAMES} are MRT attachments.
+ */
+export type GBufferOptions = {
+  /**
+   * The view-space normal buffer (RG=octahedral normal, B=metalness or
+   * reflectivity, A=roughness *and* the blend factor). Required by every
+   * normal-reading effect (aerial perspective, SSR, fog light) and, via
+   * {@link globeNormal}, by draped meshes.
+   */
+  normal?: boolean;
+  /**
+   * The selective-effect id buffer (R=bitmask), required by buffer-based
+   * selective effects (`selectiveBloom`, `selectiveOutline`).
+   */
+  selectiveEffect?: boolean;
+  /**
+   * The HDR emissive buffer (RGB=emissive), required by `selectiveBloom`
+   * extraction.
+   */
+  emissive?: boolean;
+  /**
+   * The shadow buffer (R=directional/CSM shadow amount, 0=lit,
+   * 1=fully shadowed). No built-in effect requires it – declare it from a
+   * custom effect's `requiredBuffers` to read per-pixel shadowing.
+   */
+  shadow?: boolean;
+  /**
+   * The globe normal copy (the terrain's view-space normal, sampled in screen
+   * space). Kept at 1x1 unless a draped mesh needs it, so an effect reading
+   * `getGlobeNormalTexture()` has to declare it.
+   */
+  globeNormal?: boolean;
+};
+
+/** {@link GBufferOptions} with defaults applied. */
+export type ResolvedGBufferOptions = Readonly<Required<GBufferOptions>>;
+
+/** Applies defaults (all disabled) to a partial configuration. */
+export function resolveGBufferOptions(
+  options?: GBufferOptions,
+): ResolvedGBufferOptions {
+  const globeNormal = options?.globeNormal ?? false;
+  return {
+    // The globe normal is a copy of the normal attachment, so it cannot be
+    // produced without one. Applied here so every resolved configuration is
+    // self-consistent, whichever path built it.
+    normal: (options?.normal ?? false) || globeNormal,
+    selectiveEffect: options?.selectiveEffect ?? false,
+    emissive: options?.emissive ?? false,
+    shadow: options?.shadow ?? false,
+    globeNormal,
+  };
+}
+
+/**
+ * Derives the buffer configuration for a set of effect requirements
+ * (`EffectDesc.requiredBuffers` of every active effect).
+ */
+export function unionGBufferRequirements(
+  requirements: Iterable<readonly GBufferName[]>,
+): ResolvedGBufferOptions {
+  const enabled: Record<GBufferName, boolean> = {
+    normal: false,
+    selectiveEffect: false,
+    emissive: false,
+    shadow: false,
+    globeNormal: false,
+  };
+  for (const required of requirements) {
+    for (const name of required) {
+      enabled[name] = true;
+    }
+  }
+  return resolveGBufferOptions(enabled);
+}
+
+/**
+ * Attachment indices for one view. A disabled buffer is absent rather than a
+ * placeholder, so these shift — never hardcode them.
+ */
+export type GBufferTextureIndex = {
+  color: typeof GBUFFER_TEXTURE_INDEX.color;
+  /** Present only when `buffers.normal` is enabled. */
+  normal?: number;
+  /** Present only when `buffers.selectiveEffect` is enabled. */
+  effectIds?: number;
+  /** Present only when `buffers.emissive` is enabled. */
+  emissive?: number;
+  /** Present only when `buffers.shadow` is enabled. */
+  shadow?: number;
+};
+
+/** Computes the attachment indices for resolved `buffers` options. */
+export function computeGBufferTextureIndex(
+  buffers: ResolvedGBufferOptions,
+): GBufferTextureIndex {
+  const index: GBufferTextureIndex = { ...GBUFFER_TEXTURE_INDEX };
+  let next: number = GBUFFER_TEXTURE_INDEX.color + 1;
+  // Attachment order of the optional buffers. Extend here (and mirror in
+  // appendOptionalGBufferAttachments) when adding a new optional buffer.
+  // `globeNormal` is absent on purpose: it is not an attachment.
+  for (const [option, key] of [
+    ["normal", "normal"],
+    ["selectiveEffect", "effectIds"],
+    ["emissive", "emissive"],
+    ["shadow", "shadow"],
+  ] as const) {
+    if (buffers[option]) {
+      index[key] = next++;
+    }
+  }
+  return index;
+}
+
+/**
+ * Inject once near the top of any fragment shader rendering into the
+ * G-buffer. Raw `.glsl` shaders `#include` the chunk instead.
+ */
+export const GBUFFER_PARS_FRAGMENT: string = GBufferParsFragmentChunk;
+
+/** Output location of the normal buffer. Mirrored in the GLSL chunk. */
+export const GBUFFER_NORMAL_LOCATION_DEFINE = "GBUFFER_NORMAL_LOCATION";
+/** Enables the effectIds output. Mirrored in the GLSL chunk. */
+export const USE_GBUFFER_SELECTIVE_EFFECT_DEFINE =
+  "USE_GBUFFER_SELECTIVE_EFFECT";
+/** Output location of the effectIds buffer. Mirrored in the GLSL chunk. */
+export const GBUFFER_EFFECT_ID_LOCATION_DEFINE = "GBUFFER_EFFECT_ID_LOCATION";
+/** Enables the emissive output. Mirrored in the GLSL chunk. */
+export const USE_GBUFFER_EMISSIVE_DEFINE = "USE_GBUFFER_EMISSIVE";
+/** Output location of the emissive buffer. Mirrored in the GLSL chunk. */
+export const GBUFFER_EMISSIVE_LOCATION_DEFINE = "GBUFFER_EMISSIVE_LOCATION";
+/** Enables the shadow output. Mirrored in the GLSL chunk. */
+export const USE_GBUFFER_SHADOW_DEFINE = "USE_GBUFFER_SHADOW";
+/** Output location of the shadow buffer. Mirrored in the GLSL chunk. */
+export const GBUFFER_SHADOW_LOCATION_DEFINE = "GBUFFER_SHADOW_LOCATION";
+
+/** Stampers iterate this so defines of disabled buffers are cleared, not left stale. */
+export const GBUFFER_DEFINE_NAMES = [
+  GBUFFER_NORMAL_LOCATION_DEFINE,
+  USE_GBUFFER_SELECTIVE_EFFECT_DEFINE,
+  GBUFFER_EFFECT_ID_LOCATION_DEFINE,
+  USE_GBUFFER_EMISSIVE_DEFINE,
+  GBUFFER_EMISSIVE_LOCATION_DEFINE,
+  USE_GBUFFER_SHADOW_DEFINE,
+  GBUFFER_SHADOW_LOCATION_DEFINE,
+] as const;
+
+/** Defines enabling the optional outputs and carrying their locations. */
+export function computeGBufferDefines(
+  buffers: ResolvedGBufferOptions,
+): Readonly<Record<string, number>> {
+  const index = computeGBufferTextureIndex(buffers);
+  const defines: Record<string, number> = {};
+  if (index.normal !== undefined) {
+    defines[GBUFFER_NORMAL_LOCATION_DEFINE] = index.normal;
+  }
+  if (index.effectIds !== undefined) {
+    defines[USE_GBUFFER_SELECTIVE_EFFECT_DEFINE] = 1;
+    defines[GBUFFER_EFFECT_ID_LOCATION_DEFINE] = index.effectIds;
+  }
+  if (index.emissive !== undefined) {
+    defines[USE_GBUFFER_EMISSIVE_DEFINE] = 1;
+    defines[GBUFFER_EMISSIVE_LOCATION_DEFINE] = index.emissive;
+  }
+  if (index.shadow !== undefined) {
+    defines[USE_GBUFFER_SHADOW_DEFINE] = 1;
+    defines[GBUFFER_SHADOW_LOCATION_DEFINE] = index.shadow;
+  }
+  return defines;
+}
+
+// Write snippets. Exported rather than inlined at the injection sites because
+// enhancers and the tile mesh locate the injected code by exact string match,
+// so both sides must share one constant.
+
+/**
+ * `normalBuffer` write for physically-based materials (standard/physical).
+ * `modelBaseEnhancer` matches/replaces this exact string.
+ */
+export const GBUFFER_NORMAL_WRITE_PHYSICAL =
+  "GBUFFER_WRITE_NORMAL(normal, metalnessFactor, roughnessFactor)";
+
+/**
+ * `normalBuffer` write for non-physical materials (basic/lambert/phong).
+ * `polygonBaseEnhancer` matches/replaces this exact string.
+ */
+export const GBUFFER_NORMAL_WRITE_BASIC =
+  "GBUFFER_WRITE_NORMAL(normal, reflectivity, roughnessFactor)";
+
+/**
+ * Selective-effect writes for built-in `ShaderLib` materials. The tile mesh
+ * replaces this by exact string match with
+ * `TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT`.
+ *
+ * Effect writes are always macro invocations: the macros own the alpha, which
+ * is the per-attachment blend factor rather than data (see the pars chunk).
+ */
+export const GBUFFER_EFFECT_WRITE_BUILTIN = `GBUFFER_WRITE_EFFECT(uEffectIdsMask, diffuseColor.rgb * uEmissiveIntensity + emissive)`;
+
+/**
+ * Selective-effect writes for custom `ShaderMaterial`
+ * (emissive = (fragColor + uEmissiveColor) × intensity).
+ */
+export const GBUFFER_EFFECT_WRITE_SHADER_MATERIAL = `GBUFFER_WRITE_EFFECT(uEffectIdsMask, (gl_FragColor.rgb + uEmissiveColor) * uEmissiveIntensity)`;
+
+/**
+ * Selective-effect writes for materials that support the effect-id mask but
+ * not emissive (LineMaterial, sprite, points).
+ */
+export const GBUFFER_EFFECT_WRITE_ID_ONLY = `GBUFFER_WRITE_EFFECT_ID_ONLY(uEffectIdsMask)`;
+
+/** Non-selective default — A=0.0, so a blended mesh keeps what is behind it. */
+export const GBUFFER_EFFECT_WRITE_ZERO = `GBUFFER_WRITE_EFFECT_ZERO`;
+
+/**
+ * Allocates the extra attachments in {@link computeGBufferTextureIndex} order.
+ * Disabled buffers get no placeholder texture.
+ */
+export function createGBufferAttachments(
+  renderTarget: WebGLRenderTarget,
+  buffers: ResolvedGBufferOptions,
+): void {
+  appendOptionalGBufferAttachments(renderTarget, buffers);
+}
+
+/** Split out so `CustomRenderPass` can rebuild a target around a reused color. */
+export function appendOptionalGBufferAttachments(
+  renderTarget: WebGLRenderTarget,
+  buffers: ResolvedGBufferOptions,
+): void {
+  if (buffers.normal) {
+    renderTarget.textures.push(renderTarget.texture.clone());
+  }
+
+  if (buffers.selectiveEffect) {
+    // Discrete bitmask data: HalfFloat is exact to 11 bits (0..2047), and
+    // interpolating between two masks would invent a third.
+    const effectIdsTexture = renderTarget.texture.clone();
+    effectIdsTexture.type = HalfFloatType;
+    effectIdsTexture.minFilter = NearestFilter;
+    effectIdsTexture.magFilter = NearestFilter;
+    effectIdsTexture.generateMipmaps = false;
+    renderTarget.textures.push(effectIdsTexture);
+  }
+
+  if (buffers.emissive) {
+    // HalfFloat keeps the HDR range bloom extraction thresholds against.
+    const emissiveTexture = renderTarget.texture.clone();
+    emissiveTexture.type = HalfFloatType;
+    renderTarget.textures.push(emissiveTexture);
+  }
+
+  if (buffers.shadow) {
+    // 8 bits is plenty for a shadow factor.
+    const shadowTexture = renderTarget.texture.clone();
+    shadowTexture.type = UnsignedByteType;
+    renderTarget.textures.push(shadowTexture);
+  }
+}

package/src/material/index.ts

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

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

@@ -4,11 +4,16 @@ import {
   generateTileCommonInjection,
   generateTileMapFragment,
   generateTileNormalFragmentMaps,
-  TILE_EMISSIVE_EFFECT_BUFFER_REPLACEMENT,
-  TILE_NORMAL_BUFFER_REPLACEMENT,
-  TILE_PICK_FRAGMENT_OVERRIDE,
+  type TileShaderFeatures,
+  WATERMASK_OCEAN_REFLECTIVITY,
 } from "./tileShader";
 
+const FEATURES_OFF: TileShaderFeatures = {
+  hasHillshade: false,
+  hasWater: false,
+  hasWatermask: false,
+};
+
 describe("generateTileCommonInjection", () => {
   it("declares the three atlas samplers", () => {
     const src = generateTileCommonInjection(8);
@@ -26,7 +31,7 @@ describe("generateTileCommonInjection", () => {
 });
 
 describe("generateTileMapFragment", () => {
-  const src = generateTileMapFragment(16);
+  const src = generateTileMapFragment(16, FEATURES_OFF);
 
   it("samples each atlas exactly once", () => {
     const colorMatches = src.match(/texture2D\(uColorAtlas/g) ?? [];
@@ -65,11 +70,34 @@ describe("generateTileMapFragment", () => {
     );
     expect(src).not.toMatch(/mix\(diffuseColor\.rgb,\s*atlasColor\.rgb/);
   });
+
+  it("omits the ocean reflectivity fallback when no watermask is present", () => {
+    expect(src).not.toContain("useWater && !hasSlotWaterParams");
+  });
+
+  it("overrides reflectivity/roughness on watermask water pixels", () => {
+    // Watermask water under a raster winner (or no winner – open ocean) must
+    // clear the SSR mask threshold; a texturized (vector) winner keeps its own
+    // per-slot params.
+    const masked = generateTileMapFragment(16, {
+      ...FEATURES_OFF,
+      hasWatermask: true,
+    });
+    expect(masked).toContain("if (useWater && !hasSlotWaterParams)");
+    expect(masked).toContain(
+      `tileReflectivity = ${WATERMASK_OCEAN_REFLECTIVITY.toFixed(4)};`,
+    );
+    // The override must land AFTER the per-slot reads so it wins.
+    expect(
+      masked.indexOf("if (useWater && !hasSlotWaterParams)"),
+    ).toBeGreaterThan(masked.indexOf("uReflectivities[winIdx]"));
+  });
 });
 
 describe("generateTileNormalFragmentMaps", () => {
   it("omits the hillshade lookup entirely when hasHillshade is off", () => {
     const src = generateTileNormalFragmentMaps({
+      ...FEATURES_OFF,
       hasHillshade: false,
       hasWater: false,
     });
@@ -79,6 +107,7 @@ describe("generateTileNormalFragmentMaps", () => {
 
   it("samples uNormalAtlas exactly once when hasHillshade is on", () => {
     const src = generateTileNormalFragmentMaps({
+      ...FEATURES_OFF,
       hasHillshade: true,
       hasWater: false,
     });
@@ -90,6 +119,7 @@ describe("generateTileNormalFragmentMaps", () => {
 
   it("omits water specular call when hasWater is off", () => {
     const src = generateTileNormalFragmentMaps({
+      ...FEATURES_OFF,
       hasHillshade: false,
       hasWater: false,
     });
@@ -99,38 +129,10 @@ describe("generateTileNormalFragmentMaps", () => {
 
   it("emits computeWaterSpecular when hasWater is on", () => {
     const src = generateTileNormalFragmentMaps({
+      ...FEATURES_OFF,
       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

@@ -20,8 +20,16 @@ export type TileShaderFeatures = {
   hasHillshade: boolean;
   /** Some layer uses Water material → emit the water specular branch. */
   hasWater: boolean;
+  /**
+   * Quantized-mesh watermask is present (source requested `requestWaterMask`).
+   * Emits the ocean reflectivity fallback in the map fragment.
+   */
+  hasWatermask: boolean;
 };
 
+export const WATERMASK_OCEAN_REFLECTIVITY = 0.02;
+export const WATERMASK_OCEAN_ROUGHNESS = 0.2;
+
 /**
  * Goes after `#include <common>` in the fragment shader. Declares the three
  * atlas samplers + the per-slot uniform arrays we still index by winning
@@ -71,7 +79,23 @@ export function generateTileCommonInjection(numTextures: number): string {
  * generateTileEmissiveBuffer below to decide what gets written to the
  * emissive/effect MRT attachments).
  */
-export function generateTileMapFragment(maxTextures: number): string {
+export function generateTileMapFragment(
+  maxTextures: number,
+  features: TileShaderFeatures,
+): string {
+  // Watermask ocean pixels: `useWater` fired from the tile-wide watermask but
+  // the winning slot (raster imagery, or none on open ocean) carries zeroed
+  // reflectivity/roughness – override them with the default ocean appearance
+  // so SSR and envmap reflections apply to the sea automatically. Mirrors the
+  // shininess/specularStrength fallback above. A texturized winner keeps its
+  // own params: a vector layer drawn over water should not turn reflective.
+  const watermaskReflectivityFallback = features.hasWatermask
+    ? `
+  if (useWater && !hasSlotWaterParams) {
+    tileReflectivity = ${WATERMASK_OCEAN_REFLECTIVITY.toFixed(4)};
+    tileRoughness    = ${WATERMASK_OCEAN_ROUGHNESS.toFixed(4)};
+  }`
+    : "";
   return `
   vec4 atlasColor = texture2D(uColorAtlas, vOrigUv);
   vec4 atlasAttr  = texture2D(uAttrAtlas,  vOrigUv);
@@ -135,7 +159,7 @@ export function generateTileMapFragment(maxTextures: number): string {
   // 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]);
-
+${watermaskReflectivityFallback}
   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;
@@ -234,21 +258,20 @@ export function generateTileNormalFragmentMaps(
  */
 export const TILE_NORMAL_BUFFER_REPLACEMENT = `
 vec3 finalNormal = mix(origNormal, normalize(origNormal * 0.7 + normal), applyWaterNormals);
-normalBuffer = vec4(packNormalToVec2(finalNormal), tileReflectivity, tileRoughness);
+GBUFFER_WRITE_NORMAL(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.
+ * Effect/emissive write replacement, via the `GBUFFER_WRITE_EFFECT*` macros
+ * from the pars chunk (each buffer's write is compiled out when the view
+ * disables it). 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);
+  GBUFFER_WRITE_EFFECT(tileEffectIdsMask, diffuseColor.rgb * tileEmissiveIntensity + tileEmissiveColor)
 } else {
-  effectIdBuffer = vec4(0.0);
-  emissiveBuffer = vec4(0.0);
+  GBUFFER_WRITE_EFFECT_ZERO
 }
 `;