@navaramap/three 0.0.5 → 0.0.6

package/src/passes/CustomRenderPass.test.ts

@@ -0,0 +1,143 @@
+import type { Globe } from "@navaramap/core";
+import {
+  Group,
+  Mesh,
+  MeshStandardMaterial,
+  PerspectiveCamera,
+  Scene,
+  WebGLRenderTarget,
+} from "three";
+import { describe, expect, it } from "vitest";
+
+import { NVR_UNLIT_SCENE_DEFINE } from "../material";
+import {
+  USE_GBUFFER_SHADOW_DEFINE,
+  resolveGBufferOptions,
+} from "../material/gbufferLayout";
+import type { Scenes } from "../scene";
+
+import { CustomRenderPass } from "./CustomRenderPass";
+
+const createScenes = (): Scenes => ({
+  light: new Group(),
+  mrt: new Scene(),
+  globe: new Scene(),
+  draped: new Scene(),
+  opaque: new Scene(),
+  transparent: new Scene(),
+  skyEnvMap: new Scene(),
+});
+
+const addMesh = (scene: Scene): MeshStandardMaterial => {
+  const material = new MeshStandardMaterial();
+  scene.add(new Mesh(undefined, material));
+  return material;
+};
+
+const createPass = (scenes: Scenes, lit: boolean) =>
+  new CustomRenderPass(
+    scenes,
+    new PerspectiveCamera(),
+    new WebGLRenderTarget(1, 1),
+    {} as Globe,
+    { buffers: resolveGBufferOptions({ shadow: true }), lit },
+  );
+
+// Regression: `view.lit` was stamped on the G-buffer scenes only, so meshes
+// in the forward-only scenes – the default routing - stayed lit.
+describe("stampGBufferDefines", () => {
+  it("stamps the scene lit default on both G-buffer and forward-only scenes", () => {
+    const scenes = createScenes();
+    const mrtMaterial = addMesh(scenes.mrt);
+    const opaqueMaterial = addMesh(scenes.opaque);
+    const transparentMaterial = addMesh(scenes.transparent);
+
+    const pass = createPass(scenes, false);
+    pass["stampGBufferDefines"]();
+
+    for (const material of [mrtMaterial, opaqueMaterial, transparentMaterial]) {
+      expect(material.defines?.[NVR_UNLIT_SCENE_DEFINE]).toBe(1);
+    }
+  });
+
+  it("keeps the G-buffer defines out of the forward-only scenes", () => {
+    const scenes = createScenes();
+    const mrtMaterial = addMesh(scenes.mrt);
+    const opaqueMaterial = addMesh(scenes.opaque);
+
+    const pass = createPass(scenes, true);
+    pass["stampGBufferDefines"]();
+
+    expect(mrtMaterial.defines?.[USE_GBUFFER_SHADOW_DEFINE]).toBe(1);
+    // Single-attachment target – the extra outputs would be undeclared.
+    expect(opaqueMaterial.defines?.[USE_GBUFFER_SHADOW_DEFINE] ?? false).toBe(
+      false,
+    );
+  });
+
+  it("stamps the G-buffer defines when a material moves from opaque to mrt", () => {
+    const scenes = createScenes();
+    const material = new MeshStandardMaterial();
+    const mesh = new Mesh(undefined, material);
+    scenes.opaque.add(mesh);
+
+    const pass = createPass(scenes, true);
+    pass["stampGBufferDefines"]();
+
+    // A shared "already stamped" set would leave it without the outputs.
+    scenes.opaque.remove(mesh);
+    scenes.mrt.add(mesh);
+    pass["stampGBufferDefines"]();
+
+    expect(material.defines?.[USE_GBUFFER_SHADOW_DEFINE]).toBe(1);
+  });
+
+  it("restamps every material after setLit", () => {
+    const scenes = createScenes();
+    const opaqueMaterial = addMesh(scenes.opaque);
+
+    const pass = createPass(scenes, true);
+    pass["stampGBufferDefines"]();
+    expect(opaqueMaterial.defines?.[NVR_UNLIT_SCENE_DEFINE] ?? false).toBe(
+      false,
+    );
+
+    pass.setLit(false);
+    pass["stampGBufferDefines"]();
+    expect(opaqueMaterial.defines?.[NVR_UNLIT_SCENE_DEFINE]).toBe(1);
+  });
+});
+
+describe("globe-normal copy target", () => {
+  const size = (pass: CustomRenderPass) =>
+    pass.globeNormalCopyPass.texture.image as { width: number; height: number };
+
+  it("stays 1x1 while no draped mesh exists, even across a resize", () => {
+    const pass = createPass(createScenes(), true);
+    pass.setSize(800, 600);
+
+    expect(size(pass).width).toBe(1);
+    expect(size(pass).height).toBe(1);
+  });
+
+  it("applies the size stored while inactive once a draped mesh appears", () => {
+    const pass = createPass(createScenes(), true);
+    pass.setSize(800, 600);
+
+    pass["setGlobeNormalActive"](true);
+
+    expect(size(pass).width).toBe(800);
+    expect(size(pass).height).toBe(600);
+  });
+
+  it("shrinks back when the last draped mesh goes away", () => {
+    const pass = createPass(createScenes(), true);
+    pass.setSize(800, 600);
+    pass["setGlobeNormalActive"](true);
+
+    pass["setGlobeNormalActive"](false);
+
+    expect(size(pass).width).toBe(1);
+    expect(size(pass).height).toBe(1);
+  });
+});

