@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/shaders.js

@@ -26,7 +26,13 @@ const ViewUniform = defineComponent("render/ViewUniform", {
    * Per directional light (column i): the atmosphere's transmittance (rgb) between the camera and
    * that sun, applied to its light (spec 0044). All ones without an atmosphere.
    */
-  sunTransmittance: t.mat4
+  sunTransmittance: t.mat4,
+  /**
+   * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+   * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+   * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+   */
+  pixelScale: t.vec4
 });
 const viewLayout = wgslLayout(ViewUniform);
 const materialLayout = wgslLayout(StandardMaterial);
@@ -77,9 +83,9 @@ const FLAG_VISIBLE: u32 = 1u;
 const FLAG_CASTER: u32 = 2u;
 const FLAG_RECEIVER: u32 = 4u;
 
-@group(2) @binding(0) var<storage, read> instances: array<Instance>;
+@data @group(2) @binding(0) var<storage, read> instances: array<Instance>;
 /** The view's culled slots; a draw's instance_index indexes this. */
-@group(2) @binding(1) var<storage, read> visible: array<u32>;
+@data @group(2) @binding(1) var<storage, read> visible: array<u32>;
 
 /** Visible-list entries: slot in the low 28 bits, LOD level in the top 4. */
 const SLOT_MASK: u32 = 0x0fffffffu;
@@ -98,7 +104,7 @@ fn instance_world(inst: Instance, position: vec3f) -> vec3f {
 }
 
 /** Last frame's transform of each slot (three affine rows), for motion vectors. */
