leaflet-city-mapper 0.0.9 → 0.1.1

package/src/shaders/materialBaseShader.js

@@ -1,17 +1,26 @@
-export function materialBaseShader(material, hasBase, hasRoof) {
-  return /* wgsl */ `
-      var normal = normalize(input.normal) * select(-1.0, 1.0, frontFacing);
-      let texel = ${hasBase ? 'textureSample(baseTexture, baseTextureSampler, input.uv)' : 'vec4<f32>(1.0)'};
-      let alpha = u.material.z * texel.a;
-      ${material.alphaMode === 'MASK' ? 'if (alpha < u.material.w) { discard; }' : ''}
-      ${material.alphaMode === 'BLEND' ? 'if (alpha < 0.01) { discard; }' : ''}
-      var base = ${material.vertexColors ? 'toLinear(min(input.color, vec3<f32>(1.0)))' : 'input.color'} *
-        ${material.baseTexture?.srgb ? 'texel.rgb' : 'toLinear(texel.rgb)'};
-      ${hasRoof ? /* wgsl */ `
-        if (input.roof > 0.0 && all(input.roofUv >= vec2<f32>(0.0)) &&
-          all(input.roofUv <= vec2<f32>(1.0))) {
-          let roof = textureSampleLevel(roofTexture, roofTextureSampler, input.roofUv, 0.0);
-          base = mix(base, toLinear(roof.rgb), roof.a * input.roof);
-        }
-      ` : ''}`;
-}
+/**
+ * Generate fragment code for base color, alpha and optional roof texture.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} hasBase Whether a base texture is bound.
+ * @param {boolean} hasRoof Whether a roof texture is bound.
+ *
+ * @returns {string} WGSL fragment code.
+ */
+export function materialBaseShader(material, hasBase, hasRoof) {
+  return /* wgsl */ `
+      var normal = normalize(input.normal) * select(-1.0, 1.0, frontFacing);
+      let texel = ${hasBase ? 'textureSample(baseTexture, baseTextureSampler, input.uv)' : 'vec4<f32>(1.0)'};
+      let alpha = u.material.z * texel.a;
+      ${material.alphaMode === 'MASK' ? 'if (alpha < u.material.w) { discard; }' : ''}
+      ${material.alphaMode === 'BLEND' ? 'if (alpha < 0.01) { discard; }' : ''}
+      var base = ${material.vertexColors ? 'toLinear(min(input.color, vec3<f32>(1.0)))' : 'input.color'} *
+        ${material.baseTexture?.srgb ? 'texel.rgb' : 'toLinear(texel.rgb)'};
+      ${hasRoof ? /* wgsl */ `
+        if (input.roof > 0.0 && all(input.roofUv >= vec2<f32>(0.0)) &&
+          all(input.roofUv <= vec2<f32>(1.0))) {
+          let roof = textureSampleLevel(roofTexture, roofTextureSampler, input.roofUv, 0.0);
+          base = mix(base, toLinear(roof.rgb), roof.a * input.roof);
+        }
+      ` : ''}`;
+}

package/src/shaders/materialShaders.js

@@ -4,7 +4,15 @@ import { validateRoofMaterial } from '../materials/validateRoofMaterial.js';
 import { materialVertexShader } from './materialVertexShader.js';
 import { materialSurfaceShader } from './materialSurfaceShader.js';
 