package/src/passes/CustomRenderPass.ts

@@ -4,18 +4,31 @@ import {
   Color,
   DepthStencilFormat,
   DepthTexture,
-  HalfFloatType,
-  NearestFilter,
   RGBADepthPacking,
   Scene,
   UnsignedInt248Type,
   WebGLRenderTarget,
+  type Material,
+  type Mesh,
   type PerspectiveCamera,
+  type Texture,
   type WebGLRenderer,
 } from "three";
 
 import { RenderPass } from "../effects";
-import { DrapedMesh } from "../mesh/DrapedMesh";
+import { NVR_BLENDED_DEFINE, NVR_UNLIT_SCENE_DEFINE } from "../material";
+import {
+  GBUFFER_ATTACHMENT_NAMES,
+  GBUFFER_DEFINE_NAMES,
+  appendOptionalGBufferAttachments,
+  computeGBufferDefines,
+  computeGBufferTextureIndex,
+  createGBufferAttachments,
+  resolveGBufferOptions,
+  type GBufferTextureIndex,
+  type ResolvedGBufferOptions,
+} from "../material/gbufferLayout";
+import { DrapedMesh, setupMaterialForDrape } from "../mesh/DrapedMesh";
 import type { Scenes } from "../scene";
 
 import { AllDepthCopyPass, NormalCopyPass, RenderTargetCopyPass } from ".";
@@ -30,6 +43,14 @@ export type CustomRenderPassOptions = {
   debugNormal?: boolean;
   disableShadow?: boolean;
   allowTransparent?: boolean;
+  /** G-buffer attachment configuration. Defaults to all optional buffers disabled. */
+  buffers?: ResolvedGBufferOptions;
+  /**
+   * Scene-level default of the `lit` material option (`view.lit`). When
+   * `false`, materials without an explicit `lit` output plain albedo.
+   * @defaultValue true
+   */
+  lit?: boolean;
 };
 
 export class CustomRenderPass extends RenderPass {
@@ -53,7 +74,39 @@ export class CustomRenderPass extends RenderPass {
   });
 
   private debugNormalCopyPass?: NormalCopyPass;
+  private readonly gbufferScenes: readonly Scene[];
+  // Rendered outside the G-buffer pass, so these must never declare G-buffer
+  // outputs the render target has no attachments for.
+  private readonly forwardScenes: readonly Scene[];
+  private readonly stampScenes: readonly Scene[];
   private allowTransparent: boolean;
