@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/shadow/contact/shader_contact_shadow_wavefront.js

@@ -0,0 +1,358 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32, vec2i, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { chunk_contact_shadow_wavefront_extents } from "./chunk_contact_shadow_wavefront_extents.js";
+import { CONTACT_SHADOW_WAVE_SIZE } from "./CONTACT_SHADOW_WAVE_SIZE.js";
+
+/**
+ * Bits of {@link CONTACT_SHADOW_SETTINGS_STRUCT}'s `flags`.
+ * @enum {number}
+ */
+export const ContactShadowFlags = {
+    /**
+     * A depth read the edge test calls an edge casts no shadow (Bend's `IgnoreEdgePixels`). Removes the
+     * striation a grazing flat surface gets where its own depth steps read as edges, and thins real
+     * shadows, foliage edges especially.
+     */
+    IgnoreEdgePixels: 1,
+    /**
+     * Push the starting depth away from the camera by 1/65535 of the depth (Bend's
+     * `UsePrecisionOffset`), for a depth buffer too coarse to compare against itself.
+     */
+    PrecisionOffset: 2,
+    /**
+     * Interpolate the reads toward the ray itself, using the same depth to start from and to cast from
+     * (Bend's `BilinearSamplingOffsetMode`). Off: start at pixel centres and cast from a depth pushed
+     * back by the step across the pixel, which Bend default to.
+     */
+    BilinearOffsetMode: 4,
+};
+
+/**
+ * What {@link CONTACT_SHADOW_SETTINGS_STRUCT}'s `debug_mode` writes instead of the shadow.
+ * @enum {number}
+ */
+export const ContactShadowDebugMode = {
+    None: 0,
+    /** 1 where the pixel's own read was taken as an edge, for tuning `bilinear_threshold`. */
+    EdgeMask: 1,
+    /** The thread's position in its wave, 0 to 1 along the ray. */
+    ThreadIndex: 2,
+    /** Which wave along the ring edge, cycling every {@link CONTACT_SHADOW_WAVE_SIZE}. */
+    WaveIndex: 3,
+};
+
+/**
+ * Per dispatch, as immediates: the light's coordinate and the dispatch's wave offset from
+ * {@link ContactShadowDispatchList}, and the tuning.
+ *
+ * - `surface_thickness`: how thick each depth sample is taken to be, as a fraction of its device
+ *   depth. With this engine's reverse-Z infinite projection (device depth = near / view depth) a sample
+ *   shadows the ray when it is in front of it by up to twice this fraction of its own view distance
+ *   (Bend's `SurfaceThickness`; their starting value 0.005 is 1% of the distance).
+ * - `bilinear_threshold`: two depths further apart than this fraction of the nearer one are an edge,
+ *   and are not interpolated across (`BilinearThreshold`).
+ * - `shadow_contrast`: the slope of the transition in and out of the thickness window
+ *   (`ShadowContrast`); a sample is fully shadowing over the middle `1 − 2 / contrast` of it.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CONTACT_SHADOW_SETTINGS_STRUCT = WebGPUStruct.from({
+    light_coordinate: vec4f,
+    wave_offset: vec2i,
+    surface_thickness: f32,
+    bilinear_threshold: f32,
+    shadow_contrast: f32,
+    flags: u32,
+    debug_mode: u32,
+}, "ContactShadowSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", CONTACT_SHADOW_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addTexture("tDepth")
+    .addStorageTexture("tContactShadow", "r32float", "2d", "write-only");
+
+/**
+ * Samples each pixel tests along its ray toward the light, one pixel apart on the ray's major axis
+ * (Bend's `SAMPLE_COUNT`). This is the shadow's reach in pixels and the thread's whole budget: a
+ * thread reads {@link READ_COUNT} × 2 depths and this many words of workgroup memory, whatever the scene.
+ * @type {number}
+ */
+const SAMPLE_COUNT = 60;
+
+/**
+ * The first samples, any one of which may shadow the pixel fully (`HARD_SHADOW_SAMPLES`); the rest
+ * are reduced in four interleaved sets and averaged, so one depth sample cannot fully shadow a pixel
+ * from further away.
+ * @type {number}
+ */
+const HARD_SHADOW_SAMPLES = 4;
+
+/**
+ * The last samples, which shadow progressively less, so the reach ends in a fade rather than a cut
+ * (`FADE_OUT_SAMPLES`).
+ * @type {number}
+ */
+const FADE_OUT_SAMPLES = 8;
+
+/**
+ * Reads per thread. Thread t's samples are workgroup words t + 1 … t + {@link SAMPLE_COUNT}, so the
+ * workgroup holds SAMPLE_COUNT + WAVE_SIZE words, rounded up to whole waves: two, while the reach stays
+ * within one wave.
+ * @type {number}
+ */
+const READ_COUNT = Math.ceil((SAMPLE_COUNT + CONTACT_SHADOW_WAVE_SIZE) / CONTACT_SHADOW_WAVE_SIZE);
+
+if (READ_COUNT !== 2) {
+    throw new Error(`the shader reads twice per thread; SAMPLE_COUNT ${SAMPLE_COUNT} needs ${READ_COUNT}`);
+}
+
+if (HARD_SHADOW_SAMPLES % 4 !== 0 || FADE_OUT_SAMPLES % 4 !== 0 || SAMPLE_COUNT % 4 !== 0) {
+    // the four interleaved reductions are walked four samples at a time, never by a dynamic lane index
+    throw new Error('sample counts must be multiples of 4');
+}
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WAVE_SIZE = ${CONTACT_SHADOW_WAVE_SIZE}u;
+const SAMPLE_COUNT = ${SAMPLE_COUNT}u;
+const HARD_SHADOW_SAMPLES = ${HARD_SHADOW_SAMPLES}u;
+const FADE_OUT_SAMPLES = ${FADE_OUT_SAMPLES}u;
+
+// reverse-Z: the far plane is 0 in the depth buffer, the near plane 1
+const FAR_DEPTH = 0.0;
+const Z_SIGN = -1.0;
+
+// a depth that can shadow nothing: an edge read with edges ignored, a read past the light
+const NO_SHADOW_DEPTH = 1e20;
+
+const FLAG_IGNORE_EDGE_PIXELS = ${ContactShadowFlags.IgnoreEdgePixels}u;
+const FLAG_PRECISION_OFFSET = ${ContactShadowFlags.PrecisionOffset}u;
+const FLAG_BILINEAR_OFFSET_MODE = ${ContactShadowFlags.BilinearOffsetMode}u;
+
+var<workgroup> depth_data: array<f32, ${READ_COUNT * CONTACT_SHADOW_WAVE_SIZE}>;
+
+struct ContactShadowRead {
+    // the depth the pixel starts its ray from
+    sampling_depth: f32,
+    // the depth this read casts from
+    shadowing_depth: f32,
+    // the read's distance from the far plane, in device depth: what thresholds are fractions of
+    thickness_scale: f32,
+    is_edge: bool,
+}
+
+/**
+ * Off-screen reads return the far plane, which shadows nothing (Bend's clamp-to-border sampler).
+ */
+fn contact_shadow_load_depth(xy: vec2<i32>, size: vec2<i32>) -> f32 {
+    if (any(xy < vec2<i32>(0)) || any(xy >= size)) {
+        return FAR_DEPTH;
+    }
+
+    return textureLoad(tDepth, xy, 0).r;
+}
+
+/**
+ * Two point reads across the ray's minor axis, interpolated unless they straddle an edge.
+ */
+fn contact_shadow_read(pixel_xy: vec2<f32>, major_axis_x: bool, size: vec2<i32>) -> ContactShadowRead {
+    let read_xy = vec2<i32>(floor(pixel_xy));
+    let minor_axis = select(pixel_xy.x, pixel_xy.y, major_axis_x);
+
+    var bilinear = fract(minor_axis) - 0.5;
+
+    let bias = select(-1, 1, bilinear > 0.0);
+    let offset_xy = select(vec2<i32>(bias, 0), vec2<i32>(0, bias), major_axis_x);
+
+    let depth_x = contact_shadow_load_depth(read_xy, size);
+    let depth_y = contact_shadow_load_depth(read_xy + offset_xy, size);
+
+    var result: ContactShadowRead;
+
+    result.thickness_scale = abs(FAR_DEPTH - depth_x);
+
+    let use_point_filter = abs(depth_x - depth_y) > result.thickness_scale * settings.bilinear_threshold;
+
+    result.is_edge = use_point_filter;
+
+    let ignore_edges = (settings.flags & FLAG_IGNORE_EDGE_PIXELS) != 0u;
+
+    if ((settings.flags & FLAG_BILINEAR_OFFSET_MODE) != 0u) {
+        bilinear = select(bilinear, 0.0, use_point_filter);
+
+        result.sampling_depth = mix(depth_x, depth_y, abs(bilinear));
+        result.shadowing_depth = select(result.sampling_depth, NO_SHADOW_DEPTH, ignore_edges && use_point_filter);
+    } else {
+        result.sampling_depth = depth_x;
+
+        let edge_depth = select(depth_x, NO_SHADOW_DEPTH, ignore_edges);
+
+        // any sample on this ray may sit anywhere between the two reads, so cast from the further one
+        let shadow_depth = depth_x + abs(depth_x - depth_y) * Z_SIGN;
+
+        result.shadowing_depth = select(shadow_depth, edge_depth, use_point_filter);
+    }
+
+    return result;
+}
+
+@compute @workgroup_size(${CONTACT_SHADOW_WAVE_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) group_id: vec3<u32>,
+    @builtin(local_invocation_index) thread_id: u32,
+) {
+    let wave = contact_shadow_wavefront_extents(settings.light_coordinate, settings.wave_offset, group_id, thread_id);
+
+    let size = vec2<i32>(textureDimensions(tDepth));
+    let light_depth = settings.light_coordinate.z;
+
+    // toward the light's point when it is in front of the camera, away from it when it is behind
+    let direction = -settings.light_coordinate.w;
+
+    let write_xy = vec2<i32>(floor(wave.pixel_xy));
+
+    // this pixel, then the pixel a wave further along the ray
+    let read_0 = contact_shadow_read(wave.pixel_xy, wave.major_axis_x, size);
+    let read_1 = contact_shadow_read(wave.pixel_xy + wave.delta_xy * direction, wave.major_axis_x, size);
+
+    let distance_0 = wave.pixel_distance;
+    let distance_1 = wave.pixel_distance + f32(WAVE_SIZE) * direction;
+
+    /*
+     Divided by the distance to the light, every ray to it is parallel: device depth along a screen
+     line toward the light's projection is linear in the distance to it, so (depth − light depth) /
+     distance is constant along a ray and a sample only has to be compared with the pixel's own value.
+     A second read that has run past the light can shadow nothing.
+    */
+    depth_data[thread_id] = (read_0.shadowing_depth - light_depth) / distance_0;
+    depth_data[WAVE_SIZE + thread_id] = select(NO_SHADOW_DEPTH, (read_1.shadowing_depth - light_depth) / distance_1, distance_1 > 0.0);
+
+    workgroupBarrier();
+
+    if (wave.covers_light) {
+        // a ray of no length: nothing on screen can stand between the pixel and the light
+        let light_xy = vec2<i32>(floor(settings.light_coordinate.xy));
+
+        if (all(light_xy >= vec2<i32>(0)) && all(light_xy < size)) {
+            textureStore(tContactShadow, light_xy, vec4<f32>(1.0));
+        }
+    }
+
+    if (any(write_xy < vec2<i32>(0)) || any(write_xy >= size)) {
+        // the rings overrun the viewport by up to two waves
+        return;
+    }
+
+    if (read_0.sampling_depth <= FAR_DEPTH) {
+        // background: nothing to shadow
+        textureStore(tContactShadow, write_xy, vec4<f32>(1.0));
+        return;
+    }
+
+    var start_depth = read_0.sampling_depth;
+
+    if ((settings.flags & FLAG_PRECISION_OFFSET) != 0u) {
+        start_depth = mix(start_depth, FAR_DEPTH, -1.0 / 65535.0);
+    }
+
+    start_depth = (start_depth - light_depth) / distance_0;
+
+    /*
+     Scales a depth difference so the thickness window is [0, 2]: × distance_0 undoes the divide above,
+     ÷ thickness_scale makes it a fraction of the pixel's own depth, and ÷ surface_thickness sets the
+     window. Close to the light's point the min() widens the window instead, so the pixel at the
+     centre is either wholly lit or wholly shadowed.
+    */
+    let depth_scale = min(distance_0 + direction, 1.0 / settings.surface_thickness) * distance_0 / read_0.thickness_scale;
+
+    start_depth = start_depth * depth_scale - Z_SIGN;
+
+    let sample_index = thread_id + 1u;
+
+    var hard_shadow = 1.0;
+
+    for (var i = 0u; i < HARD_SHADOW_SAMPLES; i++) {
+        // 0 where the sample sits exactly one thickness in front of the ray
+        let depth_delta = abs(start_depth - depth_data[sample_index + i] * depth_scale);
+
+        hard_shadow = min(hard_shadow, depth_delta);
+    }
+
+    // four interleaved reductions, sample i into lane i % 4, walked four at a time
+    var shadow_value = vec4<f32>(1.0);
+
+    for (var i = HARD_SHADOW_SAMPLES; i < SAMPLE_COUNT - FADE_OUT_SAMPLES; i += 4u) {
+        let k = sample_index + i;
+
+        let samples = vec4<f32>(depth_data[k], depth_data[k + 1u], depth_data[k + 2u], depth_data[k + 3u]);
+
+        shadow_value = min(shadow_value, abs(vec4<f32>(start_depth) - samples * depth_scale));
+    }
+
+    for (var i = SAMPLE_COUNT - FADE_OUT_SAMPLES; i < SAMPLE_COUNT; i += 4u) {
+        let k = sample_index + i;
+
+        let samples = vec4<f32>(depth_data[k], depth_data[k + 1u], depth_data[k + 2u], depth_data[k + 3u]);
+
+        // sample n of the fade (from 1) adds 0.75 n / (FADE_OUT_SAMPLES + 1)
+        let n = vec4<f32>(f32(i + 1u - (SAMPLE_COUNT - FADE_OUT_SAMPLES))) + vec4<f32>(0.0, 1.0, 2.0, 3.0);
+        let fade_out = n / f32(FADE_OUT_SAMPLES + 1u) * 0.75;
+
+        shadow_value = min(shadow_value, abs(vec4<f32>(start_depth) - samples * depth_scale) + fade_out);
+    }
+
+    // a sample need not match the window's centre exactly to shadow fully
+    let contrast = settings.shadow_contrast;
+
+    shadow_value = saturate(shadow_value * contrast + (1.0 - contrast));
+    hard_shadow = saturate(hard_shadow * contrast + (1.0 - contrast));
+
+    var result = min(hard_shadow, dot(shadow_value, vec4<f32>(0.25)));
+
+    switch (settings.debug_mode) {
+        case ${ContactShadowDebugMode.EdgeMask}u: {
+            result = select(0.0, 1.0, read_0.is_edge);
+        }
+        case ${ContactShadowDebugMode.ThreadIndex}u: {
+            result = f32(thread_id) / f32(WAVE_SIZE);
+        }
+        case ${ContactShadowDebugMode.WaveIndex}u: {
+            result = fract(f32(group_id.x) / f32(WAVE_SIZE));
+        }
+        default: {
+        }
+    }
+
+    textureStore(tContactShadow, write_xy, vec4<f32>(result));
+}
+`, [
+        CONTACT_SHADOW_SETTINGS_STRUCT.declaration_chunk,
+        chunk_contact_shadow_wavefront_extents,
+    ]
+);
+
+/**
+ * Screen-space contact shadow for one light, Bend Studio's wavefront method (`bend_sss_gpu.h`,
+ * Sony Interactive Entertainment, Apache 2.0; "Inside Bend: Screen Space Shadows").
+ *
+ * Writes visibility, 1 lit and 0 shadowed, for every pixel of `tContactShadow`, from the depth buffer
+ * alone. One dispatch per entry of a {@link ContactShadowDispatchList}, each with its own wave offset;
+ * the dispatches write disjoint pixels and need no barrier between them.
+ *
+ * **Bounded per thread.** Each thread reads four depths (two reads of two taps) and
+ * {@link SAMPLE_COUNT} words of workgroup memory, and nothing it does depends on the scene.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_wavefront = ComputeShader.from({
+    label: "Contact shadow / wavefront",
+    resources,
+    body,
+});

package/src/shade/renderer/shadow/map/ShadowDirectionalTechnique.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How a directional light's shadow is mapped: one technique for every directional light of a renderer,
+ * set by `Renderer.feature_virtual_shadow_maps`.
+ */
+export type ShadowDirectionalTechnique = number;
+export namespace ShadowDirectionalTechnique {
+    let Cascades: number;
+    let Virtual: number;
+}
+//# sourceMappingURL=ShadowDirectionalTechnique.d.ts.map

package/src/shade/renderer/shadow/map/ShadowDirectionalTechnique.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowDirectionalTechnique.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/ShadowDirectionalTechnique.js"],"names":[],"mappings":";;;;yCAIU,MAAM"}

package/src/shade/renderer/shadow/map/ShadowDirectionalTechnique.js

@@ -0,0 +1,12 @@
+/**
+ * How a directional light's shadow is mapped: one technique for every directional light of a renderer,
+ * set by `Renderer.feature_virtual_shadow_maps`.
+ *
+ * @enum {number}
+ */
+export const ShadowDirectionalTechnique = {
+    /** Cascaded shadow maps: a range of `shadow_cascade` rows per light, each a slice of the view frustum. */
+    Cascades: 0,
+    /** A virtual shadow map: a clipmap of pages rendered as the view asks for them. */
+    Virtual: 1,
+};

package/src/shade/renderer/shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Which technique a shader samples directional shadows with — decided by
+ * {@link chunk_shadowmap_sample_directional}, so a pipeline links one technique and never branches on
+ * the light's record to find out which.
+ *
+ * The technique is the renderer's, for every directional light at once, so the renderer sets this from
+ * `feature_virtual_shadow_maps` in the switch set it hands its passes.
+ *
+ * @type {ShaderSwitch}
+ */
+export const SHADOW_DIRECTIONAL_TECHNIQUE: ShaderSwitch;
+import { ShaderSwitch } from "../../../shader/compiler/ShaderSwitch.js";
+//# sourceMappingURL=SHADOW_DIRECTIONAL_TECHNIQUE.d.ts.map

package/src/shade/renderer/shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SHADOW_DIRECTIONAL_TECHNIQUE.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,2CAFU,YAAY,CAEoG;6BAb7F,0CAA0C"}

package/src/shade/renderer/shadow/map/shader/SHADOW_DIRECTIONAL_TECHNIQUE.js

@@ -0,0 +1,14 @@
+import { ShaderSwitch } from "../../../shader/compiler/ShaderSwitch.js";
+import { ShadowDirectionalTechnique } from "../ShadowDirectionalTechnique.js";
+
+/**
+ * Which technique a shader samples directional shadows with — decided by
+ * {@link chunk_shadowmap_sample_directional}, so a pipeline links one technique and never branches on
+ * the light's record to find out which.
+ *
+ * The technique is the renderer's, for every directional light at once, so the renderer sets this from
+ * `feature_virtual_shadow_maps` in the switch set it hands its passes.
+ *
+ * @type {ShaderSwitch}
+ */
+export const SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique);

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional.d.ts

@@ -1,11 +1,17 @@
 /**
- * Directional-light shadow sampling. The light's `shadow_directional` record either names a virtual
- * shadow map, sampled by {@link shadowmap_sample_virtual}, or names its cascades as a range of
- * `shadow_cascade` rows (atlas + view-projection each), with CSM cascade blending:
- * {@link shadowmap_csm_compute_cascade_blended} picks among them, and the one or two it picks are
- * read again here to sample.
- * @type {CodeChunk}
+ * Directional-light shadow sampling, `shadowmap_sample_directional(database, shadow_id, position_ws,
+ * view_direction_ws, surface_normal_ws, light) -> f32`, by the renderer's technique
+ * ({@link SHADOW_DIRECTIONAL_TECHNIQUE}): cascades
+ * ({@link chunk_shadowmap_sample_directional_cascades}) or a virtual shadow map
+ * ({@link chunk_shadowmap_sample_directional_virtual}).
+ *
+ * A pipeline links one of the two. The technique is the same for every directional light of a
+ * renderer, so it is decided when the pipeline is made rather than per light and per pixel. Linking
+ * both cost cascade users 6 % of the deferred pass on an RTX 4090 (0.936× without the virtual path,
+ * measured 2026-10-16), and a pipeline compiled with one technique compiles in 0.66–0.83× the time.
+ *
+ * @type {CodeChunkChoice}
  */
-export const chunk_shadowmap_sample_directional: CodeChunk;
-import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+export const chunk_shadowmap_sample_directional: CodeChunkChoice;
+import { CodeChunkChoice } from "../../../shader/compiler/CodeChunkChoice.js";
 //# sourceMappingURL=chunk_shadowmap_sample_directional.d.ts.map

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_shadowmap_sample_directional.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional.js"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,iDAFU,SAAS,CAwEjB;0BAtFwB,uCAAuC"}
+{"version":3,"file":"chunk_shadowmap_sample_directional.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH,iDAFU,eAAe,CAE4E;gCApBrE,6CAA6C"}

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional.js

@@ -1,90 +1,24 @@
-import { GPU_DATABASE_NULL } from "../../../buffer/table/GPU_DATABASE_NULL.js";
-import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
-import { INCIDENT_LIGHT_STRUCT } from "../../../shader/chunk/light/INCIDENT_LIGHT_STRUCT.js";
-import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
-import { chunk_sample_shadowmap_atlas_for_light } from "./chunk_sample_shadowmap_atlas_for_light.js";
-import { chunk_shadowmap_csm_compute_cascade_blended } from "./chunk_shadowmap_csm_compute_cascade_blended.js";
-import { chunk_shadowmap_sample_virtual } from "../../vsm/shader/chunk_shadowmap_sample_virtual.js";
-
-const SHADOW_DIRECTIONAL_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_directional');
-const CASCADE_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_cascade');
+import { CodeChunkChoice } from "../../../shader/compiler/CodeChunkChoice.js";
+import { chunk_shadowmap_sample_directional_virtual } from "../../vsm/shader/chunk_shadowmap_sample_directional_virtual.js";
+import { ShadowDirectionalTechnique } from "../ShadowDirectionalTechnique.js";
+import { chunk_shadowmap_sample_directional_cascades } from "./chunk_shadowmap_sample_directional_cascades.js";
+import { SHADOW_DIRECTIONAL_TECHNIQUE } from "./SHADOW_DIRECTIONAL_TECHNIQUE.js";
 
 /**
- * Directional-light shadow sampling. The light's `shadow_directional` record either names a virtual
- * shadow map, sampled by {@link shadowmap_sample_virtual}, or names its cascades as a range of
- * `shadow_cascade` rows (atlas + view-projection each), with CSM cascade blending:
- * {@link shadowmap_csm_compute_cascade_blended} picks among them, and the one or two it picks are
- * read again here to sample.
- * @type {CodeChunk}
+ * Directional-light shadow sampling, `shadowmap_sample_directional(database, shadow_id, position_ws,
+ * view_direction_ws, surface_normal_ws, light) -> f32`, by the renderer's technique
+ * ({@link SHADOW_DIRECTIONAL_TECHNIQUE}): cascades
+ * ({@link chunk_shadowmap_sample_directional_cascades}) or a virtual shadow map
+ * ({@link chunk_shadowmap_sample_directional_virtual}).
+ *
+ * A pipeline links one of the two. The technique is the same for every directional light of a
+ * renderer, so it is decided when the pipeline is made rather than per light and per pixel. Linking
+ * both cost cascade users 6 % of the deferred pass on an RTX 4090 (0.936× without the virtual path,
+ * measured 2026-10-16), and a pipeline compiled with one technique compiles in 0.66–0.83× the time.
+ *
+ * @type {CodeChunkChoice}
  */
-export const chunk_shadowmap_sample_directional = CodeChunk.from(
-    //language=WGSL
-    `
-fn shadowmap_sample_directional(
-    database: ptr<storage, array<u32>>,
-    shadow_id: u32,
-    position_ws: vec3f,
-    view_direction_ws: vec3f,
-    surface_normal_ws: vec3f,
-    light: ${INCIDENT_LIGHT_STRUCT.wgsl_ref},
-) -> f32 {
-    let shadowmap = ${SHADOW_DIRECTIONAL_DESCRIPTOR.marshalling_method_read}(database, shadow_id);
-
-    if (shadowmap.virtual_map != ${GPU_DATABASE_NULL}u) {
-        // a virtual shadow map rather than cascades
-        return shadowmap_sample_virtual(
-            database,
-            shadowmap.virtual_map,
-            position_ws,
-            surface_normal_ws,
-            light,
-        );
-    }
-
-    let cascade_info = shadowmap_csm_compute_cascade_blended(
-        database,
-        shadowmap.first_cascade,
-        shadowmap.cascade_count,
-        position_ws,
-        view_direction_ws,
-    );
-
-    if(cascade_info.index_0 == ~0u){
-        // not in the shadowmap, assume fully visible
-        return 1.0;
-    }
-
-    let cascade_meta_0 = ${CASCADE_DESCRIPTOR.marshalling_method_read}(database, cascade_info.index_0);
-
-    let visibility_0 = sample_shadowmap_atlas_for_light(
-        cascade_meta_0.projection,
-        position_ws,
-        surface_normal_ws,
-        light,
-        cascade_meta_0.atlas,
-    );
-
-    if(cascade_info.blend <= 0.0){
-        return visibility_0;
-    }
-
-    let cascade_meta_1 = ${CASCADE_DESCRIPTOR.marshalling_method_read}(database, cascade_info.index_1);
-
-    let visibility_1 = sample_shadowmap_atlas_for_light(
-        cascade_meta_1.projection,
-        position_ws,
-        surface_normal_ws,
-        light,
-        cascade_meta_1.atlas,
-    );
+export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
 
-    return mix(visibility_0, visibility_1, cascade_info.blend);
-}
-    `, [
-        SHADOW_DIRECTIONAL_DESCRIPTOR.chunk_read,
-        CASCADE_DESCRIPTOR.chunk_read,
-        chunk_sample_shadowmap_atlas_for_light,
-        chunk_shadowmap_csm_compute_cascade_blended,
-        chunk_shadowmap_sample_virtual,
-    ]
-);
+chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
+chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional_cascades.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `shadowmap_sample_directional` under {@link ShadowDirectionalTechnique.Cascades}. The light's
+ * `shadow_directional` record names its cascades as a range of `shadow_cascade` rows (atlas +
+ * view-projection each), with CSM cascade blending: {@link shadowmap_csm_compute_cascade_blended} picks
+ * among them, and the one or two it picks are read again here to sample.
+ *
+ * A light whose record names no cascades — a frame where the renderer has just switched to virtual
+ * maps and not yet rebuilt them — finds no cascade and is lit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_shadowmap_sample_directional_cascades: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_shadowmap_sample_directional_cascades.d.ts.map

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional_cascades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_shadowmap_sample_directional_cascades.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional_cascades.js"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,0DAFU,SAAS,CA4DjB;0BA5EwB,uCAAuC"}

package/src/shade/renderer/shadow/map/shader/chunk_shadowmap_sample_directional_cascades.js

@@ -0,0 +1,79 @@
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { INCIDENT_LIGHT_STRUCT } from "../../../shader/chunk/light/INCIDENT_LIGHT_STRUCT.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_sample_shadowmap_atlas_for_light } from "./chunk_sample_shadowmap_atlas_for_light.js";
+import { chunk_shadowmap_csm_compute_cascade_blended } from "./chunk_shadowmap_csm_compute_cascade_blended.js";
+
+const SHADOW_DIRECTIONAL_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_directional');
+const CASCADE_DESCRIPTOR = LIGHT_DATABASE_SPEC.get('shadow_cascade');
+
+/**
+ * `shadowmap_sample_directional` under {@link ShadowDirectionalTechnique.Cascades}. The light's
+ * `shadow_directional` record names its cascades as a range of `shadow_cascade` rows (atlas +
+ * view-projection each), with CSM cascade blending: {@link shadowmap_csm_compute_cascade_blended} picks
+ * among them, and the one or two it picks are read again here to sample.
+ *
+ * A light whose record names no cascades — a frame where the renderer has just switched to virtual
+ * maps and not yet rebuilt them — finds no cascade and is lit.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_shadowmap_sample_directional_cascades = CodeChunk.from(
+    //language=WGSL
+    `
+fn shadowmap_sample_directional(
+    database: ptr<storage, array<u32>>,
+    shadow_id: u32,
+    position_ws: vec3f,
+    view_direction_ws: vec3f,
+    surface_normal_ws: vec3f,
+    light: ${INCIDENT_LIGHT_STRUCT.wgsl_ref},
+) -> f32 {
+    let shadowmap = ${SHADOW_DIRECTIONAL_DESCRIPTOR.marshalling_method_read}(database, shadow_id);
+
+    let cascade_info = shadowmap_csm_compute_cascade_blended(
+        database,
+        shadowmap.first_cascade,
+        shadowmap.cascade_count,
+        position_ws,
+        view_direction_ws,
+    );
+
+    if(cascade_info.index_0 == ~0u){
+        // not in the shadowmap, assume fully visible
+        return 1.0;
+    }
+
+    let cascade_meta_0 = ${CASCADE_DESCRIPTOR.marshalling_method_read}(database, cascade_info.index_0);
+
+    let visibility_0 = sample_shadowmap_atlas_for_light(
+        cascade_meta_0.projection,
+        position_ws,
+        surface_normal_ws,
+        light,
+        cascade_meta_0.atlas,
+    );
+
+    if(cascade_info.blend <= 0.0){
+        return visibility_0;
+    }
+
+    let cascade_meta_1 = ${CASCADE_DESCRIPTOR.marshalling_method_read}(database, cascade_info.index_1);
+
+    let visibility_1 = sample_shadowmap_atlas_for_light(
+        cascade_meta_1.projection,
+        position_ws,
+        surface_normal_ws,
+        light,
+        cascade_meta_1.atlas,
+    );
+
+    return mix(visibility_0, visibility_1, cascade_info.blend);
+}
+    `, [
+        SHADOW_DIRECTIONAL_DESCRIPTOR.chunk_read,
+        CASCADE_DESCRIPTOR.chunk_read,
+        chunk_sample_shadowmap_atlas_for_light,
+        chunk_shadowmap_csm_compute_cascade_blended,
+    ]
+);

package/src/shade/renderer/shadow/ray/shader_ray_shadow_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_ray_shadow_code.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/ray/shader_ray_shadow_code.js"],"names":[],"mappings":"AA6KA,mDAII;8BA7J0B,+BAA+B"}
+{"version":3,"file":"shader_ray_shadow_code.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/ray/shader_ray_shadow_code.js"],"names":[],"mappings":"AA6KA,mDAII;8BA5J0B,+BAA+B"}