-/** Material WGSL and texture bindings, without a GPU device or Leaflet layer. */
+/**
+ * Generate material WGSL and texture bindings without a GPU device or Leaflet layer.
+ *
+ * @param {Object} [material] Material settings.
+ * @param {boolean} [sparkle=false] Whether to include sparkle coordinates and shading.
+ * @param {string} [elevationWGSL=''] Terrain elevation WGSL functions.
+ *
+ * @returns {Object} Vertex and fragment shaders, texture bindings and feature flags.
+ */
 export function materialShaders(material = defaultMaterial, sparkle = false, elevationWGSL = '') {
   const hasBase = Boolean(material.baseTexture);
   const hasMetal = Boolean(material.metalTexture);

package/src/shaders/materialSurfaceShader.js

@@ -1,47 +1,60 @@
-import { materialBaseShader } from './materialBaseShader.js';
-
-export function materialSurfaceShader(material, sparkle, hasBase, hasMetal, hasEmissive, hasOcclusion, hasRoof) {
-  return material.unlit ? /* wgsl */ `
-        let rasterTexel = ${hasBase ? 'textureSample(baseTexture, baseTextureSampler, input.uv)' : 'vec4<f32>(input.color, 1.0)'};
-        return vec4<f32>(toSRGB(toLinear(rasterTexel.rgb) * (frame.atmosphereTint.rgb * (0.55 + 0.45 * sunlight) + artificial)), ${material.alphaMode === 'BLEND' ? 'u.material.z * rasterTexel.a' : '1.0'});
-      ` : /* wgsl */ `${materialBaseShader(material, hasBase, hasRoof)}
-      let mr = ${hasMetal ? 'textureSample(metalTexture, metalTextureSampler, input.uv)' : 'vec4<f32>(1.0)'};
-      let metal = clamp(u.material.x * mr.b, 0.0, 1.0);
-      let rough = clamp(u.material.y * mr.g, 0.08, 1.0);
-      let view = normalize(-input.viewPosition);
-      let halfVector = normalize(view + frame.lightDirection.xyz);
-      let nl = max(dot(normal, frame.lightDirection.xyz), 0.0) * frame.lightDirection.w * sunlight;
-      let nv = max(dot(normal, view), 0.001);
-      let nh = max(dot(normal, halfVector), 0.0);
-      let vh = max(dot(view, halfVector), 0.0);
-      let a2 = pow(rough, 4.0);
-      let d = a2 / max(PI * pow(nh * nh * (a2 - 1.0) + 1.0, 2.0), 0.0001);
-      let gv = nl * sqrt(nv * nv * (1.0 - a2) + a2);
-      let gl = nv * sqrt(nl * nl * (1.0 - a2) + a2);
-      let visibility = 0.5 / max(gv + gl, 0.0001);
-      let f0 = mix(vec3<f32>(0.04), base, metal);
-      let fresnel = f0 + (1.0 - f0) * pow(1.0 - vh, 5.0);
-      let specular = d * visibility * fresnel;
-      let diffuse = (1.0 - metal) * base / PI;
-      let sky = dot(normal, frame.skyDirection.xyz) * 0.5 + 0.5;
-      let ambient = mix(toLinear(vec3<f32>(0.455, 0.412, 0.322)), vec3<f32>(1.0), sky) * (2.0 / PI);
-      let ao = ${hasOcclusion ? 'mix(1.0, textureSample(occlusionTexture, occlusionTextureSampler, input.uv).r, u.emissive.w)' : '1.0'};
-      ${sparkle ? /* wgsl */ `
-        let lattice = (fract(input.localPosition / 2.5) - 0.5) * 2.5;
-        let pointGlow = (1.0 - smoothstep(0.16, 0.42, length(lattice))) * u.highlight.z;
-      ` : ''}
-      // Vertex colour components above 1 are self-lit (e.g. vehicle lamps): dim by day, bright at night.
-      let glow = ${sparkle ? 'vec3<f32>(3.0, 2.6, 1.8) * pointGlow +' : ''}${material.vertexColors
-      ? ' max(input.color - vec3<f32>(1.0), vec3<f32>(0.0)) * (0.3 + 5.0 * frame.skyDirection.w) +' : ''} u.emissive.rgb * ${hasEmissive
-      ? material.emissiveTexture.srgb
-        ? 'textureSample(emissiveTexture, emissiveTextureSampler, input.uv).rgb'
-        : 'toLinear(textureSample(emissiveTexture, emissiveTextureSampler, input.uv).rgb)'
-      : 'vec3<f32>(1.0)'};
-      var color = ambient * base * (1.0 - metal) * ao +
-        (diffuse + specular) * nl * toLinear(vec3<f32>(1.0, 0.937, 0.835)) * 3.0 + glow;
-      ${material.vertexColors ? 'color = base * (ambient + toLinear(vec3<f32>(1.0, 0.937, 0.835)) * (3.0 / PI) * nl) + glow;' : ''}
-      color = (color - glow) * frame.atmosphereTint.rgb + base * artificial * (1.0 - metal * 0.5) + glow;
-      appearance(input.position.xy);
-      return vec4<f32>(toSRGB(color), ${material.alphaMode === 'BLEND' ? 'alpha' : '1.0'});
-      `;
-}
+import { materialBaseShader } from './materialBaseShader.js';
+
+/**
+ * Generate lit or unlit material fragment code for the available textures.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} sparkle Whether to include sparkle shading.
+ * @param {boolean} hasBase Whether a base texture is bound.
+ * @param {boolean} hasMetal Whether a metallic-roughness texture is bound.
+ * @param {boolean} hasEmissive Whether an emissive texture is bound.
+ * @param {boolean} hasOcclusion Whether an occlusion texture is bound.
+ * @param {boolean} hasRoof Whether a roof texture is bound.
+ *
+ * @returns {string} WGSL fragment code.
+ */
+export function materialSurfaceShader(material, sparkle, hasBase, hasMetal, hasEmissive, hasOcclusion, hasRoof) {
+  return material.unlit ? /* wgsl */ `
+        let rasterTexel = ${hasBase ? 'textureSample(baseTexture, baseTextureSampler, input.uv)' : 'vec4<f32>(input.color, 1.0)'};
+        return vec4<f32>(toSRGB(toLinear(rasterTexel.rgb) * (frame.atmosphereTint.rgb * (0.55 + 0.45 * sunlight) + artificial)), ${material.alphaMode === 'BLEND' ? 'u.material.z * rasterTexel.a' : '1.0'});
+      ` : /* wgsl */ `${materialBaseShader(material, hasBase, hasRoof)}
+      let mr = ${hasMetal ? 'textureSample(metalTexture, metalTextureSampler, input.uv)' : 'vec4<f32>(1.0)'};
+      let metal = clamp(u.material.x * mr.b, 0.0, 1.0);
+      let rough = clamp(u.material.y * mr.g, 0.08, 1.0);
+      let view = normalize(-input.viewPosition);
+      let halfVector = normalize(view + frame.lightDirection.xyz);
+      let nl = max(dot(normal, frame.lightDirection.xyz), 0.0) * frame.lightDirection.w * sunlight;
+      let nv = max(dot(normal, view), 0.001);
+      let nh = max(dot(normal, halfVector), 0.0);
+      let vh = max(dot(view, halfVector), 0.0);
+      let a2 = pow(rough, 4.0);
+      let d = a2 / max(PI * pow(nh * nh * (a2 - 1.0) + 1.0, 2.0), 0.0001);
+      let gv = nl * sqrt(nv * nv * (1.0 - a2) + a2);
+      let gl = nv * sqrt(nl * nl * (1.0 - a2) + a2);
+      let visibility = 0.5 / max(gv + gl, 0.0001);
+      let f0 = mix(vec3<f32>(0.04), base, metal);
+      let fresnel = f0 + (1.0 - f0) * pow(1.0 - vh, 5.0);
+      let specular = d * visibility * fresnel;
+      let diffuse = (1.0 - metal) * base / PI;
+      let sky = dot(normal, frame.skyDirection.xyz) * 0.5 + 0.5;
+      let ambient = mix(toLinear(vec3<f32>(0.455, 0.412, 0.322)), vec3<f32>(1.0), sky) * (2.0 / PI);
+      let ao = ${hasOcclusion ? 'mix(1.0, textureSample(occlusionTexture, occlusionTextureSampler, input.uv).r, u.emissive.w)' : '1.0'};
+      ${sparkle ? /* wgsl */ `
+        let lattice = (fract(input.localPosition / 2.5) - 0.5) * 2.5;
+        let pointGlow = (1.0 - smoothstep(0.16, 0.42, length(lattice))) * u.highlight.z;
+      ` : ''}
+      // Vertex colour components above 1 are self-lit (e.g. vehicle lamps): dim by day, bright at night.
+      let glow = ${sparkle ? 'vec3<f32>(3.0, 2.6, 1.8) * pointGlow +' : ''}${material.vertexColors
+      ? ' max(input.color - vec3<f32>(1.0), vec3<f32>(0.0)) * (0.3 + 5.0 * frame.skyDirection.w) +' : ''} u.emissive.rgb * ${hasEmissive
+      ? material.emissiveTexture.srgb
+        ? 'textureSample(emissiveTexture, emissiveTextureSampler, input.uv).rgb'
+        : 'toLinear(textureSample(emissiveTexture, emissiveTextureSampler, input.uv).rgb)'
+      : 'vec3<f32>(1.0)'};
+      var color = ambient * base * (1.0 - metal) * ao +
+        (diffuse + specular) * nl * toLinear(vec3<f32>(1.0, 0.937, 0.835)) * 3.0 + glow;
+      ${material.vertexColors ? 'color = base * (ambient + toLinear(vec3<f32>(1.0, 0.937, 0.835)) * (3.0 / PI) * nl) + glow;' : ''}
+      color = (color - glow) * frame.atmosphereTint.rgb + base * artificial * (1.0 - metal * 0.5) + glow;
+      appearance(input.position.xy);
+      return vec4<f32>(toSRGB(color), ${material.alphaMode === 'BLEND' ? 'alpha' : '1.0'});
+      `;
+}

package/src/shaders/materialVertexShader.js

@@ -1,77 +1,89 @@
-import { roofVertexShader } from './roofVertexShader.js';
-import { nativeStrokeShader } from './nativeStrokeShader.js';
-
-export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrain, textured, hasRoof) {
-  const instanceOffset = material.instanced ? ' + input.instanceOffset.xyz' : '';
-  const stroke = nativeStrokeShader(material);
-  return /* wgsl */ `
-    struct Mesh {
-      worldMatrix: mat4x4<f32>,
-      baseColor: vec4<f32>,
-      material: vec4<f32>,
-      emissive: vec4<f32>,
-      terrain: vec4<f32>,
-      highlight: vec4<f32>,
-      cutout: vec4<f32>,
-      nativeStroke: vec4<f32>,
-    };
-    struct Frame {
-      viewMatrix: mat4x4<f32>,
-      projectionMatrix: mat4x4<f32>,
-      roofMatrix: mat4x4<f32>,
-      lightDirection: vec4<f32>,
-      skyDirection: vec4<f32>,
-      atmosphereTint: vec4<f32>,
-    };
-    @group(0) @binding(0) var<uniform> u: Mesh;
-    @group(0) @binding(1) var<uniform> frame: Frame;
-    struct Solar { matrix: mat4x4<f32>, params: vec4<f32> };
-    @group(1) @binding(0) var<uniform> solar: Solar;
-    ${hasTerrain ? /* wgsl */ `@group(0) @binding(2) var dem: texture_2d<f32>;${elevationWGSL}` : ''}
-    struct VertexInput {
-      @location(0) position: vec3<f32>,
-      @location(1) normal: vec3<f32>,
-      ${material.instanced ? '@location(4) instanceOffset: vec4<f32>,' : ''}
-      ${material.vertexColors ? '@location(2) color: vec3<f32>,' : ''}
-      ${textured ? '@location(3) uv: vec2<f32>,' : ''}
-    };
-    struct VertexOutput {
-      @builtin(position) position: vec4<f32>,
-      @location(0) color: vec3<f32>,
-      @location(1) normal: vec3<f32>,
-      @location(2) viewPosition: vec3<f32>,
-      @location(6) shadowPosition: vec4<f32>,
-      @location(7) worldPosition: vec3<f32>,
-      ${sparkle ? '@location(8) localPosition: vec3<f32>,' : ''}
-      ${textured ? '@location(3) uv: vec2<f32>,' : ''}
-      ${hasRoof ? '@location(4) roofUv: vec2<f32>, @location(5) roof: f32,' : ''}
-    };
-    @vertex fn vertexMain(input: VertexInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
-      var output: VertexOutput;
-      var position = input.position${instanceOffset};
-      ${stroke.position}
-      ${hasTerrain ? 'position.y = elevation(u.terrain.xy + input.uv * u.terrain.z, u.terrain.w) - u.terrain.w;' : ''}
-      let featureVertex = f32(vertexIndex)${material.instanced ? ' + input.instanceOffset.w' : ''};
-      let highlighted = featureVertex >= u.highlight.x && featureVertex < u.highlight.y;
-      output.color = ${material.vertexColors
-      ? 'select(input.color, vec3<f32>(72.0 / 255.0, 217.0 / 255.0, 1.0), highlighted)'
-      : 'u.baseColor.rgb'};
-      // Inverse-transpose from cofactors; the camera view matrix is orthonormal.
-      let m = mat3x3<f32>(u.worldMatrix[0].xyz, u.worldMatrix[1].xyz, u.worldMatrix[2].xyz);
-      ${stroke.normal}
-      let normal = (cross(m[1], m[2]) * sourceNormal.x + cross(m[2], m[0]) * sourceNormal.y +
-        cross(m[0], m[1]) * sourceNormal.z) / determinant(m);
-      output.normal = (frame.viewMatrix * vec4<f32>(normal, 0.0)).xyz;
-      let world = u.worldMatrix * vec4<f32>(position, 1.0);
-      output.shadowPosition = solar.matrix * world;
-      output.worldPosition = world.xyz / world.w;
-      ${sparkle ? `output.localPosition = input.position${instanceOffset};` : ''}
-      let viewPosition = frame.viewMatrix * world;
-      output.viewPosition = viewPosition.xyz;
-      ${textured ? 'output.uv = input.uv;' : ''}
-      ${hasRoof ? roofVertexShader(material) : ''}
-      output.position = frame.projectionMatrix * viewPosition;
-      return output;
-    }
-  `;
-}
+import { roofVertexShader } from './roofVertexShader.js';
+import { nativeStrokeShader } from './nativeStrokeShader.js';
+
+/**
+ * Generate a vertex shader for the material and its enabled rendering features.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} sparkle Whether to output local sparkle coordinates.
+ * @param {string} elevationWGSL Terrain elevation WGSL functions.
+ * @param {boolean} hasTerrain Whether terrain elevation is enabled.
+ * @param {boolean} textured Whether texture coordinates are needed.
+ * @param {boolean} hasRoof Whether roof texture coordinates are needed.
+ *
+ * @returns {string} WGSL vertex shader.
+ */
+export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrain, textured, hasRoof) {
+  const instanceOffset = material.instanced ? ' + input.instanceOffset.xyz' : '';
+  const stroke = nativeStrokeShader(material);
+  return /* wgsl */ `
+    struct Mesh {
+      worldMatrix: mat4x4<f32>,
+      baseColor: vec4<f32>,
+      material: vec4<f32>,
+      emissive: vec4<f32>,
+      terrain: vec4<f32>,
+      highlight: vec4<f32>,
+      cutout: vec4<f32>,
+      nativeStroke: vec4<f32>,
+    };
+    struct Frame {
+      viewMatrix: mat4x4<f32>,
+      projectionMatrix: mat4x4<f32>,
+      roofMatrix: mat4x4<f32>,
+      lightDirection: vec4<f32>,
+      skyDirection: vec4<f32>,
+      atmosphereTint: vec4<f32>,
+    };
+    struct Solar {
+      matrix: mat4x4<f32>,
+      params: vec4<f32>
+    };
+    struct VertexInput {
+      @location(0) position: vec3<f32>,
+      @location(1) normal: vec3<f32>,
+      ${material.instanced ? '@location(4) instanceOffset: vec4<f32>,' : ''}
+      ${material.vertexColors ? '@location(2) color: vec3<f32>,' : ''}
+      ${textured ? '@location(3) uv: vec2<f32>,' : ''}
+    };
+    struct VertexOutput {
+      @builtin(position) position: vec4<f32>,
+      @location(0) color: vec3<f32>,
+      @location(1) normal: vec3<f32>,
+      @location(2) viewPosition: vec3<f32>,
+      @location(6) shadowPosition: vec4<f32>,
+      @location(7) worldPosition: vec3<f32>,
+      ${sparkle ? '@location(8) localPosition: vec3<f32>,' : ''}
+      ${textured ? '@location(3) uv: vec2<f32>,' : ''}
+      ${hasRoof ? '@location(4) roofUv: vec2<f32>, @location(5) roof: f32,' : ''}
+    };
+    @group(0) @binding(0) var<uniform> u: Mesh;
+    @group(0) @binding(1) var<uniform> frame: Frame;
+    @group(1) @binding(0) var<uniform> solar: Solar;
+    ${hasTerrain ? /* wgsl */ `@group(0) @binding(2) var dem: texture_2d<f32>;${elevationWGSL}` : ''}
+    @vertex fn vertexMain(input: VertexInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+      var output: VertexOutput;
+      var position = input.position${instanceOffset};
+      ${stroke.position}
+      ${hasTerrain ? 'position.y = elevation(u.terrain.xy + input.uv * u.terrain.z, u.terrain.w) - u.terrain.w;' : ''}
+      let featureVertex = f32(vertexIndex)${material.instanced ? ' + input.instanceOffset.w' : ''};
+      let highlighted = featureVertex >= u.highlight.x && featureVertex < u.highlight.y;
+      output.color = ${material.vertexColors ? 'select(input.color, vec3<f32>(72.0 / 255.0, 217.0 / 255.0, 1.0), highlighted)' : 'u.baseColor.rgb'};
+      // Inverse-transpose from cofactors; the camera view matrix is orthonormal.
+      let m = mat3x3<f32>(u.worldMatrix[0].xyz, u.worldMatrix[1].xyz, u.worldMatrix[2].xyz);
+      ${stroke.normal}
+      let normal = (cross(m[1], m[2]) * sourceNormal.x + cross(m[2], m[0]) * sourceNormal.y + cross(m[0], m[1]) * sourceNormal.z) / determinant(m);
+      output.normal = (frame.viewMatrix * vec4<f32>(normal, 0.0)).xyz;
+      let world = u.worldMatrix * vec4<f32>(position, 1.0);
+      output.shadowPosition = solar.matrix * world;
+      output.worldPosition = world.xyz / world.w;
+      ${sparkle ? `output.localPosition = input.position${instanceOffset};` : ''}
+      let viewPosition = frame.viewMatrix * world;
+      output.viewPosition = viewPosition.xyz;
+      ${textured ? 'output.uv = input.uv;' : ''}
+      ${hasRoof ? roofVertexShader(material) : ''}
+      output.position = frame.projectionMatrix * viewPosition;
+      return output;
+    }
+  `;
+}