+  private buffers: ResolvedGBufferOptions;
+  // Scene-level default of the `lit` material option (`view.lit`).
+  private sceneLit: boolean;
+  // Template for rebuilding the G-buffer render target in setBuffers.
+  private inputBufferTemplate: WebGLRenderTarget;
+  /**
+   * Attachment indices of `gbufferRenderTarget.textures` for this view.
+   * Recomputed by {@link setBuffers}.
+   */
+  textureIndex: GBufferTextureIndex;
+  // Defines carrying the enabled optional outputs and their locations,
+  // stamped onto every material rendered into the G-buffer.
+  private gbufferDefines: Readonly<Record<string, number>>;
+  private gbufferDefinesStamped = new WeakSet<Material>();
+  // Separate from the G-buffer set: the two cover different scene sets, and a
+  // shared one would skip the G-buffer defines for a material first seen in
+  // the opaque scene that later moves to the MRT pass.
+  private litStamped = new WeakSet<Material>();
+  private stampDirty = true;
+  // Drives the globe-normal copy target, which stays 1x1 until a draped mesh
+  // exists. Tracked here because setSize can arrive while it is inactive.
+  private globeNormalActive = false;
+  private readonly globeNormalUniform: { value: Texture | null };
+  private width = 1;
+  private height = 1;
+  private lastProgramCount = -1;
+  private readonly lastSceneChildCounts = [-1, -1, -1, -1, -1];
 
   constructor(
     scenes: Scenes,
@@ -72,25 +125,20 @@ export class CustomRenderPass extends RenderPass {
     this._camera = camera;
     this.globe = globe;
 
+    this.gbufferScenes = [scenes.globe, scenes.mrt, scenes.draped];
+    this.forwardScenes = [scenes.opaque, scenes.transparent];
+    this.stampScenes = [...this.gbufferScenes, ...this.forwardScenes];
+
+    this.buffers = options?.buffers ?? resolveGBufferOptions();
+    this.sceneLit = options?.lit ?? true;
+    this.textureIndex = computeGBufferTextureIndex(this.buffers);
+    this.gbufferDefines = computeGBufferDefines(this.buffers);
+    this.inputBufferTemplate = inputBuffer;
+
     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);
+    // Extra G-buffer attachments (normal/effectIds/emissive) – see
+    // material/gbufferLayout.ts for the layout definition.
+    createGBufferAttachments(this.gbufferRenderTarget, this.buffers);
 
     // The gbuffer owns its depth texture instead of sharing the composer's one
     // (postprocessing >= 6.39 no longer exposes a writable shared depth
@@ -117,16 +165,27 @@ export class CustomRenderPass extends RenderPass {
     this.allowTransparent = options?.allowTransparent ?? true;
 
     this.globeNormalCopyPass = new NormalCopyPass();
-    this.globeNormalCopyPass.setNormalTexture(
-      this.gbufferRenderTarget.textures[1],
-    );
+    // The copy target keeps its Texture identity across setSize, so draped
+    // materials can bind this ref once.
+    this.globeNormalUniform = { value: this.globeNormalCopyPass.texture };
     if (options?.debugNormal) {
       this.debugNormalCopyPass = new NormalCopyPass();
       this.debugNormalCopyPass.unpackNormal = true;
-      this.debugNormalCopyPass.setNormalTexture(
-        this.gbufferRenderTarget.textures[1],
-      );
     }
+    this.bindNormalTexture();
+  }
+
+  /**
+   * Re-points the copy passes at the normal attachment. The attachment is
+   * freshly allocated on every {@link setBuffers}, so the reference cannot be
+   * captured once.
+   */
+  private bindNormalTexture(): void {
+    const index = this.textureIndex.normal;
+    if (index === undefined) return;
+    const texture = this.gbufferRenderTarget.textures[index];
+    this.globeNormalCopyPass.setNormalTexture(texture);
+    this.debugNormalCopyPass?.setNormalTexture(texture);
   }
 
   // Render the scene with world scene that includes user setting object like a light.
@@ -140,11 +199,170 @@ export class CustomRenderPass extends RenderPass {
     scene.remove(this._scenes.light);
   }
 
+  /**
+   * Applies a new derived buffer configuration. Attachment locations may have
+   * shifted, so every material is re-stamped and its shader recompiled.
+   */
+  setBuffers(buffers: ResolvedGBufferOptions): void {
+    // Only the attachment-backed names matter here — `globeNormal` is picked
+    // up by render() and must not trigger a rebuild on its own.
+    const unchanged = GBUFFER_ATTACHMENT_NAMES.every(
+      (name) => buffers[name] === this.buffers[name],
+    );
+    this.buffers = buffers;
+    if (unchanged) {
+      return;
+    }
+    this.textureIndex = computeGBufferTextureIndex(buffers);
+    this.gbufferDefines = computeGBufferDefines(buffers);
+    this.gbufferDefinesStamped = new WeakSet();
+    this.stampDirty = true;
+
+    // Must be a fresh target: splicing textures in place leaves the renderer's
+    // cached GL state on a stale attachment, so writes land in the framebuffer
+    // while samplers read empty storage. Only color and depth keep their
+    // Texture identity; every optional attachment is reallocated, which is why
+    // consumers must re-fetch each frame rather than capture at creation.
+    const old = this.gbufferRenderTarget;
+    const rt = this.inputBufferTemplate.clone();
+    rt.setSize(old.width, old.height);
+    rt.texture = old.texture;
+    appendOptionalGBufferAttachments(rt, buffers);
+    rt.depthTexture = old.depthTexture;
+    // three disposes rt.depthTexture with the target; detach the reused one.
+    old.depthTexture = null;
+    this.gbufferRenderTarget = rt;
+    old.dispose();
+
+    this.copyPass.setRenderTarget(rt);
+    this.bindNormalTexture();
+  }
+
+  /** Applies a new scene-level `lit` default (`view.lit` changed). */
+  setLit(lit: boolean): void {
+    if (this.sceneLit === lit) return;
+    this.sceneLit = lit;
+    this.litStamped = new WeakSet();
+    this.stampDirty = true;
+  }
+
+  /**
+   * O(1) gate keeping the stamping traversal off the per-frame path. The
+   * program count catches deeply-nested async additions (a glTF populating a
+   * scene-resident group): a material must compile before it can render, so
+   * the traversal converges one frame later.
+   */
+  private shouldStampGBufferDefines(renderer: WebGLRenderer): boolean {
+    let dirty = this.stampDirty;
+    this.stampDirty = false;
+
+    const programCount = renderer.info.programs?.length ?? 0;
+    if (programCount !== this.lastProgramCount) {
+      this.lastProgramCount = programCount;
+      dirty = true;
+    }
+
+    for (let i = 0; i < this.stampScenes.length; i++) {
+      const count = this.stampScenes[i].children.length;
+      if (count !== this.lastSceneChildCounts[i]) {
+        this.lastSceneChildCounts[i] = count;
+        dirty = true;
+      }
+    }
+
+    return dirty;
+  }
+
+  // Materials reach the G-buffer from anywhere (built-ins, enhancers, user
+  // ShaderMaterials), so they are stamped here rather than per-desc. `lit` is
+  // a lighting define, not a G-buffer one, hence the forward scenes too.
+  private stampGBufferDefines(): void {
+    for (const scene of this.gbufferScenes) {
+      scene.traverse((object) => {
+        this.forEachMaterial(object, (m) => this.stampGBufferDefine(m));
+      });
+    }
+    for (const scene of this.forwardScenes) {
+      scene.traverse((object) => {
+        this.forEachMaterial(object, (m) => this.stampLitDefine(m));
+      });
+    }
+    // Drape shading is opted into here rather than per-desc, so a mesh moved
+    // into the draped scene picks it up wherever it came from.
+    this._scenes.draped.traverse((object) => {
+      this.forEachMaterial(object, (m) =>
+        setupMaterialForDrape(m, this.globeNormalUniform),
+      );
+    });
+  }
+
+  private forEachMaterial(
+    object: unknown,
+    visit: (material: Material) => void,
+  ): void {
+    const material = (object as Partial<Mesh>).material;
+    if (!material) return;
+    if (Array.isArray(material)) {
+      for (const m of material) visit(m);
+    } else {
+      visit(material);
+    }
+  }
+
+  private stampGBufferDefine(material: Material): void {
+    material.defines ??= {};
+    let changed = false;
+
+    // `material.transparent` toggles at runtime (e.g. `globe.transparent`),
+    // so this one is synced on every visit instead of being gated by the set.
+    const blended = material.transparent ? 1 : false;
+    if ((material.defines[NVR_BLENDED_DEFINE] ?? false) !== blended) {
+      material.defines[NVR_BLENDED_DEFINE] = blended;
+      changed = true;
+    }
+
+    if (!this.gbufferDefinesStamped.has(material)) {
+      this.gbufferDefinesStamped.add(material);
+      for (const name of GBUFFER_DEFINE_NAMES) {
+        // `false` clears a stale define – three's generateDefines skips it.
+        const value = this.gbufferDefines[name] ?? false;
+        const current = material.defines[name] ?? false;
+        if (current !== value) {
+          material.defines[name] = value;
+          changed = true;
+        }
+      }
+    }
+
+    if (changed) {
+      material.needsUpdate = true;
+    }
+
+    this.stampLitDefine(material);
+  }
+
+  /** Per-material `lit` (NVR_LIT / NVR_UNLIT) wins over this in the shader. */
+  private stampLitDefine(material: Material): void {
+    if (this.litStamped.has(material)) return;
+    this.litStamped.add(material);
+
+    material.defines ??= {};
+    const sceneUnlit = this.sceneLit ? false : 1;
+    if ((material.defines[NVR_UNLIT_SCENE_DEFINE] ?? false) !== sceneUnlit) {
+      material.defines[NVR_UNLIT_SCENE_DEFINE] = sceneUnlit;
+      material.needsUpdate = true;
+    }
+  }
+
   render(
     renderer: WebGLRenderer,
     inputBuffer: WebGLRenderTarget | null,
     _outputBuffer: WebGLRenderTarget | null,
   ) {
+    if (this.shouldStampGBufferDefines(renderer)) {
+      this.stampGBufferDefines();
+    }
+
     const shouldDrapeByStencilTest = this._scenes.draped.children.length !== 0;
 
     const renderTarget = this.gbufferRenderTarget;
@@ -179,8 +397,15 @@ export class CustomRenderPass extends RenderPass {
 
     this._renderWithLight(renderer, this._scenes.globe);
 
-    // Set normal texture for copy pass
-    this.globeNormalCopyPass.render(renderer, null, null);
+    // Draped meshes read it and draw further down, so the copy still happens
+    // before its consumer; effects opt in through `requiredBuffers`.
+    const needsGlobeNormal =
+      (shouldDrapeByStencilTest || this.buffers.globeNormal) &&
+      this.textureIndex.normal !== undefined;
+    this.setGlobeNormalActive(needsGlobeNormal);
+    if (needsGlobeNormal) {
+      this.globeNormalCopyPass.render(renderer, null, null);
+    }
 
     this.globeDepthCopyPass.setDepthTexture(
       renderTarget.depthTexture as DepthTexture,
@@ -263,13 +488,31 @@ export class CustomRenderPass extends RenderPass {
   setDepthTexture(): void {}
 
   setSize(width: number, height: number) {
+    this.width = width;
+    this.height = height;
     this.gbufferRenderTarget.setSize(width, height);
     this.globeDepthCopyPass.setSize(width, height);
     this.allDepthCopyPass.setSize(width, height);
-    this.globeNormalCopyPass.setSize(width, height);
+    if (this.globeNormalActive) {
+      this.globeNormalCopyPass.setSize(width, height);
+    }
     this.debugNormalCopyPass?.setSize(width, height);
   }
 
+  /**
+   * Grows the globe-normal copy target only while something consumes it, and
+   * shrinks it back to 1x1 otherwise — at full resolution it is a screen-sized
+   * RGBA16F target, the same cost again as the G-buffer's normal attachment.
+   */
+  private setGlobeNormalActive(active: boolean): void {
+    if (this.globeNormalActive === active) return;
+    this.globeNormalActive = active;
+    this.globeNormalCopyPass.setSize(
+      active ? this.width : 1,
+      active ? this.height : 1,
+    );
+  }
+
   // 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

package/src/passes/RenderTargetCopyPass.ts

@@ -77,6 +77,12 @@ export class RenderTargetCopyPass extends Pass {
     this._material.uniforms.color.value = texture;
   }
 
+  /** Points the pass at a rebuilt render target (same-purpose replacement). */
+  setRenderTarget(renderTarget: WebGLRenderTarget): void {
+    this._renderTarget = renderTarget;
+    this.setTexture(renderTarget.texture);
+  }
+
   /**
    * When a depth texture is set, the pass copies its depth into the target's
    * depth buffer via gl_FragDepth. Depth test must be enabled (with AlwaysDepth)

package/src/plugins/AttributionPlugin/index.ts

@@ -18,7 +18,8 @@
  * await view.init();
  *
  * // A 3D-tiles layer whose tiles embed their own copyright (tracked dynamically).
- * const photoreal = view.addLayer({ type: "cesium3dtiles", data: { url } });
+ * const photorealSource = view.addSource({ type: "3d-tiles", url });
+ * const photoreal = view.addLayer({ type: "3d-tiles", source: photorealSource });
  *
  * // `add` / `remove` manage the set of displayed attributions.
  * view.attribution?.add([
@@ -124,7 +125,7 @@ let styleRefCount = 0;
  */
 const NAVARA_CREDIT: AttributionItem = {
   attribution: "Navara",
-  attributionUrl: "https://navara-docs.netlify.app/",
+  attributionUrl: "https://navara-docs.reearth.workers.dev//",
 };
 
 /**

package/src/shaders/index.ts

@@ -1 +1,17 @@
+import { packing } from "@takram/three-geospatial/shaders";
+import { ShaderChunk } from "three";
+
 export * from "@takram/three-geospatial/shaders";
+
+/**
+ * Codec for the normal buffer's RG channels, which are **octahedral**, not a
+ * plain `xy * 2 - 1`: decode with `unpackVec2ToNormal`. Prepend to shaders
+ * that cannot use `#include` resolution (postprocessing effect fragments).
+ */
+export const NORMAL_PACKING_SHADER: string = packing;
+
+/**
+ * Three's `packing` chunk, for the MRT pass's packed depth buffers – check
+ * `depthBufferPacking` / `globeDepthBufferPacking` for the packing in use.
+ */
+export const DEPTH_PACKING_SHADER: string = ShaderChunk.packing;

package/src/type/index.ts

@@ -1,12 +1,5 @@
 import type { NormalizeWASMClass, TileHandle } from "@navaramap/core";
 import type {
-  B3dmLayerDescription,
-  PntsLayerDescription,
-  Cesium3dTilesLayerDescription,
-  GeoJsonLayerDescription,
-  TerrainLayerDescription,
-  TileLayerDescription,
-  MvtLayerDescription,
   VectorLayerDescription,
   RasterLayerDescription,
   TerrainSourceLayerDescription,
@@ -56,16 +49,6 @@ export type BuiltInEffectDescription =
   | SkyEnvMapPassConfig
   | TransparentPassConfig;
 
-// export type MVTLayer = {
-//   type: "mvt";
-//   zoom: number;
-//   layers?: string[];
-//   height?: number;
-//   extent?: Extent;
-//   url: string;
-//   color?: number;
-// };
-
 type Layer<LD> = NormalizeWASMClass<LD>;
 
 /**
@@ -87,31 +70,11 @@ type ConvertColorFields<T> = {
 
 /**
  * Helper type to enable Navara Color objects in all color-related fields.
- * This applies to model, point, billboard, text, polyline, polygon, rasterTile, etc.
+ * This applies to model, point, billboard, text, polyline, polygon, raster, etc.
  * Both number and Navara Color objects are accepted for backward compatibility.
  */
 type WithColorSupport<T> = ConvertColorFields<T>;
 
-export type TilesLayer = WithColorSupport<
-  Layer<TileLayerDescription & { type: "tiles" }>
->;
-export type TerrainLayer = Layer<TerrainLayerDescription & { type: "terrain" }>;
-export type GeoJsonLayer = WithColorSupport<
-  Layer<GeoJsonLayerDescription & { type: "geojson" }>
->;
-export type B3dmLayer = WithColorSupport<
-  Layer<B3dmLayerDescription & { type: "b3dm" }>
->;
-export type PntsLayer = WithColorSupport<
-  Layer<PntsLayerDescription & { type: "pnts" }>
->;
-export type Cesium3dTilesLayer = WithColorSupport<
-  Layer<Cesium3dTilesLayerDescription & { type: "cesium3dtiles" }>
->;
-export type MvtLayer = WithColorSupport<
-  Layer<MvtLayerDescription & { type: "mvt" }>
->;
-
 /**
  * A reference to a {@link Source}: either the source handle returned by
  * `addSource`, or its `id` string.
@@ -145,9 +108,14 @@ type TerrainSourceLayerBase = WithColorSupport<
 >;
 
 /**
- * A `terrain` layer renders a `raster-dem` or `quantized-mesh` source as the globe surface.
+ * A `terrain` layer renders a `raster-dem` or `quantized-mesh` source as the
+ * globe surface. Alternatively, omit `source` and pass `ellipsoid` to render a
+ * flat ellipsoid surface (e.g. to drape clamp-to-ground data on).
  */
-export type TerrainSourceLayer = SourceLayerBase<TerrainSourceLayerBase>;
+export type TerrainSourceLayer = SourceLayerBase<TerrainSourceLayerBase> & {
+  /** Render a source-less flat ellipsoid surface. Mutually exclusive with `source`. */
+  ellipsoid?: TerrainSourceLayerBase["terrain"];
+};
 
 type Tiles3dLayerBase = WithColorSupport<
   Layer<Tiles3dLayerDescription & { type: "3d-tiles" }>
@@ -157,17 +125,7 @@ type Tiles3dLayerBase = WithColorSupport<
 export type Tiles3dLayer = SourceLayerBase<Tiles3dLayerBase>;
 
 export type LayerDescription =
-  | TilesLayer
-  | TerrainLayer
-  | GeoJsonLayer
-  | B3dmLayer
-  | PntsLayer
-  | Cesium3dTilesLayer
-  | MvtLayer
-  | VectorLayer
-  | RasterLayer
-  | TerrainSourceLayer
-  | Tiles3dLayer;
+  VectorLayer | RasterLayer | TerrainSourceLayer | Tiles3dLayer;
 
 /**
  * Fields common to every source, independent of its `type`.