@woosh/meep-engine 3.67.0 → 3.68.0

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

@@ -0,0 +1,509 @@
+import { ENVIRONMENT_MAP_SAMPLER_RESOURCE } from "../../light/environment/ENVIRONMENT_MAP_SAMPLER_RESOURCE.js";
+import { LIGHT_DATA_RESOURCE } from "../../light/LIGHT_DATA_RESOURCE.js";
+import {
+    WORLD_CLUSTER_DATA_RESOURCE,
+    WORLD_CLUSTER_LOOKUP_RESOURCE
+} from "../../light/world_cluster/chunk_world_light_cluster_lookup.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.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_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_uv_octahedral_unit_encode
+} from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.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_sh3_color_get_irradiance_at
+} from "../../shader/chunk/spherical_harmonics/chunk_sh3_color_get_irradiance_at.js";
+import { chunk_sample_environment_map } from "../../shader/chunk/texture/sample/chunk_sample_environment_map.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { ShaderResourceGroupDescriptor } from "../../shader/resource/ShaderResourceGroupDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { vec2u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { BRICK_TRACE_HIT, BRICK_TRACE_MISS } from "../probe_clipmap/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 "../probe_clipmap/brick/chunk_brick_clipmap_trace.js";
+import {
+    BRICK_MATERIAL_ALBEDO_RESOURCE,
+    BRICK_MATERIAL_EMISSIVE_RESOURCE
+} from "../probe_clipmap/material/chunk_brick_material.js";
+import {
+    PROBE_LEVELS_RESOURCE,
+    PROBE_RECORD_STRUCT,
+    PROBE_WANTED_BITS_RESOURCE,
+    PROBE_WANTED_WRITE_RESOURCE
+} from "../probe_clipmap/probe/chunk_probe_clipmap.js";
+import {
+    chunk_probe_clipmap_local_irradiance,
+    chunk_probe_clipmap_sun_irradiance
+} from "../probe_clipmap/probe/chunk_probe_clipmap_hit_light.js";
+import { chunk_probe_clipmap_hit_material_pick } from "../probe_clipmap/probe/chunk_probe_clipmap_hit_material.js";
+import {
+    chunk_probe_clipmap_pick_in,
+    PROBE_CLIPMAP_SAMPLING_GROUP,
+    PROBE_DEPTH_SAMPLER_RESOURCE,
+    PROBE_SAMPLING_STRUCT
+} from "../probe_clipmap/probe/chunk_probe_clipmap_pick.js";
+import { chunk_probe_clipmap_sample_radiance } from "../probe_clipmap/probe/chunk_probe_clipmap_sample_radiance.js";
+import { chunk_probe_clipmap_want } from "../probe_clipmap/probe/chunk_probe_clipmap_want.js";
+import { PROBE_RECEIVER_BIAS_VIEW } from "../probe_clipmap/probe/PROBE_CLIPMAP.js";
+import { PROBE_WANT_SETTINGS } from "../probe_clipmap/probe/shader_probe_clipmap_want.js";
+import {
+    chunk_screen_probe,
+    chunk_screen_probe_counts,
+    SCREEN_PROBE_DISPATCH_READ_RESOURCE,
+    SCREEN_PROBE_EXPOSURE_RESOURCE,
+    SCREEN_PROBE_FRAME_RESOURCE,
+    SCREEN_PROBE_PICKS_READ_RESOURCE,
+    SCREEN_PROBE_RAYS_WRITE_RESOURCE,
+    SCREEN_PROBE_TRACE_HIT_WRITE_RESOURCE,
+    SCREEN_PROBE_TRACE_RADIANCE_WRITE_RESOURCE,
+    SCREEN_PROBES_READ_RESOURCE
+} from "./chunk_screen_probe.js";
+import { SCREEN_PROBE_THREAD_WORKGROUP_SIZE } from "./SCREEN_PROBE.js";
+
+const brick_group = () => new ShaderResourceGroupDescriptor()
+    .add(BRICK_LEVELS_RESOURCE)
+    .add(BRICK_MAP_TEXTURE_RESOURCE)
+    .add(BRICK_OCCUPANCY_TEXTURE_RESOURCE)
+    .add(BRICK_ATLAS_TEXTURE_RESOURCE)
+    .add(BRICK_SAMPLER_RESOURCE);
+
+// each pass finds a ray's probe's origin and pick (`ScreenProbePick`) at the probe
+const rays_group = () => new ShaderResourceGroupDescriptor()
+    .add(SCREEN_PROBE_FRAME_RESOURCE)
+    .add(SCREEN_PROBE_RAYS_WRITE_RESOURCE)
+    .add(SCREEN_PROBE_PICKS_READ_RESOURCE)
+    .add(SCREEN_PROBE_DISPATCH_READ_RESOURCE);
+
+const trace_resources = new ShaderResourceSetDescriptor();
+
+trace_resources.addGroup(rays_group().add(SCREEN_PROBES_READ_RESOURCE).add(LIGHT_DATA_RESOURCE));
+trace_resources.addGroup(brick_group());
+
+/**
+ * The bricks' trace of the rays the screen left (Lumen's mesh and global SDF traces): a thread a ray of their list,
+ * through its command.
+ *
+ * - From the probe's origin (`ScreenProbePick#origin`) to the probe's reach (`brick_clipmap_trace`), starting a
+ *   voxel short of where the screen showed the ray clear. The screen's ray left the surface point, so that distance
+ *   moves by the origin's offset along this ray, as Lumen's world traces start twice their bias short of the screen's
+ *   distance, the most their biases move the start along the ray.
+ * - **A front-face hit** takes E_dir from the directional lights, shadowed by rays through the bricks
+ *   (`probe_clipmap_sun_irradiance`), each light's point of its disk drawn from the ray's id and direction.
+ * - **A back face** is a hit whose field's gradient runs along the ray: the ray started inside a solid.
+ * - **No hit within the reach**, or out of the world: the world-space probes the probe picked answer past it (FAR),
+ *   or the environment where it picked none (SKY).
+ * - **A march that spends its steps** is unresolved: no light.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brick_trace = ComputeShader.from({
+    label: "Screen Probe Brick Trace",
+    resources: trace_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,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+
+    if (i >= screen_probe_brick_ray_count()) {
+        return;
+    }
+
+    var entry = screen_probe_rays[i];
+
+    let probe = entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS;
+    let pick = screen_probe_picks[probe];
+    let origin = pick.origin;
+    let direction = uv_equal_area_sphere_decode(unpack2x16unorm(entry.direction));
+    let cascades = screen_probe_frame.brick_cascade_count;
+    let atlas_shift = screen_probe_frame.brick_atlas_shift;
+    let start = max(entry.t + dot(screen_probes[probe].position - origin.xyz, direction) - origin.w, 0.0);
+
+    let hit = brick_clipmap_trace(origin.xyz, direction, start, pick.reach, cascades, atlas_shift);
+
+    var kind = SCREEN_PROBE_TRACE_UNRESOLVED;
+    var light = vec3<f32>(0.0);
+
+    if (hit.kind == ${BRICK_TRACE_HIT}u) {
+        if (dot(hit.normal, direction) > 0.0) {
+            kind = SCREEN_PROBE_TRACE_BACK;
+        } else {
+            kind = SCREEN_PROBE_TRACE_HIT;
+            light = probe_clipmap_sun_irradiance(hit.position, hit.normal, hit.cascade, vec2<u32>(entry.ray, entry.direction), screen_probe_frame.brick_t_max, cascades, atlas_shift);
+        }
+    } else if (hit.kind == ${BRICK_TRACE_MISS}u) {
+        kind = select(SCREEN_PROBE_TRACE_SKY, SCREEN_PROBE_TRACE_FAR, dot(pick.weights, vec4<f32>(1.0)) > 0.0);
+    }
+
+    entry.t = hit.t;
+    entry.normal = select(0u, pack2x16unorm(uv_octahedral_unit_encode(hit.normal)), kind == SCREEN_PROBE_TRACE_HIT);
+    entry.flags = kind | (select(0u, hit.cascade, kind == SCREEN_PROBE_TRACE_HIT) << 3u);
+    entry.albedo = 0u;
+    entry.light = rgbe9995_encode(light);
+
+    screen_probe_rays[i] = entry;
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_brick_clipmap_trace,
+            chunk_folded_workgroup_index,
+            chunk_uv_equal_area_sphere,
+            chunk_uv_octahedral_unit_encode,
+            chunk_probe_clipmap_sun_irradiance,
+            chunk_rgbe9995_encode,
+        ]),
+});
+
+const shade_resources = new ShaderResourceSetDescriptor();
+
+shade_resources.addGroup(rays_group()
+    .addTexture("tEnvironment", "float", "2d")
+    .add(ENVIRONMENT_MAP_SAMPLER_RESOURCE));
+shade_resources.addGroup(brick_group()
+    .add(BRICK_MATERIAL_ALBEDO_RESOURCE)
+    .add(BRICK_MATERIAL_EMISSIVE_RESOURCE));
+shade_resources.addGroup(PROBE_CLIPMAP_SAMPLING_GROUP);
+
+/**
+ * What each ray left to the bricks brings back (as the probe clipmap's shade): a thread a ray of the list.
+ *
+ * - **A front-face hit**: `emissive + ρ_d·E_dir/π`, its surface one texel of the brick material at the hit drawn from
+ *   the ray's id and direction (`probe_clipmap_hit_material_pick`); its diffuse albedo goes into the ray for the light
+ *   and bounce passes.
+ * - **FAR**: the world-space probes the probe picked, each share's radiance along the ray (`probe_clipmap_radiance`):
+ *   what lies past the reach, as each of them sees it.
+ * - **SKY**: the prefiltered environment along the ray, at the roughness whose lobe covers a texel of the probe's
+ *   octahedron, 1/√n (as the probe clipmap's misses take it for theirs).
+ * - A back face and an unresolved march bring nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brick_shade = ComputeShader.from({
+    label: "Screen Probe Brick Shade",
+    resources: shade_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,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+
+    if (i >= screen_probe_brick_ray_count()) {
+        return;
+    }
+
+    let entry = screen_probe_rays[i];
+    let kind = entry.flags & SCREEN_PROBE_TRACE_KIND_MASK;
+    let probe = entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS;
+    let direction = uv_equal_area_sphere_decode(unpack2x16unorm(entry.direction));
+
+    var radiance = vec3<f32>(0.0);
+    var albedo = vec3<f32>(0.0);
+
+    if (kind == SCREEN_PROBE_TRACE_HIT) {
+        let position = screen_probe_picks[probe].origin.xyz + entry.t * direction;
+        let normal = uv_octahedral_unit_decode(unpack2x16unorm(entry.normal));
+        let draw = hash_to_float01(pcg4d(vec4<u32>(entry.ray, entry.direction, 0x510E527Fu, 0u)).x);
+        let surface = probe_clipmap_hit_material_pick(position, normal, entry.flags >> 3u, draw, screen_probe_frame.brick_atlas_shift);
+
+        radiance = surface.emissive + surface.albedo * rgbe9995_decode(entry.light) * RECIPROCAL_PI;
+        albedo = surface.albedo;
+    } else if (kind == SCREEN_PROBE_TRACE_FAR) {
+        let pick = screen_probe_picks[probe];
+
+        // each share by name
+        if (pick.weights.x > 0.0) { radiance += pick.weights.x * probe_clipmap_radiance(pick.slots.x, direction).rgb; }
+        if (pick.weights.y > 0.0) { radiance += pick.weights.y * probe_clipmap_radiance(pick.slots.y, direction).rgb; }
+        if (pick.weights.z > 0.0) { radiance += pick.weights.z * probe_clipmap_radiance(pick.slots.z, direction).rgb; }
+        if (pick.weights.w > 0.0) { radiance += pick.weights.w * probe_clipmap_radiance(pick.slots.w, direction).rgb; }
+    } else if (kind == SCREEN_PROBE_TRACE_SKY) {
+        radiance = sample_environment_map(tEnvironment, sEnvironment, direction, inverseSqrt(f32(screen_probe_frame.octahedron_resolution)));
+    }
+
+    screen_probe_rays[i].light = rgbe9995_encode(radiance);
+    screen_probe_rays[i].albedo = pack4x8unorm(vec4<f32>(albedo, 0.0));
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_uv_octahedral_unit_decode,
+            chunk_folded_workgroup_index,
+            chunk_uv_equal_area_sphere,
+            chunk_probe_clipmap_hit_material_pick,
+            chunk_probe_clipmap_sample_radiance,
+            chunk_sample_environment_map,
+            chunk_hash_to_float01,
+            chunk_pcg4d,
+            chunk_rgbe9995_decode,
+            chunk_rgbe9995_encode,
+            RECIPROCAL_PI_DECLARATION,
+        ]),
+});
+
+const light_resources = new ShaderResourceSetDescriptor();
+
+light_resources.addGroup(rays_group()
+    .add(LIGHT_DATA_RESOURCE)
+    .add(WORLD_CLUSTER_LOOKUP_RESOURCE)
+    .add(WORLD_CLUSTER_DATA_RESOURCE));
+light_resources.addGroup(brick_group());
+
+/**
+ * The local lights a front-face hit takes (as the probe clipmap's light pass): a thread a ray of the list, adding
+ * `ρ_d·E_loc/π`, one light of the hit's world light cluster cell picked by its light and shadowed by a ray through the
+ * bricks (`probe_clipmap_local_irradiance`), drawn from the ray's id and direction.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brick_light = ComputeShader.from({
+    label: "Screen Probe Brick Light",
+    resources: light_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,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+
+    if (i >= screen_probe_brick_ray_count()) {
+        return;
+    }
+
+    let entry = screen_probe_rays[i];
+    let albedo = unpack4x8unorm(entry.albedo).rgb;
+
+    // only a front-face hit that bounces anything takes more light
+    if ((entry.flags & SCREEN_PROBE_TRACE_KIND_MASK) != SCREEN_PROBE_TRACE_HIT || all(albedo == vec3<f32>(0.0))) {
+        return;
+    }
+
+    let direction = uv_equal_area_sphere_decode(unpack2x16unorm(entry.direction));
+    let position = screen_probe_picks[entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS].origin.xyz + entry.t * direction;
+    let normal = uv_octahedral_unit_decode(unpack2x16unorm(entry.normal));
+
+    // the pick and its shadow ray's point, apart from the trace's and the shade's draws
+    let hash = pcg4d(vec4<u32>(entry.ray, entry.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));
+
+    let e = probe_clipmap_local_irradiance(entry.flags >> 3u, position, normal, random, screen_probe_frame.brick_cascade_count, screen_probe_frame.brick_atlas_shift) * RECIPROCAL_PI;
+
+    if (all(e == vec3<f32>(0.0))) {
+        return;
+    }
+
+    screen_probe_rays[i].light = rgbe9995_encode(rgbe9995_decode(entry.light) + albedo * e);
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_uv_octahedral_unit_decode,
+            chunk_folded_workgroup_index,
+            chunk_uv_equal_area_sphere,
+            chunk_probe_clipmap_local_irradiance,
+            chunk_hash_to_float01,
+            chunk_pcg4d,
+            chunk_rgbe9995_decode,
+            chunk_rgbe9995_encode,
+            RECIPROCAL_PI_DECLARATION,
+        ]),
+});
+
+/**
+ * One world-space probe set's sampling resources under a prefix, for a pass that picks from two.
+ *
+ * @param {string} prefix
+ * @returns {ShaderResourceGroupDescriptor}
+ */
+function probe_set_group(prefix) {
+    return new ShaderResourceGroupDescriptor()
+        .add(ShaderResourceDescriptor.uniform(`${prefix}_levels`, CLIPMAP_LEVEL_ARRAY))
+        .add(ShaderResourceDescriptor.uniform(`${prefix}_sampling`, PROBE_SAMPLING_STRUCT))
+        .add(ShaderResourceDescriptor.texture(`${prefix}_indirection`, "uint", "3d"))
+        .add(ShaderResourceDescriptor.storageBuffer(`${prefix}_states`, WebGPUArray.from(vec2u)))
+        .add(ShaderResourceDescriptor.storageBuffer(`${prefix}_records`, WebGPUArray.from(PROBE_RECORD_STRUCT)))
+        .add(ShaderResourceDescriptor.texture(`${prefix}_depth`, "float", "2d"));
+}
+
+const bounce_resources = new ShaderResourceSetDescriptor();
+
+bounce_resources.addGroup(rays_group()
+    .add(SCREEN_PROBE_EXPOSURE_RESOURCE)
+    .add(SCREEN_PROBE_TRACE_RADIANCE_WRITE_RESOURCE)
+    .add(SCREEN_PROBE_TRACE_HIT_WRITE_RESOURCE)
+    .add(PROBE_DEPTH_SAMPLER_RESOURCE));
+bounce_resources.addGroup(probe_set_group("bounce_first"));
+bounce_resources.addGroup(probe_set_group("bounce_fallback"));
+
+/**
+ * The next bounce a front-face hit takes, and every ray's result into the probes' trace textures (as the probe
+ * clipmap's bounce): a thread a ray of the list, after the light pass.
+ *
+ * - **The bounce**, E_ind: the frustum's world-space probes picked at the hit along its normal, the view back along the
+ *   ray (`probe_clipmap_pick_in`), with the ray's own noise; where they weigh nothing, the world cache's. Where neither
+ *   has a probe, no bounce: the next frame's hit wants ask the world cache for them. A hit the frustum's probes served
+ *   has its albedo cleared, so it wants nothing (`shader_screen_probe_brick_want`). `ρ_d·E_ind/π` is added.
+ * - **The result**: the ray's radiance, pre-exposed (`screen_probe_exposure`), and its kind and distance to its texel of
+ *   `screen_probe_trace_radiance` and `screen_probe_trace_hit`, where the composite reads every ray, the screen's and
+ *   the bricks' alike.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brick_bounce = ComputeShader.from({
+    label: "Screen Probe Brick Bounce",
+    resources: bounce_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,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+
+    if (i >= screen_probe_brick_ray_count()) {
+        return;
+    }
+
+    let entry = screen_probe_rays[i];
+    let kind = entry.flags & SCREEN_PROBE_TRACE_KIND_MASK;
+    let albedo = unpack4x8unorm(entry.albedo).rgb;
+
+    var light = rgbe9995_decode(entry.light);
+
+    if (kind == SCREEN_PROBE_TRACE_HIT && any(albedo != vec3<f32>(0.0))) {
+        let direction = uv_equal_area_sphere_decode(unpack2x16unorm(entry.direction));
+        let position = screen_probe_picks[entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS].origin.xyz + entry.t * direction;
+        let normal = uv_octahedral_unit_decode(unpack2x16unorm(entry.normal));
+
+        let hash = pcg4d(vec4<u32>(entry.ray, entry.direction, 0x9B05688Cu, 0u));
+        let noise = vec2<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y));
+
+        var probes = probe_clipmap_sh_in(
+            &bounce_first_records,
+            probe_clipmap_pick_in(&bounce_first_levels, &bounce_first_sampling, bounce_first_indirection, &bounce_first_states, bounce_first_depth, position, normal, -direction, noise),
+        );
+
+        if (probes.found) {
+            // served: nothing of the fallback is wanted here
+            screen_probe_rays[i].albedo = 0u;
+        } else {
+            probes = probe_clipmap_sh_in(
+                &bounce_fallback_records,
+                probe_clipmap_pick_in(&bounce_fallback_levels, &bounce_fallback_sampling, bounce_fallback_indirection, &bounce_fallback_states, bounce_fallback_depth, position, normal, -direction, noise),
+            );
+        }
+
+        if (probes.found) {
+            light += albedo * sh3_color_get_irradiance_at(normal, probes.sh) * RECIPROCAL_PI;
+        }
+    }
+
+    let probe = entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS;
+    let texel = screen_probe_texel(probe, entry.ray & SCREEN_PROBE_RAY_SLOT_MASK);
+
+    textureStore(screen_probe_trace_radiance, texel, vec4<f32>(light * screen_probe_exposure.value, 0.0));
+    textureStore(screen_probe_trace_hit, texel, vec4<u32>(screen_probe_trace_hit_pack(kind, entry.t, false), 0u, 0u, 0u));
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_uv_octahedral_unit_decode,
+            chunk_folded_workgroup_index,
+            chunk_uv_equal_area_sphere,
+            chunk_probe_clipmap_pick_in,
+            chunk_sh3_color_get_irradiance_at,
+            chunk_hash_to_float01,
+            chunk_pcg4d,
+            chunk_rgbe9995_decode,
+            RECIPROCAL_PI_DECLARATION,
+        ]),
+});
+
+const want_resources = new ShaderResourceSetDescriptor();
+
+// the world cache's late wants, as `GPUProbeClipmap#write_want_bindings` hands them
+want_resources.setImmediate("settings", PROBE_WANT_SETTINGS);
+want_resources.addGroup(rays_group()
+    .add(PROBE_WANTED_WRITE_RESOURCE)
+    .add(PROBE_WANTED_BITS_RESOURCE)
+    .add(PROBE_LEVELS_RESOURCE));
+
+/**
+ * The hits' wants (as the probe clipmap's hit wants): a thread a ray of the list, after the bounce. A front-face hit
+ * whose albedo the bounce left, which the frustum's world-space probes did not serve, wants the cages its pick reads in
+ * the world cache's late set, which the cache's next lifetime takes. Every lane calls `probe_clipmap_want`, wanting or
+ * not, from uniform control flow.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_brick_want = ComputeShader.from({
+    label: "Screen Probe Brick Want",
+    resources: want_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,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + lane;
+
+    var wants = false;
+    var position = vec3<f32>(0.0);
+    var bias_direction = vec3<f32>(0.0, 0.0, 1.0);
+
+    if (i < screen_probe_brick_ray_count()) {
+        let entry = screen_probe_rays[i];
+
+        wants = (entry.flags & SCREEN_PROBE_TRACE_KIND_MASK) == SCREEN_PROBE_TRACE_HIT && entry.albedo != 0u;
+
+        if (wants) {
+            let direction = uv_equal_area_sphere_decode(unpack2x16unorm(entry.direction));
+            let normal = uv_octahedral_unit_decode(unpack2x16unorm(entry.normal));
+            position = screen_probe_picks[entry.ray >> SCREEN_PROBE_RAY_SLOT_BITS].origin.xyz + entry.t * direction;
+            // the view back along the ray, as the bounce's pick takes it
+            bias_direction = mix(normal, -direction, ${PROBE_RECEIVER_BIAS_VIEW});
+        }
+    }
+
+    probe_clipmap_want(wants, position, bias_direction, settings.cascade_count, settings.resolution, settings.anchor, settings.select_half, settings.wanted_capacity);
+}
+`, [
+            chunk_screen_probe,
+            chunk_screen_probe_counts,
+            chunk_folded_workgroup_index,
+            chunk_uv_equal_area_sphere,
+            chunk_uv_octahedral_unit_decode,
+            chunk_probe_clipmap_want,
+        ]),
+});

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

@@ -0,0 +1,20 @@
+/**
+ * Settings of the debug view.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_DEBUG_SETTINGS: WebGPUStruct;
+/**
+ * The screen probes' debug views (`ScreenProbeDebugView`), a thread a pixel, in place of the frame's colour:
+ *
+ * - **IndirectDiffuse**: the frame's diffuse over π, what a white Lambertian surface sends back of it.
+ * - **ProbePlacement**: the same, with each probe's pixel and the eight around it marked, uniform green and adaptive
+ *   red, and the pixels the probes did not cover this frame blue.
+ * - **TraceKinds**: over each tile, the shares of its uniform probe's rays the screen resolved (red), the bricks hit
+ *   (green), and the world-space probes answered past their reach (blue); the environment's share is left dark.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_debug: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_screen_probe_debug.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_screen_probe_debug.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_debug.js"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,0CAFU,YAAY,CAKS;AAiB/B;;;;;;;;;;GAUG;AACH,wCAFU,aAAa,CA0EpB;6BAzH0B,mCAAmC;8BAJlC,+BAA+B"}

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

@@ -0,0 +1,128 @@
+import { chunk_is_background } from "../../shader/chunk/depth/chunk_is_background.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 {
+    chunk_screen_probe,
+    SCREEN_PROBE_FRAME_RESOURCE,
+    SCREEN_PROBE_TILE_COUNTS_READ_RESOURCE,
+    SCREEN_PROBE_TILE_PROBES_READ_RESOURCE,
+    SCREEN_PROBE_TRACE_HIT_READ_RESOURCE,
+    SCREEN_PROBES_READ_RESOURCE
+} from "./chunk_screen_probe.js";
+import { SCREEN_PROBE_DEPTH_RESOURCE } from "./chunk_screen_probe_surface.js";
+import { SCREEN_PROBE_INTEGRATED_READ_RESOURCE } from "./shader_screen_probe_resolve.js";
+import { ScreenProbeDebugView } from "./ScreenProbeDebugView.js";
+import { SCREEN_PROBE_TILE_WORKGROUP_SIZE } from "./SCREEN_PROBE.js";
+
+/**
+ * Settings of the debug view.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_DEBUG_SETTINGS = WebGPUStruct.from({
+    /** the view, `ScreenProbeDebugView` */
+    view: u32,
+}, "ScreenProbeDebugSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", SCREEN_PROBE_DEBUG_SETTINGS);
+
+resources.createGroup()
+    .add(SCREEN_PROBE_FRAME_RESOURCE)
+    .add(SCREEN_PROBES_READ_RESOURCE)
+    .add(SCREEN_PROBE_TILE_COUNTS_READ_RESOURCE)
+    .add(SCREEN_PROBE_TILE_PROBES_READ_RESOURCE)
+    .add(SCREEN_PROBE_DEPTH_RESOURCE)
+    .add(SCREEN_PROBE_INTEGRATED_READ_RESOURCE)
+    .add(SCREEN_PROBE_TRACE_HIT_READ_RESOURCE)
+    .add(ShaderResourceDescriptor.texture("screen_probe_debug_diffuse", "unfilterable-float"))
+    .add(ShaderResourceDescriptor.storageTexture("screen_probe_debug_out", "rgba16float", "2d", "write-only"));
+
+/**
+ * The screen probes' debug views (`ScreenProbeDebugView`), a thread a pixel, in place of the frame's colour:
+ *
+ * - **IndirectDiffuse**: the frame's diffuse over π, what a white Lambertian surface sends back of it.
+ * - **ProbePlacement**: the same, with each probe's pixel and the eight around it marked, uniform green and adaptive
+ *   red, and the pixels the probes did not cover this frame blue.
+ * - **TraceKinds**: over each tile, the shares of its uniform probe's rays the screen resolved (red), the bricks hit
+ *   (green), and the world-space probes answered past their reach (blue); the environment's share is left dark.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_screen_probe_debug = ComputeShader.from({
+    label: "Screen Probe Debug",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+fn screen_probe_debug_marks(pixel: vec2<u32>, probe: u32) -> bool {
+    let at = vec2<i32>(screen_probe_pixel_decode(screen_probes[probe].pixel));
+    let gap = abs(at - vec2<i32>(pixel));
+
+    return screen_probes[probe].depth > 0.0 && all(gap <= vec2<i32>(1));
+}
+
+@compute @workgroup_size(${SCREEN_PROBE_TILE_WORKGROUP_SIZE}, ${SCREEN_PROBE_TILE_WORKGROUP_SIZE}, 1)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let frame = screen_probe_frame;
+
+    if (any(id.xy >= frame.view_size)) {
+        return;
+    }
+
+    let pixel = id.xy;
+
+    if (is_background(textureLoad(tDepth, pixel, 0).r)) {
+        textureStore(screen_probe_debug_out, pixel, vec4<f32>(0.0, 0.0, 0.0, 1.0));
+        return;
+    }
+
+    let diffuse = textureLoad(screen_probe_debug_diffuse, pixel, 0).rgb * 0.3183098861837907;
+    let tile = min((max(vec2<i32>(pixel) - vec2<i32>(frame.jitter), vec2<i32>(0)) >> vec2<u32>(frame.downsample_shift)), vec2<i32>(frame.tile_count) - 1);
+    let tile_index = u32(tile.y) * frame.tile_count.x + u32(tile.x);
+
+    var color = diffuse;
+
+    if (settings.view == ${ScreenProbeDebugView.ProbePlacement}u) {
+        if (textureLoad(screen_probe_integrated, pixel, 0).a < 0.0) {
+            color = vec3<f32>(0.0, 0.0, 1.0);
+        }
+
+        if (screen_probe_debug_marks(pixel, tile_index)) {
+            color = vec3<f32>(0.0, 1.0, 0.0);
+        }
+
+        let count = min(screen_probe_tile_counts[tile_index], frame.adaptive_tile_capacity);
+
+        for (var i = 0u; i < count; i++) {
+            if (screen_probe_debug_marks(pixel, frame.uniform_count + screen_probe_tile_probes[tile_index * frame.adaptive_tile_capacity + i])) {
+                color = vec3<f32>(1.0, 0.0, 0.0);
+            }
+        }
+    } else if (settings.view == ${ScreenProbeDebugView.TraceKinds}u) {
+        let n = frame.octahedron_resolution;
+
+        var kinds = vec3<f32>(0.0);
+
+        for (var slot = 0u; slot < n * n; slot++) {
+            let kind = screen_probe_trace_hit_kind(textureLoad(screen_probe_trace_hit, screen_probe_texel(tile_index, slot), 0).r);
+
+            kinds += select(vec3<f32>(0.0), vec3<f32>(1.0, 0.0, 0.0), kind == SCREEN_PROBE_TRACE_SCREEN);
+            kinds += select(vec3<f32>(0.0), vec3<f32>(0.0, 1.0, 0.0), kind == SCREEN_PROBE_TRACE_HIT || kind == SCREEN_PROBE_TRACE_BACK);
+            kinds += select(vec3<f32>(0.0), vec3<f32>(0.0, 0.0, 1.0), kind == SCREEN_PROBE_TRACE_FAR);
+        }
+
+        color = kinds / f32(n * n);
+    }
+
+    textureStore(screen_probe_debug_out, pixel, vec4<f32>(color, 1.0));
+}
+`, [
+            chunk_screen_probe,
+            chunk_is_background,
+        ]),
+});