package/src/shaders/nativeStrokeShader.js

@@ -1,6 +1,13 @@
-export function nativeStrokeShader(material) {
-  return /* alloc */ {
-    position: material.nativeStroke ? 'position = input.normal + (input.position - input.normal) * u.nativeStroke.x;' : '',
-    normal: material.nativeStroke ? 'let sourceNormal = vec3<f32>(0.0, 1.0, 0.0);' : 'let sourceNormal = input.normal;',
-  };
-}
+/**
+ * Generate optional native-stroke position and normal vertex snippets.
+ *
+ * @param {Object} material Material settings.
+ *
+ * @returns {Object} WGSL position and normal snippets.
+ */
+export function nativeStrokeShader(material) {
+  return /* alloc */ {
+    position: material.nativeStroke ? 'position = input.normal + (input.position - input.normal) * u.nativeStroke.x;' : '',
+    normal: material.nativeStroke ? 'let sourceNormal = vec3<f32>(0.0, 1.0, 0.0);' : 'let sourceNormal = input.normal;',
+  };
+}

package/src/shaders/roofVertexShader.js

@@ -1,9 +1,16 @@
-export function roofVertexShader(material) {
-  const roofOpacity = Number(material.roofTexture ?? 0);
-  const wallOpacity = Number(material.wallTexture ?? 0);
-  return /* wgsl */ `
-        output.roofUv = (frame.roofMatrix * world).xz;
-        output.roof = select(0.0, select(${wallOpacity.toFixed(8)}, ${roofOpacity.toFixed(8)}, input.normal.y >= 0.5), ((${Boolean(material.roofTexture)} && input.normal.y >= 0.5) ||
-          (${Boolean(material.wallTexture)} && abs(input.normal.y) < 0.5)) && !highlighted);
-      `;
-}
+/**
+ * Generate vertex code for roof and wall texture coordinates and opacity.
+ *
+ * @param {Object} material Roof and wall texture settings.
+ *
+ * @returns {string} WGSL vertex code.
+ */
+export function roofVertexShader(material) {
+  const roofOpacity = Number(material.roofTexture ?? 0);
+  const wallOpacity = Number(material.wallTexture ?? 0);
+  return /* wgsl */ `
+        output.roofUv = (frame.roofMatrix * world).xz;
+        output.roof = select(0.0, select(${wallOpacity.toFixed(8)}, ${roofOpacity.toFixed(8)}, input.normal.y >= 0.5), ((${Boolean(material.roofTexture)} && input.normal.y >= 0.5) ||
+          (${Boolean(material.wallTexture)} && abs(input.normal.y) < 0.5)) && !highlighted);
+      `;
+}

