@woosh/meep-engine 3.65.0 → 3.68.0

package/src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_gather.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A probe's radiance from its rays (Lumen's `ScreenProbeCompositeTracesWithScatterCS`): a workgroup a probe, its lanes
+ * over its n² rays, then over its n² texels.
+ *
+ * - **A ray's weight** is its texel's share of the probe's texel, (n / its level's resolution)²: one, or a quarter
+ *   for a child of a split texel, which holds a quarter of the solid angle (the map is equal-area).
+ * - **Its radiance**, pre-exposed as every ray's is, times the weight, held to `SCREEN_PROBE_MAX_RAY_INTENSITY`, the
+ *   brightest channel scaled down to it: the display's units, so a sum of the brightest rays stays well inside the
+ *   atlas's half floats at any exposure.
+ * - **Its texel**: where its direction falls on the probe's n² grid, less half a texel, and from there to the texel
+ *   below or above along each axis as the probe's dither, one blue-noise draw at the probe's tile half the noise's
+ *   period from the jitter's, falls under or over the place's fraction: each ray lands in one of the four texels about
+ *   it in proportion to its bilinear weights, which hides the grid of directions. A step past the octahedron's edge
+ *   lands on its fold (`screen_probe_texel_wrap`).
+ * - **Accumulated** in workgroup memory, fixed point with the scale that keeps n² of the largest radiance in a word;
+ *   each texel keeps the nearest hit among the rays that landed, and whether any did.
+ * - **The texels**: the sum, not normalised, as Lumen's: a texel takes about one ray's weight on average; the nearest
+ *   hit in alpha, negative where none landed.
+ * - **The probe's moving share**: the moving rays' weight over n², Lumen's, which its thresholds are set against (the
+ *   filter's 1%, the fast update's 10%). With importance sampling the rays' weights sum to less than n², so a share
+ *   of their sum would pass those thresholds at less motion.
+ * - Rays that ended unresolved, or of no ray, bring nothing; a probe on no surface is zero.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_composite: ComputeShader;
+/**
+ * One pass of the filter between probes (Lumen's `ScreenProbeFilterGatherTracesCS`): a thread a texel of the frame's
+ * probes, through the thread-a-ray command; its result in alpha keeps the texel's own nearest hit, which no pass
+ * changes.
+ *
+ * - **The texel itself** weighs one where a ray landed in it, and nothing where none did.
+ * - **Its neighbours**: the uniform probes of the four tiles beside its probe's, the same texel of each; with the
+ *   probe's rays seeing more than 1% moving, the eight beyond them too, as the temporal filter will hold less of its
+ *   history.
+ * - **A neighbour's weight**: its plane weight from the probe's plane, on the same surface, times, unless the probe's
+ *   rays saw something moving, an angle weight: where the neighbour's ray in the texel hit, at the nearer of its own
+ *   and the probe's nearest hits, seen from the probe, against the texel's direction, `1 − angle / θ`. θ is the half
+ *   angle of the cone with a texel's solid angle, acos(1 − 2/n²), 14.4° at n = 8: a neighbour's light is the
+ *   texel's when what it saw lies inside the texel's cone from here. Lumen's 10° is the cone of half the texel's
+ *   solid angle at n = 8.
+ * - A neighbour on no surface, or whose texel no ray landed in, gives nothing. The mean of what is given; zero where
+ *   nothing is.
+ *
+ * Lumen weighs a neighbour by its depth's difference; the plane weight here is interpolation's, on which a neighbour
+ * further along a slanted surface is still the same surface.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_filter: ComputeShader;
+/**
+ * A probe's radiance as SH3 (Lumen's `ScreenProbeConvertToIrradianceCS`, its SH3 form): a workgroup a probe, its lanes
+ * over its texels. The radiance is pre-exposed, and so is the SH. Each texel holds 4π/n² of the sphere, so the
+ * projection is `Σ L(ωᵢ)·Y(ωᵢ)·4π/n²` over the texels, at
+ * each texel's centre; a texel no ray landed in adds nothing. Stored as the probe clipmap's records store theirs
+ * (`probe_record_sh_encode`), seven words a probe; readers resolve E with `sh3_color_get_irradiance_at`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_irradiance: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_screen_probe_gather.d.ts.map

package/src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_screen_probe_gather.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_gather.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4CAFU,aAAa,CAqIpB;AAaH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAFU,aAAa,CAgIpB;AAWH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CA0FpB;8BArd2B,+BAA+B"}

package/src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_gather.js

@@ -0,0 +1,478 @@
+import { chunk_uv_equal_area_sphere } from "../../shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.js";
+import {
+    chunk_uv_octahedral_unit_decode
+} from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_stbn_sample_vec2 } from "../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { chunk_sh3_basis_at } from "../../shader/chunk/spherical_harmonics/chunk_sh3_basis_at.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { STBN_VEC2_RESOURCE } from "../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { chunk_probe_clipmap } from "../probe_clipmap/probe/chunk_probe_clipmap.js";
+import {
+    chunk_screen_probe,
+    chunk_screen_probe_counts,
+    chunk_screen_probe_ray_jitter,
+    SCREEN_PROBE_DISPATCH_READ_RESOURCE,
+    SCREEN_PROBE_FRAME_RESOURCE,
+    SCREEN_PROBE_MOVING_READ_RESOURCE,
+    SCREEN_PROBE_MOVING_WRITE_RESOURCE,
+    SCREEN_PROBE_RADIANCE_READ_RESOURCE,
+    SCREEN_PROBE_RADIANCE_WRITE_RESOURCE,
+    SCREEN_PROBE_RAY_INFO_READ_RESOURCE,
+    SCREEN_PROBE_SH_WRITE_RESOURCE,
+    SCREEN_PROBE_TRACE_HIT_READ_RESOURCE,
+    SCREEN_PROBE_TRACE_RADIANCE_READ_RESOURCE,
+    SCREEN_PROBES_READ_RESOURCE
+} from "./chunk_screen_probe.js";
+import { chunk_screen_probe_workgroup_sum } from "./chunk_screen_probe_workgroup_sum.js";
+import {
+    SCREEN_PROBE_MAX_RAY_INTENSITY,
+    SCREEN_PROBE_OCTAHEDRON_LIMIT,
+    SCREEN_PROBE_THREAD_WORKGROUP_SIZE
+} from "./SCREEN_PROBE.js";
+
+const composite_resources = new ShaderResourceSetDescriptor();
+
+composite_resources.createGroup()
+    .add(SCREEN_PROBE_FRAME_RESOURCE)
+    .add(SCREEN_PROBES_READ_RESOURCE)
+    .add(SCREEN_PROBE_DISPATCH_READ_RESOURCE)
+    .add(SCREEN_PROBE_MOVING_WRITE_RESOURCE)
+    .add(STBN_VEC2_RESOURCE)
+    .add(SCREEN_PROBE_RAY_INFO_READ_RESOURCE)
+    .add(SCREEN_PROBE_TRACE_RADIANCE_READ_RESOURCE)
+    .add(SCREEN_PROBE_TRACE_HIT_READ_RESOURCE)
+    .add(SCREEN_PROBE_RADIANCE_WRITE_RESOURCE);
+
+/**
+ * A probe's radiance from its rays (Lumen's `ScreenProbeCompositeTracesWithScatterCS`): a workgroup a probe, its lanes
+ * over its n² rays, then over its n² texels.
+ *
+ * - **A ray's weight** is its texel's share of the probe's texel, (n / its level's resolution)²: one, or a quarter
+ *   for a child of a split texel, which holds a quarter of the solid angle (the map is equal-area).
+ * - **Its radiance**, pre-exposed as every ray's is, times the weight, held to `SCREEN_PROBE_MAX_RAY_INTENSITY`, the
+ *   brightest channel scaled down to it: the display's units, so a sum of the brightest rays stays well inside the
+ *   atlas's half floats at any exposure.
+ * - **Its texel**: where its direction falls on the probe's n² grid, less half a texel, and from there to the texel
+ *   below or above along each axis as the probe's dither, one blue-noise draw at the probe's tile half the noise's
+ *   period from the jitter's, falls under or over the place's fraction: each ray lands in one of the four texels about
+ *   it in proportion to its bilinear weights, which hides the grid of directions. A step past the octahedron's edge
+ *   lands on its fold (`screen_probe_texel_wrap`).
+ * - **Accumulated** in workgroup memory, fixed point with the scale that keeps n² of the largest radiance in a word;
+ *   each texel keeps the nearest hit among the rays that landed, and whether any did.
+ * - **The texels**: the sum, not normalised, as Lumen's: a texel takes about one ray's weight on average; the nearest
+ *   hit in alpha, negative where none landed.
+ * - **The probe's moving share**: the moving rays' weight over n², Lumen's, which its thresholds are set against (the
+ *   filter's 1%, the fast update's 10%). With importance sampling the rays' weights sum to less than n², so a share
+ *   of their sum would pass those thresholds at less motion.
+ * - Rays that ended unresolved, or of no ray, bring nothing; a probe on no surface is zero.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_composite = ComputeShader.from({
+    label: "Screen Probe Composite",
+    resources: composite_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+const SCREEN_PROBE_TEXEL_LIMIT = ${SCREEN_PROBE_OCTAHEDRON_LIMIT * SCREEN_PROBE_OCTAHEDRON_LIMIT}u;
+
+// each texel's red, green, blue, and how many rays landed
+var<workgroup> screen_probe_sums: array<atomic<u32>, ${4 * SCREEN_PROBE_OCTAHEDRON_LIMIT * SCREEN_PROBE_OCTAHEDRON_LIMIT}>;
+// each texel's nearest hit, a positive f32's bits, which order as the floats do
+var<workgroup> screen_probe_nearest: array<atomic<u32>, SCREEN_PROBE_TEXEL_LIMIT>;
+
+@compute @workgroup_size(${SCREEN_PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+    @builtin(subgroup_invocation_id) subgroup_lane: u32,
+    @builtin(subgroup_size) subgroup_size: u32,
+) {
+    let probe = folded_workgroup_index(workgroup_id);
+
+    if (probe >= screen_probe_count()) {
+        return;
+    }
+
+    let frame = screen_probe_frame;
+    let n = frame.octahedron_resolution;
+    let count = n * n;
+    let record = screen_probes[probe];
+
+    if (record.depth <= 0.0) {
+        for (var t = lane; t < count; t += ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u) {
+            textureStore(screen_probe_radiance_out, screen_probe_texel(probe, t), vec4<f32>(0.0, 0.0, 0.0, -1.0));
+        }
+
+        if (lane == 0u) {
+            screen_probe_moving[probe] = 0.0;
+        }
+
+        return;
+    }
+
+    for (var t = lane; t < count; t += ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u) {
+        atomicStore(&screen_probe_sums[4u * t], 0u);
+        atomicStore(&screen_probe_sums[4u * t + 1u], 0u);
+        atomicStore(&screen_probe_sums[4u * t + 2u], 0u);
+        atomicStore(&screen_probe_sums[4u * t + 3u], 0u);
+        atomicStore(&screen_probe_nearest[t], bitcast<u32>(65504.0));
+    }
+
+    workgroupBarrier();
+
+    // the largest radiance a ray may bring, and the fixed point that holds n² of it in a word: 2³² − 256, the largest
+    // u32 an f32 holds exactly, where 4294967295.0 rounds up to 2³² and n² rays at the limit wrap a word to zero
+    let limit = ${SCREEN_PROBE_MAX_RAY_INTENSITY}.0;
+    let quantum = (4294967040.0 / f32(count)) / limit;
+
+    let pixel = screen_probe_pixel_decode(record.pixel);
+    let tile = screen_probe_noise_tile(probe, pixel);
+    let jitter = screen_probe_ray_jitter(tile);
+    let dither = stbn_sample_vec2(vec3<u32>(tile, frame.frame_index + 32u));
+
+    var moving = 0.0;
+
+    for (var slot = lane; slot < count; slot += ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u) {
+        let at = screen_probe_texel(probe, slot);
+        let hit = textureLoad(screen_probe_trace_hit, at, 0).r;
+        let kind = screen_probe_trace_hit_kind(hit);
+
+        if (kind == SCREEN_PROBE_TRACE_PENDING || kind == SCREEN_PROBE_TRACE_UNRESOLVED || kind == SCREEN_PROBE_TRACE_NONE) {
+            continue;
+        }
+
+        let info = textureLoad(screen_probe_ray_info, at, 0).r;
+        let size = f32((n * 2u) >> screen_probe_ray_info_level(info));
+        let share = f32(n) / size;
+        let weight = share * share;
+
+        var radiance = textureLoad(screen_probe_trace_radiance, at, 0).rgb * weight;
+        let brightest = max(radiance.r, max(radiance.g, radiance.b));
+
+        if (brightest > limit) {
+            radiance *= limit / brightest;
+        }
+
+        // the ray's place on the probe's grid, dithered to one of the four texels about it
+        let place = (vec2<f32>(screen_probe_ray_info_texel(info)) + jitter) * share - 0.5;
+        let corner = floor(place);
+        let landing = screen_probe_texel_wrap(vec2<i32>(corner) + select(vec2<i32>(1), vec2<i32>(0), place - corner < dither));
+        let index = landing.y * n + landing.x;
+
+        let quantised = vec3<u32>(radiance * quantum);
+
+        atomicAdd(&screen_probe_sums[4u * index], quantised.r);
+        atomicAdd(&screen_probe_sums[4u * index + 1u], quantised.g);
+        atomicAdd(&screen_probe_sums[4u * index + 2u], quantised.b);
+        atomicAdd(&screen_probe_sums[4u * index + 3u], 1u);
+        atomicMin(&screen_probe_nearest[index], bitcast<u32>(max(screen_probe_trace_hit_distance(hit), 0.0)));
+
+        moving += select(0.0, weight, (hit & SCREEN_PROBE_TRACE_MOVING) != 0u);
+    }
+
+    workgroupBarrier();
+
+    for (var t = lane; t < count; t += ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u) {
+        let sum = vec3<f32>(vec3<u32>(
+            atomicLoad(&screen_probe_sums[4u * t]),
+            atomicLoad(&screen_probe_sums[4u * t + 1u]),
+            atomicLoad(&screen_probe_sums[4u * t + 2u]),
+        )) / quantum;
+        let landed = atomicLoad(&screen_probe_sums[4u * t + 3u]) != 0u;
+        let nearest = select(-1.0, bitcast<f32>(atomicLoad(&screen_probe_nearest[t])), landed);
+
+        textureStore(screen_probe_radiance_out, screen_probe_texel(probe, t), vec4<f32>(sum, nearest));
+    }
+
+    let shares = screen_probe_workgroup_sum(vec4<f32>(moving, 0.0, 0.0, 0.0), lane, subgroup_lane, subgroup_size);
+
+    if (lane == 0u) {
+        screen_probe_moving[probe] = shares.x / f32(count);
+    }
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_screen_probe_ray_jitter,
+            chunk_screen_probe_workgroup_sum,
+            chunk_folded_workgroup_index,
+            chunk_stbn_sample_vec2,
+        ]),
+});
+
+const filter_resources = new ShaderResourceSetDescriptor();
+
+filter_resources.createGroup()
+    .add(SCREEN_PROBE_FRAME_RESOURCE)
+    .add(SCREEN_PROBES_READ_RESOURCE)
+    .add(SCREEN_PROBE_DISPATCH_READ_RESOURCE)
+    .add(SCREEN_PROBE_MOVING_READ_RESOURCE)
+    .add(STBN_VEC2_RESOURCE)
+    .add(SCREEN_PROBE_RADIANCE_READ_RESOURCE)
+    .add(SCREEN_PROBE_RADIANCE_WRITE_RESOURCE);
+
+/**
+ * One pass of the filter between probes (Lumen's `ScreenProbeFilterGatherTracesCS`): a thread a texel of the frame's
+ * probes, through the thread-a-ray command; its result in alpha keeps the texel's own nearest hit, which no pass
+ * changes.
+ *
+ * - **The texel itself** weighs one where a ray landed in it, and nothing where none did.
+ * - **Its neighbours**: the uniform probes of the four tiles beside its probe's, the same texel of each; with the
+ *   probe's rays seeing more than 1% moving, the eight beyond them too, as the temporal filter will hold less of its
+ *   history.
+ * - **A neighbour's weight**: its plane weight from the probe's plane, on the same surface, times, unless the probe's
+ *   rays saw something moving, an angle weight: where the neighbour's ray in the texel hit, at the nearer of its own
+ *   and the probe's nearest hits, seen from the probe, against the texel's direction, `1 − angle / θ`. θ is the half
+ *   angle of the cone with a texel's solid angle, acos(1 − 2/n²), 14.4° at n = 8: a neighbour's light is the
+ *   texel's when what it saw lies inside the texel's cone from here. Lumen's 10° is the cone of half the texel's
+ *   solid angle at n = 8.
+ * - A neighbour on no surface, or whose texel no ray landed in, gives nothing. The mean of what is given; zero where
+ *   nothing is.
+ *
+ * Lumen weighs a neighbour by its depth's difference; the plane weight here is interpolation's, on which a neighbour
+ * further along a slanted surface is still the same surface.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_filter = ComputeShader.from({
+    label: "Screen Probe Filter",
+    resources: filter_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+struct ScreenProbeFilterSum {
+    radiance: vec3<f32>,
+    weight: f32,
+}
+
+// one neighbour's share of the texel, by its tile offset from the probe's tile
+fn screen_probe_filter_neighbour(
+    sum: ScreenProbeFilterSum,
+    tile: vec2<i32>,
+    offset: vec2<i32>,
+    slot: u32,
+    position: vec3<f32>,
+    plane: vec4<f32>,
+    depth: f32,
+    direction: vec3<f32>,
+    own_hit: f32,
+    angular: bool,
+    cos_limit: f32,
+) -> ScreenProbeFilterSum {
+    let tiles = vec2<i32>(screen_probe_frame.tile_count);
+    let at = tile + offset;
+
+    if (any(at < vec2<i32>(0)) || any(at >= tiles)) {
+        return sum;
+    }
+
+    let neighbour = u32(at.y) * screen_probe_frame.tile_count.x + u32(at.x);
+    let record = screen_probes[neighbour];
+
+    if (record.depth <= 0.0) {
+        return sum;
+    }
+
+    let position_weight = screen_probe_plane_weight(plane, record.position, depth);
+    let value = textureLoad(screen_probe_radiance, screen_probe_texel(neighbour, slot), 0);
+
+    if (position_weight <= 0.0 || value.a < 0.0) {
+        return sum;
+    }
+
+    var weight = position_weight;
+
+    if (angular) {
+        // where the neighbour's ray hit, held to the probe's own nearest so a near occluder's shadow stays
+        let reach = select(value.a, min(value.a, own_hit), own_hit >= 0.0);
+        let to_hit = record.position + direction * reach - position;
+        let cosine = dot(to_hit, direction) / max(length(to_hit), 1e-20);
+
+        weight *= 1.0 - saturate(acos(clamp(cosine, -1.0, 1.0)) / acos(cos_limit));
+    }
+
+    return ScreenProbeFilterSum(sum.radiance + value.rgb * weight, sum.weight + weight);
+}
+
+@compute @workgroup_size(${SCREEN_PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let frame = screen_probe_frame;
+    let index = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+    let shift = 2u * frame.octahedron_shift;
+    let probe = index >> shift;
+    let slot = index & ((1u << shift) - 1u);
+
+    if (probe >= screen_probe_count()) {
+        return;
+    }
+
+    let texel = screen_probe_texel(probe, slot);
+    let record = screen_probes[probe];
+
+    if (record.depth <= 0.0) {
+        textureStore(screen_probe_radiance_out, texel, vec4<f32>(0.0, 0.0, 0.0, -1.0));
+        return;
+    }
+
+    let n = frame.octahedron_resolution;
+    let own = textureLoad(screen_probe_radiance, texel, 0);
+    let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
+    let plane = vec4<f32>(normal, dot(normal, record.position));
+    let pixel = screen_probe_pixel_decode(record.pixel);
+    let tile = screen_probe_noise_tile(probe, pixel);
+    let in_probe = vec2<u32>(slot & (n - 1u), slot >> frame.octahedron_shift);
+    let direction = uv_equal_area_sphere_decode((vec2<f32>(in_probe) + screen_probe_ray_jitter(tile)) / f32(n));
+
+    let moving = screen_probe_moving[probe] > 0.01;
+    let cos_limit = 1.0 - 2.0 / f32(n * n);
+    let t = vec2<i32>(tile);
+
+    var sum = ScreenProbeFilterSum(select(vec3<f32>(0.0), own.rgb, own.a >= 0.0), select(0.0, 1.0, own.a >= 0.0));
+
+    // each neighbour by name
+    sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(-1, 0), slot, record.position, plane, record.depth, direction, own.a, !moving, cos_limit);
+    sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(1, 0), slot, record.position, plane, record.depth, direction, own.a, !moving, cos_limit);
+    sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(0, -1), slot, record.position, plane, record.depth, direction, own.a, !moving, cos_limit);
+    sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(0, 1), slot, record.position, plane, record.depth, direction, own.a, !moving, cos_limit);
+
+    if (moving) {
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(-2, 0), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(2, 0), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(0, -2), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(0, 2), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(-1, 1), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(1, 1), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(-1, -1), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+        sum = screen_probe_filter_neighbour(sum, t, vec2<i32>(1, -1), slot, record.position, plane, record.depth, direction, own.a, false, cos_limit);
+    }
+
+    let radiance = select(vec3<f32>(0.0), sum.radiance / sum.weight, sum.weight > 0.0);
+
+    textureStore(screen_probe_radiance_out, texel, vec4<f32>(radiance, own.a));
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_screen_probe_ray_jitter,
+            chunk_folded_workgroup_index,
+            chunk_uv_octahedral_unit_decode,
+        ]),
+});
+
+const irradiance_resources = new ShaderResourceSetDescriptor();
+
+irradiance_resources.createGroup()
+    .add(SCREEN_PROBE_FRAME_RESOURCE)
+    .add(SCREEN_PROBES_READ_RESOURCE)
+    .add(SCREEN_PROBE_DISPATCH_READ_RESOURCE)
+    .add(SCREEN_PROBE_SH_WRITE_RESOURCE)
+    .add(SCREEN_PROBE_RADIANCE_READ_RESOURCE);
+
+/**
+ * A probe's radiance as SH3 (Lumen's `ScreenProbeConvertToIrradianceCS`, its SH3 form): a workgroup a probe, its lanes
+ * over its texels. The radiance is pre-exposed, and so is the SH. Each texel holds 4π/n² of the sphere, so the
+ * projection is `Σ L(ωᵢ)·Y(ωᵢ)·4π/n²` over the texels, at
+ * each texel's centre; a texel no ray landed in adds nothing. Stored as the probe clipmap's records store theirs
+ * (`probe_record_sh_encode`), seven words a probe; readers resolve E with `sh3_color_get_irradiance_at`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_irradiance = ComputeShader.from({
+    label: "Screen Probe Irradiance",
+    resources: irradiance_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${SCREEN_PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+    @builtin(subgroup_invocation_id) subgroup_lane: u32,
+    @builtin(subgroup_size) subgroup_size: u32,
+) {
+    let probe = folded_workgroup_index(workgroup_id);
+
+    if (probe >= screen_probe_count()) {
+        return;
+    }
+
+    let frame = screen_probe_frame;
+    let n = frame.octahedron_resolution;
+    let count = n * n;
+
+    var sh = array<vec3<f32>, 9>();
+
+    if (screen_probes[probe].depth > 0.0) {
+        for (var t = lane; t < count; t += ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u) {
+            let value = textureLoad(screen_probe_radiance, screen_probe_texel(probe, t), 0);
+
+            if (value.a < 0.0) {
+                continue;
+            }
+
+            let texel = vec2<u32>(t & (n - 1u), t >> frame.octahedron_shift);
+            let basis = sh3_basis_at(uv_equal_area_sphere_decode((vec2<f32>(texel) + 0.5) / f32(n)));
+
+            sh[0] += value.rgb * basis[0];
+            sh[1] += value.rgb * basis[1];
+            sh[2] += value.rgb * basis[2];
+            sh[3] += value.rgb * basis[3];
+            sh[4] += value.rgb * basis[4];
+            sh[5] += value.rgb * basis[5];
+            sh[6] += value.rgb * basis[6];
+            sh[7] += value.rgb * basis[7];
+            sh[8] += value.rgb * basis[8];
+        }
+    }
+
+    // the 27 coefficients in seven sums
+    let a = screen_probe_workgroup_sum(vec4<f32>(sh[0], sh[1].r), lane, subgroup_lane, subgroup_size);
+    let b = screen_probe_workgroup_sum(vec4<f32>(sh[1].gb, sh[2].rg), lane, subgroup_lane, subgroup_size);
+    let c = screen_probe_workgroup_sum(vec4<f32>(sh[2].b, sh[3]), lane, subgroup_lane, subgroup_size);
+    let d = screen_probe_workgroup_sum(vec4<f32>(sh[4], sh[5].r), lane, subgroup_lane, subgroup_size);
+    let e = screen_probe_workgroup_sum(vec4<f32>(sh[5].gb, sh[6].rg), lane, subgroup_lane, subgroup_size);
+    let f = screen_probe_workgroup_sum(vec4<f32>(sh[6].b, sh[7]), lane, subgroup_lane, subgroup_size);
+    let g = screen_probe_workgroup_sum(vec4<f32>(sh[8], 0.0), lane, subgroup_lane, subgroup_size);
+
+    if (lane == 0u) {
+        // each texel's solid angle on the equal-area map
+        let w = 12.566370614359172 / f32(count);
+
+        let total = array<vec3<f32>, 9>(
+            a.xyz * w,
+            vec3<f32>(a.w, b.xy) * w,
+            vec3<f32>(b.zw, c.x) * w,
+            c.yzw * w,
+            d.xyz * w,
+            vec3<f32>(d.w, e.xy) * w,
+            vec3<f32>(e.zw, f.x) * w,
+            f.yzw * w,
+            g.xyz * w,
+        );
+
+        let words = probe_record_sh_encode(total);
+
+        for (var i = 0u; i < 7u; i++) {
+            screen_probe_sh[probe * 7u + i] = words[i];
+        }
+    }
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_screen_probe_workgroup_sum,
+            chunk_folded_workgroup_index,
+            chunk_sh3_basis_at,
+            chunk_probe_clipmap,
+        ]),
+});

package/src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_importance.d.ts

@@ -0,0 +1,69 @@
+/** Each probe's BRDF density, SH3 in three `vec4`s: coefficients 0–3, 4–7, and 8 alone. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_BRDF_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_BRDF_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each probe texel's lighting density, `r32float`, a texel a texel in the probes' atlas. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_LIGHTING_PDF_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_LIGHTING_PDF_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Last frame's probe radiance after the spatial filter, `rgba16float`. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RADIANCE_HISTORY_RESOURCE: ShaderResourceDescriptor;
+/** The G-buffer's shading normals. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_NORMAL_RESOURCE: ShaderResourceDescriptor;
+/**
+ * A probe's BRDF density (Lumen's `ScreenProbeComputeBRDFProbabilityDensityFunctionCS`): a workgroup a probe, a lane a
+ * pixel of an 8 × 8 grid over the square of 2D pixels about it, the pixels whose light interpolates from it. The centre
+ * lane takes the probe's own pixel.
+ *
+ * A pixel counts where it stands on the probe's surface: the probe's plane weight from the pixel's plane is past
+ * `SCREEN_PROBE_BRDF_PIXEL_WEIGHT` (the centre always counts). It adds its clamped cosine lobe about its shading normal
+ * as SH3 (`sh3_cosine_convolved_basis_at`, Lumen's `CalcDiffuseTransferSH3`), and the probe's density is the mean of
+ * the lobes: at a direction, how much the pixels' diffuse would weigh light from it.
+ *
+ * Lumen offsets its grid by `t/8·2D − 1` pixels, to one side of the probe; here the cells are centred on it, as the
+ * pixels that read the probe are.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brdf_pdf: ComputeShader;
+/**
+ * A probe's lighting density (Lumen's `ScreenProbeComputeLightingProbabilityDensityFunctionCS`): a workgroup a probe,
+ * its lanes over its n² texels.
+ *
+ * - **History**: last frame's four uniform probes around the probe's surface point that stood on its surface
+ *   (`screen_probe_lighting_history`), each giving its filtered radiance in the same texel, since a texel is a
+ *   direction in the world. They are averaged, pre-exposed as last frame's exposure left them and brought to this
+ *   frame's (`screen_probe_exposure` over `screen_probe_exposure_previous`), as Lumen rescales its history.
+ * - **The rest**: the share of the four that gave nothing, 1 − accepted / 4, is the world-space probes' radiance the
+ *   probe's pick reads (`screen_probe_picks`), along the texel's direction at this frame's jitter, pre-exposed by this
+ *   frame's exposure. Where nothing was picked, the history alone, or one where there is none: a density that ranks
+ *   nothing.
+ * - The density is each texel's luminance over the probe's sum.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_lighting_pdf: ComputeShader;
+/**
+ * A probe's rays (Lumen's `ScreenProbeGenerateRaysCS`): a workgroup a probe, its lanes over its n² rays, each written
+ * as the texel and level it falls in (`screen_probe_ray_info_pack`), a ray's slot its place in the sorted order.
+ *
+ * 1. **Density**: each texel's BRDF density at its centre, `max(0, Σ brdf·Y(ω))`; times its lighting density · n².
+ *    A texel any of whose directions the BRDF density reaches `SCREEN_PROBE_MIN_PDF` is held there
+ *    (`screen_probe_brdf_keeps`), so the light ranks texels and only the pixels' lobes cull one; another falls under
+ *    it unless its light lifts it.
+ * 2. **Sort**: the probe's own rays, ascending by density, ties in index order (`screen_probe_ray_sort`: the engine's
+ *    bitonic network in the workgroup's memory, O(n² log² n) a probe, where Lumen ranks every ray against every other,
+ *    O(n⁴)).
+ * 3. **Reassignment**: the sorted rays in threes from the lowest; a three whose highest is under the minimum gives
+ *    its rays to the highest texel not yet given, from the top: that texel splits into its four children at twice the
+ *    resolution, the three take three children and the texel the fourth. One level only, as Lumen's parallel path.
+ *    A child holds a quarter of its parent's solid angle (the map is equal-area), which the composite weighs it by.
+ *
+ * With importance sampling off, or where the probe stands on no surface, ray i is texel i at the probe's own n.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_generate_rays: ComputeShader;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_screen_probe_importance.d.ts.map

package/src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_importance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_screen_probe_importance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_importance.js"],"names":[],"mappings":"AAgDA,4HAA4H;AAC5H,8CADgG,wBAAwB,CACM;AAC9H,uCAAuC;AACvC,+CADW,wBAAwB,CACkG;AAErI,8HAA8H;AAC9H,sDADkG,wBAAwB,CACiB;AAC3I,uCAAuC;AACvC,uDADW,wBAAwB,CAC0H;AAE7J,4GAA4G;AAC5G,qDADgF,wBAAwB,CACsC;AAE9I,uEAAuE;AACvE,2CAD2C,wBAAwB,CAC6B;AAchG;;;;;;;;;;;;;;GAcG;AACH,2CAFU,aAAa,CA6EpB;AAoBH;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,aAAa,CAiHpB;AAYH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAFU,aAAa,CAiHpB;yCA7bsC,mDAAmD;8BAD9D,+BAA+B"}