@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_indirect_lighting.js

@@ -0,0 +1,175 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_get_ibl_irradiance } from "../../../deferred/indirect/chunk_get_ibl_irradiance.js";
+import { chunk_get_ibl_radiance } from "../../../deferred/indirect/chunk_get_ibl_radiance.js";
+import { DEPTH_STENCIL_FOREGROUND_ONLY } from "../../../depth/DEPTH_STENCIL_FOREGROUND_ONLY.js";
+import { BSDF_ROUGHNESS_MINIMUM } from "../../../light/environment/DEFINES.js";
+import { ENVIRONMENT_MAP_RESOURCE } from "../../../light/environment/ENVIRONMENT_MAP_RESOURCE.js";
+import { ENVIRONMENT_MAP_SAMPLER_RESOURCE } from "../../../light/environment/ENVIRONMENT_MAP_SAMPLER_RESOURCE.js";
+import { chunk_compute_specular_occlusion_bn } from "../../../shader/chunk/brdf/chunk_compute_specular_occlusion_bn.js";
+import { chunk_MIN_DIELECTRICS_F0 } from "../../../shader/chunk/brdf/chunk_MIN_DIELECTRICS_F0.js";
+import { chunk_project_position_from_depth } from "../../../shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_mat4_extract_position } from "../../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
+import { chunk_decode_g_buffer_normal } from "../../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { chunk_compute_indirect_specular } from "../../../shader/chunk/material/chunk_compute_indirect_specular.js";
+import { chunk_decode_g_buffer_metalness } from "../../../shader/chunk/material/chunk_decode_g_buffer_metalness.js";
+import { chunk_decode_g_buffer_roughness } from "../../../shader/chunk/material/chunk_decode_g_buffer_roughness.js";
+import { chunk_metalness_to_specular_color } from "../../../shader/chunk/material/chunk_metalness_to_specular_color.js";
+import { PI_DECLARATION } from "../../../shader/chunk/math/PI_DECLARATION.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import {
+    chunk_resolve_irradiance_sh_to_diffuse
+} from "../../../shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_diffuse.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ImageShader } from "../../../shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shader/ShaderDescriptor.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { VIEW_UNIFORM_STRUCT } from "../../../view/VIEW_UNIFORM_STRUCT.js";
+import { chunk_probe_clipmap_pick, PROBE_CLIPMAP_SAMPLING_GROUP } from "./chunk_probe_clipmap_pick.js";
+import { chunk_probe_clipmap_sample_radiance } from "./chunk_probe_clipmap_sample_radiance.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addTexture("tDepth")
+    .addTexture("tNormals", "uint")
+    .addTexture("tBentNormals", "uint")
+    .addTexture("tGBufferAlbedo")
+    .addTexture("tGBufferPBR")
+    .add(STBN_VEC2_RESOURCE)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .add(ENVIRONMENT_MAP_RESOURCE)
+    .add(ENVIRONMENT_MAP_SAMPLER_RESOURCE)
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addTexture("tSplitSum", "float");
+
+resources.addGroup(PROBE_CLIPMAP_SAMPLING_GROUP);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+    @builtin(position) coord: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+) -> @location(0) vec4<f32> {
+    let i_coord = vec2<u32>(coord.xy);
+
+    let depth = textureLoad(tDepth, i_coord, 0).r;
+    let texel_pbr = textureLoad(tGBufferPBR, i_coord, 0);
+    let albedo_ao = textureLoad(tGBufferAlbedo, i_coord, 0);
+
+    let albedo = albedo_ao.rgb;
+    let occlusion = albedo_ao.a;
+
+    let f_metalness = decode_g_buffer_metalness(texel_pbr);
+
+    // the radiance is sampled at the surface's roughness, as the IBL pass samples it; the resolve holds it off zero
+    let surface_roughness = decode_g_buffer_roughness(texel_pbr);
+    let roughness = max(surface_roughness, ${BSDF_ROUGHNESS_MINIMUM});
+    let alpha = roughness * roughness;
+
+    let position = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
+    let view_direction = normalize(mat4_extract_position(camera.transform) - position);
+
+    // the surface's own normal picks, as want chose by it; the bent normal resolves the diffuse, as IBL's does
+    let normal = decode_g_buffer_normal(textureLoad(tNormals, i_coord, 0).xy);
+    let bent_normal = decode_g_buffer_normal(textureLoad(tBentNormals, i_coord, 0).xy);
+
+    // one pick for both lobes
+    let noise = stbn_sample_vec2(vec3<u32>(i_coord, view.frame_index));
+    let pick = probe_clipmap_pick(position, normal, view_direction, noise);
+
+    let probes = probe_clipmap_sh_of(pick);
+
+    var irradiance: vec3<f32>;
+    var radiance: vec3<f32>;
+
+    if (probes.found) {
+        // the resolve gives E/π
+        irradiance = PI * resolve_irradiance_sh_to_diffuse(probes.sh.Y, probes.sh.CoCg, bent_normal);
+        radiance = probe_clipmap_radiance_of(pick, position, normal, view_direction, surface_roughness).radiance;
+    } else {
+        // a pixel no probe weighs anything for takes the environment's, as the IBL passes give it
+        irradiance = get_ibl_irradiance(bent_normal);
+        radiance = get_ibl_radiance(view_direction, normal, surface_roughness);
+    }
+
+    // what shader_resolve_indirect_lighting does with the pair: the diffuse with AO in, the specular occluded
+    // along the lobe it was taken along
+    let indirect = compute_indirect_specular(
+        radiance,
+        irradiance * occlusion,
+        normal,
+        view_direction,
+        albedo * (1.0 - f_metalness),
+        metalness_to_specular_color(f_metalness, albedo),
+        vec3(MIN_DIELECTRICS_F0),
+        albedo,
+        1.0,
+        roughness,
+    );
+
+    let spec_direction = normalize(mix(reflect(-view_direction, normal), normal, alpha));
+    let specular_occlusion = compute_specular_occlusion_bn(spec_direction, bent_normal, occlusion, roughness);
+
+    return vec4(indirect[0] * specular_occlusion + indirect[1], 1.0);
+}
+`, [
+    chunk_project_position_from_depth,
+    chunk_mat4_extract_position,
+    chunk_decode_g_buffer_normal,
+    chunk_decode_g_buffer_metalness,
+    chunk_decode_g_buffer_roughness,
+    chunk_metalness_to_specular_color,
+    chunk_MIN_DIELECTRICS_F0,
+    chunk_stbn_sample_vec2,
+    chunk_probe_clipmap_pick,
+    chunk_probe_clipmap_sample_radiance,
+    chunk_resolve_irradiance_sh_to_diffuse,
+    chunk_get_ibl_irradiance,
+    chunk_get_ibl_radiance,
+    chunk_compute_indirect_specular,
+    chunk_compute_specular_occlusion_bn,
+    PI_DECLARATION,
+]);
+
+/**
+ * The probe clipmap's deferred indirect light in one pass (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.6), for SSR
+ * off: one pick a pixel, by its own normal and the view, with the frame's STBN, for both lobes.
+ * - The diffuse is `shader_probe_clipmap_diffuse`'s: the picked SH resolved at the bent normal, times π. Its
+ *   shares are the pick's, not re-weighted for the bent normal, so SSR on and off light the diffuse alike.
+ * - The specular is the pick's radiance (`probe_clipmap_radiance_of`), its shares re-weighted for the lobe.
+ * - A pixel no probe weighs anything for takes the environment's for both.
+ * - The two are resolved as `shader_resolve_indirect_lighting` resolves the IBL pair: AO multiplies the
+ *   diffuse, the specular is occluded along its lobe, and the result is added to the scene's colour.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_indirect_lighting = ImageShader.from({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap / Indirect Lighting (Fused)",
+        resources,
+        body,
+    }),
+    targets: [
+        {
+            format: "rgba16float",
+            blend: {
+                color: {
+                    operation: "add",
+                    srcFactor: "one",
+                    dstFactor: "one",
+                },
+                alpha: {
+                    operation: "add",
+                    srcFactor: "zero",
+                    dstFactor: "one",
+                }
+            }
+        }
+    ],
+    depthStencil: DEPTH_STENCIL_FOREGROUND_ONLY,
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The light a front-face hit takes from beyond the trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a
+ * thread a ray, after shade through the same launch, `PROBE_DISPATCH_RAYS`, its probe the one trace wrote
+ * into its flags. It adds ρ_d·(E_loc + E_ind)/π to the radiance shade left, ρ_d being the albedo shade
+ * left in the ray's \`row\`.
+ *
+ * - **E_loc, the local lights**: one of the point and spot lights of the hit's cell of the world light
+ *   clusters, built over the bricks' cascades so that every hit has one, at most
+ *   `IRRADIANCE_CLIPMAP_LIGHT_BUDGET` of each; past them lights are dropped. Each light's unshadowed
+ *   irradiance is the irradiance clipmap's, at the footprint of a voxel of the hit's cascade, by its
+ *   cosine at the hit's normal.
+ *   - One is picked by weighted reservoir sampling over the cell's lights, its weight the luminance of
+ *     that irradiance, with one number stretched over the candidates as `sample_discrete_wrs` does; it
+ *     lights the hit by its irradiance over the chance of its pick, w/W. The probe's blend of its rays
+ *     averages the picks to the cell's sum.
+ *   - The picked light's shadow is a ray traced through the brick clipmap, as the hit's own ray was:
+ *     from a voxel off the surface, past the field's half-voxel expand, toward a point of the light's
+ *     sphere drawn as the path tracer draws it, stopping short of that point by the light's near clip or
+ *     a voxel, whichever is more, for the expand at that end. It sees the light if it misses; a hit, or a
+ *     march that spends its steps, is no light. A light that casts no shadow traces none.
+ *   - The pick and the point are drawn from the ray's slot and direction, fresh every update.
+ * - **E_ind, the next bounce**: this mode's own diffuse at the hit, `probe_clipmap_sample_sh` from the
+ *   hit along its normal, the view back along the ray, with the ray's own jitter as the pick's noise.
+ *   The projection writes the records later in the frame, so they hold last frame's SH: each frame takes
+ *   one more bounce.
+ * - Where no probe weighs anything the bounce is **zero**, not the environment: a hit behind the camera
+ *   in a cave must not bring daylight in. The next frame's hits' wants ask for the probes it read
+ *   (`shader_probe_clipmap_want_hits`), so the bounce has them a frame or two later.
+ * - LPV's 0.97 a bounce is dropped: an albedo under one bounds the series already.
+ *
+ * Its own pass because shade binds nine of a stage's ten storage buffers, and the pick takes two more.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_light: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_light.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_light.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,yCAFU,aAAa,CA6LpB;8BApS2B,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.js

@@ -0,0 +1,316 @@
+import { MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { chunk_light_cluster_counts } from "../../../light/cluster/chunk_light_cluster_counts.js";
+import { LIGHT_DATA_RESOURCE } from "../../../light/LIGHT_DATA_RESOURCE.js";
+import { LIGHT_DATABASE_SPEC } from "../../../light/LIGHT_DATABASE_SPEC.js";
+import { LIGHT_FLAGS } from "../../../light/model/io/LIGHT_FLAGS.js";
+import {
+    chunk_world_light_cluster_lookup_at,
+    WORLD_CLUSTER_DATA_RESOURCE,
+    WORLD_CLUSTER_LOOKUP_RESOURCE
+} from "../../../light/world_cluster/chunk_world_light_cluster_lookup.js";
+import { chunk_rgb_to_luminance } from "../../../shader/chunk/color/chunk_rgb_to_luminance.js";
+import { chunk_rgbe9995_decode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_decode.js";
+import { chunk_rgbe9995_encode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_encode.js";
+import { chunk_uv_octahedral_unit_decode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { chunk_sphere_sample_volume } from "../../../shader/chunk/geometry/sphere/chunk_sphere_sample_volume.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { RECIPROCAL_PI_DECLARATION } from "../../../shader/chunk/math/RECIPROCAL_PI_DECLARATION.js";
+import { chunk_hash_to_float01 } from "../../../shader/chunk/random/chunk_hash_to_float01.js";
+import { chunk_pcg4d } from "../../../shader/chunk/random/pcg/chunk_pcg4d.js";
+import {
+    chunk_resolve_irradiance_sh_to_diffuse
+} from "../../../shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_diffuse.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import { chunk_irradiance_clipmap_local_light } from "../../../volumetrics/irradiance_clipmap/chunk_irradiance_clipmap_local_light.js";
+import { IRRADIANCE_CLIPMAP_LIGHT_BUDGET } from "../../../volumetrics/irradiance_clipmap/IRRADIANCE_CLIPMAP.js";
+import { BRICK_TRACE_HIT } from "../brick/BRICK_CLIPMAP.js";
+import {
+    BRICK_ATLAS_TEXTURE_RESOURCE,
+    BRICK_LEVELS_RESOURCE,
+    BRICK_MAP_TEXTURE_RESOURCE,
+    BRICK_OCCUPANCY_TEXTURE_RESOURCE,
+    BRICK_SAMPLER_RESOURCE,
+    chunk_brick_clipmap_trace
+} from "../brick/chunk_brick_clipmap_trace.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_jitter,
+    chunk_probe_clipmap_ray_layout,
+    chunk_probe_clipmap_ray_origin,
+    chunk_probe_clipmap_ray_texel,
+    PROBE_DEPTH_HISTORY_RESOURCE,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
+    PROBE_RAYS_WRITE_RESOURCE,
+    PROBE_RECORDS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import {
+    chunk_probe_clipmap_pick,
+    PROBE_DEPTH_SAMPLER_RESOURCE,
+    PROBE_INDIRECTION_READ_RESOURCE,
+    PROBE_SAMPLING_RESOURCE
+} from "./chunk_probe_clipmap_pick.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+import { PROBE_TRACE_SETTINGS } from "./shader_probe_clipmap_trace.js";
+
+const POINT = LIGHT_DATABASE_SPEC.get('light_point');
+const SPOT = LIGHT_DATABASE_SPEC.get('light_spot');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_TRACE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_READ_RESOURCE)
+    .add(PROBE_RAYS_WRITE_RESOURCE)
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(STBN_VEC2_RESOURCE);
+
+resources.createGroup()
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_SAMPLING_RESOURCE)
+    .add(PROBE_INDIRECTION_READ_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_DEPTH_HISTORY_RESOURCE)
+    .add(PROBE_DEPTH_SAMPLER_RESOURCE);
+
+resources.createGroup()
+    .add(BRICK_LEVELS_RESOURCE)
+    .add(BRICK_MAP_TEXTURE_RESOURCE)
+    .add(BRICK_OCCUPANCY_TEXTURE_RESOURCE)
+    .add(BRICK_ATLAS_TEXTURE_RESOURCE)
+    .add(BRICK_SAMPLER_RESOURCE)
+    .add(LIGHT_DATA_RESOURCE)
+    .add(WORLD_CLUSTER_LOOKUP_RESOURCE)
+    .add(WORLD_CLUSTER_DATA_RESOURCE);
+
+/**
+ * The light a front-face hit takes from beyond the trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a
+ * thread a ray, after shade through the same launch, `PROBE_DISPATCH_RAYS`, its probe the one trace wrote
+ * into its flags. It adds ρ_d·(E_loc + E_ind)/π to the radiance shade left, ρ_d being the albedo shade
+ * left in the ray's \`row\`.
+ *
+ * - **E_loc, the local lights**: one of the point and spot lights of the hit's cell of the world light
+ *   clusters, built over the bricks' cascades so that every hit has one, at most
+ *   `IRRADIANCE_CLIPMAP_LIGHT_BUDGET` of each; past them lights are dropped. Each light's unshadowed
+ *   irradiance is the irradiance clipmap's, at the footprint of a voxel of the hit's cascade, by its
+ *   cosine at the hit's normal.
+ *   - One is picked by weighted reservoir sampling over the cell's lights, its weight the luminance of
+ *     that irradiance, with one number stretched over the candidates as `sample_discrete_wrs` does; it
+ *     lights the hit by its irradiance over the chance of its pick, w/W. The probe's blend of its rays
+ *     averages the picks to the cell's sum.
+ *   - The picked light's shadow is a ray traced through the brick clipmap, as the hit's own ray was:
+ *     from a voxel off the surface, past the field's half-voxel expand, toward a point of the light's
+ *     sphere drawn as the path tracer draws it, stopping short of that point by the light's near clip or
+ *     a voxel, whichever is more, for the expand at that end. It sees the light if it misses; a hit, or a
+ *     march that spends its steps, is no light. A light that casts no shadow traces none.
+ *   - The pick and the point are drawn from the ray's slot and direction, fresh every update.
+ * - **E_ind, the next bounce**: this mode's own diffuse at the hit, `probe_clipmap_sample_sh` from the
+ *   hit along its normal, the view back along the ray, with the ray's own jitter as the pick's noise.
+ *   The projection writes the records later in the frame, so they hold last frame's SH: each frame takes
+ *   one more bounce.
+ * - Where no probe weighs anything the bounce is **zero**, not the environment: a hit behind the camera
+ *   in a cave must not bring daylight in. The next frame's hits' wants ask for the probes it read
+ *   (`shader_probe_clipmap_want_hits`), so the bounce has them a frame or two later.
+ * - LPV's 0.97 a bounce is dropped: an albedo under one bounds the series already.
+ *
+ * Its own pass because shade binds nine of a stage's ten storage buffers, and the pick takes two more.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_light = ComputeShader.from({
+    label: "Probe Clipmap Light",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+// E_loc at a front-face hit in brick cascade \`cascade\`: one of its world cluster cell's point and spot lights,
+// picked by \`random.x\` in proportion to its light at the hit and over the chance of its pick, shadowed by a ray
+// toward the point of the light's sphere \`random.yzw\` draws
+fn probe_clipmap_local_irradiance(cascade: u32, position: vec3<f32>, normal: vec3<f32>, random: vec4<f32>) -> vec3<f32> {
+    let level = brick_levels[cascade];
+    let voxel = level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+    let cell = world_light_cluster_metadata_at(cascade, level, 0.0, position);
+    let point_count = min(light_cluster_count_point(cell.counts), ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u);
+    let spot_count = min(light_cluster_count_spot(cell.counts), ${IRRADIANCE_CLIPMAP_LIGHT_BUDGET}u);
+
+    // the cell's spot lights follow its point lights
+    let spots = cell.offset + light_cluster_count_point(cell.counts);
+
+    // the reservoir: the weights so far, and the light it holds
+    var u = random.x;
+    var total = 0.0;
+    var picked = vec3<f32>(0.0);
+    var picked_weight = 0.0;
+    var picked_index = 0u;
+    var picked_spot = false;
+
+    for (var j = 0u; j < point_count + spot_count; j++) {
+        let spot = j >= point_count;
+        let index = world_cluster_data[select(cell.offset + j, spots + (j - point_count), spot)];
+
+        var irradiance: vec3<f32>;
+
+        if (spot) {
+            let light = irradiance_clipmap_get_spot_light_info_by_index(&light_data, index, position, voxel);
+
+            irradiance = light.color * max(dot(normal, light.direction), 0.0);
+        } else {
+            let light = irradiance_clipmap_get_point_light_info_by_index(&light_data, index, position, voxel);
+
+            irradiance = light.color * max(dot(normal, light.direction), 0.0);
+        }
+
+        let weight = rgb_to_luminance(irradiance);
+
+        if (weight <= 0.0) {
+            continue;
+        }
+
+        // the light takes the reservoir by its share of the weights so far, and the number is stretched back
+        // over [0, 1) from whichever side of the share it fell
+        total += weight;
+
+        let share = weight / total;
+
+        if (u < share) {
+            u = u / share;
+            picked = irradiance;
+            picked_weight = weight;
+            picked_index = index;
+            picked_spot = spot;
+        } else {
+            u = (u - share) / (1.0 - share);
+        }
+    }
+
+    if (total <= 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    // the pick's light over the chance of the pick, w / W
+    let estimate = picked * (total / picked_weight);
+
+    var source: vec3<f32>;
+    var radius: f32;
+    var near_clip: f32;
+    var flags: u32;
+
+    if (picked_spot) {
+        let light = ${SPOT.marshalling_method_read}(&light_data, picked_index);
+
+        source = light.position;
+        radius = light.radius;
+        near_clip = light.near_clip_distance;
+        flags = light.flags;
+    } else {
+        let light = ${POINT.marshalling_method_read}(&light_data, picked_index);
+
+        source = light.position.xyz;
+        radius = light.radius;
+        near_clip = light.near_clip_distance;
+        flags = light.flags;
+    }
+
+    if ((flags & ${LIGHT_FLAGS.CASTS_SHADOW_BIT}u) == 0u) {
+        return estimate;
+    }
+
+    // from a voxel off the surface, past the half voxel the field's surface may sit off it, to a point of the
+    // light, short of it by the light's near clip or by a voxel for the expand at that end
+    let lifted = position + normal * voxel;
+    let to_light = source + radius * sphere_sample_volume(random.yzw) - lifted;
+    let span = length(to_light);
+    let reach = span - max(near_clip, voxel);
+
+    if (reach <= 0.0) {
+        return estimate;
+    }
+
+    let shadow = brick_clipmap_trace(lifted, to_light / span, 0.0, reach, settings.brick_cascade_count);
+
+    return select(vec3<f32>(0.0), estimate, shadow.kind == BRICK_TRACE_MISS);
+}
+
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+    let record = probe_rays[ray];
+    let albedo = unpack4x8unorm(record.row).rgb;
+    let front_hit = (record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_HIT}u && (record.flags & PROBE_RAY_BACK_FACE) == 0u;
+
+    // only a front-face hit that bounces anything takes more light
+    if (!front_hit || all(albedo == vec3<f32>(0.0))) {
+        return;
+    }
+
+    // the probe's update's rays, and this one's place among them
+    let k = record.flags >> PROBE_RAY_PROBE_SHIFT;
+    let span = probe_clipmap_probe_rays(k);
+    let rays = span.y;
+    let i = ray - span.x;
+
+    let slot = probe_trace.elements[k];
+    let n = settings.radiance_resolution;
+    let updates = probe_state_updates(probe_states[slot].x);
+    let texel = probe_clipmap_ray_texel(i, updates, rays, n * n);
+
+    let direction = uv_octahedral_unit_decode(unpack2x16unorm(record.direction));
+    let position = probe_clipmap_ray_origin(probe_origins[k], slot, record.direction) + record.t * direction;
+    let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
+
+    // the local lights' pick and their shadow ray's point, apart from the origin's draw
+    let hash = pcg4d(vec4<u32>(slot, record.direction, 0xA54FF53Au, 0u));
+    let random = vec4<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y), hash_to_float01(hash.z), hash_to_float01(hash.w));
+
+    // E/π: the local lights', then the next bounce's, which the resolve gives as E/π
+    var e = probe_clipmap_local_irradiance((record.flags >> PROBE_RAY_CASCADE_SHIFT) & PROBE_RAY_CASCADE_MASK, position, normal, random) * RECIPROCAL_PI;
+
+    let probes = probe_clipmap_sample_sh(position, normal, -direction, probe_clipmap_ray_jitter(slot, texel, i, updates, rays, n));
+
+    if (probes.found) {
+        e += resolve_irradiance_sh_to_diffuse(probes.sh.Y, probes.sh.CoCg, normal);
+    }
+
+    if (all(e == vec3<f32>(0.0))) {
+        return;
+    }
+
+    probe_rays[ray].light = rgbe9995_encode(rgbe9995_decode(record.light) + albedo * e);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_layout,
+            chunk_probe_clipmap_ray_texel,
+            chunk_probe_clipmap_ray_jitter,
+            chunk_probe_clipmap_ray_origin,
+            chunk_folded_workgroup_index,
+            chunk_uv_octahedral_unit_decode,
+            chunk_probe_clipmap_pick,
+            chunk_resolve_irradiance_sh_to_diffuse,
+            RECIPROCAL_PI_DECLARATION,
+            chunk_world_light_cluster_lookup_at,
+            chunk_light_cluster_counts,
+            chunk_irradiance_clipmap_local_light,
+            chunk_rgb_to_luminance,
+            chunk_brick_clipmap_trace,
+            chunk_pcg4d,
+            chunk_hash_to_float01,
+            chunk_sphere_sample_volume,
+            POINT.chunk_read,
+            SPOT.chunk_read,
+            chunk_rgbe9995_decode,
+            chunk_rgbe9995_encode,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_order.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ORDER_SETTINGS: WebGPUStruct;
+/**
+ * The trace list in the probes' order (§8.6): a workgroup a run of `PROBE_ORDER_RUN` listed
+ * probes, dispatched through `PROBE_DISPATCH_ORDER` once the due passes have listed the frame's updates,
+ * sorts its run in place by each probe's cascade and the Morton code of its lattice point in the
+ * cascade's window, the cascade above. Every pass after it reads a probe's place in the list from the
+ * sorted list, the rays' layout among them, so the rays of neighbouring probes run in neighbouring
+ * waves. Past one run the list is ordered within each run, not across them.
+ *
+ * Measured (PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md): the rays' stretch 1–4% shorter on
+ * the iGPU at 131k rays a frame, level on the 4090. The order is the only one of the rays' orders
+ * measured that pays: every sort of the rays themselves, global or within chunks, by direction, by
+ * place or by both, costs more than it buys, because the rays of one probe already share their waves.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_order: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_order.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_order.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_order.js"],"names":[],"mappings":"AAeA;;GAEG;AACH,mCAFU,YAAY,CASG;AAWzB;;;;;;;;;;;;;;GAcG;AACH,yCAFU,aAAa,CA4DpB;6BArG0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_order.js

@@ -0,0 +1,110 @@
+import { chunk_sort_bitonic_workgroup } from "../../../gpu_primitive/sort/chunk_sort_bitonic_workgroup.js";
+import { SORT_KEYS_PER_THREAD, SORT_TILE_SIZE, SORT_WORKGROUP_SIZE } from "../../../gpu_primitive/sort/defs.js";
+import { chunk_v3_morton_encode } from "../../../shader/chunk/bvh/morton/chunk_v3_morton_encode.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.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 { assert } from "../../../../../core/assert.js";
+import { chunk_probe_clipmap, PROBE_LEVELS_RESOURCE, PROBE_RECORDS_READ_RESOURCE, PROBE_TRACE_ORDER_RESOURCE } from "./chunk_probe_clipmap.js";
+import { PROBE_ORDER_RUN } from "./PROBE_CLIPMAP.js";
+
+assert.equal(PROBE_ORDER_RUN, SORT_TILE_SIZE, 'PROBE_ORDER_RUN is a tile of the bitonic sort');
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ORDER_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** lattice points a side of a cascade's window */
+    resolution: u32,
+    /** bits an axis of the Morton code, ⌈log2 resolution⌉ */
+    axis_bits: u32,
+}, "ProbeOrderSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_ORDER_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_ORDER_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_LEVELS_RESOURCE);
+
+/**
+ * The trace list in the probes' order (§8.6): a workgroup a run of `PROBE_ORDER_RUN` listed
+ * probes, dispatched through `PROBE_DISPATCH_ORDER` once the due passes have listed the frame's updates,
+ * sorts its run in place by each probe's cascade and the Morton code of its lattice point in the
+ * cascade's window, the cascade above. Every pass after it reads a probe's place in the list from the
+ * sorted list, the rays' layout among them, so the rays of neighbouring probes run in neighbouring
+ * waves. Past one run the list is ordered within each run, not across them.
+ *
+ * Measured (PROBE_RAYS_VARIABLE_AND_SORTED_SCOPE_2026_10_30.md): the rays' stretch 1–4% shorter on
+ * the iGPU at 131k rays a frame, level on the 4090. The order is the only one of the rays' orders
+ * measured that pays: every sort of the rays themselves, global or within chunks, by direction, by
+ * place or by both, costs more than it buys, because the rays of one probe already share their waves.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_order = ComputeShader.from({
+    label: "Probe Clipmap Order",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+// the run's keys and the slots they carry, which the bitonic sort orders by name
+var<workgroup> keys: array<u32, ${SORT_TILE_SIZE}>;
+var<workgroup> values: array<u32, ${SORT_TILE_SIZE}>;
+
+var<workgroup> wg_count: u32;
+
+@compute @workgroup_size(${SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) thread_id: u32,
+) {
+    let base = folded_workgroup_index(workgroup_id) * ${SORT_TILE_SIZE}u;
+
+    if (thread_id == 0u) {
+        let listed = min(probe_trace.count, settings.trace_capacity);
+
+        wg_count = min(select(0u, listed - base, listed > base), ${SORT_TILE_SIZE}u);
+    }
+
+    // the sort's barriers sit under loops its count bounds, so the count is the workgroup's
+    let count = workgroupUniformLoad(&wg_count);
+    let last = i32(settings.resolution) - 1;
+
+    for (var k = 0u; k < ${SORT_KEYS_PER_THREAD}u; k++) {
+        let at = k * ${SORT_WORKGROUP_SIZE}u + thread_id;
+
+        if (at < count) {
+            let slot = probe_trace.elements[base + at];
+            let cascade = probe_record_cascade(probe_records[slot].flags);
+            let local = vec3<u32>(clamp(probe_records[slot].cell - probe_levels[cascade].corner, vec3<i32>(0), vec3<i32>(last)));
+
+            keys[at] = (cascade << (3u * settings.axis_bits)) | v3_morton_encode(local.x, local.y, local.z);
+            values[at] = slot;
+        }
+    }
+
+    sort_bitonic_workgroup(thread_id, count);
+
+    for (var k = 0u; k < ${SORT_KEYS_PER_THREAD}u; k++) {
+        let at = k * ${SORT_WORKGROUP_SIZE}u + thread_id;
+
+        if (at < count) {
+            probe_trace.elements[base + at] = values[at];
+        }
+    }
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_v3_morton_encode,
+            chunk_sort_bitonic_workgroup,
+        ]),
+});