@woosh/meep-engine 3.67.0 → 3.69.0

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

@@ -0,0 +1,126 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import {
+    chunk_screen_probe,
+    SCREEN_PROBE_TILE_PROBES_READ_RESOURCE,
+    SCREEN_PROBES_READ_RESOURCE
+} from "./chunk_screen_probe.js";
+import { SCREEN_PROBE_WEIGHT_EPSILON } from "./SCREEN_PROBE.js";
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+struct ScreenProbeSample {
+    probes: vec4<u32>,
+    weights: vec4<f32>,
+}
+
+struct ScreenProbeCorner {
+    probe: u32,
+    weight: f32,
+}
+
+fn screen_probe_corner_weight(probe: u32, plane: vec4<f32>, depth: f32) -> f32 {
+    let record = screen_probes[probe];
+
+    return select(0.0, screen_probe_plane_weight(plane, record.position, depth), record.depth > 0.0);
+}
+
+// a uniform corner, or the heaviest of its tile's adaptive probes where it weighs no more than the epsilon
+fn screen_probe_corner(tile: vec2<u32>, axes: f32, pixel: vec2<u32>, plane: vec4<f32>, depth: f32) -> ScreenProbeCorner {
+    let frame = screen_probe_frame;
+
+    // a uniform probe's index is its tile's
+    let tile_index = tile.y * frame.tile_count.x + tile.x;
+
+    var corner = ScreenProbeCorner(tile_index, axes * screen_probe_corner_weight(tile_index, plane, depth));
+
+    if (corner.weight > ${SCREEN_PROBE_WEIGHT_EPSILON}) {
+        return corner;
+    }
+
+    let span = f32(1u << frame.downsample_shift);
+    let count = min(screen_probe_tile_adaptive_count(tile_index), frame.adaptive_tile_capacity);
+
+    for (var i = 0u; i < count; i++) {
+        let probe = frame.uniform_count + screen_probe_tile_probes[tile_index * frame.adaptive_tile_capacity + i];
+        let record = screen_probes[probe];
+
+        let gap = abs(vec2<f32>(screen_probe_pixel_decode(record.pixel)) - vec2<f32>(pixel));
+        let weight = select(0.0, screen_probe_plane_weight(plane, record.position, depth), record.depth > 0.0)
+            * (1.0 - saturate(min(gap.x, gap.y) / span));
+
+        if (weight > corner.weight) {
+            corner = ScreenProbeCorner(probe, weight);
+        }
+    }
+
+    return corner;
+}
+
+fn screen_probe_interpolate(pixel: vec2<u32>, offset: vec2<f32>, position: vec3<f32>, depth: f32, normal: vec3<f32>) -> ScreenProbeSample {
+    let frame = screen_probe_frame;
+    let shift = vec2<u32>(frame.downsample_shift);
+    let tiles = frame.tile_count;
+    let last = tiles - 1u;
+
+    // the lookup on the uniform grid: the pixel less the probes' place in their tiles, held between the outermost probes
+    let lookup = clamp(vec2<f32>(pixel) - vec2<f32>(frame.jitter) + offset, vec2<f32>(0.0), vec2<f32>(last << shift));
+    let coord = vec2<u32>(lookup);
+    let tile00 = min(coord >> shift, max(tiles, vec2<u32>(2u)) - 2u);
+
+    let span = f32(1u << frame.downsample_shift);
+    let b = (vec2<f32>(coord - (tile00 << shift)) + 1.0) / (span + 2.0);
+    let plane = vec4<f32>(normal, dot(normal, position));
+
+    let c00 = screen_probe_corner(tile00, (1.0 - b.x) * (1.0 - b.y), pixel, plane, depth);
+    let c10 = screen_probe_corner(min(tile00 + vec2<u32>(1u, 0u), last), b.x * (1.0 - b.y), pixel, plane, depth);
+    let c01 = screen_probe_corner(min(tile00 + vec2<u32>(0u, 1u), last), (1.0 - b.x) * b.y, pixel, plane, depth);
+    let c11 = screen_probe_corner(min(tile00 + vec2<u32>(1u, 1u), last), b.x * b.y, pixel, plane, depth);
+
+    return ScreenProbeSample(
+        vec4<u32>(c00.probe, c10.probe, c01.probe, c11.probe),
+        vec4<f32>(c00.weight, c10.weight, c01.weight, c11.weight),
+    );
+}
+`, [
+        chunk_screen_probe,
+    ]);
+
+chunk_screen_probe_interpolate.requireResource(SCREEN_PROBES_READ_RESOURCE);
+chunk_screen_probe_interpolate.requireResource(SCREEN_PROBE_TILE_PROBES_READ_RESOURCE);

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

@@ -0,0 +1,21 @@
+/**
+ * Last frame's probes a probe's lighting density takes its history from (Lumen's `PROBE_RADIANCE_HISTORY`):
+ *
+ * ```wgsl
+ * const SCREEN_PROBE_HISTORY_NONE = 0xFFFFFFFFu;
+ * fn screen_probe_lighting_history(record: ScreenProbe) -> vec4<u32> // last frame's grid, y · previous_tile_count.x + x
+ * ```
+ *
+ * Where the probe's surface point stood last frame (`screen_probe_point_before`: the velocity buffer, the surface's
+ * own motion with the camera's, as Lumen's `GetHistoryScreenPosition`); last frame's four uniform probes around its
+ * place then, on last frame's grid and jitter, in the order (0, 0), (1, 0), (0, 1), (1, 1). Each that stood on the
+ * plane the surface stood in then, through that point, its plane weight past `SCREEN_PROBE_BRDF_PIXEL_WEIGHT` of the
+ * depth then, is its place in last frame's grid; any other, and all four where there is no history or the point was
+ * off last frame's screen, is `SCREEN_PROBE_HISTORY_NONE`. Lumen weighs them against this frame's plane here, and
+ * against last frame's in its temporal filter; last frame's keeps the history of a surface moving along its normal.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_lighting_history: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_lighting_history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_lighting_history.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_lighting_history.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAFU,SAAS,CAiDZ;0BAtEmB,oCAAoC"}

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

@@ -0,0 +1,74 @@
+import { chunk_uv_octahedral_unit_decode } from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_screen_probe, SCREEN_PROBES_PREVIOUS_RESOURCE } from "./chunk_screen_probe.js";
+import { chunk_screen_probe_point_before } from "./chunk_screen_probe_surface.js";
+import { SCREEN_PROBE_BRDF_PIXEL_WEIGHT } from "./SCREEN_PROBE.js";
+
+/**
+ * Last frame's probes a probe's lighting density takes its history from (Lumen's `PROBE_RADIANCE_HISTORY`):
+ *
+ * ```wgsl
+ * const SCREEN_PROBE_HISTORY_NONE = 0xFFFFFFFFu;
+ * fn screen_probe_lighting_history(record: ScreenProbe) -> vec4<u32> // last frame's grid, y · previous_tile_count.x + x
+ * ```
+ *
+ * Where the probe's surface point stood last frame (`screen_probe_point_before`: the velocity buffer, the surface's
+ * own motion with the camera's, as Lumen's `GetHistoryScreenPosition`); last frame's four uniform probes around its
+ * place then, on last frame's grid and jitter, in the order (0, 0), (1, 0), (0, 1), (1, 1). Each that stood on the
+ * plane the surface stood in then, through that point, its plane weight past `SCREEN_PROBE_BRDF_PIXEL_WEIGHT` of the
+ * depth then, is its place in last frame's grid; any other, and all four where there is no history or the point was
+ * off last frame's screen, is `SCREEN_PROBE_HISTORY_NONE`. Lumen weighs them against this frame's plane here, and
+ * against last frame's in its temporal filter; last frame's keeps the history of a surface moving along its normal.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_lighting_history = CodeChunk.from(
+    //language=WGSL
+    `
+const SCREEN_PROBE_HISTORY_NONE = 0xFFFFFFFFu;
+
+fn screen_probe_lighting_history_probe(tile: vec2<i32>, plane: vec4<f32>, depth: f32) -> u32 {
+    let frame = screen_probe_frame;
+    let clamped = vec2<u32>(clamp(tile, vec2<i32>(0), vec2<i32>(frame.previous_tile_count) - 1));
+    let index = clamped.y * frame.previous_tile_count.x + clamped.x;
+    let previous = screen_probes_previous[index];
+
+    if (previous.depth <= 0.0 || screen_probe_plane_weight(plane, previous.position, depth) <= ${SCREEN_PROBE_BRDF_PIXEL_WEIGHT}) {
+        return SCREEN_PROBE_HISTORY_NONE;
+    }
+
+    return index;
+}
+
+fn screen_probe_lighting_history(record: ScreenProbe) -> vec4<u32> {
+    let frame = screen_probe_frame;
+
+    if (frame.history == 0u) {
+        return vec4<u32>(SCREEN_PROBE_HISTORY_NONE);
+    }
+
+    let before = screen_probe_point_before(screen_probe_pixel_decode(record.pixel), record.depth);
+
+    if (any(before.place < vec2<f32>(0.0)) || any(before.place > vec2<f32>(frame.view_size)) || before.depth <= 0.0) {
+        return vec4<u32>(SCREEN_PROBE_HISTORY_NONE);
+    }
+
+    let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
+    let plane = vec4<f32>(normal, dot(normal, before.position));
+    let tile = (before.place - vec2<f32>(frame.previous_jitter)) / f32(1u << frame.downsample_shift);
+    let t0 = vec2<i32>(floor(tile));
+
+    return vec4<u32>(
+        screen_probe_lighting_history_probe(t0, plane, before.depth),
+        screen_probe_lighting_history_probe(t0 + vec2<i32>(1, 0), plane, before.depth),
+        screen_probe_lighting_history_probe(t0 + vec2<i32>(0, 1), plane, before.depth),
+        screen_probe_lighting_history_probe(t0 + vec2<i32>(1, 1), plane, before.depth),
+    );
+}
+`, [
+        chunk_screen_probe,
+        chunk_screen_probe_point_before,
+        chunk_uv_octahedral_unit_decode,
+    ]);
+
+chunk_screen_probe_lighting_history.requireResource(SCREEN_PROBES_PREVIOUS_RESOURCE);

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

@@ -0,0 +1,20 @@
+/**
+ * How far along its ray a screen trace got, in metres, from its place on the segment it marched in screen space:
+ *
+ * ```wgsl
+ * fn screen_probe_march_distance(t: f32, segment: f32, w_start: f32, w_end: f32) -> f32
+ * ```
+ *
+ * `t` is the place, 0 at the segment's start and 1 at its end, `segment` the segment's length in metres, `w_start` and
+ * `w_end` the clip-space w of its two ends, both positive.
+ *
+ * Screen space is the segment's perspective projection, along which 1/w runs evenly and metres do not: the point s
+ * metres along projects to `t = (s / w(s)) / (segment / w_end)`, so `s = segment·t·w_start / (t·w_start + (1 − t)·w_end)`.
+ * A ray receding from the camera is further along on the screen than in metres, one approaching it less. The
+ * denominator is at least the smaller w.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_march_distance: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_march_distance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_march_distance.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_march_distance.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,gDAFU,SAAS,CAQhB;0BAzBuB,oCAAoC"}

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

@@ -0,0 +1,26 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * How far along its ray a screen trace got, in metres, from its place on the segment it marched in screen space:
+ *
+ * ```wgsl
+ * fn screen_probe_march_distance(t: f32, segment: f32, w_start: f32, w_end: f32) -> f32
+ * ```
+ *
+ * `t` is the place, 0 at the segment's start and 1 at its end, `segment` the segment's length in metres, `w_start` and
+ * `w_end` the clip-space w of its two ends, both positive.
+ *
+ * Screen space is the segment's perspective projection, along which 1/w runs evenly and metres do not: the point s
+ * metres along projects to `t = (s / w(s)) / (segment / w_end)`, so `s = segment·t·w_start / (t·w_start + (1 − t)·w_end)`.
+ * A ray receding from the camera is further along on the screen than in metres, one approaching it less. The
+ * denominator is at least the smaller w.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_march_distance = CodeChunk.from(
+    //language=WGSL
+    `
+fn screen_probe_march_distance(t: f32, segment: f32, w_start: f32, w_end: f32) -> f32 {
+    return segment * t * w_start / (t * w_start + (1.0 - t) * w_end);
+}
+`);

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

@@ -0,0 +1,24 @@
+/**
+ * A probe's rays in the order the reassignment takes them, sorted in the workgroup's memory:
+ *
+ * ```wgsl
+ * var<workgroup> screen_probe_sort: array<vec2<u32>, 2 · 16²> // (info, key): the rays, then the sorted ones
+ * fn screen_probe_ray_sort(lane: u32, lanes: u32, count: u32)  // the first count sorted, then copied after them
+ * ```
+ *
+ * - **The order**: ascending by key, then by info (`sort_pair_less`). The caller's key is the density's bits, which
+ *   order as the density does once it is held off −0; a level-one ray's info orders as its texel's index, so ties fall
+ *   in index order and the order is total.
+ * - **The sort**: the engine's bitonic network (`sort_bitonic_comparator`), in place over the first `count`, a power of
+ *   two (the probe's n²): each of its log₂count·(log₂count + 1)/2 steps is `count / 2` comparators shared by the `lanes`
+ *   lanes from the caller's `lane`, with a barrier after it. `sort_bitonic_workgroup` runs the same network over the
+ *   radix sort's 256-thread tiles; this is its loop at any workgroup's width. The sorted rays are then copied to
+ *   `[count, 2·count)`, where the reassignment builds the probe's rays.
+ * - Every lane of the workgroup calls it, from uniform control flow, with the same `lanes` and `count`; the rays stand
+ *   in the first `count` before the call, and a barrier has passed since they were written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_ray_sort: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_ray_sort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_ray_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_ray_sort.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0CAFU,SAAS,CAiCZ;0BAvDmB,oCAAoC"}

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

@@ -0,0 +1,57 @@
+import { chunk_sort_bitonic_comparator } from "../../gpu_primitive/sort/chunk_sort_bitonic_comparator.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { SCREEN_PROBE_OCTAHEDRON_LIMIT } from "./SCREEN_PROBE.js";
+
+/**
+ * A probe's rays in the order the reassignment takes them, sorted in the workgroup's memory:
+ *
+ * ```wgsl
+ * var<workgroup> screen_probe_sort: array<vec2<u32>, 2 · 16²> // (info, key): the rays, then the sorted ones
+ * fn screen_probe_ray_sort(lane: u32, lanes: u32, count: u32)  // the first count sorted, then copied after them
+ * ```
+ *
+ * - **The order**: ascending by key, then by info (`sort_pair_less`). The caller's key is the density's bits, which
+ *   order as the density does once it is held off −0; a level-one ray's info orders as its texel's index, so ties fall
+ *   in index order and the order is total.
+ * - **The sort**: the engine's bitonic network (`sort_bitonic_comparator`), in place over the first `count`, a power of
+ *   two (the probe's n²): each of its log₂count·(log₂count + 1)/2 steps is `count / 2` comparators shared by the `lanes`
+ *   lanes from the caller's `lane`, with a barrier after it. `sort_bitonic_workgroup` runs the same network over the
+ *   radix sort's 256-thread tiles; this is its loop at any workgroup's width. The sorted rays are then copied to
+ *   `[count, 2·count)`, where the reassignment builds the probe's rays.
+ * - Every lane of the workgroup calls it, from uniform control flow, with the same `lanes` and `count`; the rays stand
+ *   in the first `count` before the call, and a barrier has passed since they were written.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_ray_sort = CodeChunk.from(
+    //language=WGSL
+    `
+var<workgroup> screen_probe_sort: array<vec2<u32>, ${2 * SCREEN_PROBE_OCTAHEDRON_LIMIT * SCREEN_PROBE_OCTAHEDRON_LIMIT}>;
+
+fn screen_probe_ray_sort(lane: u32, lanes: u32, count: u32) {
+    for (var block = 2u; block <= count; block <<= 1u) {
+        for (var stride = block >> 1u; stride > 0u; stride >>= 1u) {
+            for (var pair = lane; pair < (count >> 1u); pair += lanes) {
+                let slots = sort_bitonic_comparator(pair, block, stride);
+                let low = screen_probe_sort[slots.x];
+                let high = screen_probe_sort[slots.y];
+
+                if (sort_pair_less(high.y, high.x, low.y, low.x)) {
+                    screen_probe_sort[slots.x] = high;
+                    screen_probe_sort[slots.y] = low;
+                }
+            }
+
+            workgroupBarrier();
+        }
+    }
+
+    for (var t = lane; t < count; t += lanes) {
+        screen_probe_sort[count + t] = screen_probe_sort[t];
+    }
+
+    workgroupBarrier();
+}
+`, [
+        chunk_sort_bitonic_comparator,
+    ]);

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

@@ -0,0 +1,22 @@
+/**
+ * A screen trace's march through the depth buffer's hierarchy, and whether it stopped on a surface:
+ *
+ * ```wgsl
+ * struct ScreenProbeScreenMarch { reached: vec3<f32>, t: f32, hit: bool }
+ * fn screen_probe_screen_march(start: vec3<f32>, span: vec3<f32>, size: vec2<f32>) -> ScreenProbeScreenMarch
+ * ```
+ *
+ * `start` is the segment's start and `span` its run to the end, in UV and device depth; `size` is the view's pixels.
+ * The march is `ffx_sssr_hierarchical_raymarch` from the full-resolution level, `SCREEN_PROBE_SCREEN_TRACE_STEPS`
+ * steps at most. `reached` is where it stopped, `t` its place on the segment held to [0, 1].
+ *
+ * `hit` is whether it converged, short of the segment's end: went below the full-resolution level's surface, Lumen's
+ * `MipLevel < BaseMipLevel`. A march that spent its steps, left the screen or reached the sky stopped where it was,
+ * on no surface, though the march's `valid_hit` reports one that did so on the full-resolution level; one converging
+ * on its very last step is taken for one that spent them, and left to what traces the ray on.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_screen_march: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_screen_march.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_screen_march.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_screen_march.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,8CAFU,SAAS,CA4BZ;0BAhDmB,oCAAoC"}

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

@@ -0,0 +1,53 @@
+import { chunk_is_background } from "../../shader/chunk/depth/chunk_is_background.js";
+import {
+    chunk_ffx_sssr_hierarchical_raymarch
+} from "../../shader/chunk/screen_space/chunk_ffx_sssr_hierarchical_raymarch.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { SCREEN_PROBE_SCREEN_TRACE_STEPS } from "./SCREEN_PROBE.js";
+
+/**
+ * A screen trace's march through the depth buffer's hierarchy, and whether it stopped on a surface:
+ *
+ * ```wgsl
+ * struct ScreenProbeScreenMarch { reached: vec3<f32>, t: f32, hit: bool }
+ * fn screen_probe_screen_march(start: vec3<f32>, span: vec3<f32>, size: vec2<f32>) -> ScreenProbeScreenMarch
+ * ```
+ *
+ * `start` is the segment's start and `span` its run to the end, in UV and device depth; `size` is the view's pixels.
+ * The march is `ffx_sssr_hierarchical_raymarch` from the full-resolution level, `SCREEN_PROBE_SCREEN_TRACE_STEPS`
+ * steps at most. `reached` is where it stopped, `t` its place on the segment held to [0, 1].
+ *
+ * `hit` is whether it converged, short of the segment's end: went below the full-resolution level's surface, Lumen's
+ * `MipLevel < BaseMipLevel`. A march that spent its steps, left the screen or reached the sky stopped where it was,
+ * on no surface, though the march's `valid_hit` reports one that did so on the full-resolution level; one converging
+ * on its very last step is taken for one that spent them, and left to what traces the ray on.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_screen_march = CodeChunk.from(
+    //language=WGSL
+    `
+struct ScreenProbeScreenMarch {
+    reached: vec3<f32>,
+    t: f32,
+    hit: bool,
+}
+
+fn screen_probe_screen_march(start: vec3<f32>, span: vec3<f32>, size: vec2<f32>) -> ScreenProbeScreenMarch {
+    var converged: bool;
+    var steps: u32;
+
+    let reached = ffx_sssr_hierarchical_raymarch(start, span, size, 0, ${SCREEN_PROBE_SCREEN_TRACE_STEPS}u, &converged, &steps);
+
+    // the march's place along the segment, 1 at its end
+    let t = saturate(dot(reached - start, span) / max(dot(span, span), 1e-20));
+
+    let on_screen = all(reached.xy >= vec2<f32>(0.0)) && all(reached.xy <= vec2<f32>(1.0));
+    let hit = converged && steps < ${SCREEN_PROBE_SCREEN_TRACE_STEPS}u && on_screen && !is_background(reached.z) && t < 1.0;
+
+    return ScreenProbeScreenMarch(reached, t, hit);
+}
+`, [
+        chunk_ffx_sssr_hierarchical_raymarch,
+        chunk_is_background,
+    ]);

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

@@ -0,0 +1,62 @@
+/** The view's camera this frame. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_CAMERA_RESOURCE: ShaderResourceDescriptor;
+/** The view's camera last frame. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_CAMERA_PREVIOUS_RESOURCE: ShaderResourceDescriptor;
+/** The frame's reverse-Z depth. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DEPTH_RESOURCE: ShaderResourceDescriptor;
+/** The G-buffer's PBR target, for the face normal it holds. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PBR_RESOURCE: ShaderResourceDescriptor;
+/** The frame's motion, `VELOCITY_FORMAT`: internal pixels from last frame's place to this one's, and the view depth moved through. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_VELOCITY_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Where a pixel's surface point stood last frame, by the velocity buffer:
+ *
+ * ```wgsl
+ * struct ScreenProbePointBefore { place: vec2<f32>, depth: f32, position: vec3<f32> }
+ * fn screen_probe_point_before(pixel: vec2<u32>, depth: f32) -> ScreenProbePointBefore // depth: its view depth now
+ * ```
+ *
+ * - `place`: its place on last frame's screen, internal pixels: the pixel's centre less its motion across the view;
+ * - `depth`: its view depth then, its depth now less the depth it moved through;
+ * - `position`: the world point those show through last frame's camera, where the point stood.
+ *
+ * The camera's motion and the surface's own together, as the velocity buffer holds them; up to the jitter between
+ * the two frames' projections. Off last frame's screen, or with no depth then, `position` means nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_point_before: CodeChunk;
+/**
+ * How fast a pixel's surface point moves of itself, apart from the camera (Lumen's probe and hit world velocity, as a
+ * length):
+ *
+ * ```wgsl
+ * fn screen_probe_object_speed(pixel: vec2<u32>, position: vec3<f32>, depth: f32) -> f32 // metres a frame
+ * ```
+ *
+ * The velocity buffer holds a pixel's motion since last frame, the camera's and the surface's own together: the
+ * point's place on last frame's screen and its view depth then. Last frame's camera takes those back to the world,
+ * where the point stood a frame ago; how far that is from where it stands now is its own motion, across the view and
+ * along it. A still surface reads zero under any camera motion, up to the jitter between the two frames' projections.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_object_speed: CodeChunk;
+/**
+ * The record of a probe standing on a pixel of the G-buffer (Lumen's `GetScreenProbeMaterial` and
+ * `WriteDownsampledProbeMaterial`):
+ *
+ * ```wgsl
+ * fn screen_probe_surface_at(pixel: vec2<u32>) -> ScreenProbe
+ * ```
+ *
+ * The pixel's surface point from its depth at its centre, its view depth, the face normal of the triangle it shows
+ * (the plane, where the shading normal would carry the normal map), and its own speed
+ * (`screen_probe_object_speed`). A pixel of the sky gives a record of depth zero: no probe.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_surface: CodeChunk;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe_surface.js"],"names":[],"mappings":"AAeA,qEAAqE;AACrE,2CADyC,wBAAwB,CAC6C;AAE9G,qEAAqE;AACrE,oDADyC,wBAAwB,CAC+D;AAEhI,oEAAoE;AACpE,0CADwC,wBAAwB,CACsB;AAEtF,gGAAgG;AAChG,wCADoE,wBAAwB,CACV;AAElF,uKAAuK;AACvK,6CAD2I,wBAAwB,CACvE;AAE5F;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CA8BZ;AAKP;;;;;;;;;;;;;;GAcG;AACH,8CAFU,SAAS,CAUZ;AAEP;;;;;;;;;;;;;GAaG;AACH,yCAFU,SAAS,CAkCZ;yCA3IkC,mDAAmD;0BADlE,oCAAoC"}