leaflet-city-mapper 0.0.9 → 0.1.1

package/src/lighting/README.md

@@ -0,0 +1,28 @@
+# Lighting
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Collects point lights from visible scene layers and maintains spatial grids for
+fixed and moving lights. Grid data is uploaded for the shared renderer.
+
+## Point-light grids
+
+```mermaid
+flowchart LR
+  Layers["Visible nightLight layers"] --> Collect["Collect world-space lights"]
+  Collect --> Fixed["Fixed grid"]
+  Collect --> Moving["Moving grid"]
+  Fixed --> Buffer["Shared GPU storage buffer"]
+  Moving --> Buffer
+  Buffer --> Shader["Nearby-light lookup"]
+```
+
+Grids use 32-metre cells. If their data exceeds the GPU storage limit, the
+update throws; buffer growth also refreshes bindings. Directional sunlight uses
+separate [shadows](../shadows/README.md).
+
+- [updatePointLights.js](./updatePointLights.js): collect, cache and upload light grids.
+- [lightGrid.js](./lightGrid.js): build a spatial light grid.
+- [worldLights.js](./worldLights.js): transform lights into world coordinates.
+
+Related: [shadows](../shadows/README.md), [sunlight](../sunlight/README.md), [rendering](../rendering/README.md).

package/src/lighting/cacheLightGrid.js

@@ -1,7 +1,15 @@
 import { lightGrid } from './lightGrid.js';
 import { worldLights } from './worldLights.js';
 
