@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/renderer/shader/chunk/material/chunk_re_indirect_specular_physical.js

@@ -26,6 +26,8 @@ fn re_indirect_specular_physical(
         geometry.view_direction,
         material.diffuse,
         material.specularF0,
+        material.specularF0_dielectric,
+        material.specularF0_metal,
         material.specularF90,
         material.roughness
     );

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_linear_ray.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Most linear steps one march takes, whatever it asks for. With bisection, the work of one thread is
+ * bounded by 4 depth reads × (this + {@link SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT} + 1).
+ * @type {number}
+ */
+export const SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT: number;
+/**
+ * Most bisection steps refining a hit.
+ * @type {number}
+ */
+export const SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT: number;
+/**
+ * A linear ray march against the depth buffer: a port of Tomasz Stachowiak's `raymarch.hlsl`
+ * (https://gist.github.com/h3r2tic/9c8356bdaefbe80b1a22ae0aaee192db, MIT or Apache 2.0), the march
+ * Bevy uses for contact shadows, SSR and SSGI. One routine for any screen-space trace that wants a
+ * first hit along a segment.
+ *
+ * **Where the accuracy comes from.**
+ * - The segment is clipped to the view frustum in NDC before marching, so every step lands on screen.
+ * - Steps are linear in NDC, where a straight 3D line stays straight and device depth is affine along it,
+ *   so the ray's depth at a step is exact. There is never more than one step per pixel.
+ * - Each step reads the depth buffer both point-sampled and bilinear, and claims occlusion only when the ray
+ *   is behind both. Point samples alone make a surface of stacked bricks that self-shadows; bilinear alone
+ *   shrink-wraps a continuous surface over every silhouette. Each rejects the other's false hits.
+ * - Depth is compared as view distance (`get_view_space_depth`), so the thickness is in world units.
+ *
+ * **How it is configured** (`ScreenSpaceLinearRay`, from `screen_space_linear_ray_new`):
+ * - `linear_steps`: capped at {@link SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT}, and at the segment's length in pixels.
+ * - `linear_march_exponent`: 1 for equal steps; above 1 packs them toward the start.
+ * - `bisection_steps` and `use_secant`: refine a hit's position, for a trace that samples colour there.
+ * - `jitter`: the first step's fraction of a step, in (0, 1]; 1 is none.
+ * - `depth_thickness`: how deep behind a depth sample still counts as inside it, view-space units.
+ * - `march_behind_surfaces`: carry on past a surface the ray has gone further behind than the thickness,
+ *   for shadows; it misses surfaces unless `depth_thickness` ≥ the segment's length / `linear_steps`.
+ * - `use_sloppy_march`: point samples only.
+ *
+ * The result's `t` runs over the clipped segment, start to end: the hit, or the furthest the march got.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_space_linear_ray: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_space_linear_ray.d.ts.map

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_linear_ray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_space_linear_ray.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_linear_ray.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,iDAFU,MAAM,CAEqC;AAErD;;;GAGG;AACH,sDAFU,MAAM,CAEyC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4CAFU,SAAS,CA8QjB;0BA7TwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_linear_ray.js

@@ -0,0 +1,319 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_get_view_space_depth } from "../depth/chunk_get_view_space_depth.js";
+import { chunk_v3_matrix4_project } from "../geometry/vec3/chunk_v3_matrix4_project.js";
+import { chunk_ndc_to_uv } from "../texture/chunk_ndc_to_uv.js";
+import { chunk_get_bilinear_filter_texel } from "../texture/sample/chunk_get_bilinear_filter_texel.js";
+import { chunk_interpolate_bilinear_f32 } from "../texture/sample/chunk_interpolate_bilinear_f32.js";
+
+/**
+ * Most linear steps one march takes, whatever it asks for. With bisection, the work of one thread is
+ * bounded by 4 depth reads × (this + {@link SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT} + 1).
+ * @type {number}
+ */
+export const SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT = 64;
+
+/**
+ * Most bisection steps refining a hit.
+ * @type {number}
+ */
+export const SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT = 8;
+
+/**
+ * A linear ray march against the depth buffer: a port of Tomasz Stachowiak's `raymarch.hlsl`
+ * (https://gist.github.com/h3r2tic/9c8356bdaefbe80b1a22ae0aaee192db, MIT or Apache 2.0), the march
+ * Bevy uses for contact shadows, SSR and SSGI. One routine for any screen-space trace that wants a
+ * first hit along a segment.
+ *
+ * **Where the accuracy comes from.**
+ * - The segment is clipped to the view frustum in NDC before marching, so every step lands on screen.
+ * - Steps are linear in NDC, where a straight 3D line stays straight and device depth is affine along it,
+ *   so the ray's depth at a step is exact. There is never more than one step per pixel.
+ * - Each step reads the depth buffer both point-sampled and bilinear, and claims occlusion only when the ray
+ *   is behind both. Point samples alone make a surface of stacked bricks that self-shadows; bilinear alone
+ *   shrink-wraps a continuous surface over every silhouette. Each rejects the other's false hits.
+ * - Depth is compared as view distance (`get_view_space_depth`), so the thickness is in world units.
+ *
+ * **How it is configured** (`ScreenSpaceLinearRay`, from `screen_space_linear_ray_new`):
+ * - `linear_steps`: capped at {@link SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT}, and at the segment's length in pixels.
+ * - `linear_march_exponent`: 1 for equal steps; above 1 packs them toward the start.
+ * - `bisection_steps` and `use_secant`: refine a hit's position, for a trace that samples colour there.
+ * - `jitter`: the first step's fraction of a step, in (0, 1]; 1 is none.
+ * - `depth_thickness`: how deep behind a depth sample still counts as inside it, view-space units.
+ * - `march_behind_surfaces`: carry on past a surface the ray has gone further behind than the thickness,
+ *   for shadows; it misses surfaces unless `depth_thickness` ≥ the segment's length / `linear_steps`.
+ * - `use_sloppy_march`: point samples only.
+ *
+ * The result's `t` runs over the clipped segment, start to end: the hit, or the furthest the march got.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_space_linear_ray = CodeChunk.from(
+    //language=WGSL
+    `
+const SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT = ${SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT}u;
+const SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT = ${SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT}u;
+
+struct ScreenSpaceLinearRay {
+    // NDC, after the divide: xy in [-1, 1], z the device depth
+    start_ndc: vec3<f32>,
+    end_ndc: vec3<f32>,
+    linear_steps: u32,
+    linear_march_exponent: f32,
+    bisection_steps: u32,
+    use_secant: bool,
+    jitter: f32,
+    depth_thickness: f32,
+    march_behind_surfaces: bool,
+    use_sloppy_march: bool,
+}
+
+struct ScreenSpaceLinearRayHit {
+    hit: bool,
+    // the hit, or on a miss the furthest the march got, from 0 at start_ndc to 1 at end_ndc
+    t: f32,
+    uv: vec2<f32>,
+    // how far behind the depth buffer the hit point is, view-space units; on a miss, undefined
+    penetration: f32,
+    // ditto, as a fraction of depth_thickness
+    penetration_fraction: f32,
+    // linear steps taken
+    steps: u32,
+}
+
+// one step's comparison against the depth buffer
+struct ScreenSpaceLinearRaySample {
+    // how far in front of the further of the two depth reads the ray is: negative behind both
+    distance: f32,
+    // false where the ray has gone deeper behind the nearer read than the thickness, marching behind
+    valid: bool,
+    // how far behind the nearer of the two reads the ray is
+    penetration: f32,
+}
+
+fn screen_space_linear_ray_new(start_ndc: vec3<f32>) -> ScreenSpaceLinearRay {
+    var ray: ScreenSpaceLinearRay;
+
+    ray.start_ndc = start_ndc;
+    ray.end_ndc = start_ndc;
+    ray.linear_steps = 4u;
+    ray.linear_march_exponent = 1.0;
+    ray.bisection_steps = 0u;
+    ray.use_secant = false;
+    ray.jitter = 1.0;
+    ray.depth_thickness = 1.0;
+    ray.march_behind_surfaces = false;
+    ray.use_sloppy_march = false;
+
+    return ray;
+}
+
+/**
+ * Point the ray along a clip-space direction from its start, clipping both ends to the view frustum.
+ * \`infinite\` extends it to the frustum's edge.
+ */
+fn screen_space_linear_ray_clip(ray: ptr<function, ScreenSpaceLinearRay>, direction_clip: vec4<f32>, infinite: bool) {
+    var end_clip = vec4<f32>((*ray).start_ndc, 1.0) + direction_clip;
+
+    // the divide, keeping clear of zero for a ray heading straight at the eye
+    end_clip /= select(-1.0, 1.0, end_clip.w >= 0.0) * max(1e-10, abs(end_clip.w));
+
+    // the start, onto the frustum
+    var delta = end_clip.xyz - (*ray).start_ndc;
+    let near_edge = select(vec3<f32>(-1.0, -1.0, 0.0), vec3<f32>(1.0, 1.0, 1.0), delta < vec3<f32>(0.0));
+    let to_near_edge = (near_edge - (*ray).start_ndc) / delta;
+
+    (*ray).start_ndc += delta * max(0.0, max(to_near_edge.x, to_near_edge.y));
+
+    // the end, onto the frustum
+    delta = end_clip.xyz - (*ray).start_ndc;
+    let far_edge = select(vec3<f32>(-1.0, -1.0, 0.0), vec3<f32>(1.0, 1.0, 1.0), delta >= vec3<f32>(0.0));
+    let to_far_edge = (far_edge - (*ray).start_ndc) / delta;
+    let nearest_far_edge = min(min(to_far_edge.x, to_far_edge.y), to_far_edge.z);
+
+    delta *= select(min(1.0, nearest_far_edge), nearest_far_edge, infinite);
+
+    (*ray).end_ndc = (*ray).start_ndc + delta;
+}
+
+/**
+ * March to an NDC point, clipped to the frustum.
+ */
+fn screen_space_linear_ray_to_ndc(ray: ptr<function, ScreenSpaceLinearRay>, end_ndc: vec3<f32>) {
+    let direction = vec4<f32>(end_ndc - (*ray).start_ndc, 0.0) * sign(end_ndc.z);
+
+    screen_space_linear_ray_clip(ray, direction, false);
+}
+
+/**
+ * March to a world-space point, clipped to the frustum.
+ */
+fn screen_space_linear_ray_to_world(ray: ptr<function, ScreenSpaceLinearRay>, end_ws: vec3<f32>, view_projection: mat4x4<f32>) {
+    screen_space_linear_ray_to_ndc(ray, v3_matrix4_project(end_ws, view_projection));
+}
+
+/**
+ * March toward a world-space direction, to the frustum's edge.
+ */
+fn screen_space_linear_ray_to_world_direction(ray: ptr<function, ScreenSpaceLinearRay>, direction_ws: vec3<f32>, view_projection: mat4x4<f32>) {
+    screen_space_linear_ray_clip(ray, view_projection * vec4<f32>(direction_ws, 0.0), true);
+}
+
+fn screen_space_linear_ray_sample(
+    ray: ptr<function, ScreenSpaceLinearRay>,
+    depth: texture_2d<f32>,
+    size: vec2<f32>,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+    point_ndc: vec3<f32>,
+) -> ScreenSpaceLinearRaySample {
+    let uv = ndc_to_uv(point_ndc.xy);
+
+    let ray_depth = get_view_space_depth(point_ndc.z, camera);
+
+    // the four texels around the point, clamped to the edge; the nearest of them is the point sample
+    let footprint = get_bilinear_filter_texel(uv * size - 0.5);
+    let base = vec2<i32>(footprint.origin);
+    let last = vec2<i32>(size) - 1;
+
+    let d00 = textureLoad(depth, clamp(base, vec2<i32>(0), last), 0).r;
+    let d10 = textureLoad(depth, clamp(base + vec2<i32>(1, 0), vec2<i32>(0), last), 0).r;
+    let d01 = textureLoad(depth, clamp(base + vec2<i32>(0, 1), vec2<i32>(0), last), 0).r;
+    let d11 = textureLoad(depth, clamp(base + vec2<i32>(1, 1), vec2<i32>(0), last), 0).r;
+
+    let right = footprint.weights.x >= 0.5;
+    let nearest = select(select(d00, d10, right), select(d01, d11, right), footprint.weights.y >= 0.5);
+
+    let unfiltered_depth = get_view_space_depth(nearest, camera);
+    var linear_depth = get_view_space_depth(interpolate_bilinear_f32(vec4<f32>(d00, d10, d01, d11), footprint.weights), camera);
+
+    if ((*ray).use_sloppy_march) {
+        linear_depth = unfiltered_depth;
+    }
+
+    // relative, so it scales with the depth it pads
+    const BIAS = 0.000002;
+
+    var result: ScreenSpaceLinearRaySample;
+
+    result.distance = max(linear_depth, unfiltered_depth) * (1.0 + BIAS) - ray_depth;
+    result.penetration = ray_depth - min(linear_depth, unfiltered_depth);
+    result.valid = !(*ray).march_behind_surfaces || result.penetration < (*ray).depth_thickness;
+
+    return result;
+}
+
+fn screen_space_linear_ray_occludes(s: ScreenSpaceLinearRaySample) -> bool {
+    return s.distance < 0.0 && s.valid;
+}
+
+/**
+ * March the ray against \`depth\`, a device-depth buffer under \`camera\`'s projection.
+ */
+fn screen_space_linear_ray_march(
+    ray: ptr<function, ScreenSpaceLinearRay>,
+    depth: texture_2d<f32>,
+    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
+) -> ScreenSpaceLinearRayHit {
+    let size = vec2<f32>(textureDimensions(depth));
+
+    let start = (*ray).start_ndc;
+    let direction = (*ray).end_ndc - start;
+
+    let start_uv = ndc_to_uv(start.xy);
+    let end_uv = ndc_to_uv((*ray).end_ndc.xy);
+
+    // never more than one step per pixel, nor more than the limit; two at least
+    let length_px = length((end_uv - start_uv) * size);
+    let step_count = max(2u, min(min((*ray).linear_steps, SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT), u32(floor(length_px))));
+
+    var min_t = 0.0;
+    var max_t = 1.0;
+
+    var min_sample = ScreenSpaceLinearRaySample(0.0, false, 0.0);
+    var max_sample = ScreenSpaceLinearRaySample(0.0, false, 0.0);
+
+    var intersected = false;
+
+    var result: ScreenSpaceLinearRayHit;
+
+    result.hit = false;
+    result.steps = 0u;
+
+    // linear search for the first step behind both depth reads
+    for (var step = 0u; step < step_count; step++) {
+        let candidate_t = pow((f32(step) + (*ray).jitter) / f32(step_count), (*ray).linear_march_exponent);
+        let candidate = screen_space_linear_ray_sample(ray, depth, size, camera, start + direction * candidate_t);
+
+        result.steps = step + 1u;
+
+        if (screen_space_linear_ray_occludes(candidate)) {
+            max_t = candidate_t;
+            max_sample = candidate;
+            intersected = true;
+            break;
+        }
+
+        min_t = candidate_t;
+        min_sample = candidate;
+    }
+
+    var hit_t = min_t;
+    var hit_sample = min_sample;
+
+    if (intersected) {
+        // narrow [min_t, max_t] around the crossing
+        let bisection_steps = min((*ray).bisection_steps, SCREEN_SPACE_LINEAR_RAY_BISECTION_LIMIT);
+
+        for (var i = 0u; i < bisection_steps; i++) {
+            let mid_t = (min_t + max_t) * 0.5;
+            let candidate = screen_space_linear_ray_sample(ray, depth, size, camera, start + direction * mid_t);
+
+            if (screen_space_linear_ray_occludes(candidate)) {
+                max_t = mid_t;
+                max_sample = candidate;
+            } else {
+                min_t = mid_t;
+                min_sample = candidate;
+            }
+        }
+
+        hit_t = max_t;
+        hit_sample = max_sample;
+
+        if ((*ray).use_secant) {
+            // where the line through the bracket's two distances crosses zero; kept only if it is closer
+            let mid_t = mix(min_t, max_t, min_sample.distance / (min_sample.distance - max_sample.distance));
+            let candidate = screen_space_linear_ray_sample(ray, depth, size, camera, start + direction * mid_t);
+
+            if (abs(candidate.distance) < min_sample.distance * 0.9 && candidate.valid) {
+                hit_t = mid_t;
+                hit_sample = candidate;
+            }
+        }
+    }
+
+    result.t = hit_t;
+    result.uv = mix(start_uv, end_uv, hit_t);
+
+    let thickness = (*ray).depth_thickness;
+
+    if (intersected && hit_sample.penetration < thickness && hit_sample.distance < thickness) {
+        result.hit = true;
+        result.penetration = hit_sample.penetration;
+        result.penetration_fraction = hit_sample.penetration / thickness;
+    } else {
+        // the furthest the march got clear
+        result.t = min_t;
+        result.uv = mix(start_uv, end_uv, min_t);
+    }
+
+    return result;
+}
+`, [
+        chunk_v3_matrix4_project,
+        chunk_ndc_to_uv,
+        chunk_get_view_space_depth,
+        chunk_get_bilinear_filter_texel,
+        chunk_interpolate_bilinear_f32,
+    ]
+);

package/src/shade/renderer/shader/compiler/CodeChunk.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
 export class CodeChunk {
     /**
      * Special singleton
@@ -11,6 +15,13 @@ export class CodeChunk {
      * @returns {CodeChunk}
      */
     static from(code: string, dependencies?: CodeChunk[]): CodeChunk;
+    /**
+     * @param {CodeChunk} chunk
+     * @param {ShaderSwitchSet} set
+     * @param {Map<CodeChunk, CodeChunk>} memo what each chunk of this call's graph became
+     * @returns {CodeChunk}
+     */
+    static "__#71@#specialize"(chunk: CodeChunk, set: ShaderSwitchSet, memo: Map<CodeChunk, CodeChunk>): CodeChunk;
     get isCodeChunk(): boolean;
     /**
      *
@@ -51,6 +62,26 @@ export class CodeChunk {
      * @returns {CodeChunk[]}
      */
     collectDependencies(): CodeChunk[];
+    /**
+     * Every {@link ShaderSwitch} this chunk's graph decides somewhere, through every alternative of
+     * every {@link CodeChunkChoice}, selected or not: the switches a shader built on it depends on.
+     * Each appears once, in the order a breadth-first walk from here meets it.
+     *
+     * @returns {ShaderSwitch[]}
+     */
+    collectSwitches(): ShaderSwitch[];
+    /**
+     * This graph as `set` makes it: every {@link CodeChunkChoice} in it replaced by the alternative
+     * `set` selects, so the result holds no choice and links like any other graph.
+     *
+     * Only what lies above a choice is new. A chunk whose closure holds no choice is returned as it is,
+     * and so is this chunk when the whole graph holds none. Within one call each chunk is specialized
+     * once, so what two chunks share in this graph they still share in the result.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk}
+     */
+    specialize(set: ShaderSwitchSet): CodeChunk;
     /**
      * Unroll all dependencies, excluding this chunk, into a single list where all dependencies are in the correct order
      * @return {CodeChunk[]}
@@ -88,5 +119,7 @@ export class CodeChunk {
     equals(other: CodeChunk): boolean;
     #private;
 }
+export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
+export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 //# sourceMappingURL=CodeChunk.d.ts.map

package/src/shade/renderer/shader/compiler/CodeChunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAOA;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAkGjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IAnID,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAoCvB;IAED;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;OAEG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAA;KAAC,CA4C9E;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAOnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAWnB;;CACJ;oCAtXmC,4CAA4C"}
+{"version":3,"file":"CodeChunk.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunk.js"],"names":[],"mappings":"AAMA;;;GAGG;AAGH;IAMI;;;OAGG;IACH,cAFU,SAAS,SAAS,CAAC,CAEoB;IAkGjD;;;;;OAKG;IACH,kBAHW,MAAM,iBADN,SAAS,EAAE,GAET,SAAS,CAqBrB;IA+JD;;;;;OAKG;IACH,kCALW,SAAS,OACT,eAAe,QACf,IAAI,SAAS,EAAE,SAAS,CAAC,GACvB,SAAS,CAsDrB;IA5VD,2BAEC;IAcD;;;OAGG;IACH,mBAEC;IAeD;;;;OAIG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAMnB;IAkBD;;;OAGG;IACH,gCAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;OAIG;IACH,0BAHW,SAAS,GACP,OAAO,CAmBnB;IAqCD;;;;OAIG;IACH,6CAHW,IAAI,SAAS,CAAC,GACZ,OAAO,CAgBnB;IAED;;;;OAIG;IACH,+BAHW,SAAS,GACP,OAAO,CAqBnB;IAED;;;OAGG;IACH,uBAFa,SAAS,EAAE,CAuCvB;IAED;;;;;;OAMG;IACH,mBAFa,YAAY,EAAE,CA0C1B;IAED;;;;;;;;;;OAUG;IACH,gBAHW,eAAe,GACb,SAAS,CAOrB;IA8DD;;;OAGG;IACH,wBAFY,SAAS,EAAE,CAgDtB;IAED;;OAEG;IACH,WAFa;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,mBAAmB,EAAE,MAAM,EAAE,CAAA;KAAC,CA4C9E;IAED,mBAEC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,YAFW,SAAS,QAOnB;IAED;;;OAGG;IACH,SAFY,SAAS,CAQpB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAgBnB;;CACJ;2BA/fY,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;oCAJvB,4CAA4C"}

package/src/shade/renderer/shader/compiler/CodeChunk.js

@@ -4,6 +4,11 @@ import { isArrayEqual } from "../../../../core/collection/array/isArrayEqual.js"
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
 
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+
 
 export class CodeChunk {
 
@@ -206,6 +211,9 @@ export class CodeChunk {
 
             const chunk = stack[stack_pointer];
 
+            if (chunk.isCodeChunkChoice === true) {
+                throw new Error(`The graph holds a ${chunk}; specialize it before linking it, see CodeChunk.specialize`);
+            }
 
             if (collected.has(chunk)) {
                 // already visited, skip
@@ -227,6 +235,133 @@ export class CodeChunk {
         return Array.from(collected);
     }
 
+    /**
+     * Every {@link ShaderSwitch} this chunk's graph decides somewhere, through every alternative of
+     * every {@link CodeChunkChoice}, selected or not: the switches a shader built on it depends on.
+     * Each appears once, in the order a breadth-first walk from here meets it.
+     *
+     * @returns {ShaderSwitch[]}
+     */
+    collectSwitches() {
+        /**
+         * @type {ShaderSwitch[]}
+         */
+        const switches = [];
+
+        /**
+         * @type {Set<CodeChunk>}
+         */
+        const visited = new Set([this]);
+
+        /**
+         * @type {CodeChunk[]}
+         */
+        const queue = [this];
+
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            const chunk = queue[cursor];
+
+            let next;
+
+            if (chunk.isCodeChunkChoice === true) {
+                array_push_if_unique(switches, chunk.shader_switch);
+
+                next = chunk.alternatives;
+            } else {
+                next = chunk.#dependencies;
+            }
+
+            for (let i = 0; i < next.length; i++) {
+                const dependency = next[i];
+
+                if (!visited.has(dependency)) {
+                    visited.add(dependency);
+                    queue.push(dependency);
+                }
+            }
+        }
+
+        return switches;
+    }
+
+    /**
+     * This graph as `set` makes it: every {@link CodeChunkChoice} in it replaced by the alternative
+     * `set` selects, so the result holds no choice and links like any other graph.
+     *
+     * Only what lies above a choice is new. A chunk whose closure holds no choice is returned as it is,
+     * and so is this chunk when the whole graph holds none. Within one call each chunk is specialized
+     * once, so what two chunks share in this graph they still share in the result.
+     *
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk}
+     */
+    specialize(set) {
+        assert.defined(set, 'set');
+        assert.equal(set.isShaderSwitchSet, true, 'set.isShaderSwitchSet !== true');
+
+        return CodeChunk.#specialize(this, set, new Map());
+    }
+
+    /**
+     * @param {CodeChunk} chunk
+     * @param {ShaderSwitchSet} set
+     * @param {Map<CodeChunk, CodeChunk>} memo what each chunk of this call's graph became
+     * @returns {CodeChunk}
+     */
+    static #specialize(chunk, set, memo) {
+        let r = memo.get(chunk);
+
+        if (r !== undefined) {
+            return r;
+        }
+
+        if (chunk.isCodeChunkChoice === true) {
+            r = CodeChunk.#specialize(chunk.alternative_for(set), set, memo);
+
+            memo.set(chunk, r);
+
+            return r;
+        }
+
+        const dependencies = chunk.#dependencies;
+        const n = dependencies.length;
+
+        /**
+         * Left null for as long as every dependency comes back as itself.
+         * @type {CodeChunk[]|null}
+         */
+        let specialized = null;
+
+        for (let i = 0; i < n; i++) {
+            const dependency = dependencies[i];
+            const s = CodeChunk.#specialize(dependency, set, memo);
+
+            if (specialized === null && s !== dependency) {
+                specialized = dependencies.slice(0, i);
+            }
+
+            if (specialized !== null) {
+                // two choices may select one chunk, or a choice the chunk that is also a sibling
+                array_push_if_unique(specialized, s);
+            }
+        }
+
+        if (specialized === null) {
+            r = chunk;
+        } else {
+            r = new CodeChunk();
+
+            r.#text = chunk.#text;
+            r.#dependencies = specialized;
+            r.#extensions = chunk.#extensions.slice();
+            r.#language_extensions = chunk.#language_extensions.slice();
+        }
+
+        memo.set(chunk, r);
+
+        return r;
+    }
+
     /**
      * Unroll all dependencies, excluding this chunk, into a single list where all dependencies are in the correct order
      * @return {CodeChunk[]}
@@ -371,6 +506,11 @@ export class CodeChunk {
             return true;
         }
 
+        if (other.isCodeChunkChoice === true) {
+            // a choice has no text of its own; it is equal only to itself
+            return false;
+        }
+
         return this.#text === other.#text
             && isArrayEqual(this.#dependencies, other.#dependencies)
             ;

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @typedef {import("./ShaderSwitch.js").ShaderSwitch} ShaderSwitch
+ * @typedef {import("./ShaderSwitchSet.js").ShaderSwitchSet} ShaderSwitchSet
+ */
+/**
+ * The place in a chunk graph where a {@link ShaderSwitch} is decided: a chunk that stands for one
+ * alternative per value of the switch.
+ *
+ * Every alternative defines the same WGSL functions, so whatever depends on the choice is written
+ * once, whichever is linked. Each alternative is an ordinary {@link CodeChunk} with its own
+ * dependencies. {@link CodeChunk#specialize} replaces the choice with the alternative a
+ * {@link ShaderSwitchSet} selects, so the graph that is compiled has only that alternative's closure
+ * in it, and no choice.
+ *
+ * ```js
+ * export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
+ * chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);
+ * ```
+ *
+ * A chunk depends on the choice as on any chunk, however deep, and a shader learns that it depends on
+ * the switch from its graph ({@link CodeChunk#collectSwitches}).
+ */
+export class CodeChunkChoice extends CodeChunk {
+    /**
+     * @param {ShaderSwitch} shader_switch
+     * @returns {CodeChunkChoice} with no alternatives yet; {@link add} one per value
+     */
+    static from(shader_switch: ShaderSwitch): CodeChunkChoice;
+    /**
+     * @returns {ShaderSwitch}
+     */
+    get shader_switch(): import("./ShaderSwitch.js").ShaderSwitch;
+    /**
+     * Every alternative given so far, for walks that must see all of them.
+     * @returns {CodeChunk[]}
+     */
+    get alternatives(): CodeChunk[];
+    /**
+     * @param {number|boolean} value one of the switch's values — a member of its enum, or `false`/`true` — not
+     * given an alternative yet
+     * @param {CodeChunk} alternative linked when the switch has this value. It may itself be a choice,
+     * of another switch.
+     */
+    add(value: number | boolean, alternative: CodeChunk): void;
+    /**
+     * @param {ShaderSwitchSet} set
+     * @returns {CodeChunk} the alternative `set` selects
+     * @throws {Error} when the selected value has no alternative here
+     */
+    alternative_for(set: ShaderSwitchSet): CodeChunk;
+    /**
+     * A choice is linked as the alternative it stands for; see {@link CodeChunk#specialize}.
+     */
+    compile(): void;
+    /**
+     * @param {CodeChunkChoice} other
+     */
+    copy(other: CodeChunkChoice): void;
+    /**
+     * @returns {CodeChunkChoice}
+     */
+    clone(): CodeChunkChoice;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCodeChunkChoice: boolean;
+    #private;
+}
+export type ShaderSwitch = import("./ShaderSwitch.js").ShaderSwitch;
+export type ShaderSwitchSet = import("./ShaderSwitchSet.js").ShaderSwitchSet;
+import { CodeChunk } from "./CodeChunk.js";
+//# sourceMappingURL=CodeChunkChoice.d.ts.map

package/src/shade/renderer/shader/compiler/CodeChunkChoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeChunkChoice.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/compiler/CodeChunkChoice.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAsHI;;;OAGG;IACH,2BAHW,YAAY,GACV,eAAe,CAW3B;IA7HD;;OAEG;IACH,8DAEC;IAQD;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,WALW,MAAM,GAAC,OAAO,eAEd,SAAS,QAcnB;IAED;;;;OAIG;IACH,qBAJW,eAAe,GACb,SAAS,CAarB;IAkBD;;OAEG;IACH,gBAEC;IAWD;;OAEG;IACH,YAFW,eAAe,QAKzB;IAED;;OAEG;IACH,SAFa,eAAe,CAQ3B;IAsBL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;2BA3JY,OAAO,mBAAmB,EAAE,YAAY;8BACxC,OAAO,sBAAsB,EAAE,eAAe;0BAJjC,gBAAgB"}