@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/playground/contact_shadows/ContactShadowLab.js

@@ -0,0 +1,654 @@
+import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { TextureResourceDescriptor } from "../../device/graph/TextureResourceDescriptor.js";
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { GBufferTextures } from "../../renderer/extension/GBufferTextures.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ViewTextures } from "../../renderer/extension/ViewTextures.js";
+import { graph_compute_pass } from "../../renderer/shader/graph/compute/graph_compute_pass.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_buffer } from "../../renderer/shader/graph/graph_import_buffer.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { STATIC_GRAPHICS_ENGINE_ASSETS } from "../../renderer/STATIC_GRAPHICS_ENGINE_ASSETS.js";
+import { ContactShadowDispatchList } from "../../renderer/shadow/contact/ContactShadowDispatchList.js";
+import { graph_contact_shadow_linear } from "../../renderer/shadow/contact/graph_contact_shadow_linear.js";
+import { graph_contact_shadow_wavefront } from "../../renderer/shadow/contact/graph_contact_shadow_wavefront.js";
+import { ContactCombine, ContactCompositeFlags, shader_contact_lab_composite } from "./shader_contact_lab_composite.js";
+import { shader_contact_lab_reference } from "./shader_contact_lab_reference.js";
+import { CONTACT_STAT_COUNT, shader_contact_lab_stats } from "./shader_contact_lab_stats.js";
+import { ContactLabView, shader_contact_lab_view } from "./shader_contact_lab_view.js";
+import { shader_contact_shadow_march } from "./shader_contact_shadow_march.js";
+
+/**
+ * Which contact term the sun's shadow reads.
+ * @enum {number}
+ */
+export const ContactMethod = {
+    /** none: the shadow map alone */
+    Off: 0,
+    /** the wavefront pass in `renderer/shadow/contact/` (Bend Studio's method) */
+    Wavefront: 1,
+    /** the engine's unwired per-pixel march, same budget and window */
+    March: 2,
+    /** the generic linear trace (`chunk_screen_space_linear_ray`), a world-space reach per pixel */
+    Linear: 3,
+};
+
+const MIP_0 = TextureViewDescriptor.from({ baseMipLevel: 0, mipLevelCount: 1 });
+
+/**
+ * The contact shadow playground's frame work, as two render extensions sharing this state:
+ *
+ * - at {@link FramePhase.AfterLighting}: the contact term ({@link method}), the ray-traced sun
+ *   visibility when asked for ({@link reference}), the composite that puts the contact term into the
+ *   sun's shadow, and, while {@link measuring}, the counters;
+ * - at {@link FramePhase.BeforePresent}: the debug {@link view}, drawn after the upscale and before the
+ *   tonemap.
+ *
+ * Nothing here changes the renderer's own passes; see {@link shader_contact_lab_composite} for how the
+ * mask reaches the lit image without them.
+ */
+export class ContactShadowLab {
+    /** @type {number} a {@link ContactMethod} */
+    method = ContactMethod.Wavefront;
+
+    /** @type {number} a {@link ContactCombine} */
+    combine = ContactCombine.Multiply;
+
+    /** @type {number} a {@link ContactLabView} */
+    view = ContactLabView.Final;
+
+    /**
+     * Trace the sun's visibility from every pixel through the scene's BVH, for the reference and error
+     * views. Always on while {@link measuring}.
+     * @type {boolean}
+     */
+    reference = false;
+
+    /**
+     * Run the counters this frame; {@link read_stats} collects them.
+     * @type {boolean}
+     */
+    measuring = false;
+
+    /**
+     * Tuning shared by both methods: Bend's starting values (`bend_sss_gpu.h`, `SetDefaults`).
+     */
+    settings = {
+        surface_thickness: 0.005,
+        bilinear_threshold: 0.02,
+        shadow_contrast: 4,
+        flags: 0,
+        debug_mode: 0,
+    };
+
+    /**
+     * Unit vector from the scene toward the sun, world space. The playground's scenes keep it.
+     * @type {Float32Array}
+     */
+    to_light = new Float32Array([0, 1, 0]);
+
+    /**
+     * How far the reference's rays start off their surface, along its geometric normal, as a fraction of
+     * the pixel's distance from the camera: a position rebuilt from the depth buffer is off by an amount
+     * that grows with distance, and a ray starting under its own surface shadows itself.
+     *
+     * Measured on the 4090 (still camera, 1578×802), pixels the reference shadows: with `offset_ray`
+     * alone 180,140 in `combine` and 96,352 in `grazing` (the far ground shadowing itself); 43,101 and
+     * 45,579 at 1e-6; 25,166 and 9,709 at 1e-5, where both settle (3e-5 … 3e-4 within 0.2% of it); at
+     * 1e-3 real contacts start to go (`grazing` 9,393). 3e-5 is three times the onset.
+     * @type {number}
+     */
+    reference_normal_offset = 3e-5;
+
+    /**
+     * Samples per pixel the march arm takes, matched to the wavefront pass's 60.
+     * @type {number}
+     */
+    march_steps = 60;
+
+    /**
+     * The linear trace's settings, read when its pass executes (`CONTACT_SHADOW_LINEAR_SETTINGS_STRUCT`).
+     * `to_light` is kept equal to {@link to_light}; `jitter_frame` is the view's frame index while
+     * {@link linear_jitter} is on. The page sets the rest.
+     */
+    linear_settings = {
+        to_light: this.to_light,
+        length: 0.5,
+        steps: 64,
+        thickness: 0.5 / 16,
+        jitter_frame: 0,
+    };
+
+    /**
+     * Shift each pixel's first step by noise every frame, for TAA to integrate.
+     * @type {boolean}
+     */
+    linear_jitter = false;
+
+    /**
+     * Whose frames this records into; the composite is built for its shader switches, as its deferred
+     * pass is.
+     * @type {import("../../renderer/Renderer.js").Renderer}
+     */
+    #renderer;
+
+    /** @type {import("../../renderer/GraphicsContext.js").GraphicsContext} */
+    #graphics;
+
+    #dispatch_list = new ContactShadowDispatchList();
+    #light_projection = new Float32Array(4);
+
+    /**
+     * This frame's visibility record, handed from the lighting phase to the view phase.
+     * @type {number}
+     */
+    #visibility = -1;
+
+    /** The last measured frame's record, for flips. */
+    #visibility_previous;
+    #has_previous = false;
+
+    /** Bound where a term is off, so the composite's layout never changes. */
+    #empty_contact;
+    #empty_reference;
+
+    /** @type {GPUBuffer} */
+    #stats_buffer;
+    /** @type {GPUBuffer} */
+    #stats_readback;
+
+    #zero_stats = new Uint32Array(CONTACT_STAT_COUNT);
+
+    /**
+     * Copy the lit colour of the next frames aside, for {@link read_capture}.
+     * @type {boolean}
+     */
+    capture = false;
+
+    /** @type {GPUTexture|undefined} */
+    #capture_texture;
+    #capture_width = 0;
+    #capture_height = 0;
+
+    /**
+     * Records at {@link FramePhase.AfterLighting}.
+     * @type {RenderExtension}
+     */
+    lighting;
+
+    /**
+     * Records at {@link FramePhase.BeforePresent}.
+     * @type {RenderExtension}
+     */
+    overlay;
+
+    /**
+     * @param {import("../../renderer/Renderer.js").Renderer} renderer
+     */
+    constructor(renderer) {
+        const graphics = renderer.graphics;
+
+        this.#renderer = renderer;
+        this.#graphics = graphics;
+
+        const textures = graphics.textures;
+
+        this.#empty_contact = textures.contextFromDescriptor(TextureDescriptor.from({
+            label: 'contact lab / no contact',
+            size: [1, 1, 1],
+            format: 'r32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        }));
+
+        this.#empty_reference = textures.contextFromDescriptor(TextureDescriptor.from({
+            label: 'contact lab / no reference',
+            size: [1, 1, 1],
+            format: 'r32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        }));
+
+        this.#visibility_previous = textures.contextFromDescriptor(TextureDescriptor.from({
+            label: 'contact lab / previous visibility',
+            size: [1, 1, 1],
+            format: 'rgba8unorm',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        }));
+
+        const device = graphics.device;
+
+        this.#stats_buffer = device.createBuffer({
+            label: 'contact lab / stats',
+            size: CONTACT_STAT_COUNT * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        });
+
+        this.#stats_readback = device.createBuffer({
+            label: 'contact lab / stats readback',
+            size: CONTACT_STAT_COUNT * 4,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+
+        const lab = this;
+
+        this.lighting = new class extends RenderExtension {
+            name = 'playground/contact lab';
+            phase = FramePhase.AfterLighting;
+
+            record(frame) {
+                lab.#record_lighting(frame);
+            }
+        }();
+
+        this.overlay = new class extends RenderExtension {
+            name = 'playground/contact lab view';
+            phase = FramePhase.BeforePresent;
+            relative_order = 1000;
+
+            record(frame) {
+                lab.#record_view(frame);
+            }
+        }();
+    }
+
+    /**
+     * Forget the last measured frame, so the next one counts no flips against a frame from elsewhere.
+     */
+    reset_history() {
+        this.#has_previous = false;
+    }
+
+    /**
+     * Zero the counters ahead of a measured frame; queued, so it lands before the frame's commands.
+     */
+    clear_stats() {
+        this.#graphics.device.queue.writeBuffer(this.#stats_buffer, 0, this.#zero_stats);
+    }
+
+    /**
+     * The counters of the last measured frame, after its commands.
+     *
+     * @returns {Promise<Uint32Array>} indexed by {@link ContactStat}
+     */
+    async read_stats() {
+        const device = this.#graphics.device;
+        const encoder = device.createCommandEncoder({ label: 'contact lab / read stats' });
+
+        encoder.copyBufferToBuffer(this.#stats_buffer, 0, this.#stats_readback, 0, CONTACT_STAT_COUNT * 4);
+        device.queue.submit([encoder.finish()]);
+
+        await this.#stats_readback.mapAsync(GPUMapMode.READ);
+
+        const result = new Uint32Array(this.#stats_readback.getMappedRange().slice(0));
+
+        this.#stats_readback.unmap();
+
+        return result;
+    }
+
+    /**
+     * The sun through this frame's view-projection, as a direction (w = 0), for the dispatch list.
+     *
+     * @param {import("../../renderer/view/GPUViewContext.js").GPUViewContext} view
+     */
+    #project_light(view) {
+        const m = view.camera.view_projection_matrix;
+        const d = this.to_light;
+        const out = this.#light_projection;
+
+        for (let i = 0; i < 4; i++) {
+            out[i] = m[i] * d[0] + m[4 + i] * d[1] + m[8 + i] * d[2];
+        }
+
+        return out;
+    }
+
+    /**
+     * @param {import("../../renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    #record_lighting(frame) {
+        const graph = frame.graph;
+        const view = frame.view;
+        const scene_ctx = view.scene;
+
+        const depth = frame.get(ViewTextures).depth;
+        const gbuffer = frame.get(GBufferTextures);
+        const scene_color = frame.get(SceneColor);
+
+        const resolution = frame.describe(depth).resolution;
+        const width = resolution[0];
+        const height = resolution[1];
+
+        let contact = -1;
+
+        if (this.method === ContactMethod.Wavefront) {
+            this.#dispatch_list.build(this.#project_light(view), width, height);
+
+            contact = graph_contact_shadow_wavefront({
+                graph,
+                depth,
+                resolution,
+                dispatch_list: this.#dispatch_list,
+                settings: this.settings,
+            });
+        } else if (this.method === ContactMethod.March) {
+            contact = graph_compute_pass({
+                graph,
+                shader: shader_contact_shadow_march,
+                group_count: [Math.ceil(width / 8), Math.ceil(height / 8), 1],
+                bindings: {
+                    settings: {
+                        to_light: this.to_light,
+                        surface_thickness: this.settings.surface_thickness,
+                        step_count: this.march_steps,
+                    },
+                    gBufferDepth: depth,
+                    gBufferNormal: gbuffer.normal,
+                    camera: view.camera.buffer,
+                    tContactShadow: TextureResourceDescriptor.from({
+                        resolution: [width, height],
+                        format: 'r32float',
+                        usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+                    }),
+                },
+            }).tContactShadow;
+        } else if (this.method === ContactMethod.Linear) {
+            const settings = this.linear_settings;
+
+            settings.to_light = this.to_light;
+            // never 0, which means no jitter
+            settings.jitter_frame = this.linear_jitter ? view.frame_index + 1 : 0;
+
+            contact = graph_contact_shadow_linear({
+                graph,
+                depth,
+                normal: gbuffer.normal,
+                camera: view.camera.buffer,
+                resolution,
+                settings,
+            });
+        }
+
+        const traced = this.reference || this.measuring;
+
+        const reference = traced ? this.#record_reference(graph, view, depth, gbuffer.normal, width, height) : -1;
+
+        let flags = 0;
+
+        if (contact !== -1) {
+            flags |= ContactCompositeFlags.Contact;
+        }
+
+        if (reference !== -1) {
+            flags |= ContactCompositeFlags.Reference;
+        }
+
+        const [color, visibility] = graph_image_pass({
+            graph,
+            shader: shader_contact_lab_composite.variant(this.#renderer.shader_switches),
+            inputs: {
+                settings: {
+                    combine: this.combine,
+                    flags,
+                },
+                tColor: scene_color.color,
+                gBufferDepth: depth,
+                gBufferPBR: gbuffer.pbr,
+                gBufferNormal: gbuffer.normal,
+                gBufferAlbedo: gbuffer.albedo,
+                gBufferEmissive: gbuffer.emissive,
+                tContact: contact !== -1 ? contact : graph_import_texture(graph, this.#empty_contact),
+                tReference: reference !== -1 ? reference : graph_import_texture(graph, this.#empty_reference),
+                tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
+                light_data: scene_ctx.lights.buffer_data,
+                shadowmapAtlas: graph_import_texture(graph, scene_ctx.lights.shadow_context.texture, 'contact lab / shadow atlas'),
+                view: view.uniform_buffer.buffer,
+                camera: view.camera.buffer,
+            },
+            output_resolution: resolution,
+            output_extra_usage_flags: GPUTextureUsage.COPY_SRC,
+        });
+
+        scene_color.color = color;
+
+        this.#visibility = visibility;
+
+        if (this.capture) {
+            this.#record_capture(graph, color, width, height);
+        }
+
+        if (this.measuring) {
+            this.#record_stats(graph, view, depth, visibility, width, height);
+        }
+    }
+
+    /**
+     * One ray per pixel from its G-buffer position toward the sun, through the scene's BVH
+     * ({@link shader_contact_lab_reference}): visibility, 1 lit and 0 shadowed.
+     */
+    #record_reference(graph, view, depth, normal, width, height) {
+        const data = {};
+        const pass = graph.add('Contact lab / ray-traced reference', data, (data, resources, context) => {
+            const scene_ctx = view.scene;
+            const geometries = scene_ctx.geometries;
+            const materials = context.graphics.materials_resident;
+
+            materials.ensure_scene_materials(scene_ctx);
+            materials.update();
+
+            shader_contact_lab_reference.dispatch({
+                encoder: context.encoder,
+                group_count_x: Math.ceil(width / 8),
+                group_count_y: Math.ceil(height / 8),
+                bindings: {
+                    settings: { normal_offset: this.reference_normal_offset },
+                    gBufferDepth: resources.get(data.depth).obtainView(MIP_0),
+                    gBufferNormal: resources.get(data.normal).obtainView(MIP_0),
+                    camera: view.camera.buffer,
+                    view: view.uniform_buffer,
+                    tlas: scene_ctx.tlas.buffer,
+                    blas_lookup: geometries.blas.buffer_metadata,
+                    blas_data: geometries.blas.buffer_data,
+                    scene_database: scene_ctx.scene_database_buffer,
+                    geometries: geometries.buffer_metadata,
+                    meshlet_data: geometries.meshlets.buffer_data,
+                    meshlet_metadata: geometries.meshlets.buffer_metadata,
+                    materials: materials.buffer_materials,
+                    textures: materials.textureView,
+                    light_data: scene_ctx.lights.buffer_data,
+                    tReference: resources.get(data.output).obtainView(),
+                },
+            });
+        });
+
+        data.depth = pass.read(depth);
+        data.normal = pass.read(normal);
+        data.output = pass.create('contact lab / reference', TextureResourceDescriptor.from({
+            resolution: [width, height],
+            format: 'r32float',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        }));
+
+        return data.output;
+    }
+
+    /**
+     * Count this frame's record against the last measured one, then keep it for the next.
+     */
+    #record_stats(graph, view, depth, visibility, width, height) {
+        const previous = this.#visibility_previous;
+
+        if (previous.descriptor.size[0] !== width || previous.descriptor.size[1] !== height) {
+            previous.resize(width, height);
+            this.#has_previous = false;
+        }
+
+        const previous_handle = graph_import_texture(graph, previous, 'contact lab / previous visibility');
+
+        graph_compute_pass({
+            graph,
+            shader: shader_contact_lab_stats,
+            group_count: [Math.ceil(width / 8), Math.ceil(height / 8), 1],
+            bindings: {
+                settings: { has_previous: this.#has_previous ? 1 : 0 },
+                tVisibility: visibility,
+                tVisibilityPrevious: previous_handle,
+                gBufferDepth: depth,
+                camera: view.camera.buffer,
+                stats: graph_import_buffer(graph, this.#stats_buffer, 'contact lab / stats'),
+            },
+        });
+
+        const data = {};
+        const pass = graph.add('Contact lab / keep visibility', data, (data, resources, context) => {
+            context.encoder.copyTextureToTexture(
+                { texture: resources.get(data.source).gpu_texture, mipLevel: 0, origin: [0, 0, 0] },
+                { texture: resources.get(data.destination).gpu_texture, mipLevel: 0, origin: [0, 0, 0] },
+                [width, height, 1]
+            );
+        });
+
+        data.source = pass.read(visibility);
+        data.destination = pass.write(previous_handle);
+
+        this.#has_previous = true;
+    }
+
+    /**
+     * Keep the composite's colour, as lit and before anything after lighting touches it.
+     */
+    #record_capture(graph, color, width, height) {
+        const device = this.#graphics.device;
+
+        if (this.#capture_width !== width || this.#capture_height !== height) {
+            this.#capture_texture?.destroy();
+
+            this.#capture_texture = device.createTexture({
+                label: 'contact lab / capture',
+                size: [width, height, 1],
+                format: 'rgba16float',
+                usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC,
+            });
+
+            this.#capture_width = width;
+            this.#capture_height = height;
+        }
+
+        const target = this.#capture_texture;
+
+        const data = {};
+        const pass = graph.add('Contact lab / capture', data, (data, resources, context) => {
+            context.encoder.copyTextureToTexture(
+                { texture: resources.get(data.source).gpu_texture, mipLevel: 0, origin: [0, 0, 0] },
+                { texture: target, mipLevel: 0, origin: [0, 0, 0] },
+                [width, height, 1]
+            );
+        });
+
+        data.source = pass.read(color);
+
+        pass.make_side_effect();
+    }
+
+    /**
+     * The colour the last captured frame was lit with, as RGB floats.
+     *
+     * @returns {Promise<{rgb: Float32Array, width: number, height: number}>}
+     */
+    async read_capture() {
+        const device = this.#graphics.device;
+        const width = this.#capture_width;
+        const height = this.#capture_height;
+        const bytes_per_row = Math.ceil(width * 8 / 256) * 256;
+
+        const buffer = device.createBuffer({
+            label: 'contact lab / capture readback',
+            size: bytes_per_row * height,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+
+        const encoder = device.createCommandEncoder({ label: 'contact lab / capture readback' });
+
+        encoder.copyTextureToBuffer(
+            { texture: this.#capture_texture, mipLevel: 0 },
+            { buffer, bytesPerRow: bytes_per_row },
+            [width, height, 1]
+        );
+
+        device.queue.submit([encoder.finish()]);
+
+        await buffer.mapAsync(GPUMapMode.READ);
+
+        const halves = new Uint16Array(buffer.getMappedRange());
+        const stride = bytes_per_row / 2;
+        const rgb = new Float32Array(width * height * 3);
+
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                for (let c = 0; c < 3; c++) {
+                    rgb[(y * width + x) * 3 + c] = half_to_float(halves[y * stride + x * 4 + c]);
+                }
+            }
+        }
+
+        buffer.unmap();
+        buffer.destroy();
+
+        return { rgb, width, height };
+    }
+
+    /**
+     * @param {import("../../renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    #record_view(frame) {
+        const visibility = this.#visibility;
+
+        this.#visibility = -1;
+
+        if (this.view === ContactLabView.Final || visibility === -1) {
+            return;
+        }
+
+        const scene_color = frame.get(SceneColor);
+
+        const [output] = graph_image_pass({
+            graph: frame.graph,
+            shader: shader_contact_lab_view,
+            inputs: {
+                settings: { mode: this.view },
+                tScene: scene_color.color,
+                tVisibility: visibility,
+            },
+            output_resolution: frame.resolution,
+        });
+
+        scene_color.color = output;
+    }
+
+    destroy() {
+        this.#stats_buffer.destroy();
+        this.#stats_readback.destroy();
+        this.#capture_texture?.destroy();
+    }
+}
+
+/**
+ * @param {number} h a float16 bit pattern
+ * @returns {number}
+ */
+function half_to_float(h) {
+    const sign = (h & 0x8000) !== 0 ? -1 : 1;
+    const exponent = (h & 0x7C00) >> 10;
+    const fraction = h & 0x03FF;
+
+    if (exponent === 0) {
+        return sign * Math.pow(2, -14) * (fraction / 1024);
+    }
+
+    if (exponent === 31) {
+        return fraction !== 0 ? NaN : sign * Infinity;
+    }
+
+    return sign * Math.pow(2, exponent - 15) * (1 + fraction / 1024);
+}