-/** Keep fixed lamps cached when moving headlights change. */
+/**
+ * Reuse a light grid when its meshes and world-space light snapshots are unchanged.
+ *
+ * @param {Object[]} meshes Meshes containing point lights.
+ * @param {Object} [previous] Previous grid and mesh snapshots, if any.
+ * @param {number} maxBytes Maximum GPU storage size in bytes.
+ *
+ * @returns {Object} Reused or rebuilt light grid and snapshots.
+ */
 export function cacheLightGrid(meshes, previous, maxBytes) {
   let unchanged = previous?.meshes.length === meshes.length;
   let i, mesh, matrix, lights, cache, sameMatrix, j;

package/src/lighting/collectLightMeshes.js

@@ -1,6 +1,12 @@
 import { geometryEmpty } from '../globals/geometryEmpty.js';
 
-
+/**
+ * Collect visible nodes with lights into fixed and moving mesh lists.
+ *
+ * @param {Object} node Scene node to visit.
+ * @param {Object[]} fixed Output list for fixed lights.
+ * @param {Object[]} moving Output list for dynamic lights.
+ */
 export function collectLightMeshes(node, fixed, moving) {
   if (!node.visible) return;
   if (node.extras?.lights) (node.extras.dynamicLights ? moving : fixed).push(node);

package/src/lighting/lightGrid.js

@@ -1,6 +1,15 @@
 import { visitCells } from './visitLightGridCells.js';
 
-/** Pack world-space point lights into the shader's spatial grid. */
+/**
+ * Pack world-space point lights into the shader's spatial grid.
+ *
+ * @param {Float32Array[]} packed Arrays of world-space light records.
+ * @param {number} maxBytes Maximum GPU storage size in bytes.
+ *
+ * @returns {Object} Packed grid data and light count.
+ *
+ * @throws {Error} If the grid exceeds the GPU storage limit.
+ */
 export function lightGrid(packed, maxBytes) {
   let count = 0;
   let values, i, value, key;

package/src/lighting/updatePointLights.js

@@ -1,14 +1,18 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { bindSunlight } from '../shadows/bindSunlight.js';
 import { cacheLightGrid } from './cacheLightGrid.js';
 import { collectLightMeshes } from './collectLightMeshes.js';
 
+/**
+ * Cache and upload fixed and moving point-light grids for the shared renderer.
+ *
+ * @param {L.Layer} layer Layer owning the shared renderer.
+ *
+ * @throws {Error} If the combined grids exceed the GPU storage limit.
+ */
 export function updatePointLights(layer) {
   const { device, sunlight: sun } = rendererByLayer.get(layer);
   const fixed = /* alloc */ [];

package/src/lighting/visitLightCells.js

@@ -1,13 +1,26 @@
-export function visitLightCells(values, i, minX, minZ, cellSize, columns, offsets, data) {
-  const radius = values[i + 3], x = values[i] - minX, z = values[i + 2] - minZ;
-  let y, c, key;
-  for (y = Math.floor((z - radius) / cellSize); y <= Math.floor((z + radius) / cellSize); y++) {
-    for (c = Math.floor((x - radius) / cellSize); c <= Math.floor((x + radius) / cellSize); c++) {
-      key = y * columns + c;
-      if (data) {
-        writeLightCell(values, i, key, offsets, data);
-      } else offsets[key]++;
-    }
-  }
-}
-import { writeLightCell } from './writeLightCell.js';
+import { writeLightCell } from './writeLightCell.js';
+
+/**
+ * Count or write a light into each spatial grid cell covered by its radius.
+ *
+ * @param {Float32Array} values Packed light records.
+ * @param {number} i Starting index of the light record.
+ * @param {number} minX Grid origin on the x axis.
+ * @param {number} minZ Grid origin on the z axis.
+ * @param {number} cellSize Grid cell width.
+ * @param {number} columns Number of grid columns.
+ * @param {Uint32Array} offsets Per-cell counts or write offsets.
+ * @param {Float32Array} [data] Output grid data; omitted during counting.
+ */
+export function visitLightCells(values, i, minX, minZ, cellSize, columns, offsets, data) {
+  const radius = values[i + 3], x = values[i] - minX, z = values[i + 2] - minZ;
+  let y, c, key;
+  for (y = Math.floor((z - radius) / cellSize); y <= Math.floor((z + radius) / cellSize); y++) {
+    for (c = Math.floor((x - radius) / cellSize); c <= Math.floor((x + radius) / cellSize); c++) {
+      key = y * columns + c;
+      if (data) {
+        writeLightCell(values, i, key, offsets, data);
+      } else offsets[key]++;
+    }
+  }
+}

package/src/lighting/visitLightGridCells.js

@@ -1,5 +1,16 @@
 import { visitLightCells } from './visitLightCells.js';
 
+/**
+ * Visit covered grid cells for every packed light.
+ *
+ * @param {Float32Array[]} packed Arrays of packed light records.
+ * @param {number} minX Grid origin on the x axis.
+ * @param {number} minZ Grid origin on the z axis.
+ * @param {number} cellSize Grid cell width.
+ * @param {number} columns Number of grid columns.
+ * @param {Uint32Array} offsets Per-cell counts or write offsets.
+ * @param {Float32Array} [data] Output grid data; omitted during counting.
+ */
 export function visitCells(packed, minX, minZ, cellSize, columns, offsets, data) {
   let values, i;
   for (values of packed) for (i = 0; i < values.length; i += 8) {

package/src/lighting/worldLights.js

@@ -1,6 +1,13 @@
 import { lightScale } from '../globals/lightScale.js';
 
-/** World-space [x, y, z, radius, r, g, b, intensity] for one mesh's point lights. */
+/**
+ * Transform a mesh's point lights to world-space packed records.
+ *
+ * @param {Object[]} lights Local point lights.
+ * @param {number[]|Float32Array} m Column-major world matrix.
+ *
+ * @returns {Float32Array} Records of [x, y, z, radius, r, g, b, intensity].
+ */
 export function worldLights(lights, m) {
   const values = /* alloc */ new Float32Array(lights.length * 8);
   let i, x, y, z, radius, color, flux, w;

package/src/lighting/writeLightCell.js

@@ -1,5 +1,14 @@
-export function writeLightCell(values, i, key, offsets, data) {
-  let j, o;
-  for (j = 0, o = offsets[key] * 4; j < 8; j++) data[o + j] = values[i + j];
-  offsets[key] += 2;
-}
+/**
+ * Copy a packed light record into a cell and advance that cell's write offset.
+ *
+ * @param {Float32Array} values Packed light records.
+ * @param {number} i Starting index of the light record.
+ * @param {number} key Grid cell index.
+ * @param {Uint32Array} offsets Per-cell write offsets in vec4 units.
+ * @param {Float32Array} data Output grid data.
+ */
+export function writeLightCell(values, i, key, offsets, data) {
+  let j, o;
+  for (j = 0, o = offsets[key] * 4; j < 8; j++) data[o + j] = values[i + j];
+  offsets[key] += 2;
+}

package/src/materials/README.md

@@ -0,0 +1,28 @@
+# Materials
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Builds GPU material programs, layouts and uniforms, converts model materials,
+and handles terrain and roof material requirements.
+
+## Material to GPU program
+
+```mermaid
+flowchart LR
+  Model["glTF material"] --> Convert["Convert material"]
+  Convert --> Features["Material features"]
+  Features --> WGSL["Generate WGSL + bindings"]
+  Features --> Layout["Program layout + uniforms"]
+  WGSL --> Program["GPU program / pipeline cache"]
+  Layout --> Program
+  Textures["Texture uploads"] --> Program
+```
+
+Shader declarations, binding order, uniforms and mesh attributes must agree.
+Compilation diagnostics are reported through [gpu](../gpu/README.md).
+
+- [createProgram.js](./createProgram.js): create a material program.
+- [createProgramLayout.js](./createProgramLayout.js): configure GPU bindings.
+- [modelMaterialFor.js](./modelMaterialFor.js): derive materials from model data.
+
+Related: [shaders](../shaders/README.md), [textures](../textures/README.md), [rendering](../rendering/README.md).

package/src/materials/createProgram.js

@@ -1,5 +1,4 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { defaultMaterial } from '../globals/defaultMaterial.js';
 import { vertexShader } from '../globals/vertexShader.js';
 import { fragmentShader } from '../globals/fragmentShader.js';
@@ -12,12 +11,17 @@ import { uVLayout } from '../globals/uVLayout.js';
 import { instanceLayout } from '../globals/instanceLayout.js';
 import { createProgramLayout } from './createProgramLayout.js';
 import { createProgramUniforms } from './createProgramUniforms.js';
-
-
 import { materialShaders } from '../shaders/materialShaders.js';
-
 import { reportCompilation } from '../gpu/reportShaderCompilation.js';
 
+/**
+ * Create shader modules, layouts and uniforms for a layer material.
+ *
+ * @param {L.Layer} layer Layer providing the renderer and shader options.
+ * @param {Object} [material] Material options.
+ *
+ * @returns {Object} Program state and pipeline cache.
+ */
 export function createProgram(layer, material = defaultMaterial) {
   const renderer = rendererByLayer.get(layer), { device } = renderer;
   const shaders = materialShaders(

package/src/materials/createProgramLayout.js

@@ -1,36 +1,44 @@
-import { programLayout } from '../globals/programLayout.js';
-import { programEntries } from '../globals/programEntries.js';
-import { meshLayoutEntry } from '../globals/meshLayoutEntry.js';
-import { frameLayoutEntry } from '../globals/frameLayoutEntry.js';
-import { terrainLayoutEntry } from '../globals/terrainLayoutEntry.js';
-import { textureLayoutEntries } from '../globals/textureLayoutEntries.js';
-import { samplerLayoutEntries } from '../globals/samplerLayoutEntries.js';
-
-export function createProgramLayout(device, shaders) {
-  const bindGroupEntries = programEntries;
-  bindGroupEntries.length = 0;
-  meshLayoutEntry.visibility = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
-  frameLayoutEntry.visibility = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
-  bindGroupEntries.push(meshLayoutEntry, frameLayoutEntry);
-  if (shaders.hasTerrain) {
-    terrainLayoutEntry.visibility = GPUShaderStage.VERTEX;
-    bindGroupEntries.push(terrainLayoutEntry);
-  }
-  let texture, entry, index = 0;
-  for (texture of shaders.bindings) {
-    entry = textureLayoutEntries[index];
-    entry.binding = texture.texture;
-    entry.visibility = GPUShaderStage.FRAGMENT;
-    bindGroupEntries.push(entry);
-    entry = samplerLayoutEntries[index++];
-    entry.binding = texture.sampler;
-    entry.visibility = GPUShaderStage.FRAGMENT;
-    bindGroupEntries.push(entry);
-  }
-  const layout = device.createBindGroupLayout((
-    programLayout.entries = bindGroupEntries,
-    programLayout
-  ));
-  programLayout.entries = null;
-  return layout;
-}
+import { programLayout } from '../globals/programLayout.js';
+import { programEntries } from '../globals/programEntries.js';
+import { meshLayoutEntry } from '../globals/meshLayoutEntry.js';
+import { frameLayoutEntry } from '../globals/frameLayoutEntry.js';
+import { terrainLayoutEntry } from '../globals/terrainLayoutEntry.js';
+import { textureLayoutEntries } from '../globals/textureLayoutEntries.js';
+import { samplerLayoutEntries } from '../globals/samplerLayoutEntries.js';
+
+/**
+ * Create a bind group layout for mesh, frame, terrain and shader texture bindings.
+ *
+ * @param {GPUDevice} device Device creating the layout.
+ * @param {Object} shaders Shader bindings and terrain requirements.
+ *
+ * @returns {GPUBindGroupLayout} The created layout.
+ */
+export function createProgramLayout(device, shaders) {
+  const bindGroupEntries = programEntries;
+  bindGroupEntries.length = 0;
+  meshLayoutEntry.visibility = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
+  frameLayoutEntry.visibility = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
+  bindGroupEntries.push(meshLayoutEntry, frameLayoutEntry);
+  if (shaders.hasTerrain) {
+    terrainLayoutEntry.visibility = GPUShaderStage.VERTEX;
+    bindGroupEntries.push(terrainLayoutEntry);
+  }
+  let texture, entry, index = 0;
+  for (texture of shaders.bindings) {
+    entry = textureLayoutEntries[index];
+    entry.binding = texture.texture;
+    entry.visibility = GPUShaderStage.FRAGMENT;
+    bindGroupEntries.push(entry);
+    entry = samplerLayoutEntries[index++];
+    entry.binding = texture.sampler;
+    entry.visibility = GPUShaderStage.FRAGMENT;
+    bindGroupEntries.push(entry);
+  }
+  const layout = device.createBindGroupLayout((
+    programLayout.entries = bindGroupEntries,
+    programLayout
+  ));
+  programLayout.entries = null;
+  return layout;
+}

package/src/materials/createProgramUniforms.js

@@ -1,18 +1,25 @@
-export function createProgramUniforms(material) {
-  const uniforms = /* alloc */ {
-    baseColor: /* alloc */ { value: material.color || /* alloc */ [1, 1, 1] },
-    metallic: /* alloc */ { value: material.metallic ?? 0 },
-    roughness: /* alloc */ { value: material.roughness ?? 0.85 },
-    opacity: /* alloc */ { value: material.opacity ?? 1 },
-    alphaCutoff: /* alloc */ { value: material.alphaCutoff ?? 0.5 },
-    occlusionStrength: /* alloc */ { value: material.occlusionStrength ?? 1 },
-    emissive: /* alloc */ { value: material.emissive || /* alloc */ [0, 0, 0] },
-  };
-  if (material.baseTexture) uniforms.baseTexture = /* alloc */ { value: material.baseTexture };
-  if (material.metalTexture) uniforms.metalTexture = /* alloc */ { value: material.metalTexture };
-  if (material.emissiveTexture) uniforms.emissiveTexture = /* alloc */ { value: material.emissiveTexture };
-  if (material.occlusionTexture) uniforms.occlusionTexture = /* alloc */ { value: material.occlusionTexture };
-  if (material.roofTexture || material.wallTexture) uniforms.roofTexture = /* alloc */ { value: null };
-  if (material.nativeStroke) uniforms.strokeScale = /* alloc */ { value: 1 };
-  return uniforms;
-}
+/**
+ * Create material uniform values and add bindings for configured textures.
+ *
+ * @param {Object} material Material properties.
+ *
+ * @returns {Object} Uniform values keyed by shader property.
+ */
+export function createProgramUniforms(material) {
+  const uniforms = /* alloc */ {
+    baseColor: /* alloc */ { value: material.color || /* alloc */ [1, 1, 1] },
+    metallic: /* alloc */ { value: material.metallic ?? 0 },
+    roughness: /* alloc */ { value: material.roughness ?? 0.85 },
+    opacity: /* alloc */ { value: material.opacity ?? 1 },
+    alphaCutoff: /* alloc */ { value: material.alphaCutoff ?? 0.5 },
+    occlusionStrength: /* alloc */ { value: material.occlusionStrength ?? 1 },
+    emissive: /* alloc */ { value: material.emissive || /* alloc */ [0, 0, 0] },
+  };
+  if (material.baseTexture) uniforms.baseTexture = /* alloc */ { value: material.baseTexture };
+  if (material.metalTexture) uniforms.metalTexture = /* alloc */ { value: material.metalTexture };
+  if (material.emissiveTexture) uniforms.emissiveTexture = /* alloc */ { value: material.emissiveTexture };
+  if (material.occlusionTexture) uniforms.occlusionTexture = /* alloc */ { value: material.occlusionTexture };
+  if (material.roofTexture || material.wallTexture) uniforms.roofTexture = /* alloc */ { value: null };
+  if (material.nativeStroke) uniforms.strokeScale = /* alloc */ { value: 1 };
+  return uniforms;
+}

package/src/materials/modelMaterialFor.js

@@ -1,21 +1,29 @@
-import { textureFor } from '../textures/modelTextureFor.js';
-
-export function materialFor(context, material) {
-  const { backend: layer } = context;
-  const pbr = material.pbrMetallicRoughness;
-  return /* alloc */ {
-    color: pbr?.baseColorFactor ? pbr.baseColorFactor.slice(0, 3) : /* alloc */ [1, 1, 1],
-    opacity: pbr?.baseColorFactor?.[3] ?? 1,
-    metallic: pbr?.metallicFactor ?? 1,
-    roughness: pbr?.roughnessFactor ?? 1,
-    baseTexture: textureFor(context, pbr?.baseColorTexture, true),
-    metalTexture: textureFor(context, pbr?.metallicRoughnessTexture),
-    emissiveTexture: textureFor(context, material.emissiveTexture, true),
-    occlusionTexture: textureFor(context, material.occlusionTexture),
-    emissive: material.emissiveFactor || /* alloc */ [0, 0, 0],
-    occlusionStrength: material.occlusionTexture?.strength ?? 1,
-    alphaMode: layer.options.alphaMode || material.alphaMode || 'OPAQUE',
-    alphaCutoff: material.alphaCutoff ?? 0.5,
-    doubleSided: material.doubleSided,
-  };
-}
+import { textureFor } from '../textures/modelTextureFor.js';
+
+/**
+ * Translate a glTF material into renderer material properties and texture bindings.
+ *
+ * @param {Object} context Model loading context and backend layer.
+ * @param {Object} material glTF material definition.
+ *
+ * @returns {Object} Renderer material properties.
+ */
+export function materialFor(context, material) {
+  const { backend: layer } = context;
+  const pbr = material.pbrMetallicRoughness;
+  return /* alloc */ {
+    color: pbr?.baseColorFactor ? pbr.baseColorFactor.slice(0, 3) : /* alloc */ [1, 1, 1],
+    opacity: pbr?.baseColorFactor?.[3] ?? 1,
+    metallic: pbr?.metallicFactor ?? 1,
+    roughness: pbr?.roughnessFactor ?? 1,
+    baseTexture: textureFor(context, pbr?.baseColorTexture, true),
+    metalTexture: textureFor(context, pbr?.metallicRoughnessTexture),
+    emissiveTexture: textureFor(context, material.emissiveTexture, true),
+    occlusionTexture: textureFor(context, material.occlusionTexture),
+    emissive: material.emissiveFactor || /* alloc */ [0, 0, 0],
+    occlusionStrength: material.occlusionTexture?.strength ?? 1,
+    alphaMode: layer.options.alphaMode || material.alphaMode || 'OPAQUE',
+    alphaCutoff: material.alphaCutoff ?? 0.5,
+    doubleSided: material.doubleSided,
+  };
+}

package/src/materials/prepareMeshCutout.js

@@ -1,12 +1,21 @@
-export function prepareMeshCutout(renderer, mesh, base) {
-  const data = renderer.uniformData;
-  const cutout = (mesh._nativeSource || mesh._rasterSource)?.options.cutout;
-  if (cutout && (!Number.isFinite(cutout.x) || !Number.isFinite(cutout.y) ||
-      !Number.isFinite(cutout.radius) || cutout.radius < 0)) {
-    throw /* alloc */ new Error('cutout requires finite x, y and a non-negative radius in CSS pixels');
-  }
-  data[base + 36] = (cutout?.x ?? 0) * renderer.dpr;
-  data[base + 37] = (cutout?.y ?? 0) * renderer.dpr;
-  data[base + 38] = (cutout?.radius ?? 0) * renderer.dpr;
-  data[base + 39] = cutout?.outside ? 1 : 0;
-}
+/**
+ * Validate and write native or raster cutout settings into the mesh uniform buffer.
+ *
+ * @param {Object} renderer Renderer containing uniform data and pixel ratio.
+ * @param {Object} mesh Mesh with optional native or raster source.
+ * @param {number} base Starting index in the uniform array.
+ *
+ * @throws {Error} If cutout coordinates or radius are invalid.
+ */
+export function prepareMeshCutout(renderer, mesh, base) {
+  const data = renderer.uniformData;
+  const cutout = (mesh._nativeSource || mesh._rasterSource)?.options.cutout;
+  if (cutout && (!Number.isFinite(cutout.x) || !Number.isFinite(cutout.y) ||
+      !Number.isFinite(cutout.radius) || cutout.radius < 0)) {
+    throw /* alloc */ new Error('cutout requires finite x, y and a non-negative radius in CSS pixels');
+  }
+  data[base + 36] = (cutout?.x ?? 0) * renderer.dpr;
+  data[base + 37] = (cutout?.y ?? 0) * renderer.dpr;
+  data[base + 38] = (cutout?.radius ?? 0) * renderer.dpr;
+  data[base + 39] = cutout?.outside ? 1 : 0;
+}

package/src/materials/terrainRasterProgram.js

@@ -5,54 +5,61 @@ import { terrainBoundsByLayer } from '../weakmaps/terrainBoundsByLayer.js';
 import { terrainGridsByLayer } from '../weakmaps/terrainGridsByLayer.js';
 import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevationByLayer.js';
 import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
+import { demTexture } from '../globals/demTexture.js';
+import { demTarget } from '../globals/demTarget.js';
+import { demLayout } from '../globals/demLayout.js';
+import { demSize } from '../globals/demSize.js';
+import { createProgram } from './createProgram.js';
+import { destroyTexture } from '../textures/destroyTexture.js';
+import { terrainAtlas } from '../terrain/terrainAtlas.js';
 
-import { demTexture } from '../globals/demTexture.js';
-import { demTarget } from '../globals/demTarget.js';
-import { demLayout } from '../globals/demLayout.js';
-import { demSize } from '../globals/demSize.js';
-import { createProgram } from './createProgram.js';
-import { destroyTexture } from '../textures/destroyTexture.js';
-import { terrainAtlas } from '../terrain/terrainAtlas.js';
-
-export function rasterProgram(layer, texture) {
-  const device = rendererByLayer.get(layer).device
-  if (rasterProgramByLayer.get(layer)?.device === device) return rasterProgramByLayer.get(layer);
-  // DEM atlas over the archive's tile grid; invalid or missing samples become -1e9 (the shader's no-data).
-  // ponytail: one texture, capped by maxTextureDimension2D (32x32 DEM tiles at 8192 px); split it for larger archives.
-  const bounds = terrainBoundsByLayer.get(layer), columns = bounds.max.x - bounds.min.x + 1, rows = bounds.max.y - bounds.min.y + 1;
-  const { elevations, low, high } = terrainAtlas(terrainTilesByLayer.get(layer), bounds);
-  if (demByLayer.get(layer)) destroyTexture(layer, demByLayer.get(layer).texture);
-  demByLayer.set(layer, /* alloc */ {
-    texture: device.createTexture((
-      demTexture.size[0] = columns * 256,
-      demTexture.size[1] = rows * 256,
-      demTexture.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-      demTexture
-    )),
-    low: Number.isFinite(low) ? low : terrainOriginElevationByLayer.get(layer),
-    high: Number.isFinite(high) ? high : terrainOriginElevationByLayer.get(layer),
-  });
-  device.queue.writeTexture((
-    demTarget.texture = demByLayer.get(layer).texture,
-    demTarget
-  ), elevations,
-    (
-      demLayout.bytesPerRow = columns * 1024,
-      demLayout
-    ), (
-      demSize[0] = columns * 256,
-      demSize[1] = rows * 256,
-      demSize
-    ));
-  demTarget.texture = null;
-  terrainGridsByLayer.set(layer, /* alloc */ new Map());
-  rasterProgramByLayer.set(layer, createProgram(layer, /* alloc */ {
-    baseTexture: texture,
-    unlit: true,
-    terrain: demByLayer.get(layer),
-    alphaMode: 'BLEND',
-    depthWrite: true,
-    doubleSided: layer.options.doubleSided,
-  }));
-  return rasterProgramByLayer.get(layer);
-}
+/**
+ * Reuse the current terrain raster program or create it with an uploaded elevation atlas.
+ *
+ * @param {L.Layer} layer Layer providing terrain and renderer state.
+ * @param {Object} texture Raster texture used by the program.
+ *
+ * @returns {Object} Terrain raster program.
+ */
+export function rasterProgram(layer, texture) {
+  const device = rendererByLayer.get(layer).device
+  if (rasterProgramByLayer.get(layer)?.device === device) return rasterProgramByLayer.get(layer);
+  // DEM atlas over the archive's tile grid; invalid or missing samples become -1e9 (the shader's no-data).
+  // ponytail: one texture, capped by maxTextureDimension2D (32x32 DEM tiles at 8192 px); split it for larger archives.
+  const bounds = terrainBoundsByLayer.get(layer), columns = bounds.max.x - bounds.min.x + 1, rows = bounds.max.y - bounds.min.y + 1;
+  const { elevations, low, high } = terrainAtlas(terrainTilesByLayer.get(layer), bounds);
+  if (demByLayer.get(layer)) destroyTexture(layer, demByLayer.get(layer).texture);
+  demByLayer.set(layer, /* alloc */ {
+    texture: device.createTexture((
+      demTexture.size[0] = columns * 256,
+      demTexture.size[1] = rows * 256,
+      demTexture.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      demTexture
+    )),
+    low: Number.isFinite(low) ? low : terrainOriginElevationByLayer.get(layer),
+    high: Number.isFinite(high) ? high : terrainOriginElevationByLayer.get(layer),
+  });
+  device.queue.writeTexture((
+    demTarget.texture = demByLayer.get(layer).texture,
+    demTarget
+  ), elevations,
+    (
+      demLayout.bytesPerRow = columns * 1024,
+      demLayout
+    ), (
+      demSize[0] = columns * 256,
+      demSize[1] = rows * 256,
+      demSize
+    ));
+  demTarget.texture = null;
+  terrainGridsByLayer.set(layer, /* alloc */ new Map());
+  rasterProgramByLayer.set(layer, createProgram(layer, /* alloc */ {
+    baseTexture: texture,
+    unlit: true,
+    terrain: demByLayer.get(layer),
+    alphaMode: 'BLEND',
+    depthWrite: true,
+    doubleSided: layer.options.doubleSided,
+  }));
+  return rasterProgramByLayer.get(layer);
+}

package/src/materials/validateRoofMaterial.js

@@ -1,10 +1,17 @@
-export function validateRoofMaterial(material) {
-  let name, value;
-  for (name of /* alloc */ ['roofTexture', 'wallTexture']) {
-    value = material[name];
-    if (value !== undefined && typeof value !== 'boolean' &&
-      (!Number.isFinite(value) || value < 0 || value > 1)) {
-      throw /* alloc */ new Error(`${name} must be a boolean or a finite number between 0 and 1`);
-    }
-  }
-}
+/**
+ * Validate the optional roof and wall texture material settings.
+ *
+ * @param {Object} material Material containing texture settings.
+ *
+ * @throws {Error} If a texture setting is not a boolean or a finite number from 0 to 1.
+ */
+export function validateRoofMaterial(material) {
+  let name, value;
+  for (name of /* alloc */ ['roofTexture', 'wallTexture']) {
+    value = material[name];
+    if (value !== undefined && typeof value !== 'boolean' &&
+      (!Number.isFinite(value) || value < 0 || value > 1)) {
+      throw /* alloc */ new Error(`${name} must be a boolean or a finite number between 0 and 1`);
+    }
+  }
+}