@woosh/meep-engine 3.67.0 → 3.68.0

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

@@ -0,0 +1,156 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_project_position_from_depth } from "../../shader/chunk/camera/chunk_project_position_from_depth.js";
+import { chunk_get_device_depth } from "../../shader/chunk/depth/chunk_get_device_depth.js";
+import { chunk_get_view_space_depth } from "../../shader/chunk/depth/chunk_get_view_space_depth.js";
+import { chunk_is_background } from "../../shader/chunk/depth/chunk_is_background.js";
+import {
+    chunk_uv_octahedral_unit_encode
+} from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import {
+    chunk_decode_g_buffer_face_normal
+} from "../../shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { chunk_screen_probe } from "./chunk_screen_probe.js";
+
+/** The view's camera this frame. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_CAMERA_RESOURCE = ShaderResourceDescriptor.uniform("camera", CAMERA_UNIFORM_STRUCT);
+
+/** The view's camera last frame. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_CAMERA_PREVIOUS_RESOURCE = ShaderResourceDescriptor.uniform("camera_previous", CAMERA_UNIFORM_STRUCT);
+
+/** The frame's reverse-Z depth. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DEPTH_RESOURCE = ShaderResourceDescriptor.texture("tDepth");
+
+/** The G-buffer's PBR target, for the face normal it holds. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PBR_RESOURCE = ShaderResourceDescriptor.texture("tPBR");
+
+/** 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.texture("tVelocity");
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+struct ScreenProbePointBefore {
+    place: vec2<f32>,
+    depth: f32,
+    position: vec3<f32>,
+}
+
+fn screen_probe_point_before(pixel: vec2<u32>, depth: f32) -> ScreenProbePointBefore {
+    let motion = textureLoad(tVelocity, pixel, 0).xyz;
+
+    var before: ScreenProbePointBefore;
+
+    before.place = vec2<f32>(pixel) + 0.5 - motion.xy;
+    before.depth = depth - motion.z;
+    before.position = project_position_from_depth(
+        before.place / vec2<f32>(screen_probe_frame.view_size),
+        get_device_depth(before.depth, camera_previous),
+        camera_previous.view_projection_matrix_inverse,
+    );
+
+    return before;
+}
+`, [
+        chunk_screen_probe,
+        chunk_project_position_from_depth,
+        chunk_get_device_depth,
+    ]);
+
+chunk_screen_probe_point_before.requireResource(SCREEN_PROBE_VELOCITY_RESOURCE);
+chunk_screen_probe_point_before.requireResource(SCREEN_PROBE_CAMERA_PREVIOUS_RESOURCE);
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+fn screen_probe_object_speed(pixel: vec2<u32>, position: vec3<f32>, depth: f32) -> f32 {
+    return distance(position, screen_probe_point_before(pixel, depth).position);
+}
+`, [
+        chunk_screen_probe_point_before,
+    ]);
+
+/**
+ * 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.from(
+    //language=WGSL
+    `
+fn screen_probe_surface_at(pixel: vec2<u32>) -> ScreenProbe {
+    var record: ScreenProbe;
+
+    record.pixel = screen_probe_pixel_encode(pixel);
+
+    let device_depth = textureLoad(tDepth, pixel, 0).r;
+
+    if (is_background(device_depth)) {
+        return record;
+    }
+
+    let uv = (vec2<f32>(pixel) + 0.5) / vec2<f32>(screen_probe_frame.view_size);
+    let depth = get_view_space_depth(device_depth, camera);
+
+    record.position = project_position_from_depth(uv, device_depth, camera.view_projection_matrix_inverse);
+    record.depth = depth;
+    record.normal = pack2x16unorm(uv_octahedral_unit_encode(decode_g_buffer_face_normal(textureLoad(tPBR, pixel, 0))));
+    record.speed = screen_probe_object_speed(pixel, record.position, depth);
+
+    return record;
+}
+`, [
+        chunk_screen_probe,
+        chunk_screen_probe_object_speed,
+        chunk_is_background,
+        chunk_get_view_space_depth,
+        chunk_project_position_from_depth,
+        chunk_decode_g_buffer_face_normal,
+        chunk_uv_octahedral_unit_encode,
+    ]);
+
+chunk_screen_probe_surface.requireResource(SCREEN_PROBE_DEPTH_RESOURCE);
+chunk_screen_probe_surface.requireResource(SCREEN_PROBE_PBR_RESOURCE);
+chunk_screen_probe_surface.requireResource(SCREEN_PROBE_CAMERA_RESOURCE);

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

@@ -0,0 +1,18 @@
+/**
+ * The sum of a `vec4<f32>` over the lanes of a one-dimensional workgroup of `SCREEN_PROBE_THREAD_WORKGROUP_SIZE`,
+ * handed to every lane:
+ *
+ * ```wgsl
+ * fn screen_probe_workgroup_sum(value: vec4<f32>, lane: u32, subgroup_lane: u32, subgroup_size: u32) -> vec4<f32>
+ * ```
+ *
+ * Each subgroup adds its lanes' values (`subgroupAdd`); its first lane leaves the subgroup's sum in workgroup memory
+ * at the subgroup's place, `(lane − subgroup_lane) / subgroup_size`, which a one-dimensional workgroup's subgroups
+ * follow; then every lane adds the subgroups' sums. Every lane of the workgroup calls it from uniform control flow:
+ * it holds two barriers.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_workgroup_sum: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe_workgroup_sum.d.ts.map

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

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

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

@@ -0,0 +1,50 @@
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { SCREEN_PROBE_THREAD_WORKGROUP_SIZE } from "./SCREEN_PROBE.js";
+
+/**
+ * The sum of a `vec4<f32>` over the lanes of a one-dimensional workgroup of `SCREEN_PROBE_THREAD_WORKGROUP_SIZE`,
+ * handed to every lane:
+ *
+ * ```wgsl
+ * fn screen_probe_workgroup_sum(value: vec4<f32>, lane: u32, subgroup_lane: u32, subgroup_size: u32) -> vec4<f32>
+ * ```
+ *
+ * Each subgroup adds its lanes' values (`subgroupAdd`); its first lane leaves the subgroup's sum in workgroup memory
+ * at the subgroup's place, `(lane − subgroup_lane) / subgroup_size`, which a one-dimensional workgroup's subgroups
+ * follow; then every lane adds the subgroups' sums. Every lane of the workgroup calls it from uniform control flow:
+ * it holds two barriers.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_workgroup_sum = CodeChunk.from(
+    //language=WGSL
+    `
+var<workgroup> screen_probe_partial_sums: array<vec4<f32>, ${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}>;
+
+fn screen_probe_workgroup_sum(value: vec4<f32>, lane: u32, subgroup_lane: u32, subgroup_size: u32) -> vec4<f32> {
+    let partial = subgroupAdd(value);
+
+    if (subgroup_lane == 0u) {
+        screen_probe_partial_sums[(lane - subgroup_lane) / subgroup_size] = partial;
+    }
+
+    workgroupBarrier();
+
+    // a subgroup wider than the workgroup holds all its lanes
+    let subgroups = (${SCREEN_PROBE_THREAD_WORKGROUP_SIZE}u + subgroup_size - 1u) / subgroup_size;
+
+    var total = vec4<f32>(0.0);
+
+    for (var i = 0u; i < subgroups; i++) {
+        total += screen_probe_partial_sums[i];
+    }
+
+    // before the next call writes over the sums
+    workgroupBarrier();
+
+    return total;
+}
+`);
+
+chunk_screen_probe_workgroup_sum.addExtension(WebGPUExtensionType.Subgroups);

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

@@ -0,0 +1,21 @@
+/**
+ * Record a screen probe debug view in place of the frame's colour (`ScreenProbeDebugView`), after this frame's
+ * `GPUScreenProbeGI#graph_resolve`.
+ *
+ * @param {Object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {import("./GPUScreenProbeGI.js").GPUScreenProbeGI} options.gi
+ * @param {ScreenProbeDebugView} options.view_mode
+ * @param {number} options.depth graph handle of the view's depth
+ * @param {number[]} options.resolution the view's pixels
+ * @returns {number} graph handle of the image, `rgba16float`
+ */
+export function graph_screen_probe_debug_view({ graph, gi, view_mode, depth, resolution }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    gi: import("./GPUScreenProbeGI.js").GPUScreenProbeGI;
+    view_mode: ScreenProbeDebugView;
+    depth: number;
+    resolution: number[];
+}): number;
+import { ScreenProbeDebugView } from "./ScreenProbeDebugView.js";
+//# sourceMappingURL=graph_screen_probe_debug_view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_screen_probe_debug_view.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/graph_screen_probe_debug_view.js"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH;IAPsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;IACvB,EAAE,EAA5D,OAAO,uBAAuB,EAAE,gBAAgB;IAClB,SAAS,EAAvC,oBAAoB;IACJ,KAAK,EAArB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACN,MAAM,CAkClB;qCAnDoC,2BAA2B"}

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