package/src/shadows/README.md

@@ -0,0 +1,28 @@
+# Shadows
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Creates and renders directional sunlight shadow maps, with cached camera and
+mesh state to avoid unnecessary redraws.
+
+## Shadow pass and cache
+
+```mermaid
+flowchart LR
+  Sun["Sun position"] --> Check{"Casters + sun altitude ≥ 3°?"}
+  Meshes["Loaded shadow casters"] --> Check
+  Check -->|no| Disable["Disable shadow pass"]
+  Check -->|yes| Cache{"Cache matches?"}
+  Cache -->|yes| Reuse["Reuse depth map"]
+  Cache -->|no| Draw["Fit matrix + render depth map"]
+```
+
+Loaded off-screen geometry can cast shadows. Cache snapshots include direction,
+world versions, geometry and draw ranges: changes affecting shadows must
+invalidate the cache. Point lights are separate.
+
+- [renderSunlight.js](./renderSunlight.js): update sunlight shadow rendering.
+- [shadowMatrix.js](./shadowMatrix.js): fit the shadow camera to scene bounds.
+- [ensureShadowPipeline.js](./ensureShadowPipeline.js): prepare shadow GPU pipelines.
+
+Related: [lighting](../lighting/README.md), [sunlight](../sunlight/README.md), [rendering](../rendering/README.md).

