@woosh/meep-engine 3.67.0 → 3.69.0

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

@@ -0,0 +1,408 @@
+import { chunk_uv_equal_area_sphere } from "../../shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.js";
+import { chunk_index_to_grid2d_reciprocal } from "../../shader/chunk/grid/chunk_index_to_grid2d_reciprocal.js";
+import { chunk_stbn_sample_vec2 } from "../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { F32_CONTAINER_STRUCT } from "../../shader/type/F32_CONTAINER_STRUCT.js";
+import { atomic_u32, f32, u32, vec2u, vec3f, vec4f, vec4u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { STBN_VEC2_RESOURCE } from "../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
+import {
+    SCREEN_PROBE_DISPATCH_BRICK_RAY_COUNT,
+    SCREEN_PROBE_DISPATCH_PROBE_COUNT,
+    SCREEN_PROBE_PLANE_WEIGHT_SCALE,
+    SCREEN_PROBE_RAY_SLOT_BITS,
+    SCREEN_PROBE_TRACE_BACK,
+    SCREEN_PROBE_TRACE_FAR,
+    SCREEN_PROBE_TRACE_HIT,
+    SCREEN_PROBE_TRACE_KIND_MASK,
+    SCREEN_PROBE_TRACE_MOVING,
+    SCREEN_PROBE_TRACE_NONE,
+    SCREEN_PROBE_TRACE_PENDING,
+    SCREEN_PROBE_TRACE_SCREEN,
+    SCREEN_PROBE_TRACE_SKY,
+    SCREEN_PROBE_TRACE_UNRESOLVED
+} from "./SCREEN_PROBE.js";
+
+/**
+ * What every pass of a frame reads of the frame's probes, a uniform the host writes once a frame.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_FRAME_STRUCT = WebGPUStruct.from({
+    /** the view's pixels, x and y */
+    view_size: vec2u,
+    /** uniform probes along x and y: a tile of D × D pixels each, the view rounded up */
+    tile_count: vec2u,
+    /** where the uniform probes stand in their tiles this frame, pixels from the tile's corner */
+    jitter: vec2u,
+    /** where they stood last frame */
+    previous_jitter: vec2u,
+    /** last frame's uniform probes along x and y */
+    previous_tile_count: vec2u,
+    /** 1 / tile_count.x, rounded to f32: a probe's place in the atlas without an integer division */
+    tile_count_x_reciprocal: f32,
+    /** log2 of D, the pixels between uniform probes */
+    downsample_shift: u32,
+    /** n, a probe's octahedral texels a side */
+    octahedron_resolution: u32,
+    /** log2 of n */
+    octahedron_shift: u32,
+    /** uniform probes, tile_count.x · tile_count.y: the adaptive ones follow them */
+    uniform_count: u32,
+    /** adaptive probe slots */
+    adaptive_capacity: u32,
+    /** the most adaptive probes a tile holds, 4^levels − 1 */
+    adaptive_tile_capacity: u32,
+    /** frames rendered, for noise */
+    frame_index: u32,
+    /** 1 where last frame's probes, radiance and colour describe this view at this structure, else 0 */
+    history: u32,
+    /** how far a ray of a probe no world probe serves is traced, metres: across the coarsest brick window */
+    brick_t_max: f32,
+    /** the brick clipmap's cascades */
+    brick_cascade_count: u32,
+    /** the brick atlas's footprint as shifts, `GPUBrickClipmap#atlas_shift` */
+    brick_atlas_shift: u32,
+    /** the most frames the temporal filter averages a pixel over (`ScreenProbeSettings#temporal_frames`) */
+    temporal_frames: f32,
+    /** 1 where a probe's rays follow its densities (`ScreenProbeSettings#importance_sampling`), else 0 */
+    importance_sampling: u32,
+    /** 1 where rays are traced through the screen before the bricks (`ScreenProbeSettings#screen_traces`), else 0 */
+    screen_traces: u32,
+}, "ScreenProbeFrame");
+
+/**
+ * A screen probe, 32 bytes: where it stands on the G-buffer, as placement writes it.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_STRUCT = WebGPUStruct.from({
+    /** the surface point it stands on, world metres */
+    position: vec3f,
+    /** that point's view-space depth, metres; zero where the probe stands on no surface (sky) */
+    depth: f32,
+    /** the surface's face normal, octahedral, two unorm16: the plane interpolation weighs probes by */
+    normal: u32,
+    /** its pixel, x in the low half and y in the high */
+    pixel: u32,
+    /** how far its surface point moved since last frame, metres */
+    speed: f32,
+}, "ScreenProbe");
+
+/**
+ * Where a screen probe's rays leave from in the bricks, where they end their trace and what answers for the rest,
+ * 64 bytes: the world-space probes picked at the probe (`probe_clipmap_pick`), its rays' origin, and its reach.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_PICK_STRUCT = WebGPUStruct.from({
+    slots: vec4u,
+    /** each slot's share, summing to one; all zero where no world probe weighs anything */
+    weights: vec4f,
+    /**
+     * Where its rays leave from in the bricks, world metres, off its surface point to where the bricks' field reads a
+     * voxel of its cascade there; that voxel in w
+     */
+    origin: vec4f,
+    /**
+     * How far its rays are traced, metres: `SCREEN_PROBE_REACH_SPACINGS` spacings of the coarsest cascade picked from,
+     * or `brick_t_max` where nothing was picked
+     */
+    reach: f32,
+}, "ScreenProbePick");
+
+/**
+ * A ray the screen left to the bricks, 28 bytes, through the passes that trace and light it.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_RAY_STRUCT = WebGPUStruct.from({
+    /** its probe, above its slot among the probe's rays (`SCREEN_PROBE_RAY_SLOT_BITS`) */
+    ray: u32,
+    /** from the screen trace, how far it is known clear; from the bricks, its hit or where the march stopped */
+    t: f32,
+    /** its direction, the equal-area map's square, two unorm16 */
+    direction: u32,
+    /** a hit's normal, octahedral, two unorm16 */
+    normal: u32,
+    /** how it ended (`SCREEN_PROBE_TRACE_*`), and the hit's brick cascade above the kind's bits */
+    flags: u32,
+    /** a front-face hit's diffuse albedo, `pack4x8unorm`, which the light and bounce passes multiply in; else zero */
+    albedo: u32,
+    /** the light, RGB9E5: E_dir from the trace at a front-face hit, then the radiance the ray brings back */
+    light: u32,
+}, "ScreenProbeRay");
+
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_FRAME_RESOURCE = ShaderResourceDescriptor.uniform("screen_probe_frame", SCREEN_PROBE_FRAME_STRUCT);
+
+/**
+ * The factor the display multiplies radiance by ahead of its tone curve, as the last frame was shown: what the
+ * probes' radiance is pre-exposed by, Lumen's `View.PreExposure`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SCREEN_PROBE_EXPOSURE_RESOURCE = ShaderResourceDescriptor.uniform("screen_probe_exposure", F32_CONTAINER_STRUCT);
+
+/** The exposure last frame's probes' radiance was pre-exposed by. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_EXPOSURE_PREVIOUS_RESOURCE = ShaderResourceDescriptor.uniform("screen_probe_exposure_previous", F32_CONTAINER_STRUCT);
+
+/** The frame's probes, uniform then adaptive. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probes", WebGPUArray.from(SCREEN_PROBE_STRUCT));
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probes", WebGPUArray.from(SCREEN_PROBE_STRUCT), true);
+
+/** Last frame's probes, as this frame's lighting density reprojects into. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_PREVIOUS_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probes_previous", WebGPUArray.from(SCREEN_PROBE_STRUCT));
+
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PICKS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_picks", WebGPUArray.from(SCREEN_PROBE_PICK_STRUCT));
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PICKS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_picks", WebGPUArray.from(SCREEN_PROBE_PICK_STRUCT), true);
+
+/** The commands and counts of the frame (`SCREEN_PROBE_DISPATCH_*`), read-only to the passes after the one that writes them. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DISPATCH_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_dispatch", WebGPUArray.u32);
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DISPATCH_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_dispatch", WebGPUArray.u32, true);
+
+/** The frame's atomic counters (`SCREEN_PROBE_COUNTER_*`). @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_COUNTERS_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_counters", WebGPUArray.from(atomic_u32), true);
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_COUNTERS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_counters", WebGPUArray.u32);
+
+/** Each tile's count of adaptive probes. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_COUNTS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_tile_counts", WebGPUArray.u32);
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_COUNTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_tile_counts", WebGPUArray.from(atomic_u32), true);
+
+/** Each tile's adaptive probes, `adaptive_tile_capacity` slots a tile: the k of probe uniform_count + k. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_PROBES_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_tile_probes", WebGPUArray.u32);
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_PROBES_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_tile_probes", WebGPUArray.u32, true);
+
+/** The rays the screen left to the bricks. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAYS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_rays", WebGPUArray.from(SCREEN_PROBE_RAY_STRUCT));
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAYS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_rays", WebGPUArray.from(SCREEN_PROBE_RAY_STRUCT), true);
+
+/** Each probe's share of its rays' light that came from something moving relative to it, 0 to 1, as the composite writes it. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_MOVING_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_moving", WebGPUArray.from(f32));
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_MOVING_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_moving", WebGPUArray.from(f32), true);
+
+/** Each probe's radiance, `rgba16float`, n² texels a probe in the atlas: rgb the radiance pre-exposed (`screen_probe_exposure`), a the nearest hit of the rays it holds, negative where none landed. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RADIANCE_READ_RESOURCE = ShaderResourceDescriptor.texture("screen_probe_radiance", "unfilterable-float");
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RADIANCE_WRITE_RESOURCE = ShaderResourceDescriptor.storageTexture("screen_probe_radiance_out", "rgba16float", "2d", "write-only");
+
+/** Each probe's pre-exposed radiance SH3, as the probe clipmap's records hold theirs (`probe_record_sh_encode`). @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_SH_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_sh", WebGPUArray.u32);
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_SH_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("screen_probe_sh", WebGPUArray.u32, true);
+
+/** Each ray's texel and level, `r32uint`, a texel a ray in the probes' atlas. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAY_INFO_READ_RESOURCE = ShaderResourceDescriptor.texture("screen_probe_ray_info", "uint");
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAY_INFO_WRITE_RESOURCE = ShaderResourceDescriptor.storageTexture("screen_probe_ray_info", "r32uint", "2d", "write-only");
+
+/** Each ray's radiance pre-exposed (`screen_probe_exposure`), `rgba16float`. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_RADIANCE_READ_RESOURCE = ShaderResourceDescriptor.texture("screen_probe_trace_radiance", "unfilterable-float");
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_RADIANCE_WRITE_RESOURCE = ShaderResourceDescriptor.storageTexture("screen_probe_trace_radiance", "rgba16float", "2d", "write-only");
+
+/** Each ray's hit word (`screen_probe_trace_hit_pack`), `r32uint`. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_HIT_READ_RESOURCE = ShaderResourceDescriptor.texture("screen_probe_trace_hit", "uint");
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_HIT_WRITE_RESOURCE = ShaderResourceDescriptor.storageTexture("screen_probe_trace_hit", "r32uint", "2d", "write-only");
+
+/**
+ * Probe addressing, the probes' records and their rays' words (Lumen's `LumenScreenProbeCommon.ush`):
+ *
+ * ```wgsl
+ * fn screen_probe_atlas(probe: u32) -> vec2<u32>                    // the probe's place in the atlas, in probes
+ * fn screen_probe_texel(probe: u32, slot: u32) -> vec2<u32>          // its slot's texel in an atlas of n² a probe
+ * fn screen_probe_pixel_encode(pixel: vec2<u32>) -> u32
+ * fn screen_probe_pixel_decode(word: u32) -> vec2<u32>
+ * fn screen_probe_tile_of_pixel(pixel: vec2<u32>) -> vec2<u32>       // the tile of a pixel placed on this frame's grid
+ * fn screen_probe_plane_weight(plane: vec4<f32>, point: vec3<f32>, depth: f32) -> f32
+ * fn screen_probe_ray_info_pack(texel: vec2<u32>, level: u32) -> u32
+ * fn screen_probe_ray_info_texel(info: u32) -> vec2<u32>
+ * fn screen_probe_ray_info_level(info: u32) -> u32                   // 1 the probe's n, 0 twice it
+ * fn screen_probe_ray_direction(info: u32, jitter: vec2<f32>) -> vec3<f32>
+ * fn screen_probe_trace_hit_pack(kind: u32, distance: f32, moving: bool) -> u32
+ * fn screen_probe_trace_hit_kind(word: u32) -> u32
+ * fn screen_probe_trace_hit_distance(word: u32) -> f32
+ * fn screen_probe_texel_wrap(texel: vec2<i32>) -> vec2<u32>         // a texel a step outside the octahedron, folded in
+ * ```
+ *
+ * - **The atlas**: probe i at (i mod tile_count.x, i div tile_count.x), the uniform probes on their tiles and the
+ *   adaptive ones in the rows below, a probe's n² texels at n times its place in every per-ray and per-texel texture.
+ * - **The plane weight**: `exp2(−k·(|n·p − d| / depth)²)`, `SCREEN_PROBE_PLANE_WEIGHT_SCALE`, the distance of a point
+ *   from a receiver's plane over the receiver's depth: Lumen's, with the face normal's plane where Lumen takes the
+ *   shading normal's, so a normal map does not part probes on one flat surface.
+ * - **A ray's info**: the texel at its level's resolution, 2n at level 0 and n at level 1, and the level.
+ * - **A ray's direction**: Clarberg's equal-area map at its texel plus the probe's jitter over the level's resolution,
+ *   so a probe's texels all hold the same solid angle, 4π/n², and a child a quarter of it.
+ * - **A hit word**: the kind (`SCREEN_PROBE_TRACE_*`) and moving bit low, the distance as a half float high.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe = CodeChunk.from(
+    //language=WGSL
+    `
+const SCREEN_PROBE_RAY_SLOT_BITS = ${SCREEN_PROBE_RAY_SLOT_BITS}u;
+const SCREEN_PROBE_RAY_SLOT_MASK = ${(1 << SCREEN_PROBE_RAY_SLOT_BITS) - 1}u;
+
+const SCREEN_PROBE_TRACE_PENDING = ${SCREEN_PROBE_TRACE_PENDING}u;
+const SCREEN_PROBE_TRACE_SCREEN = ${SCREEN_PROBE_TRACE_SCREEN}u;
+const SCREEN_PROBE_TRACE_HIT = ${SCREEN_PROBE_TRACE_HIT}u;
+const SCREEN_PROBE_TRACE_BACK = ${SCREEN_PROBE_TRACE_BACK}u;
+const SCREEN_PROBE_TRACE_FAR = ${SCREEN_PROBE_TRACE_FAR}u;
+const SCREEN_PROBE_TRACE_SKY = ${SCREEN_PROBE_TRACE_SKY}u;
+const SCREEN_PROBE_TRACE_UNRESOLVED = ${SCREEN_PROBE_TRACE_UNRESOLVED}u;
+const SCREEN_PROBE_TRACE_NONE = ${SCREEN_PROBE_TRACE_NONE}u;
+const SCREEN_PROBE_TRACE_KIND_MASK = ${SCREEN_PROBE_TRACE_KIND_MASK}u;
+const SCREEN_PROBE_TRACE_MOVING = ${SCREEN_PROBE_TRACE_MOVING}u;
+
+fn screen_probe_atlas(probe: u32) -> vec2<u32> {
+    return index_to_grid2d_reciprocal(probe, screen_probe_frame.tile_count.x, screen_probe_frame.tile_count_x_reciprocal);
+}
+
+fn screen_probe_texel(probe: u32, slot: u32) -> vec2<u32> {
+    let n = screen_probe_frame.octahedron_resolution;
+    let in_probe = vec2<u32>(slot & (n - 1u), slot >> screen_probe_frame.octahedron_shift);
+
+    return screen_probe_atlas(probe) * n + in_probe;
+}
+
+fn screen_probe_pixel_encode(pixel: vec2<u32>) -> u32 {
+    return (pixel.x & 0xFFFFu) | (pixel.y << 16u);
+}
+
+fn screen_probe_pixel_decode(word: u32) -> vec2<u32> {
+    return vec2<u32>(word & 0xFFFFu, word >> 16u);
+}
+
+fn screen_probe_tile_of_pixel(pixel: vec2<u32>) -> vec2<u32> {
+    return (pixel - screen_probe_frame.jitter) >> vec2<u32>(screen_probe_frame.downsample_shift);
+}
+
+fn screen_probe_plane_weight(plane: vec4<f32>, point: vec3<f32>, depth: f32) -> f32 {
+    let relative = abs(dot(plane.xyz, point) - plane.w) / depth;
+
+    return exp2(-${SCREEN_PROBE_PLANE_WEIGHT_SCALE}.0 * relative * relative);
+}
+
+fn screen_probe_ray_info_pack(texel: vec2<u32>, level: u32) -> u32 {
+    return texel.x | (texel.y << 8u) | (level << 16u);
+}
+
+fn screen_probe_ray_info_texel(info: u32) -> vec2<u32> {
+    return vec2<u32>(info & 0xFFu, (info >> 8u) & 0xFFu);
+}
+
+fn screen_probe_ray_info_level(info: u32) -> u32 {
+    return info >> 16u;
+}
+
+fn screen_probe_ray_direction(info: u32, jitter: vec2<f32>) -> vec3<f32> {
+    // level 1 is the probe's own n, level 0 twice it
+    let size = f32((screen_probe_frame.octahedron_resolution * 2u) >> screen_probe_ray_info_level(info));
+
+    return uv_equal_area_sphere_decode((vec2<f32>(screen_probe_ray_info_texel(info)) + jitter) / size);
+}
+
+fn screen_probe_trace_hit_pack(kind: u32, distance: f32, moving: bool) -> u32 {
+    return kind | select(0u, SCREEN_PROBE_TRACE_MOVING, moving) | (pack2x16float(vec2<f32>(0.0, distance)) & 0xFFFF0000u);
+}
+
+fn screen_probe_trace_hit_kind(word: u32) -> u32 {
+    return word & SCREEN_PROBE_TRACE_KIND_MASK;
+}
+
+fn screen_probe_trace_hit_distance(word: u32) -> f32 {
+    return unpack2x16float(word).y;
+}
+
+fn screen_probe_texel_wrap(texel: vec2<i32>) -> vec2<u32> {
+    let n = i32(screen_probe_frame.octahedron_resolution);
+
+    var t = texel;
+
+    // a step past an edge of the octahedral square lands on the mirrored side of the same edge
+    if (t.x < 0 || t.x >= n) {
+        t = vec2<i32>(select(t.x, -1 - t.x, t.x < 0), n - 1 - t.y);
+        t.x = select(t.x, 2 * n - 1 - t.x, t.x >= n);
+    }
+
+    if (t.y < 0 || t.y >= n) {
+        t = vec2<i32>(n - 1 - t.x, select(t.y, -1 - t.y, t.y < 0));
+        t.y = select(t.y, 2 * n - 1 - t.y, t.y >= n);
+    }
+
+    return vec2<u32>(clamp(t, vec2<i32>(0), vec2<i32>(n - 1)));
+}
+`, [
+        SCREEN_PROBE_FRAME_STRUCT.declaration_chunk,
+        SCREEN_PROBE_STRUCT.declaration_chunk,
+        SCREEN_PROBE_PICK_STRUCT.declaration_chunk,
+        SCREEN_PROBE_RAY_STRUCT.declaration_chunk,
+        chunk_index_to_grid2d_reciprocal,
+        chunk_uv_equal_area_sphere,
+    ]);
+
+chunk_screen_probe.requireResource(SCREEN_PROBE_FRAME_RESOURCE);
+
+/**
+ * Where in its texel each of a probe's rays falls this frame, the same for every texel of the probe:
+ *
+ * ```wgsl
+ * fn screen_probe_noise_tile(probe: u32, pixel: vec2<u32>) -> vec2<u32>   // the tile whose noise a probe draws
+ * fn screen_probe_ray_jitter(tile: vec2<u32>) -> vec2<f32>
+ * ```
+ *
+ * The spatio-temporal blue noise at the probe's tile and the frame (Lumen's per-tile blue noise), shared by the
+ * tile's probes: neighbouring probes' jitters are spread apart, and a probe's spread over the frames the temporal
+ * filter averages. A uniform probe's tile is its place in the atlas; an adaptive probe's, the tile its pixel stands
+ * in (`pixel`, its record's), as Lumen keys a probe's noise by its screen tile. Every pass that places a probe's
+ * rays or reads them back by direction takes the tile from here.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_ray_jitter = CodeChunk.from(
+    //language=WGSL
+    `
+fn screen_probe_noise_tile(probe: u32, pixel: vec2<u32>) -> vec2<u32> {
+    return select(screen_probe_tile_of_pixel(pixel), screen_probe_atlas(probe), probe < screen_probe_frame.uniform_count);
+}
+
+fn screen_probe_ray_jitter(tile: vec2<u32>) -> vec2<f32> {
+    return stbn_sample_vec2(vec3<u32>(tile, screen_probe_frame.frame_index));
+}
+`, [
+        chunk_screen_probe,
+        chunk_stbn_sample_vec2,
+    ]);
+
+chunk_screen_probe_ray_jitter.requireResource(STBN_VEC2_RESOURCE);
+
+/**
+ * The frame's counts, from the pass that writes the commands:
+ *
+ * ```wgsl
+ * fn screen_probe_count() -> u32        // the frame's probes, uniform and adaptive
+ * fn screen_probe_brick_ray_count() -> u32 // the rays the screen left to the bricks, held to their list's slots
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_counts = CodeChunk.from(
+    //language=WGSL
+    `
+fn screen_probe_count() -> u32 {
+    return screen_probe_dispatch[${SCREEN_PROBE_DISPATCH_PROBE_COUNT}u];
+}
+
+fn screen_probe_brick_ray_count() -> u32 {
+    return screen_probe_dispatch[${SCREEN_PROBE_DISPATCH_BRICK_RAY_COUNT}u];
+}
+`);
+
+chunk_screen_probe_counts.requireResource(SCREEN_PROBE_DISPATCH_READ_RESOURCE);

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

@@ -0,0 +1,23 @@
+/**
+ * A probe's BRDF density, and whether a texel of its octahedron keeps its ray whatever its light:
+ *
+ * ```wgsl
+ * struct ScreenProbeBRDF { low: vec4<f32>, high: vec4<f32>, last: f32 } // SH3: coefficients 0–3, 4–7 and 8
+ * fn screen_probe_brdf_density(brdf: ScreenProbeBRDF, direction: vec3<f32>) -> f32
+ * fn screen_probe_brdf_keeps(brdf: ScreenProbeBRDF, texel: vec2<u32>, n: u32) -> bool
+ * ```
+ *
+ * - **The density** at a direction: `max(0, Σ brdf·Y(ω))`, the mean of the probe's pixels' clamped cosine lobes there.
+ * - **A texel keeps its ray** where any of its directions reaches `SCREEN_PROBE_MIN_PDF`: its density at nine points,
+ *   its corners, the middles of its edges and its centre, the most of a smooth function over the small patch the
+ *   texel is. Lumen tests the centre alone. A surface's horizon runs through texel centres wherever the surface faces
+ *   the equal-area map's pole, ±z, and a lobe's density there is 0.094, under the minimum, though the texel's upper
+ *   half reaches cosines of 0.4 and more: those texels gave their rays away, taking 7.3% of the surface's irradiance
+ *   at n = 8 (29% at 4, 2% at 16) and none of a surface facing ±x or ±y. A texel no point of which reaches the
+ *   minimum lies below the lobes' horizon, where they weigh almost nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_brdf_density: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_brdf_density.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_brdf_density.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_brdf_density.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8CAFU,SAAS,CAuCZ;0BA5DmB,oCAAoC"}

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

@@ -0,0 +1,63 @@
+import { chunk_uv_equal_area_sphere } from "../../shader/chunk/geometry/octahedron/chunk_uv_equal_area_sphere.js";
+import { chunk_sh3_basis_at } from "../../shader/chunk/spherical_harmonics/chunk_sh3_basis_at.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { SCREEN_PROBE_MIN_PDF } from "./SCREEN_PROBE.js";
+
+/**
+ * A probe's BRDF density, and whether a texel of its octahedron keeps its ray whatever its light:
+ *
+ * ```wgsl
+ * struct ScreenProbeBRDF { low: vec4<f32>, high: vec4<f32>, last: f32 } // SH3: coefficients 0–3, 4–7 and 8
+ * fn screen_probe_brdf_density(brdf: ScreenProbeBRDF, direction: vec3<f32>) -> f32
+ * fn screen_probe_brdf_keeps(brdf: ScreenProbeBRDF, texel: vec2<u32>, n: u32) -> bool
+ * ```
+ *
+ * - **The density** at a direction: `max(0, Σ brdf·Y(ω))`, the mean of the probe's pixels' clamped cosine lobes there.
+ * - **A texel keeps its ray** where any of its directions reaches `SCREEN_PROBE_MIN_PDF`: its density at nine points,
+ *   its corners, the middles of its edges and its centre, the most of a smooth function over the small patch the
+ *   texel is. Lumen tests the centre alone. A surface's horizon runs through texel centres wherever the surface faces
+ *   the equal-area map's pole, ±z, and a lobe's density there is 0.094, under the minimum, though the texel's upper
+ *   half reaches cosines of 0.4 and more: those texels gave their rays away, taking 7.3% of the surface's irradiance
+ *   at n = 8 (29% at 4, 2% at 16) and none of a surface facing ±x or ±y. A texel no point of which reaches the
+ *   minimum lies below the lobes' horizon, where they weigh almost nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_brdf_density = CodeChunk.from(
+    //language=WGSL
+    `
+struct ScreenProbeBRDF {
+    low: vec4<f32>,
+    high: vec4<f32>,
+    last: f32,
+}
+
+fn screen_probe_brdf_density(brdf: ScreenProbeBRDF, direction: vec3<f32>) -> f32 {
+    let basis = sh3_basis_at(direction);
+
+    return max(
+        dot(brdf.low, vec4<f32>(basis[0], basis[1], basis[2], basis[3]))
+        + dot(brdf.high, vec4<f32>(basis[4], basis[5], basis[6], basis[7]))
+        + brdf.last * basis[8],
+        0.0,
+    );
+}
+
+fn screen_probe_brdf_keeps(brdf: ScreenProbeBRDF, texel: vec2<u32>, n: u32) -> bool {
+    let corner = vec2<f32>(texel);
+    let size = 1.0 / f32(n);
+
+    var most = 0.0;
+
+    for (var k = 0u; k < 9u; k++) {
+        let at = (corner + 0.5 * vec2<f32>(f32(k % 3u), f32(k / 3u))) * size;
+
+        most = max(most, screen_probe_brdf_density(brdf, uv_equal_area_sphere_decode(at)));
+    }
+
+    return most >= ${SCREEN_PROBE_MIN_PDF};
+}
+`, [
+        chunk_sh3_basis_at,
+        chunk_uv_equal_area_sphere,
+    ]);

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

@@ -0,0 +1,24 @@
+/**
+ * Where a screen probe's rays leave from in the bricks:
+ *
+ * ```wgsl
+ * fn screen_probe_brick_origin(position: vec3<f32>, normal: vec3<f32>, cascade_count: u32, atlas_shift: u32) -> vec4<f32>
+ * ```
+ *
+ * `position` is the probe's surface point and `normal` its face normal; `atlas_shift` is the brick atlas's footprint,
+ * as `brick_clipmap_distance` takes it. Returns the origin, and in w a voxel of the brick cascade at the surface point
+ * (the finest window holding it).
+ *
+ * - **The lift**: the point a voxel out along the face normal, as a hit's shadow rays leave theirs: past the half voxel
+ *   the bricks' trace counts as a hit, where the bricks' surface is the G-buffer's.
+ * - **The push**: while the bricks' field there (`brick_clipmap_distance`) reads less than the voxel, along its slope
+ *   (`brick_clipmap_gradient`) by what it lacks, `q += ∇d·(voxel − d)`, at most `SCREEN_PROBE_ORIGIN_STEPS` times, as
+ *   the probe clipmap relocates its probes. The bricks hold a coarser surface than the G-buffer's, up to a voxel of the
+ *   mesh field they were built from off it, and a ray that leaves from inside their hit band hits the solid it starts
+ *   in. A field with no slope, as deep in a solid past its band, moves nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_brick_origin: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_brick_origin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_brick_origin.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_brick_origin.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8CAFU,SAAS,CAgCZ;0BA3DmB,oCAAoC"}

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

@@ -0,0 +1,61 @@
+import { MESH_SDF_BRICK_VOXELS } from "../../geometry/sdf/MESH_SDF.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import {
+    chunk_brick_clipmap_distance,
+    chunk_brick_clipmap_gradient,
+    chunk_brick_clipmap_window
+} from "../probe_clipmap/brick/chunk_brick_clipmap_trace.js";
+import { SCREEN_PROBE_ORIGIN_STEPS } from "./SCREEN_PROBE.js";
+
+/**
+ * Where a screen probe's rays leave from in the bricks:
+ *
+ * ```wgsl
+ * fn screen_probe_brick_origin(position: vec3<f32>, normal: vec3<f32>, cascade_count: u32, atlas_shift: u32) -> vec4<f32>
+ * ```
+ *
+ * `position` is the probe's surface point and `normal` its face normal; `atlas_shift` is the brick atlas's footprint,
+ * as `brick_clipmap_distance` takes it. Returns the origin, and in w a voxel of the brick cascade at the surface point
+ * (the finest window holding it).
+ *
+ * - **The lift**: the point a voxel out along the face normal, as a hit's shadow rays leave theirs: past the half voxel
+ *   the bricks' trace counts as a hit, where the bricks' surface is the G-buffer's.
+ * - **The push**: while the bricks' field there (`brick_clipmap_distance`) reads less than the voxel, along its slope
+ *   (`brick_clipmap_gradient`) by what it lacks, `q += ∇d·(voxel − d)`, at most `SCREEN_PROBE_ORIGIN_STEPS` times, as
+ *   the probe clipmap relocates its probes. The bricks hold a coarser surface than the G-buffer's, up to a voxel of the
+ *   mesh field they were built from off it, and a ray that leaves from inside their hit band hits the solid it starts
+ *   in. A field with no slope, as deep in a solid past its band, moves nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_brick_origin = CodeChunk.from(
+    //language=WGSL
+    `
+fn screen_probe_brick_origin(position: vec3<f32>, normal: vec3<f32>, cascade_count: u32, atlas_shift: u32) -> vec4<f32> {
+    let voxel = brick_levels[min(brick_clipmap_start(position, cascade_count), cascade_count - 1u)].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+
+    var origin = position + normal * voxel;
+
+    for (var step = 0u; step < ${SCREEN_PROBE_ORIGIN_STEPS}u; step++) {
+        let distance = brick_clipmap_distance(origin, cascade_count, atlas_shift);
+
+        if (distance >= voxel) {
+            break;
+        }
+
+        let gradient = brick_clipmap_gradient(origin, cascade_count, atlas_shift);
+
+        if (all(gradient == vec3<f32>(0.0))) {
+            break;
+        }
+
+        origin += gradient * (voxel - distance);
+    }
+
+    return vec4<f32>(origin, voxel);
+}
+`, [
+        chunk_brick_clipmap_window,
+        chunk_brick_clipmap_distance,
+        chunk_brick_clipmap_gradient,
+    ]);

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

@@ -0,0 +1,39 @@
+/**
+ * Which probes light a point on the screen, and by how much (Lumen's `CalculateUpsampleInterpolationWeights`):
+ *
+ * ```wgsl
+ * struct ScreenProbeSample { probes: vec4<u32>, weights: vec4<f32> }
+ * fn screen_probe_interpolate(pixel: vec2<u32>, offset: vec2<f32>, position: vec3<f32>, depth: f32, normal: vec3<f32>) -> ScreenProbeSample
+ * ```
+ *
+ * `pixel` is the point's pixel, `offset` a shift of the lookup in pixels (the integration's jitter, zero for
+ * placement), `position` and `depth` the point's world position and view depth, `normal` its face normal.
+ *
+ * - **The uniform corners**: the four uniform probes around the pixel, its place less the frame's jitter, by bilinear
+ *   weights over a tile widened by a pixel each side, `(p − D·tile + 1) / (D + 2)` an axis, so no corner's weight is
+ *   ever exactly one or zero. The place is held to the grid: past the last row or column of probes a pixel takes the
+ *   weights of one standing on them, so no weight is extrapolated. (Lumen holds it to the view and extrapolates there,
+ *   by up to (D − 1) / (D + 2) of a tile; its integration then skips the negative corners it normalised by.) Each is
+ *   multiplied by the corner's plane weight from the point's plane (`screen_probe_plane_weight`); a corner on no
+ *   surface weighs nothing.
+ * - **Adaptive probes**: a corner weighing no more than `SCREEN_PROBE_WEIGHT_EPSILON` looks among its tile's adaptive
+ *   probes for one weighing more: its plane weight times `1 − min(|dx|, |dy|) / D`, the pixels between it and the
+ *   point. The heaviest takes the corner's place.
+ * - The weights are as found, not normalised: their sum says how well the probes cover the point
+ *   (`screen_probe_covers`).
+ *
+ * The includer defines how a tile's count of adaptive probes is read, as its pass binds the counts:
+ *
+ * ```wgsl
+ * fn screen_probe_tile_adaptive_count(tile: u32) -> u32
+ * ```
+ *
+ * Reads the four uniform corners' records and, for a corner that fails, the records of its tile's adaptive probes:
+ * at most `adaptive_tile_capacity`, the tile's points of the adaptive grids. Each corner is taken by name: an index
+ * into the result's vectors would put them in local memory.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_interpolate: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_interpolate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_interpolate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_interpolate.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,6CAFU,SAAS,CAgFZ;0BA1HmB,oCAAoC"}