@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/renderer/shadow/contact/graph_contact_shadow_wavefront.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Record the contact shadow of one light into a new visibility texture: 1 lit, 0 shadowed, at the
+ * depth buffer's resolution. One graph pass, one compute dispatch per entry of `dispatch_list`.
+ *
+ * The caller builds `dispatch_list` for this frame's camera and light (it holds the light's position
+ * on screen) and keeps it alive until the graph has executed; `settings` is read at execution too.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth the depth buffer
+ * @param {ArrayLike<number>} options.resolution of `depth`
+ * @param {import("./ContactShadowDispatchList.js").ContactShadowDispatchList} options.dispatch_list
+ * @param {{surface_thickness: number, bilinear_threshold: number, shadow_contrast: number, flags: number, debug_mode: number}} options.settings
+ * @returns {number} the visibility texture
+ */
+export function graph_contact_shadow_wavefront({ graph, depth, resolution, dispatch_list, settings }: {
+    graph: FrameGraph;
+    depth: number;
+    resolution: ArrayLike<number>;
+    dispatch_list: import("./ContactShadowDispatchList.js").ContactShadowDispatchList;
+    settings: {
+        surface_thickness: number;
+        bilinear_threshold: number;
+        shadow_contrast: number;
+        flags: number;
+        debug_mode: number;
+    };
+}): number;
+//# sourceMappingURL=graph_contact_shadow_wavefront.d.ts.map

package/src/shade/renderer/shadow/contact/graph_contact_shadow_wavefront.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_contact_shadow_wavefront.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/graph_contact_shadow_wavefront.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;GAcG;AACH;IAP+B,KAAK;IACT,KAAK,EAArB,MAAM;IACqB,UAAU,EAArC,UAAU,MAAM,CAAC;IAC2D,aAAa,EAAzF,OAAO,gCAAgC,EAAE,yBAAyB;IAC2D,QAAQ,EAArI;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC;IACjH,MAAM,CAsElB"}

package/src/shade/renderer/shadow/contact/graph_contact_shadow_wavefront.js

