@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,252 @@
+import { assert } from "../../../../core/assert.js";
+import { CONTACT_SHADOW_WAVE_SIZE } from "./CONTACT_SHADOW_WAVE_SIZE.js";
+
+/**
+ * Most dispatches one light needs: two for each quadrant of the screen around the light's position.
+ * @type {number}
+ */
+export const CONTACT_SHADOW_DISPATCH_LIMIT = 8;
+
+/**
+ * Words per dispatch in {@link ContactShadowDispatchList#dispatches}: workgroup counts x, y, z, then
+ * the wave offset x, y in pixels.
+ * @type {number}
+ */
+export const CONTACT_SHADOW_DISPATCH_STRIDE = 5;
+
+/**
+ * Furthest the light's coordinate may sit from the viewport's centre, in pixels: 2^20, where f32
+ * spacing is 1/8 pixel. See {@link ContactShadowDispatchList#build}.
+ * @type {number}
+ */
+export const CONTACT_SHADOW_LIGHT_DISTANCE_LIMIT = 2 ** 20;
+
+/**
+ * The compute dispatches that cover a viewport with wavefronts converging on one light's position on
+ * screen, and the light coordinate every one of them is handed.
+ *
+ * A port of Bend Studio's `Bend::BuildDispatchList` (`bend_sss_cpu.h`, Sony Interactive Entertainment,
+ * Apache 2.0). The screen is split into the four quadrants around the light; each is a stack of square
+ * rings of {@link CONTACT_SHADOW_WAVE_SIZE} pixels, and a quadrant whose rectangle is not square is split
+ * along the diagonal through the light into a second dispatch. One to two dispatches when the light is
+ * off screen, up to eight when it is on it.
+ *
+ * Built on the CPU because the counts depend on where the light lands on screen, which is a function
+ * of the camera and the light the CPU already holds; the dispatches are sized by the viewport, not by
+ * any capacity. Rebuilding writes into the same arrays, so a frame allocates nothing.
+ */
+export class ContactShadowDispatchList {
+    /**
+     * What the shader calls `light_coordinate`: the light's position in pixels (x, y), its device depth,
+     * and +1 when it is in front of the camera (the rays march toward it), −1 when it is behind (they
+     * march away from the point it projects to).
+     *
+     * @type {Float32Array}
+     */
+    light_coordinate = new Float32Array(4);
+
+    /**
+     * {@link CONTACT_SHADOW_DISPATCH_STRIDE} words per dispatch: workgroups x, y, z, wave offset x, y.
+     *
+     * @type {Int32Array}
+     */
+    dispatches = new Int32Array(CONTACT_SHADOW_DISPATCH_LIMIT * CONTACT_SHADOW_DISPATCH_STRIDE);
+
+    /**
+     * Dispatches in use, from the front of {@link dispatches}.
+     *
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * @param {number} index
+     * @param {number} offset word within the dispatch
+     * @returns {number}
+     */
+    #word(index, offset) {
+        return this.dispatches[index * CONTACT_SHADOW_DISPATCH_STRIDE + offset];
+    }
+
+    /**
+     * @param {number} index
+     * @param {number} offset
+     * @param {number} value
+     */
+    #set(index, offset, value) {
+        this.dispatches[index * CONTACT_SHADOW_DISPATCH_STRIDE + offset] = value;
+    }
+
+    /**
+     * @param {number} to
+     * @param {number} from
+     */
+    #copy(to, from) {
+        const words = this.dispatches;
+
+        words.copyWithin(
+            to * CONTACT_SHADOW_DISPATCH_STRIDE,
+            from * CONTACT_SHADOW_DISPATCH_STRIDE,
+            (from + 1) * CONTACT_SHADOW_DISPATCH_STRIDE
+        );
+    }
+
+    /**
+     * Cover the whole viewport for a light.
+     *
+     * @param {ArrayLike<number>} light_projection the light through the view-projection matrix, before
+     *        the divide: `(position, 1)` for a point light, `(direction toward the light, 0)` for a
+     *        directional one
+     * @param {number} width viewport, in pixels
+     * @param {number} height viewport, in pixels
+     */
+    build(light_projection, width, height) {
+        assert.isNonNegativeInteger(width, 'width');
+        assert.isNonNegativeInteger(height, 'height');
+
+        const wave_size = CONTACT_SHADOW_WAVE_SIZE;
+
+        /*
+         The divide loses precision for a light a million pixels off screen; Bend clamps w away from
+         zero by this much rather than let x/w and y/w blow up.
+        */
+        const fp_limit = 0.000002 * wave_size;
+
+        let xy_light_w = light_projection[3];
+
+        if (xy_light_w >= 0 && xy_light_w < fp_limit) {
+            xy_light_w = fp_limit;
+        } else if (xy_light_w < 0 && xy_light_w > -fp_limit) {
+            xy_light_w = -fp_limit;
+        }
+
+        const coordinate = this.light_coordinate;
+
+        coordinate[0] = ((light_projection[0] / xy_light_w) * 0.5 + 0.5) * width;
+        coordinate[1] = ((light_projection[1] / xy_light_w) * -0.5 + 0.5) * height;
+        coordinate[2] = light_projection[3] === 0 ? 0 : light_projection[2] / light_projection[3];
+        coordinate[3] = light_projection[3] > 0 ? 1 : -1;
+
+        /*
+         The shader forms each ray from the light's coordinate and a ring position next to it, both in
+         f32. A light just short of Bend's w clamp still lands millions of pixels out, where f32 spaces
+         its values a pixel or more apart and the rays' pixels drift by whole pixels: the spec saw rows
+         left unwritten at 9e6 px. Pulled in along the same line to where the spacing is 1/8 px, the
+         rays turn by at most the viewport's width over that distance — under 0.1° at 1600 px.
+        */
+        const centre_x = width * 0.5;
+        const centre_y = height * 0.5;
+        const offset_x = coordinate[0] - centre_x;
+        const offset_y = coordinate[1] - centre_y;
+        const offset = Math.hypot(offset_x, offset_y);
+
+        if (offset > CONTACT_SHADOW_LIGHT_DISTANCE_LIMIT) {
+            const scale = CONTACT_SHADOW_LIGHT_DISTANCE_LIMIT / offset;
+
+            coordinate[0] = centre_x + offset_x * scale;
+            coordinate[1] = centre_y + offset_y * scale;
+        }
+
+        // C++'s (int)(x + 0.5f), which truncates toward zero
+        const light_x = Math.trunc(coordinate[0] + 0.5);
+        const light_y = Math.trunc(coordinate[1] + 0.5);
+
+        // the viewport, inclusive, relative to the light, y up
+        const biased_0 = 0 - light_x;
+        const biased_1 = -(height - light_y);
+        const biased_2 = width - light_x;
+        const biased_3 = -(0 - light_y);
+
+        this.count = 0;
+
+        // quadrants: 0 bottom left, 1 bottom right, 2 top left, 3 top right
+        for (let q = 0; q < 4; q++) {
+            // quadrants 0 and 3 take one wave more vertically, 1 and 2 one more horizontally
+            const vertical = q === 0 || q === 3;
+
+            const bounds_0 = Math.trunc(Math.max(0, (q & 1) ? biased_0 : -biased_2) / wave_size);
+            const bounds_1 = Math.trunc(Math.max(0, (q & 2) ? biased_1 : -biased_3) / wave_size);
+            const bounds_2 = Math.trunc(Math.max(0, ((q & 1) ? biased_2 : -biased_0) + wave_size * (vertical ? 1 : 2) - 1) / wave_size);
+            const bounds_3 = Math.trunc(Math.max(0, ((q & 2) ? biased_3 : -biased_1) + wave_size * (vertical ? 2 : 1) - 1) / wave_size);
+
+            if (bounds_2 - bounds_0 <= 0 || bounds_3 - bounds_1 <= 0) {
+                continue;
+            }
+
+            const bias_x = (q === 2 || q === 3) ? 1 : 0;
+            const bias_y = (q === 1 || q === 3) ? 1 : 0;
+
+            const first = this.count++;
+
+            this.#set(first, 0, wave_size);
+            this.#set(first, 1, bounds_2 - bounds_0);
+            this.#set(first, 2, bounds_3 - bounds_1);
+            this.#set(first, 3, ((q & 1) ? bounds_0 : -bounds_2) + bias_x);
+            this.#set(first, 4, ((q & 2) ? -bounds_3 : bounds_1) + bias_y);
+
+            // the quadrant's far corner relative to the light: where the diagonal ray leaves the viewport
+            let axis_delta = biased_0 - biased_1;
+
+            if (q === 1) {
+                axis_delta = biased_2 + biased_1;
+            } else if (q === 2) {
+                axis_delta = -biased_0 - biased_3;
+            } else if (q === 3) {
+                axis_delta = -biased_2 + biased_3;
+            }
+
+            axis_delta = Math.trunc((axis_delta + wave_size - 1) / wave_size);
+
+            if (axis_delta <= 0) {
+                continue;
+            }
+
+            const second = this.count++;
+
+            this.#copy(second, first);
+
+            if (q === 0) {
+                // split on y; the split is one larger in x
+                this.#set(second, 2, Math.min(this.#word(first, 2), axis_delta));
+                this.#set(first, 2, this.#word(first, 2) - this.#word(second, 2));
+                this.#set(second, 4, this.#word(first, 4) + this.#word(first, 2));
+                this.#set(second, 3, this.#word(second, 3) - 1);
+                this.#set(second, 1, this.#word(second, 1) + 1);
+            } else if (q === 1) {
+                // split on x; the split is one larger in y
+                this.#set(second, 1, Math.min(this.#word(first, 1), axis_delta));
+                this.#set(first, 1, this.#word(first, 1) - this.#word(second, 1));
+                this.#set(second, 3, this.#word(first, 3) + this.#word(first, 1));
+                this.#set(second, 2, this.#word(second, 2) + 1);
+            } else if (q === 2) {
+                // split on x; the split is one larger in y, one lower
+                this.#set(second, 1, Math.min(this.#word(first, 1), axis_delta));
+                this.#set(first, 1, this.#word(first, 1) - this.#word(second, 1));
+                this.#set(first, 3, this.#word(first, 3) + this.#word(second, 1));
+                this.#set(second, 2, this.#word(second, 2) + 1);
+                this.#set(second, 4, this.#word(second, 4) - 1);
+            } else {
+                // split on y; the split is one larger in x
+                this.#set(second, 2, Math.min(this.#word(first, 2), axis_delta));
+                this.#set(first, 2, this.#word(first, 2) - this.#word(second, 2));
+                this.#set(first, 4, this.#word(first, 4) + this.#word(second, 2));
+                this.#set(second, 1, this.#word(second, 1) + 1);
+            }
+
+            // either half may have come out empty; the list's last entry takes its place
+            if (this.#word(second, 1) <= 0 || this.#word(second, 2) <= 0) {
+                this.#copy(second, --this.count);
+            }
+
+            if (this.#word(first, 1) <= 0 || this.#word(first, 2) <= 0) {
+                this.#copy(first, --this.count);
+            }
+        }
+
+        // the shader takes the offsets in pixels
+        for (let i = 0; i < this.count; i++) {
+            this.#set(i, 3, this.#word(i, 3) * wave_size);
+            this.#set(i, 4, this.#word(i, 4) * wave_size);
+        }
+    }
+}