@woosh/meep-engine 3.53.0 → 3.54.0

package/src/shade/renderer/hiz/HierarchicalZBuffer.js

@@ -1,294 +1,350 @@
-import { assert } from "../../../core/assert.js";
-import { max2 } from "../../../core/math/max2.js";
-import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
-import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
-import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
-import { HZB_TEXTURE_FORMAT } from "./HZB_TEXTURE_FORMAT.js";
-import { shader_hzb_reduce_any, shader_hzb_reduce_mip0 } from "./shader_hzb_reduce_any.js";
-import { shader_hzb_reduce_mip0_clip } from "./shader_hzb_reduce_mip0_clip.js";
-
-/**
- * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
- * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
- * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
- */
-
-export class HierarchicalZBuffer {
-
-    /**
-     * @type {GPUTextureContext}
-     */
-    #texture;
-
-    /**
-     * @type {string|GPUTextureFormat}
-     */
-    #format = HZB_TEXTURE_FORMAT
-
-    /**
-     * Offer the pipelines {@link build} draws with — see {@link PipelineEnquiry}. A viewport that
-     * clips part of its source draws mip 0 with {@link shader_hzb_reduce_mip0_clip} instead, which
-     * is left to the frame that does that.
-     *
-     * @param {PipelineEnquiry} enquiry
-     */
-    static enquirePipelines(enquiry) {
-        enquiry.render.push(shader_hzb_reduce_mip0.pipeline);
-        enquiry.render.push(shader_hzb_reduce_any.pipeline);
-    }
-
-    /**
-     *
-     * @returns {GPUTextureContext}
-     */
-    get texture() {
-        return this.#texture;
-    }
-
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics;
-
-    /**
-     *
-     * @type {number[]}
-     */
-    #viewport_size = [1, 1];
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     */
-    constructor(graphics) {
-        this.#graphics = graphics;
-
-        this.#texture = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-            label: "Hierarchical Z Buffer",
-            format: this.#format,
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
-            mipLevelCount: 1,
-            size: [1, 1]
-        }));
-
-
-    }
-
-    /**
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {GPUTextureContext} source
-     * @param {number[]} [source_offset] [x0,y0]
-     */
-    build(
-        encoder,
-        source,
-        source_offset
-    ) {
-
-        assert.defined(encoder, 'encoder');
-        assert.notNull(encoder, 'encoder');
-        assert.equal(encoder.isGPUCommandContext, true, 'encoder is not a GPUCommandContext')
-
-        assert.defined(source, 'source');
-        assert.notNull(source, 'source');
-        assert.equal(source.isGPUTextureContext, true, 'source is not a GPUTextureContext')
-
-        // the first pass is special, we need to read from source texture and write to first mip level of hzb
-
-        const texture = this.#texture;
-
-        assert.equal(texture.isDestroyed, false, 'texture is destroyed');
-
-        const mipLevelCount = texture.descriptor.mipLevelCount;
-
-        let source_view = source.obtainView(TextureViewDescriptor.from({
-            baseMipLevel: 0,
-            mipLevelCount: 1,
-            dimension: "2d",
-            baseArrayLayer: 0,
-            arrayLayerCount: 1
-        }));
-
-        const destination_view = texture.obtainView(TextureViewDescriptor.from({
-            baseMipLevel: 0,
-            mipLevelCount: 1,
-            dimension: "2d",
-            baseArrayLayer: 0,
-            arrayLayerCount: 1
-        }));
-
-        const viewport_size = this.#viewport_size;
-
-        const is_clipped_variant = source_offset !== undefined
-            && (
-                (
-                    source_offset[0] !== 0
-                    || source_offset[1] !== 0
-                )
-                || (
-                    viewport_size[0] !== source.width
-                    || viewport_size[1] !== source.height
-                )
-            );
-
-        if (is_clipped_variant) {
-            // special case for clip region
-
-            shader_hzb_reduce_mip0_clip.draw({
-                encoder,
-                bindings: {
-                    tInput: source_view,
-                    settings: {
-                        clip_region: [
-                            source_offset[0], source_offset[1],
-                            viewport_size[0], viewport_size[1],
-                        ],
-                        output_resolution: this.#mip_resolution(0),
-                    },
-                },
-                colorAttachments: [{
-                    view: destination_view,
-                    loadOp: 'clear',
-                    storeOp: 'store'
-                }]
-            })
-        } else {
-
-            this.#do_reduction_pass(encoder, shader_hzb_reduce_mip0, source_view, destination_view, 0);
-        }
-
-        source_view = destination_view;
-
-        for (let i = 1; i < mipLevelCount; i++) {
-
-            const destination_view = texture.obtainView(TextureViewDescriptor.from({
-                baseMipLevel: i,
-                mipLevelCount: 1,
-                dimension: "2d",
-                baseArrayLayer: 0,
-                arrayLayerCount: 1
-            }));
-
-            this.#do_reduction_pass(encoder, shader_hzb_reduce_any, source_view, destination_view, i);
-
-            // swap
-            source_view = destination_view;
-        }
-    }
-
-    /**
-     *
-     * @param {ShadeGPUCommandContext} encoder
-     * @param {ImageShader} shader
-     * @param {GPUTextureView} source_view
-     * @param {GPUTextureView} destination_view
-     * @param {number} index
-     * @param {number[]} [viewport]
-     */
-    #do_reduction_pass(
-        encoder,
-        shader,
-        source_view,
-        destination_view,
-        index,
-        viewport
-    ) {
-
-        shader.draw({
-            encoder,
-            bindings: {
-                tInput: source_view,
-                output_resolution: this.#mip_resolution(index),
-            },
-            colorAttachments: [
-                {
-                    view: destination_view,
-                    loadOp: 'clear',
-                    storeOp: 'store'
-                }
-            ],
-            viewport
-        })
-
-    }
-
-    /**
-     * Scratch for {@link #mip_resolution}. The value is serialised into the pass's immediate bytes
-     * before the next call, so one array can serve every mip.
-     *
-     * @type {number[]}
-     */
-    #mip_resolution_scratch = [1, 1];
-
-    /**
-     * Size of mip `index` of the HZB, which is what the reduction pass writing into it needs to know.
-     *
-     * Each mip halves the one above it, floored at one texel — the same walk that used to be
-     * precomputed into a uniform buffer of every mip's resolution and bound at a per-mip dynamic
-     * offset. As immediate data there is nothing to precompute into.
-     *
-     * @param {number} index
-     * @returns {number[]}
-     */
-    #mip_resolution(index) {
-        const size = this.#texture.size;
-
-        const out = this.#mip_resolution_scratch;
-
-        out[0] = max2(1, size[0] >>> index);
-        out[1] = max2(1, size[1] >>> index);
-
-        return out;
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     */
-    setViewportSize(x, y) {
-        assert.isNonNegativeInteger(x, 'x');
-        assert.isNonNegativeInteger(y, 'y');
-
-        this.#viewport_size[0] = x;
-        this.#viewport_size[1] = y;
-
-        const hzb_w = Math.max(x >>> 1, 1);
-        const hzb_h = Math.max(y >>> 1, 1);
-
-        this.#resize(hzb_w, hzb_h);
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     */
-    #resize(
-        x,
-        y
-    ) {
-
-        const texture = this.#texture;
-        const size = texture.size;
-
-        if (size[0] === x && size[1] === y) {
-            // no size change
-            return;
-        }
-
-        // a screen-space depth pyramid, 2D always
-        const mip_count = texture_mip_level_count(x, y, 1, "2d");
-
-        texture.descriptor.mipLevelCount = mip_count;
-
-        texture.resize(x, y);
-    }
-
-    destroy() {
-        this.#texture.destroy();
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { max2 } from "../../../core/math/max2.js";
+import { round_up } from "../../../core/math/round_up.js";
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+import { hzb_pick_alignment } from "./hzb_pick_alignment.js";
+import { hzb_plan_reduction_steps } from "./hzb_plan_reduction_steps.js";
+import { HZB_TEXTURE_FORMAT } from "./HZB_TEXTURE_FORMAT.js";
+import { shader_hzb_reduce_any, shader_hzb_reduce_mip0 } from "./shader_hzb_reduce_any.js";
+import { shader_hzb_reduce_mip0_clip } from "./shader_hzb_reduce_mip0_clip.js";
+import { shader_hzb_spd_2, shader_hzb_spd_3, shader_hzb_spd_4 } from "./shader_hzb_spd.js";
+
+/**
+ * @typedef {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
+ * @typedef {import("./hzb_plan_reduction_steps.js").HZBReductionStep} HZBReductionStep
+ */
+
+export class HierarchicalZBuffer {
+
+    /**
+     * @type {GPUTextureContext}
+     */
+    #texture;
+
+    /**
+     * @type {string|GPUTextureFormat}
+     */
+    #format = HZB_TEXTURE_FORMAT
+
+    /**
+     * Precomputed reduction schedule from mip 0 to the 1x1 tail for the current HZB dimensions.
+     * @type {HZBReductionStep[]}
+     */
+    #steps = [];
+
+    /**
+     * Offer the pipelines {@link build} dispatches — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.compute.push(
+            shader_hzb_reduce_mip0.pipeline,
+            shader_hzb_reduce_mip0_clip.pipeline,
+            shader_hzb_reduce_any.pipeline,
+            shader_hzb_spd_2.pipeline,
+            shader_hzb_spd_3.pipeline,
+            shader_hzb_spd_4.pipeline,
+        );
+    }
+
+    /**
+     *
+     * @returns {GPUTextureContext}
+     */
+    get texture() {
+        return this.#texture;
+    }
+
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     *
+     * @type {number[]}
+     */
+    #viewport_size = [1, 1];
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        this.#graphics = graphics;
+
+        this.#texture = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+            label: "Hierarchical Z Buffer",
+            format: this.#format,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            mipLevelCount: 1,
+            size: [1, 1]
+        }));
+
+
+    }
+
+    /**
+     * @param {number} mip
+     * @returns {GPUTextureView}
+     */
+    #obtain_mip_view(mip) {
+        return this.#texture.obtainView(TextureViewDescriptor.from({
+            baseMipLevel: mip,
+            mipLevelCount: 1,
+            dimension: "2d",
+            baseArrayLayer: 0,
+            arrayLayerCount: 1
+        }));
+    }
+
+    /**
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {GPUTextureContext} source
+     * @param {number[]} [source_offset] [x0,y0]
+     */
+    build(
+        encoder,
+        source,
+        source_offset
+    ) {
+
+        assert.defined(encoder, 'encoder');
+        assert.notNull(encoder, 'encoder');
+        assert.equal(encoder.isGPUCommandContext, true, 'encoder is not a GPUCommandContext')
+
+        assert.defined(source, 'source');
+        assert.notNull(source, 'source');
+        assert.equal(source.isGPUTextureContext, true, 'source is not a GPUTextureContext')
+
+        // the first pass is special, we need to read from source texture and write to first mip level of hzb
+
+        const texture = this.#texture;
+
+        assert.equal(texture.isDestroyed, false, 'texture is destroyed');
+
+        let source_view = source.obtainView(TextureViewDescriptor.from({
+            baseMipLevel: 0,
+            mipLevelCount: 1,
+            dimension: "2d",
+            baseArrayLayer: 0,
+            arrayLayerCount: 1
+        }));
+
+        const destination_view = this.#obtain_mip_view(0);
+
+        const viewport_size = this.#viewport_size;
+
+        const is_clipped_variant = source_offset !== undefined
+            && (
+                (
+                    source_offset[0] !== 0
+                    || source_offset[1] !== 0
+                )
+                || (
+                    viewport_size[0] !== source.width
+                    || viewport_size[1] !== source.height
+                )
+            );
+
+        if (is_clipped_variant) {
+            // special case for clip region
+            const mip0_resolution = this.#mip_resolution(0);
+
+            shader_hzb_reduce_mip0_clip.dispatchThreads({
+                encoder,
+                bindings: {
+                    tInput: source_view,
+                    tOutput: destination_view,
+                    settings: {
+                        clip_region: [
+                            source_offset[0], source_offset[1],
+                            viewport_size[0], viewport_size[1],
+                        ],
+                        output_resolution: mip0_resolution,
+                    },
+                },
+                thread_count_x: mip0_resolution[0],
+                thread_count_y: mip0_resolution[1],
+            });
+        } else {
+
+            this.#do_reduction_pass(encoder, shader_hzb_reduce_mip0, source_view, destination_view, 0);
+        }
+
+        source_view = destination_view;
+
+        const steps = this.#steps;
+        const step_count = steps.length;
+
+        for (let s = 0; s < step_count; s++) {
+            const { base_mip, mip_count } = steps[s];
+
+            if (mip_count === 1) {
+                const target_mip = base_mip + 1;
+                const out_view = this.#obtain_mip_view(target_mip);
+
+                this.#do_reduction_pass(encoder, shader_hzb_reduce_any, source_view, out_view, target_mip);
+
+                source_view = out_view;
+            } else {
+                const out1 = this.#obtain_mip_view(base_mip + 1);
+                const out2 = this.#obtain_mip_view(base_mip + 2);
+                const out1_res = this.#mip_resolution(base_mip + 1);
+                const group_count_x = (out1_res[0] + 15) >>> 4;
+                const group_count_y = (out1_res[1] + 15) >>> 4;
+
+                if (mip_count === 2) {
+                    shader_hzb_spd_2.dispatch({
+                        encoder,
+                        bindings: { tInput: source_view, tOut1: out1, tOut2: out2 },
+                        group_count_x,
+                        group_count_y,
+                    });
+                    source_view = out2;
+                } else if (mip_count === 3) {
+                    const out3 = this.#obtain_mip_view(base_mip + 3);
+                    shader_hzb_spd_3.dispatch({
+                        encoder,
+                        bindings: { tInput: source_view, tOut1: out1, tOut2: out2, tOut3: out3 },
+                        group_count_x,
+                        group_count_y,
+                    });
+                    source_view = out3;
+                } else {
+                    const out3 = this.#obtain_mip_view(base_mip + 3);
+                    const out4 = this.#obtain_mip_view(base_mip + 4);
+                    shader_hzb_spd_4.dispatch({
+                        encoder,
+                        bindings: { tInput: source_view, tOut1: out1, tOut2: out2, tOut3: out3, tOut4: out4 },
+                        group_count_x,
+                        group_count_y,
+                    });
+                    source_view = out4;
+                }
+            }
+        }
+    }
+
+    /**
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {ComputeShader} shader
+     * @param {GPUTextureView} source_view
+     * @param {GPUTextureView} destination_view
+     * @param {number} index
+     */
+    #do_reduction_pass(
+        encoder,
+        shader,
+        source_view,
+        destination_view,
+        index
+    ) {
+        const output_resolution = this.#mip_resolution(index);
+
+        shader.dispatchThreads({
+            encoder,
+            bindings: {
+                tInput: source_view,
+                tOutput: destination_view,
+                output_resolution,
+            },
+            thread_count_x: output_resolution[0],
+            thread_count_y: output_resolution[1],
+        });
+
+    }
+
+    /**
+     * Scratch for {@link #mip_resolution}. The value is serialised into the pass's immediate bytes
+     * before the next call, so one array can serve every mip.
+     *
+     * @type {number[]}
+     */
+    #mip_resolution_scratch = [1, 1];
+
+    /**
+     * Size of mip `index` of the HZB, which is what the reduction pass writing into it needs to know.
+     *
+     * Each mip halves the one above it, floored at one texel — the same walk that used to be
+     * precomputed into a uniform buffer of every mip's resolution and bound at a per-mip dynamic
+     * offset. As immediate data there is nothing to precompute into.
+     *
+     * @param {number} index
+     * @returns {number[]}
+     */
+    #mip_resolution(index) {
+        const size = this.#texture.size;
+
+        const out = this.#mip_resolution_scratch;
+
+        out[0] = max2(1, size[0] >>> index);
+        out[1] = max2(1, size[1] >>> index);
+
+        return out;
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     */
+    setViewportSize(x, y) {
+        assert.isNonNegativeInteger(x, 'x');
+        assert.isNonNegativeInteger(y, 'y');
+
+        this.#viewport_size[0] = x;
+        this.#viewport_size[1] = y;
+
+        const base_w = Math.max(x >>> 1, 1);
+        const base_h = Math.max(y >>> 1, 1);
+
+        const [align_w, align_h] = hzb_pick_alignment(x, y, 1.05);
+
+        const hzb_w = round_up(base_w, align_w);
+        const hzb_h = round_up(base_h, align_h);
+
+        this.#resize(hzb_w, hzb_h);
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     */
+    #resize(
+        x,
+        y
+    ) {
+
+        const texture = this.#texture;
+        const size = texture.size;
+
+        if (size[0] === x && size[1] === y) {
+            // no size change
+            return;
+        }
+
+        // a screen-space depth pyramid, 2D always
+        const mip_count = texture_mip_level_count(x, y, 1, "2d");
+
+        texture.descriptor.mipLevelCount = mip_count;
+
+        texture.resize(x, y);
+
+        this.#steps = hzb_plan_reduction_steps(x, y);
+    }
+
+    destroy() {
+        this.#texture.destroy();
+    }
+}

package/src/shade/renderer/hiz/generate_downsampler_code.d.ts

@@ -1,7 +1,5 @@
 /**
  * Idea is to down-sample any kind of texture.
- * Somewhat inspired by AMD's FSR single-pass-downsampler.
- * At present, it is impossible to implement a single-pass downsampler in WebGPU, because you can't bind multiple mips of a storage texture in compute shader.
  *
  * @example
  *  const min = generate_downsampler_code({

package/src/shade/renderer/hiz/generate_downsampler_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate_downsampler_code.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/hiz/generate_downsampler_code.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAN+B,IAAI;IACR,cAAc,EAA9B,MAAM;IACU,aAAa,EAA7B,MAAM;IACgB,YAAY,GAAlC,SAAS,EAAE;IACV,SAAS,CA+EpB;0BAlGyB,iCAAiC"}
+{"version":3,"file":"generate_downsampler_code.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/hiz/generate_downsampler_code.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH;IAN+B,IAAI;IACR,cAAc,EAA9B,MAAM;IACU,aAAa,EAA7B,MAAM;IACgB,YAAY,GAAlC,SAAS,EAAE;IACV,SAAS,CAgFpB;0BAjGyB,iCAAiC"}