-@group(2) @binding(2) var<storage, read> previous: array<vec4f>;
+@data @group(2) @binding(2) var<storage, read> previous: array<vec4f>;
 
 /** Where an object-space position was last frame, in world space. */
 fn previous_world(instance_index: u32, position: vec3f) -> vec3f {
@@ -171,9 +177,9 @@ struct Deform {
 const FLAG_SKINNED: u32 = 32u;
 const FLAG_MORPH: u32 = 64u;
 
-@group(2) @binding(3) var<storage, read> deforms: array<Deform>;
-@group(2) @binding(4) var<storage, read> poses: array<vec4f>;
-@group(2) @binding(5) var<storage, read> deform_data: array<u32>;
+@data @group(2) @binding(3) var<storage, read> deforms: array<Deform>;
+@data @group(2) @binding(4) var<storage, read> poses: array<vec4f>;
+@data @group(2) @binding(5) var<storage, read> deform_data: array<u32>;
 
 struct Deformed {
   position: vec3f,
@@ -360,6 +366,7 @@ import shard::view::view;
 import shard::pbr::types::VertexOutput;
 import shard::mesh::mesh_vertex_at;
 import shard::unlit::shading::shade;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -376,9 +383,11 @@ import shard::unlit::shading::shade;
 }
 
 @fragment fn fs(in: VertexOutput) -> @location(0) vec4f {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   let c = shade(in);
   @if(MASK) if (c.a < 0.5) { discard; }
-  return vec4f(c.rgb * view.exposure, c.a);
+  @if(OPAQUE) return vec4f(c.rgb * view.exposure, 1.0);
+  @if(!OPAQUE) return vec4f(c.rgb * view.exposure, c.a);
 }`,
   "shard::pbr::brdf": `
 const PI: f32 = 3.14159265359;
@@ -416,8 +425,24 @@ struct Light {
   shadow_bias: f32,
   shadow_normal_bias: f32,
   shadow_softness: f32,
-  _pad0: f32,
-  _pad1: f32,
+  /** 0: physical; 1: tabletop (0057). */
+  falloff: f32,
+  /** Tabletop: full intensity inside this radius. */
+  bright: f32,
+}
+
+/**
+ * Distance attenuation of a point or spot light: physical inverse square windowed to zero at
+ * range, or tabletop (0057): full intensity inside bright, linear to zero at range.
+ */
+fn light_falloff(light: Light, d: f32, d2: f32) -> f32 {
+  if (light.falloff > 0.5) {
+    return clamp((light.range - d) / max(light.range - light.bright, 1e-4), 0.0, 1.0);
+  }
+  let ratio = d / light.range;
+  let r4 = ratio * ratio * ratio * ratio;
+  let window = clamp(1.0 - r4, 0.0, 1.0);
+  return window * window / d2;
 }
 
 struct DirectionalLight {
@@ -446,10 +471,29 @@ const CLUSTER_Z: u32 = 24u;
 const CLUSTER_COUNT: u32 = 3456u;
 const MAX_PER_CLUSTER: u32 = 128u;
 
-@group(0) @binding(1) var<storage, read> lights: array<Light>;
+@data(uniform, 128) @group(0) @binding(1) var<storage, read> lights: array<Light>;
 /** counts[CLUSTER_COUNT], then MAX_PER_CLUSTER light indices per cluster. */
-@group(0) @binding(2) var<storage, read> clusters: array<u32>;
-@group(0) @binding(3) var<storage, read> directional: DirectionalLights;`,
+@if(!BASELINE) @group(0) @binding(2) var<storage, read> clusters: array<u32>;
+/** Baseline (0064): a bit per packed light, 128 per cluster. */
+@if(BASELINE) @data @group(0) @binding(2) var<storage, read> cluster_bits: array<vec4u>;
+@data(uniform) @group(0) @binding(3) var<storage, read> directional: DirectionalLights;
+
+/**
+ * Baseline (0064): takes the lowest light left in \`mask\` (a cluster's bits) into \`index\`;
+ * false once none are left.
+ */
+@if(BASELINE) fn next_light(mask: ptr<function, vec4u>, index: ptr<function, u32>) -> bool {
+  for (var w = 0u; w < 4u; w++) {
+    let word = (*mask)[w];
+    if (word != 0u) {
+      let lowest = word & (~word + 1u);
+      (*mask)[w] = word ^ lowest;
+      *index = w * 32u + u32(round(log2(f32(lowest))));
+      return true;
+    }
+  }
+  return false;
+}`,
   "shard::pbr::shadows": `
 import shard::color::ign;
 
@@ -473,7 +517,7 @@ struct ShadowData {
   spot_params: array<vec4f, 8>,
 }
 
-@group(0) @binding(4) var<storage, read> shadows: ShadowData;
+@data(uniform) @group(0) @binding(4) var<storage, read> shadows: ShadowData;
 @group(0) @binding(5) var cascade_maps: texture_depth_2d_array;
 @group(0) @binding(6) var spot_maps: texture_depth_2d_array;
 @group(0) @binding(7) var point_maps: texture_depth_2d_array;
@@ -576,9 +620,11 @@ fn point_shadow(index: u32, world: vec3f, n: vec3f, bias: f32, normal_bias: f32,
 import shard::view::view;
 import shard::pbr::types::PbrInput;
 import shard::pbr::brdf::{ PI, d_ggx, v_smith_ggx_correlated, f_schlick };
-import shard::pbr::lights::{ lights, clusters, directional, LIGHT_SPOT, NO_SHADOW, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, CLUSTER_COUNT, MAX_PER_CLUSTER };
+import shard::pbr::lights::{ lights, clusters, cluster_bits, next_light, directional, light_falloff, LIGHT_SPOT, NO_SHADOW, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, CLUSTER_COUNT, MAX_PER_CLUSTER };
 import shard::pbr::shadows::{ directional_shadow, spot_shadow, point_shadow, cascade_index };
 import shard::pbr::environment::environment_light;
+@if(SKY_VISIBILITY) import shard::interior::interior_ambient;
+@if(BLOCKED_LIGHTS) import shard::interior::{ wall_visibility, interior_receiver };
 
 const FLAG_RECEIVER: u32 = 4u;
 
@@ -618,6 +664,26 @@ fn heat(count: u32) -> vec3f {
  * Lighting stage: the only place lights are evaluated. Returns scene-referred radiance.
  * Directional lights (with cascaded shadows), then clustered point and spot lights, then ambient.
  */
+/**
+ * SSAO at a full-resolution pixel, from the half-resolution AO and view depth (rg): the four
+ * nearest texels, weighted by how well their depth matches this pixel's. Without SSAO a white
+ * 1\xD71 texture is bound, which gives 1.
+ */
+fn ssao_at(frag: vec2f, z: f32) -> f32 {
+  let half_size = vec2i(textureDimensions(ao_texture));
+  let base = vec2i(floor((frag - 1.0) * 0.5));
+  var sum = 0.0;
+  var weight = 0.0;
+  for (var k = 0; k < 4; k++) {
+    let q = clamp(base + vec2i(k & 1, k >> 1), vec2i(0), half_size - 1);
+    let s = textureLoad(ao_texture, q, 0);
+    let w = 1.0 / (1e-3 + abs(s.y - z) / max(z, 1e-3));
+    sum += s.x * w;
+    weight += w;
+  }
+  return sum / max(weight, 1e-6);
+}
+
 fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags: u32) -> vec3f {
   let n = p.normal;
   let v = normalize(view.cameraPosition - world_position);
@@ -642,7 +708,39 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
   // Point and spot lights from this fragment's cluster: intensity (cd) / d\xB2 \xD7 window.
   let cluster = cluster_of(frag_coord, view_depth);
   var count = 0u;
-  if (cluster >= 0) {
+  @if(BLOCKED_LIGHTS) let receiver = interior_receiver(world_position, n);
+  @if(BASELINE) if (cluster >= 0) {
+    // The cluster's lights, lowest first; keep the body in step with the loop below.
+    var mask = cluster_bits[cluster];
+    var index = 0u;
+    while (next_light(&mask, &index)) {
+      count++;
+      let light = lights[index];
+      let to_light = light.position - world_position;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let cd = dot(-l, light.direction);
+        let spot = clamp(cd * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      if (attenuation <= 0.0) { continue; }
+      @if(BLOCKED_LIGHTS) attenuation *= wall_visibility(light, receiver);
+      if (receives && light.shadow != NO_SHADOW) {
+        if (light.kind == LIGHT_SPOT) {
+          attenuation *= spot_shadow(light.shadow, world_position, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
+        } else {
+          attenuation *= point_shadow(light.shadow, world_position, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
+        }
+      }
+      let a_light = clamp(a + light.radius / (2.0 * d), 0.0, 1.0);
+      let norm = (a / a_light) * (a / a_light);
+      color += brdf(n, v, l, a_light, diffuse_color, f0, norm) * light.color * attenuation;
+    }
+  }
+  @if(!BASELINE) if (cluster >= 0) {
     count = clusters[cluster];
     let base = CLUSTER_COUNT + u32(cluster) * MAX_PER_CLUSTER;
     for (var k = 0u; k < count; k++) {
@@ -651,16 +749,14 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
       let d2 = max(dot(to_light, to_light), 1e-4);
       let d = sqrt(d2);
       let l = to_light / d;
-      let ratio = d / light.range;
-      let r4 = ratio * ratio * ratio * ratio;
-      let window = clamp(1.0 - r4, 0.0, 1.0);
-      var attenuation = window * window / d2;
+      var attenuation = light_falloff(light, d, d2);
       if (light.kind == LIGHT_SPOT) {
         let cd = dot(-l, light.direction);
         let spot = clamp(cd * light.spot_scale + light.spot_offset, 0.0, 1.0);
         attenuation *= spot * spot;
       }
       if (attenuation <= 0.0) { continue; }
+      @if(BLOCKED_LIGHTS) attenuation *= wall_visibility(light, receiver);
       if (receives && light.shadow != NO_SHADOW) {
         if (light.kind == LIGHT_SPOT) {
           attenuation *= spot_shadow(light.shadow, world_position, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
@@ -678,14 +774,13 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
   // Ambient: image-based lighting from the environment, or the uniform AmbientLight (cd/m\xB2).
   // SSAO darkens it on opaque surfaces (it measures the depth buffer, which blended ones aren't in).
   var surface = p;
-  if (p.alpha >= 0.999) {
-    let dims = vec2i(textureDimensions(ao_texture));
-    surface.occlusion *= textureLoad(ao_texture, min(vec2i(frag_coord.xy), dims - 1), 0).r;
-  }
+  if (p.alpha >= 0.999) { surface.occlusion *= ssao_at(frag_coord.xy, view_depth); }
   if (view.envParams.w > 0.5) {
-    color += environment_light(surface, n, v);
+    @if(!SKY_VISIBILITY) color += environment_light(surface, n, v);
+    @if(SKY_VISIBILITY) color += interior_ambient(environment_light(surface, n, v), diffuse_color * surface.occlusion, world_position, n);
   } else {
-    color += diffuse_color * view.ambient * surface.occlusion;
+    @if(!SKY_VISIBILITY) color += diffuse_color * view.ambient * surface.occlusion;
+    @if(SKY_VISIBILITY) color += interior_ambient(diffuse_color * view.ambient * surface.occlusion, diffuse_color * surface.occlusion, world_position, n);
   }
 
   let debug = u32(view.clusterParams.w);
@@ -912,6 +1007,7 @@ import shard::mesh::mesh_vertex_at;
 import shard::pbr::material::{ pbr_input, fragment_output };
 import shard::pbr::standard::material;
 import shard::pbr::lighting::apply_lighting;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -928,12 +1024,15 @@ import shard::pbr::lighting::apply_lighting;
 }
 
 @fragment fn fs(in: VertexOutput) -> @location(0) vec4f {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   let p = pbr_input(in);
   if (material.alphaMode == 1u && p.alpha < material.alphaCutoff) { discard; }
   let color = (apply_lighting(p, in.world_position, in.clip, in.flags) + p.emissive) * view.exposure;
   // Premultiplied blending expects color \xD7 alpha; additive and alpha blend multiply in hardware.
   @if(PREMULTIPLY) return fragment_output(vec4f(color * p.alpha, p.alpha));
-  @if(!PREMULTIPLY) return fragment_output(vec4f(color, p.alpha));
+  // Opaque and masked surfaces cover their pixel, whatever their base color's alpha (0052).
+  @if(OPAQUE) return vec4f(fragment_output(vec4f(color, p.alpha)).rgb, 1.0);
+  @if(!PREMULTIPLY && !OPAQUE) return fragment_output(vec4f(color, p.alpha));
 }`,
   "shard::post::depth_resolve": `
 @group(0) @binding(0) var depth_ms: texture_depth_multisampled_2d;
@@ -950,7 +1049,7 @@ import shard::pbr::types::PbrInput;
 @group(0) @binding(10) var env_lut: texture_2d<f32>;
 @group(0) @binding(11) var env_sampler: sampler;
 /** SH9, convolved with the cosine lobe and divided by \u03C0: dot with the basis = irradiance / \u03C0. */
-@group(0) @binding(12) var<storage, read> env_sh: array<vec4f, 9>;
+@data(uniform) @group(0) @binding(12) var<storage, read> env_sh: array<vec4f, 9>;
 @group(0) @binding(13) var env_source: texture_cube<f32>;
 
 const ENV_SPECULAR_MIPS: f32 = 5.0;
@@ -1001,10 +1100,21 @@ fn environment_light(p: PbrInput, n: vec3f, v: vec3f) -> vec3f {
 /** The environment's own radiance toward d (the background), in cd/m\xB2. */
 fn environment_background(d: vec3f) -> vec3f {
   return textureSampleLevel(env_source, env_sampler, env_rotate(d), 0.0).rgb * view.envParams.x;
+}`,
+  "shard::post::glow": `
+/**
+ * Bloom's first level over the image: mixed, conserving energy, without a threshold; added with
+ * one. \`glow\`: intensity, the chain's level count, mix (1) or add (0), 0. The tonemap applies it
+ * as it reads the image, and auto exposure meters the same mix.
+ */
+fn add_glow(c: vec3f, level0: vec3f, glow: vec4f) -> vec3f {
+  let g = level0 / glow.y;
+  return select(c + g * glow.x, mix(c, g, glow.x), glow.z > 0.5);
 }`,
   "shard::post::tonemap": `
 import shard::color::{ linear_to_srgb, srgb_to_linear, ign, luminance };
 import shard::tonemap::tonemap;
+@if(BLOOM) import shard::post::glow::add_glow;
 
 struct TonemapParams {
   /** curve, dither, flags (1 grading, 2 vignette, 4 LUT, 8 sRGB LUT), 0. */
@@ -1020,12 +1130,16 @@ struct TonemapParams {
   vignette: vec4f,
   /** 1 / width, 1 / height of the view. */
   texel: vec4f,
+  /** Bloom: intensity, level count, mix (1) or add (0), 0. */
+  glow: vec4f,
 }
 
 @group(0) @binding(0) var hdr: texture_2d<f32>;
 @group(0) @binding(1) var<uniform> params: TonemapParams;
 @group(0) @binding(2) var lut: texture_2d<f32>;
 @group(0) @binding(3) var lut_sampler: sampler;
+/** Bloom's first level, composited here instead of in a pass of its own. */
+@if(BLOOM) @group(0) @binding(4) var bloom: texture_2d<f32>;
 
 const LIN_TO_LMS = mat3x3f(
   vec3f(3.90405e-1, 7.08416e-2, 2.31082e-2),
@@ -1063,8 +1177,19 @@ fn apply_lut(c: vec3f) -> vec3f {
 }
 
 @fragment fn fs(@builtin(position) p: vec4f) -> @location(0) vec4f {
-  let texel = textureLoad(hdr, vec2i(p.xy), 0);
+  var texel = textureLoad(hdr, vec2i(p.xy), 0);
+  @if(BLOOM) {
+    let level0 = textureSampleLevel(bloom, lut_sampler, p.xy * params.texel.xy, 0.0).rgb;
+    texel = vec4f(add_glow(texel.rgb, level0, params.glow), texel.a);
+  }
   var hdr_color = max(texel.rgb, vec3f(0.0));
+  @if(TRANSPARENT) var alpha = 1.0;
+  @if(TRANSPARENT) {
+    // Premultiplied (0052): light over less coverage raises alpha, so a glow shows over the page;
+    // then the color is un-premultiplied for grading and the curve, and premultiplied again below.
+    alpha = clamp(max(texel.a, max(hdr_color.r, max(hdr_color.g, hdr_color.b))), 0.0, 1.0);
+    hdr_color = hdr_color / max(alpha, 1e-6);
+  }
   let flags = params.mode.z;
   if ((flags & 1u) != 0u) { hdr_color = grade(hdr_color); }
   if ((flags & 2u) != 0u) {
@@ -1080,9 +1205,12 @@ fn apply_lut(c: vec3f) -> vec3f {
     let n = ign(p.xy) + ign(p.xy + vec2f(71.0, 13.0)) - 1.0;
     c = c + vec3f(n / 255.0);
   }
+  // The page composites in display space, so premultiply there; it keeps rgb <= alpha.
+  @if(TRANSPARENT) c = clamp(c, vec3f(0.0), vec3f(1.0)) * alpha;
   // sRGB targets encode in hardware: hand them linear values.
   @if(SRGB_TARGET) c = srgb_to_linear(clamp(c, vec3f(0.0), vec3f(1.0)));
-  return vec4f(c, 1.0);
+  @if(TRANSPARENT) return vec4f(c, max(alpha, max(c.r, max(c.g, c.b))));
+  @if(!TRANSPARENT) return vec4f(c, 1.0);
 }`,
   "shard::post::upscale": `
 struct Upscale {
@@ -1094,8 +1222,18 @@ struct Upscale {
 @group(0) @binding(1) var input_sampler: sampler;
 @group(0) @binding(2) var<uniform> upscale: Upscale;
 
-fn at(uv: vec2f) -> vec3f {
-  return textureSampleLevel(input, input_sampler, uv, 0.0).rgb;
+@if(!TRANSPARENT) alias Texel = vec3f;
+@if(TRANSPARENT) alias Texel = vec4f;
+
+fn at(uv: vec2f) -> Texel {
+  @if(!TRANSPARENT) return textureSampleLevel(input, input_sampler, uv, 0.0).rgb;
+  @if(TRANSPARENT) return textureSampleLevel(input, input_sampler, uv, 0.0);
+}
+
+/** Opaque views write alpha 1; premultiplied ones keep rgb <= alpha after sharpening (0052). */
+fn out(c: Texel) -> vec4f {
+  @if(!TRANSPARENT) return vec4f(c, 1.0);
+  @if(TRANSPARENT) return vec4f(c.rgb, max(c.a, max(c.r, max(c.g, c.b))));
 }
 
 /**
@@ -1106,7 +1244,7 @@ fn at(uv: vec2f) -> vec3f {
   let uv = frag.xy * upscale.params.xy;
   let c = at(uv);
   let k = upscale.params.z;
-  if (k <= 0.0) { return vec4f(c, 1.0); }
+  if (k <= 0.0) { return out(c); }
   let texel = 1.0 / vec2f(textureDimensions(input));
   let n = at(uv + vec2f(0.0, -texel.y));
   let s = at(uv + vec2f(0.0, texel.y));
@@ -1115,7 +1253,7 @@ fn at(uv: vec2f) -> vec3f {
   let lo = min(c, min(min(n, s), min(e, w)));
   let hi = max(c, max(max(n, s), max(e, w)));
   let sharp = c + (4.0 * c - (n + s + e + w)) * (0.25 * k);
-  return vec4f(clamp(sharp, lo, hi), 1.0);
+  return out(clamp(sharp, lo, hi));
 }`,
   "shard::post::common": `
 import shard::view::view;
@@ -1132,6 +1270,23 @@ fn world_at(uv: vec2f, depth: f32) -> vec3f {
   return w.xyz / w.w;
 }
 
+/**
+ * Rounds to nearest on a device that truncates when it stores rg11b10ufloat (Metal does): half a
+ * step of each channel's own exponent (6 mantissa bits in red and green, 5 in blue) added before
+ * the store. Without it every pass through the format loses half a step on average, blue twice
+ * as much, and the image drifts warm.
+ */
+fn rg11_round(c: vec3f) -> vec3f {
+  let e = exp2(floor(log2(max(c, vec3f(6.2e-5)))));
+  return c + e * vec3f(1.0 / 128.0, 1.0 / 128.0, 1.0 / 64.0);
+}
+
+/** A post pass's output into the chain: rounded where it's rg11b10ufloat on a truncating device. */
+fn post_out(c: vec4f) -> vec4f {
+  @if(RG11_ROUND) return vec4f(rg11_round(c.rgb), c.a);
+  @if(!RG11_ROUND) return c;
+}
+
 /** Distance along the view axis, in meters. */
 fn view_depth(world: vec3f) -> f32 {
   return -(view.view * vec4f(world, 1.0)).z;

package/dist/shadow-catcher.d.ts

@@ -0,0 +1,9 @@
+export declare const SHADOW_CATCHER_SHADERS: Record<string, string>;
+/**
+ * Invisible except for the shadows it receives (0052): color 0, alpha `opacity × (1 − visibility)`
+ * over every shadow-casting light. Premultiplied, so it darkens what's behind it by that alpha.
+ * Needs `shadowCatcherPlugin` (in `forwardPlugin`).
+ */
+export declare const ShadowCatcher: import("./materials.js").MaterialType;
+/** The ShadowCatcher material's shader. */
+export declare const shadowCatcherPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/shadow-catcher.js

@@ -0,0 +1,133 @@
+import { t } from "@aethervtt/shard-core";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { defineMaterial } from "./materials.js";
+import { Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+const SHADOW_CATCHER_SHADERS = {
+  "shard::pbr::catcher": `
+import shard::view::view;
+import shard::pbr::types::VertexOutput;
+import shard::pbr::lights::{ lights, clusters, cluster_bits, next_light, directional, light_falloff, LIGHT_SPOT, NO_SHADOW, CLUSTER_COUNT, MAX_PER_CLUSTER };
+import shard::pbr::shadows::{ directional_shadow, spot_shadow, point_shadow };
+import shard::pbr::lighting::cluster_of;
+
+const FLAG_RECEIVER: u32 = 4u;
+
+fn brightest(c: vec3f) -> f32 { return max(c.r, max(c.g, c.b)); }
+
+/**
+ * How much of the shadow-casting light reaches the surface: the light of every shadow-casting
+ * light with shadows, over that light without them. 1 when none cast shadows, or when the mesh
+ * doesn't receive them. Shadow catchers (and the dice tray, 0054) turn 1 \u2212 this into alpha.
+ */
+fn shadow_visibility(in: VertexOutput) -> f32 {
+  if ((in.flags & FLAG_RECEIVER) == 0u) { return 1.0; }
+  let n = normalize(in.world_normal);
+  let p = in.world_position;
+  let view_depth = -(view.view * vec4f(p, 1.0)).z;
+  var lit = 0.0;
+  var total = 0.0;
+  for (var i = 0u; i < directional.count; i++) {
+    let light = directional.lights[i];
+    if (light.shadowed == 0u) { continue; }
+    let e = max(dot(n, normalize(light.direction)), 0.0) * brightest(light.color);
+    total += e;
+    lit += e * directional_shadow(p, n, view_depth, in.clip.xy);
+  }
+  let cluster = cluster_of(in.clip, view_depth);
+  // Baseline (0064): the cluster's bits; keep the body in step with the loop below.
+  @if(BASELINE) if (cluster >= 0) {
+    var mask = cluster_bits[cluster];
+    var index = 0u;
+    while (next_light(&mask, &index)) {
+      let light = lights[index];
+      if (light.shadow == NO_SHADOW) { continue; }
+      let to_light = light.position - p;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let spot = clamp(dot(-l, light.direction) * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      let e = max(dot(n, l), 0.0) * attenuation * brightest(light.color);
+      if (e <= 0.0) { continue; }
+      var shadow = 1.0;
+      if (light.kind == LIGHT_SPOT) {
+        shadow = spot_shadow(light.shadow, p, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      } else {
+        shadow = point_shadow(light.shadow, p, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      }
+      total += e;
+      lit += e * shadow;
+    }
+  }
+  @if(!BASELINE) if (cluster >= 0) {
+    let count = clusters[cluster];
+    let base = CLUSTER_COUNT + u32(cluster) * MAX_PER_CLUSTER;
+    for (var k = 0u; k < count; k++) {
+      let light = lights[clusters[base + k]];
+      if (light.shadow == NO_SHADOW) { continue; }
+      let to_light = light.position - p;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let spot = clamp(dot(-l, light.direction) * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      let e = max(dot(n, l), 0.0) * attenuation * brightest(light.color);
+      if (e <= 0.0) { continue; }
+      var shadow = 1.0;
+      if (light.kind == LIGHT_SPOT) {
+        shadow = spot_shadow(light.shadow, p, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      } else {
+        shadow = point_shadow(light.shadow, p, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      }
+      total += e;
+      lit += e * shadow;
+    }
+  }
+  return select(1.0, lit / total, total > 0.0);
+}`,
+  "shard::material::shadow_catcher": `
+import shard::pbr::types::VertexOutput;
+import shard::pbr::catcher::shadow_visibility;
+import material::shadow_catcher::ShadowCatcher;
+
+/** No color; alpha opacity \xD7 (1 \u2212 visibility) over every shadow-casting light. */
+override fn shade(in: VertexOutput) -> vec4f {
+  return vec4f(0.0, 0.0, 0.0, ShadowCatcher.opacity * (1.0 - shadow_visibility(in)));
+}`
+};
+const ShadowCatcher = defineMaterial("render/ShadowCatcher", {
+  extends: "none",
+  blend: "premultiplied",
+  fields: {
+    opacity: t.f32({
+      default: 0.6,
+      min: 0,
+      max: 1,
+      description: "Alpha of full shadow. Partial shadow (penumbra, one of two lights) is less."
+    })
+  },
+  shader: "shard::material::shadow_catcher",
+  description: "Invisible except for the shadows it receives: under a camera clearing to alpha 0 they fall on the page (a dice tray floor). Give its mesh NotShadowCaster."
+});
+const shadowCatcherPlugin = definePlugin({
+  name: "render/shadow-catcher",
+  dependencies: ["render/forward"],
+  provides: [ShadowCatcher],
+  build() {
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), SHADOW_CATCHER_SHADERS);
+  }
+});
+export {
+  SHADOW_CATCHER_SHADERS,
+  ShadowCatcher,
+  shadowCatcherPlugin
+};

package/dist/shadows.d.ts

@@ -1,7 +1,8 @@
 import { type World } from '@aethervtt/shard-core';
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import type { FoliageSupport } from './foliage-path.js';
 import type { NodeContext } from './graph.js';
-import { type DrawList } from './instances.js';
+import { type DrawList, type InstanceStore } from './instances.js';
 import { type LightRecord, type LightStore } from './lights.js';
 import { type MaterialPipelines } from './material-pipelines.js';
 import type { CameraData } from './view.js';
@@ -15,10 +16,28 @@ export declare function pointTanHalf(size: number): number;
 export interface ShadowViewDraw {
     viewProj: Float32Array;
     frustum: Float32Array;
+    /** What casters are culled against: the frustum, but open toward the light for cascades. */
+    cullPlanes: Float32Array;
     draws: DrawList;
     /** Dynamic offset of this view's matrix in the frame's shadow uniforms. */
     offset: number;
+    /** Whether its layer holds a complete draw (0055: cached shadows keep it). */
+    drawn: boolean;
+    /** The matrix and `InstanceStore.shadowEpoch` it was drawn with. */
+    drawnViewProj: Float32Array;
+    drawnEpoch: number;
+    /** Set by the queue: draw it this frame. */
+    redraw: boolean;
 }
+/**
+ * Whether a shadow view must draw this frame (0055). Views of `shadowUpdate: 'always'` lights
+ * always do. A cached view draws when its layer isn't complete, its matrix changed (the light or
+ * the cascade's fit moved), what casts shadows changed (`shadowEpoch`), poses deform, or a
+ * caster inside its cull planes moved.
+ */
+export declare function shadowRedraw(view: ShadowViewDraw, cached: boolean, store: InstanceStore): boolean;
+/** Records that a shadow view's layer now holds a complete draw of this frame's state. */
+export declare function markShadowDrawn(view: ShadowViewDraw, store: InstanceStore): void;
 /** A camera's cascades: fitted each frame, one depth layer each. */
 export declare class Cascades {
     count: number;
@@ -98,11 +117,17 @@ export declare class ShadowPassUniforms {
     bindGroup: GPUBindGroup | undefined;
     private bound;
     private readonly gpu;
+    /** What the buffer holds, so unchanged shadow views write nothing (0055). */
+    private sent;
+    private sentCount;
+    private sentVersion;
+    private sentGeneration;
     constructor(gpu: GpuContext);
     reset(): void;
     /** Adds a view matrix; returns its dynamic offset. */
     push(viewProj: Float32Array): number;
     upload(layout: GPUBindGroupLayout, globals: GpuBuffer): void;
+    private unchanged;
 }
 export declare function shadowViewLayout(gpu: GpuContext): GPUBindGroupLayout;
 /**
@@ -110,7 +135,7 @@ export declare function shadowViewLayout(gpu: GpuContext): GPUBindGroupLayout;
  * `vertex_position` displacement moves shadows too). Opaque materials are vertex-only; masked
  * standard materials run the surface stage to discard.
  */
-export declare function drawShadowCasters(ctx: NodeContext, target: GPUTextureView, view: ShadowViewDraw, offset: number, uniforms: ShadowPassUniforms, pipelines: MaterialPipelines, shadowView: GPUBindGroupLayout, label: string): void;
+export declare function drawShadowCasters(ctx: NodeContext, target: GPUTextureView, view: ShadowViewDraw, offset: number, uniforms: ShadowPassUniforms, pipelines: MaterialPipelines, shadowView: GPUBindGroupLayout, label: string, foliage?: FoliageSupport, cam?: CameraData, cascade?: number): void;
 /** Culls instances that cast shadows into a shadow view, and unions their world bounds. */
 export declare function cullCasters(world: World, view: ShadowViewDraw, planes: Float32Array, box?: Float32Array): boolean;
 export declare const ShadowsResource: import("@aethervtt/shard-core").ResourceDef<{