@@ -0,0 +1,54 @@
+import { assert } from "../../../../core/assert.js";
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { ScreenProbeDebugView } from "./ScreenProbeDebugView.js";
+import { SCREEN_PROBE_TILE_WORKGROUP_SIZE } from "./SCREEN_PROBE.js";
+import { shader_screen_probe_debug } from "./shader_screen_probe_debug.js";
+
+const settings = { view: 0 };
+const bindings = {};
+
+/**
+ * Record a screen probe debug view in place of the frame's colour (`ScreenProbeDebugView`), after this frame's
+ * `GPUScreenProbeGI#graph_resolve`.
+ *
+ * @param {Object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {import("./GPUScreenProbeGI.js").GPUScreenProbeGI} options.gi
+ * @param {ScreenProbeDebugView} options.view_mode
+ * @param {number} options.depth graph handle of the view's depth
+ * @param {number[]} options.resolution the view's pixels
+ * @returns {number} graph handle of the image, `rgba16float`
+ */
+export function graph_screen_probe_debug_view({ graph, gi, view_mode, depth, resolution }) {
+    assert.enum(view_mode, ScreenProbeDebugView, 'view_mode');
+    assert.notEqual(view_mode, ScreenProbeDebugView.None, 'view_mode');
+
+    const data = {};
+    const pass = graph.add("Screen Probe Debug", data, (data, resources, context) => {
+        settings.view = view_mode;
+
+        gi.write_debug_bindings(bindings);
+
+        bindings.settings = settings;
+        bindings.tDepth = resources.get(data.depth);
+        bindings.screen_probe_debug_diffuse = resources.get(data.diffuse);
+        bindings.screen_probe_debug_out = resources.get(data.output);
+
+        shader_screen_probe_debug.dispatch({
+            encoder: context.encoder,
+            bindings,
+            group_count_x: Math.ceil(resolution[0] / SCREEN_PROBE_TILE_WORKGROUP_SIZE),
+            group_count_y: Math.ceil(resolution[1] / SCREEN_PROBE_TILE_WORKGROUP_SIZE),
+        });
+    });
+
+    data.depth = pass.read(depth);
+    data.diffuse = pass.read(gi.diffuse_handle);
+    data.output = pass.create("screen_probe_debug", TextureResourceDescriptor.from({
+        format: "rgba16float",
+        resolution,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+    }));
+
+    return data.output;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_screen_probe_brick.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_screen_probe_brick.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/shader_screen_probe_brick.js"],"names":[],"mappings":"AAkGA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,aAAa,CA+DpB;AAYH;;;;;;;;;;;;;GAaG;AACH,8CAFU,aAAa,CAiEpB;AAUH;;;;;;GAMG;AACH,8CAFU,aAAa,CAwDpB;AA4BH;;;;;;;;;;;;;GAaG;AACH,+CAFU,aAAa,CAwEpB;AAWH;;;;;;;GAOG;AACH,6CAFU,aAAa,CA2CpB;8BAne2B,+BAA+B"}