@@ -0,0 +1,92 @@
+import { assert } from "../../../../core/assert.js";
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { graph_prepare_bindings } from "../../shader/graph/graph_prepare_bindings.js";
+import { CONTACT_SHADOW_DISPATCH_STRIDE } from "./ContactShadowDispatchList.js";
+import { shader_contact_shadow_wavefront } from "./shader_contact_shadow_wavefront.js";
+
+const BINDING_NAMES = ["tDepth", "tContactShadow"];
+
+/**
+ * Record the contact shadow of one light into a new visibility texture: 1 lit, 0 shadowed, at the
+ * depth buffer's resolution. One graph pass, one compute dispatch per entry of `dispatch_list`.
+ *
+ * The caller builds `dispatch_list` for this frame's camera and light (it holds the light's position
+ * on screen) and keeps it alive until the graph has executed; `settings` is read at execution too.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.depth the depth buffer
+ * @param {ArrayLike<number>} options.resolution of `depth`
+ * @param {import("./ContactShadowDispatchList.js").ContactShadowDispatchList} options.dispatch_list
+ * @param {{surface_thickness: number, bilinear_threshold: number, shadow_contrast: number, flags: number, debug_mode: number}} options.settings
+ * @returns {number} the visibility texture
+ */
+export function graph_contact_shadow_wavefront({ graph, depth, resolution, dispatch_list, settings }) {
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(depth, 'depth');
+    assert.defined(dispatch_list, 'dispatch_list');
+    assert.defined(settings, 'settings');
+
+    const shader = shader_contact_shadow_wavefront;
+
+    /*
+     One immediate block reused across the dispatches: it is serialised as each dispatch is encoded,
+     so writing the next wave offset into it afterwards changes nothing already recorded.
+    */
+    const immediate = {
+        light_coordinate: dispatch_list.light_coordinate,
+        wave_offset: [0, 0],
+        surface_thickness: 0,
+        bilinear_threshold: 0,
+        shadow_contrast: 0,
+        flags: 0,
+        debug_mode: 0,
+    };
+
+    const pass_data = {};
+
+    /**
+     * @param data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(data, resources, context) {
+        const bindings = graph_prepare_bindings(shader.descriptor, BINDING_NAMES, data, resources, context);
+
+        immediate.surface_thickness = settings.surface_thickness;
+        immediate.bilinear_threshold = settings.bilinear_threshold;
+        immediate.shadow_contrast = settings.shadow_contrast;
+        immediate.flags = settings.flags;
+        immediate.debug_mode = settings.debug_mode;
+
+        bindings.settings = immediate;
+
+        const words = dispatch_list.dispatches;
+
+        for (let i = 0; i < dispatch_list.count; i++) {
+            const base = i * CONTACT_SHADOW_DISPATCH_STRIDE;
+
+            immediate.wave_offset[0] = words[base + 3];
+            immediate.wave_offset[1] = words[base + 4];
+
+            shader.dispatch({
+                encoder: context.encoder,
+                bindings,
+                group_count_x: words[base],
+                group_count_y: words[base + 1],
+                group_count_z: words[base + 2],
+            });
+        }
+    }
+
+    const pass = graph.add(shader.descriptor.label, pass_data, execute);
+
+    pass_data.tDepth = pass.read(depth);
+    pass_data.tContactShadow = pass.create("contact shadow", TextureResourceDescriptor.from({
+        resolution: [resolution[0], resolution[1]],
+        format: "r32float",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+    }));
+
+    return pass_data.tContactShadow;
+}

package/src/shade/renderer/shadow/contact/shader_contact_shadow_linear.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Per dispatch, as immediates.
+ *
+ * - `to_light`: unit vector toward the light, world space.
+ * - `length`: how far toward the light each pixel's ray reaches, world units.
+ * - `steps`: linear steps along it, capped by the trace (`SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT`, and one per
+ *   pixel the ray crosses).
+ * - `thickness`: how far behind a depth sample still counts as inside it, view-space units. Marching behind
+ *   surfaces, it must be at least `length / steps` or a step can pass a surface without seeing it.
+ * - `jitter_frame`: 0 for a fixed first step; otherwise the frame, which shifts each pixel's first step by
+ *   interleaved gradient noise for TAA to integrate.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Screen-space contact shadow for one light, by the generic linear trace
+ * (`chunk_screen_space_linear_ray`): each pixel marches its own ray toward the light, a world-space length,
+ * in up to `steps` steps of at least a pixel, against both the point-sampled and bilinear depth.
+ *
+ * Writes visibility, 1 lit and 0 shadowed, for every pixel of `tContactShadow`. A thread's work is bounded
+ * by the trace's step limit: 4 depth reads a step.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_linear: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_contact_shadow_linear.d.ts.map

package/src/shade/renderer/shadow/contact/shader_contact_shadow_linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_contact_shadow_linear.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/shader_contact_shadow_linear.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;GAaG;AACH,oDAFU,YAAY,CAQY;AA+ElC;;;;;;;;;GASG;AACH,2CAFU,aAAa,CAMpB;6BAnH0B,mCAAmC;8BAHlC,+BAA+B"}

package/src/shade/renderer/shadow/contact/shader_contact_shadow_linear.js

@@ -0,0 +1,128 @@
+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_is_background } from "../../shader/chunk/depth/chunk_is_background.js";
+import { chunk_decode_g_buffer_normal } from "../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import { chunk_interleaved_gradient_noise } from "../../shader/chunk/noise/chunk_interleaved_gradient_noise.js";
+import { chunk_screen_space_linear_ray } from "../../shader/chunk/screen_space/chunk_screen_space_linear_ray.js";
+import { chunk_texel_coordinate_to_uv } from "../../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
+import { chunk_uv_to_ndc } from "../../shader/chunk/texture/chunk_uv_to_ndc.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per dispatch, as immediates.
+ *
+ * - `to_light`: unit vector toward the light, world space.
+ * - `length`: how far toward the light each pixel's ray reaches, world units.
+ * - `steps`: linear steps along it, capped by the trace (`SCREEN_SPACE_LINEAR_RAY_STEP_LIMIT`, and one per
+ *   pixel the ray crosses).
+ * - `thickness`: how far behind a depth sample still counts as inside it, view-space units. Marching behind
+ *   surfaces, it must be at least `length / steps` or a step can pass a surface without seeing it.
+ * - `jitter_frame`: 0 for a fixed first step; otherwise the frame, which shifts each pixel's first step by
+ *   interleaved gradient noise for TAA to integrate.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT = WebGPUStruct.from({
+    to_light: vec3f,
+    length: f32,
+    steps: u32,
+    thickness: f32,
+    jitter_frame: u32,
+}, "ContactShadowLinearSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addTexture("gBufferDepth")
+    .addTexture("gBufferNormal", "uint")
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageTexture("tContactShadow", "r32float", "2d", "write-only");
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let size = textureDimensions(gBufferDepth);
+
+    if (any(id.xy >= size)) {
+        return;
+    }
+
+    let depth = textureLoad(gBufferDepth, id.xy, 0).r;
+
+    if (is_background(depth)) {
+        textureStore(tContactShadow, id.xy, vec4<f32>(1.0));
+        return;
+    }
+
+    let to_light = settings.to_light;
+    let geometric_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, id.xy, 0).zw);
+
+    if (dot(geometric_normal, to_light) <= 0.0) {
+        // facing away: the shadow map's term is already 0, nothing to add to it
+        textureStore(tContactShadow, id.xy, vec4<f32>(1.0));
+        return;
+    }
+
+    let uv = texel_coordinate_to_uv(vec2<f32>(id.xy), size);
+    let position_ws = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
+
+    // from the pixel's own NDC, not a reprojection of it
+    var ray = screen_space_linear_ray_new(vec3<f32>(uv_to_ndc(uv), depth));
+
+    screen_space_linear_ray_to_world(&ray, position_ws + to_light * settings.length, camera.view_projection_matrix);
+
+    ray.linear_steps = settings.steps;
+    ray.depth_thickness = settings.thickness;
+    ray.march_behind_surfaces = true;
+
+    if (settings.jitter_frame != 0u) {
+        // in (0, 1]: a first step at 0 would sample the pixel itself
+        ray.jitter = 1.0 - interleaved_gradient_noise(vec2<f32>(id.xy) + 5.588238 * f32(settings.jitter_frame % 64u));
+    }
+
+    let hit = screen_space_linear_ray_march(&ray, gBufferDepth, camera);
+
+    // a hit in the back half of the thickness fades out, as Bevy does: deep hits are the least sure
+    var visibility = 1.0;
+
+    if (hit.hit) {
+        visibility = saturate((hit.penetration_fraction - 0.5) / 0.5);
+    }
+
+    textureStore(tContactShadow, id.xy, vec4<f32>(visibility));
+}
+`, [
+        CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT.declaration_chunk,
+        chunk_is_background,
+        chunk_decode_g_buffer_normal,
+        chunk_texel_coordinate_to_uv,
+        chunk_uv_to_ndc,
+        chunk_project_position_from_depth,
+        chunk_interleaved_gradient_noise,
+        chunk_screen_space_linear_ray,
+    ]
+);
+
+/**
+ * Screen-space contact shadow for one light, by the generic linear trace
+ * (`chunk_screen_space_linear_ray`): each pixel marches its own ray toward the light, a world-space length,
+ * in up to `steps` steps of at least a pixel, against both the point-sampled and bilinear depth.
+ *
+ * Writes visibility, 1 lit and 0 shadowed, for every pixel of `tContactShadow`. A thread's work is bounded
+ * by the trace's step limit: 4 depth reads a step.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_linear = ComputeShader.from({
+    label: "Contact shadow / linear trace",
+    resources,
+    body,
+});

package/src/shade/renderer/shadow/contact/shader_contact_shadow_wavefront.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bits of {@link CONTACT_SHADOW_SETTINGS_STRUCT }'s `flags`.
+ */
+export type ContactShadowFlags = number;
+export namespace ContactShadowFlags {
+    let IgnoreEdgePixels: number;
+    let PrecisionOffset: number;
+    let BilinearOffsetMode: number;
+}
+/**
+ * What {@link CONTACT_SHADOW_SETTINGS_STRUCT }'s `debug_mode` writes instead of the shadow.
+ */
+export type ContactShadowDebugMode = number;
+export namespace ContactShadowDebugMode {
+    let None: number;
+    let EdgeMask: number;
+    let ThreadIndex: number;
+    let WaveIndex: number;
+}
+/**
+ * Per dispatch, as immediates: the light's coordinate and the dispatch's wave offset from
+ * {@link ContactShadowDispatchList}, and the tuning.
+ *
+ * - `surface_thickness`: how thick each depth sample is taken to be, as a fraction of its device
+ *   depth. With this engine's reverse-Z infinite projection (device depth = near / view depth) a sample
+ *   shadows the ray when it is in front of it by up to twice this fraction of its own view distance
+ *   (Bend's `SurfaceThickness`; their starting value 0.005 is 1% of the distance).
+ * - `bilinear_threshold`: two depths further apart than this fraction of the nearer one are an edge,
+ *   and are not interpolated across (`BilinearThreshold`).
+ * - `shadow_contrast`: the slope of the transition in and out of the thickness window
+ *   (`ShadowContrast`); a sample is fully shadowing over the middle `1 − 2 / contrast` of it.
+ *
+ * @type {WebGPUStruct}
+ */
+export const CONTACT_SHADOW_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Screen-space contact shadow for one light, Bend Studio's wavefront method (`bend_sss_gpu.h`,
+ * Sony Interactive Entertainment, Apache 2.0; "Inside Bend: Screen Space Shadows").
+ *
+ * Writes visibility, 1 lit and 0 shadowed, for every pixel of `tContactShadow`, from the depth buffer
+ * alone. One dispatch per entry of a {@link ContactShadowDispatchList}, each with its own wave offset;
+ * the dispatches write disjoint pixels and need no barrier between them.
+ *
+ * **Bounded per thread.** Each thread reads four depths (two reads of two taps) and
+ * {@link SAMPLE_COUNT} words of workgroup memory, and nothing it does depends on the scene.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_contact_shadow_wavefront: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_contact_shadow_wavefront.d.ts.map

package/src/shade/renderer/shadow/contact/shader_contact_shadow_wavefront.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_contact_shadow_wavefront.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/shader_contact_shadow_wavefront.js"],"names":[],"mappings":";;;iCAUU,MAAM;;;;;;;;;qCAwBN,MAAM;;;;;;;AAYhB;;;;;;;;;;;;;;GAcG;AACH,6CAFU,YAAY,CAUM;AA+Q5B;;;;;;;;;;;;GAYG;AACH,8CAFU,aAAa,CAMpB;6BAjW0B,mCAAmC;8BAHlC,+BAA+B"}