package/src/shadows/bindSunlight.js

@@ -1,9 +1,11 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { sunBindGroup } from '../globals/sunBindGroup.js';
 
-
-
+/**
+ * Bind the renderer's sunlight uniforms, shadow texture, sampler and light buffer.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ */
 export function bindSunlight(layer) {
   const sun = rendererByLayer.get(layer).sunlight;
   sun.bindGroup = rendererByLayer.get(layer).device.createBindGroup((

package/src/shadows/drawShadowMeshes.js

@@ -1,10 +1,15 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { shadowPass } from '../globals/shadowPass.js';
 import { shadowBindGroup } from '../globals/shadowBindGroup.js';
 import { shadowOffsets } from '../globals/shadowOffsets.js';
 
-
+/**
+ * Encode the shadow depth pass for the supplied meshes.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the render pass.
+ * @param {Object[]} meshes Meshes to draw into the depth texture.
+ */
 export function drawShadowMeshes(layer, encoder, meshes) {
   const renderer = rendererByLayer.get(layer), device = renderer.device, sun = renderer.sunlight;
   const pass = encoder.beginRenderPass((

package/src/shadows/ensureShadowPipeline.js

@@ -7,6 +7,13 @@ import { shadowPipelineLayout } from '../globals/shadowPipelineLayout.js';
 import { shadowInstanceLayouts } from '../globals/shadowInstanceLayouts.js';
 import { shadowLayouts } from '../globals/shadowLayouts.js';
 
+/**
+ * Create the shadow pipeline and shared depth bindings if they are not yet available.
+ *
+ * @param {GPUDevice} device Device creating the GPU resources.
+ * @param {Object} sun Renderer sunlight state.
+ * @param {boolean} [instanced=false] Whether to create the instanced pipeline.
+ */
 export function ensureShadowPipeline(device, sun, instanced = false) {
   const key = instanced ? 'instancePipeline' : 'pipeline';
   if (!sun[key]) {

package/src/shadows/renderSunlight.js

@@ -1,16 +1,20 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { disabledShadow } from '../globals/disabledShadow.js';
 import { shadowValues } from '../globals/shadowValues.js';
-
 import { shadowCacheMatches } from './shadowCacheMatches.js';
 import { shadowMatrix } from './shadowMatrix.js';
 import { ensureShadowPipeline } from './ensureShadowPipeline.js';
 import { drawShadowMeshes } from './drawShadowMeshes.js';
 import { resizeSunlight } from './resizeSunlight.js';
 
-/** One shared directional depth map. Off-screen but loaded geometry can cast shadows. */
-
+/**
+ * Render one shared directional depth map, including off-screen loaded geometry.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the shadow pass.
+ * @param {Object[]} meshes Meshes that can cast shadows.
+ * @param {Object|null} sunlight Sun position and direction, if available.
+ */
 export function renderSunlight(layer, encoder, meshes, sunlight) {
   const renderer = rendererByLayer.get(layer), device = renderer.device, sun = renderer.sunlight;
   if (!meshes.length || !sunlight || sunlight.altitude < 3) {

package/src/shadows/resizeSunlight.js

@@ -1,11 +1,14 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { shadowTexture } from '../globals/shadowTexture.js';
-
-
 import { bindSunlight } from './bindSunlight.js';
 import { destroyTexture } from '../textures/destroyTexture.js';
 
+/**
+ * Replace the shadow depth texture when its required size changes and rebind sunlight.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {number} size Width and height of the square texture in pixels.
+ */
 export function resizeSunlight(layer, size) {
   const device = rendererByLayer.get(layer).device, sun = rendererByLayer.get(layer).sunlight;
   if (sun.size === size) return;

package/src/shadows/shadowCacheMatches.js

@@ -1,3 +1,14 @@
+import { shadowMeshMatches } from './shadowMeshMatches.js';
+
+/**
+ * Check whether the cached shadow map still matches sunlight and all meshes.
+ *
+ * @param {Object} sun Renderer sunlight state and shadow cache.
+ * @param {Object[]} meshes Current shadow-casting meshes.
+ * @param {Object} sunlight Current sunlight direction.
+ *
+ * @returns {boolean|undefined} Truthy if the cache is still valid.
+ */
 export function shadowCacheMatches(sun, meshes, sunlight) {
   const cache = sun.cache;
   let unchanged = sun.enabled && cache?.meshes.size === meshes.length;
@@ -14,4 +25,3 @@ export function shadowCacheMatches(sun, meshes, sunlight) {
   }
   return unchanged;
 }
-import { shadowMeshMatches } from './shadowMeshMatches.js';

package/src/shadows/shadowMatrix.js

@@ -2,10 +2,17 @@ import { shadowBounds as sharedShadowBounds } from '../globals/shadowBounds.js';
 import { shadowCamera } from '../globals/shadowCamera.js';
 import { shadowLow } from '../globals/shadowLow.js';
 import { shadowHigh } from '../globals/shadowHigh.js';
-
 import { shadowBounds } from '../geometry/shadowBounds.js';
 import { updateCamera } from '../camera/updateSceneCamera.js';
 
+/**
+ * Fit a directional shadow projection to the bounds of the supplied meshes.
+ *
+ * @param {Object[]} meshes Shadow-casting meshes.
+ * @param {Object} sunlight Sunlight direction.
+ *
+ * @returns {Float32Array} Column-major shadow projection-view matrix.
+ */
 export function shadowMatrix(meshes, sunlight) {
   const { min, max } = shadowBounds(meshes, sharedShadowBounds);
   const camera = shadowCamera;

package/src/shadows/shadowMeshMatches.js

@@ -1,11 +1,19 @@
-export function shadowMeshMatches(cache, mesh) {
-  const previous = cache.meshes.get(mesh), range = mesh.geometry.drawRange;
-  if (!(previous && previous.world === mesh._worldMatrixVersion && previous.geometry === mesh.geometry &&
-    previous.start === range.start && previous.count === range.count &&
-    previous.appearance === (mesh._appearance ?? 1))) return false;
-  let attribute;
-  for (attribute of Object.values(mesh.geometry.attributes)) {
-    if (attribute.needsUpdate) return false;
-  }
-  return true;
-}
+/**
+ * Check a mesh against its cached shadow state and pending attribute updates.
+ *
+ * @param {Object} cache Shadow cache containing mesh snapshots.
+ * @param {Object} mesh Mesh to compare.
+ *
+ * @returns {boolean} Whether the mesh still matches its snapshot.
+ */
+export function shadowMeshMatches(cache, mesh) {
+  const previous = cache.meshes.get(mesh), range = mesh.geometry.drawRange;
+  if (!(previous && previous.world === mesh._worldMatrixVersion && previous.geometry === mesh.geometry &&
+    previous.start === range.start && previous.count === range.count &&
+    previous.appearance === (mesh._appearance ?? 1))) return false;
+  let attribute;
+  for (attribute of Object.values(mesh.geometry.attributes)) {
+    if (attribute.needsUpdate) return false;
+  }
+  return true;
+}