@woosh/meep-engine 3.47.0 → 3.50.0

package/src/shade/renderer/shader/resource/ShaderResourceGroupDescriptor.js

@@ -2,13 +2,6 @@ import { assert } from "../../../../core/assert.js";
 import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
 import { string_compute_similarity } from "../../../../core/primitives/strings/string_compute_similarity.js";
 import { BindGroupLayoutDescriptor } from "../../../descriptor/binding/BindGroupLayoutDescriptor.js";
-import { BufferBindingLayout } from "../../../descriptor/binding/BufferBindingLayout.js";
-import { SamplerBindingLayout } from "../../../descriptor/binding/SamplerBindingLayout.js";
-import { StorageTextureBindingLayout } from "../../../descriptor/binding/StorageTextureBindingLayout.js";
-import { TextureBindingLayout } from "../../../descriptor/binding/TextureBindingLayout.js";
-import { parse_wgsl_type } from "../type/parse_wgsl_type.js";
-import { write_gpu_typed_buffer } from "../type/serde/write_gpu_typed_buffer.js";
-import { type_has_atomics } from "../type/type_has_atomics.js";
 import { ResourceType } from "./ResourceType.js";
 import { RX_VALID_NAME } from "./RX_VALID_NAME.js";
 import { ShaderResourceDescriptor } from "./ShaderResourceDescriptor.js";
@@ -83,6 +76,14 @@ export class ShaderResourceGroupDescriptor {
                 // binding is not present, check defaults
                 binding_value = resource.default_value;
 
+                if (binding_value === undefined && resource.transient_default) {
+                    // not an assert: binding by hand, there is nothing to fall back to
+                    throw new Error(
+                        `Storage buffer '${resource.name}' has a transient default, which only a frame graph pass`
+                        + ` can bind; generateBindings needs a buffer for it`
+                    );
+                }
+
                 if (binding_value === undefined) {
 
                     // format inputs for error
@@ -359,33 +360,19 @@ export class ShaderResourceGroupDescriptor {
     }
 
     /**
+     * Place `declaration` in this group, at the first free binding index. The group holds a copy, so
+     * the one declaration, exported beside the data it describes, can be placed in any number of groups.
      *
-     * @param {string} name
-     * @param {WebGPUType|string} type
-     * @returns {ShaderResourceDescriptor}
+     * @param {ShaderResourceDescriptor} declaration see {@link ShaderResourceDescriptor.uniform} and its siblings
+     * @returns {this}
      */
-    #createBuffer(name, type) {
-        assert.isString(name, 'name');
-        assert.defined(type, 'type');
-
-        const resource = new ShaderResourceDescriptor();
-
-        resource.name = name;
-        resource.type = ResourceType.Buffer;
+    add(declaration) {
+        assert.defined(declaration, 'declaration');
+        assert.equal(declaration.isShaderResourceDescriptor, true, 'declaration.isShaderResourceDescriptor !== true');
 
-        let _type = type;
+        this.#add(declaration.clone_declaration());
 
-        if (typeof type === "string") {
-            _type = parse_wgsl_type(type);
-        } else {
-
-            assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
-
-        }
-
-        resource.buffer_type = _type;
-
-        return resource;
+        return this;
     }
 
     /**
@@ -396,38 +383,7 @@ export class ShaderResourceGroupDescriptor {
      * @returns {this}
      */
     addUniform(name, _type, default_value = undefined) {
-        assert.isString(name, 'name');
-
-        let type = _type;
-        if (typeof type === "string") {
-            type = parse_wgsl_type(type);
-        } else {
-            assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
-        }
-
-        if (type.runtime_sized) {
-            // TODO check if this is true, I don't remember exact details from the spec
-            throw new Error(`Uniforms can not use runtime sized structures. Size must be defined ahead of time. name='${name}', type=${type}`);
-        }
-
-        // https://www.w3.org/TR/WGSL/#atomic-type
-        assert.equal(type_has_atomics(type), false, 'atomics are not allowed in uniforms');
-
-        const resource = this.#createBuffer(name, type);
-
-        resource.member_descriptor = BufferBindingLayout.uniform;
-
-        if (default_value !== undefined) {
-
-            const buffer = new ArrayBuffer(type.size);
-
-            write_gpu_typed_buffer(default_value, resource.buffer_type, buffer, 0);
-
-            resource.default_value = buffer;
-
-        }
-
-        this.#add(resource);
+        this.#add(ShaderResourceDescriptor.uniform(name, _type, default_value));
 
         return this;
     }
@@ -437,25 +393,17 @@ export class ShaderResourceGroupDescriptor {
      * @param {string} name
      * @param {WebGPUType} type
      * @param {boolean} [write_enabled]
+     * @param {boolean} [transient_default] when a frame graph pass is given nothing for this binding, it binds
+     *        a transient buffer of the type's minimum binding size in its place. The buffer comes from the
+     *        frame's pool, so its contents are whatever it last held: declare this only for a binding some
+     *        variants of the shader do not read, such as one shader switch value's resource in a union of
+     *        every value's bindings. A pass that binds by hand ({@link generateBindings}) gets no default.
      * @returns {this}
      */
-    addStorageBuffer(name, type, write_enabled = false) {
-        assert.defined(type, 'type');
-        assert.isBoolean(write_enabled, 'write_enabled');
-        assert.isObject(type, 'type');
-        assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
-
-        // https://www.w3.org/TR/WGSL/#atomic-type
-        assert.equal(type_has_atomics(type) && !write_enabled, false, 'atomics are only allowed in write-access mode');
-
-        const resource = this.#createBuffer(name, type);
-
-        resource.member_descriptor = write_enabled ? BufferBindingLayout.storage : BufferBindingLayout.readOnlyStorage;
-
-        this.#add(resource);
+    addStorageBuffer(name, type, write_enabled = false, transient_default = false) {
+        this.#add(ShaderResourceDescriptor.storageBuffer(name, type, write_enabled, transient_default));
 
         return this;
-
     }
 
     /**
@@ -474,41 +422,7 @@ export class ShaderResourceGroupDescriptor {
         multisampled = false,
         default_value = undefined,
     ) {
-        assert.isString(name, 'name');
-        assert.isOneOf(type, [
-            "unfilterable-float",
-            "float",
-            "sint",
-            "uint",
-            "depth"
-        ], 'type');
-
-        assert.isOneOf(dimension, [
-            "1d",
-            "2d",
-            "2d-array",
-            "cube",
-            "cube-array",
-            "3d"
-        ], "dimension");
-
-        const resource = new ShaderResourceDescriptor();
-
-        resource.name = name;
-        resource.type = ResourceType.Texture;
-        resource.member_descriptor = TextureBindingLayout.fromJSON({
-            sampleType: type,
-            viewDimension: dimension,
-            multisampled
-        });
-
-        if (default_value !== undefined) {
-            assert.equal(default_value.isShadeTexture, true, 'default_value.isShadeTexture !== true');
-
-            resource.default_value = default_value;
-        }
-
-        this.#add(resource);
+        this.#add(ShaderResourceDescriptor.texture(name, type, dimension, multisampled, default_value));
 
         return this;
     }
@@ -527,21 +441,7 @@ export class ShaderResourceGroupDescriptor {
         dimension,
         access
     ) {
-
-        assert.isString(name, 'name');
-
-        const resource = new ShaderResourceDescriptor();
-
-        resource.name = name;
-        resource.type = ResourceType.StorageTexture;
-
-        resource.member_descriptor = StorageTextureBindingLayout.fromJSON({
-            format,
-            access,
-            viewDimension: dimension
-        });
-
-        this.#add(resource);
+        this.#add(ShaderResourceDescriptor.storageTexture(name, format, dimension, access));
 
         return this;
     }
@@ -554,29 +454,7 @@ export class ShaderResourceGroupDescriptor {
      * @returns {ShaderResourceGroupDescriptor}
      */
     addSampler(name, type = "filtering", default_value = undefined) {
-        assert.isString(name, 'name');
-        assert.isOneOf(type, ["filtering", "non-filtering", "comparison"])
-
-
-        const resource = new ShaderResourceDescriptor();
-
-        resource.name = name;
-        resource.type = ResourceType.Sampler;
-
-        resource.member_descriptor = SamplerBindingLayout.fromJSON({
-            type
-        });
-
-        if (default_value !== undefined) {
-            assert.isObject(default_value, 'default_value');
-            assert.equal(default_value.isSamplerDescriptor, true, 'default_value.isSamplerDescriptor !== true');
-
-            // TODO validate that type matches
-
-            resource.default_value = default_value;
-        }
-
-        this.#add(resource);
+        this.#add(ShaderResourceDescriptor.sampler(name, type, default_value));
 
         return this;
     }

package/src/shade/renderer/shader/resource/encoder_prepare_shader_bindings_defaults.d.ts

@@ -1,6 +1,11 @@
 /**
  * Given a set of bindings (the target), fill out the rest with defaults where applicable
  * Make sure that you run this at the end, once all the other bindings have been assigned
+ *
+ * A storage buffer declared with a transient default gets a transient buffer of its type's minimum
+ * binding size from the frame's pool, contents undefined; see
+ * {@link ShaderResourceGroupDescriptor#addStorageBuffer}.
+ *
  * @param {Object} target
  * @param {GraphicsExecutionContext} context
  * @param {ShaderResourceSetDescriptor} resources

package/src/shade/renderer/shader/resource/encoder_prepare_shader_bindings_defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoder_prepare_shader_bindings_defaults.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/encoder_prepare_shader_bindings_defaults.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,uJA0BC"}
+{"version":3,"file":"encoder_prepare_shader_bindings_defaults.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/encoder_prepare_shader_bindings_defaults.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,uJA+BC"}

package/src/shade/renderer/shader/resource/encoder_prepare_shader_bindings_defaults.js

@@ -3,6 +3,11 @@ import { encoder_prepare_shader_binding } from "./encoder_prepare_shader_binding
 /**
  * Given a set of bindings (the target), fill out the rest with defaults where applicable
  * Make sure that you run this at the end, once all the other bindings have been assigned
+ *
+ * A storage buffer declared with a transient default gets a transient buffer of its type's minimum
+ * binding size from the frame's pool, contents undefined; see
+ * {@link ShaderResourceGroupDescriptor#addStorageBuffer}.
+ *
  * @param {Object} target
  * @param {GraphicsExecutionContext} context
  * @param {ShaderResourceSetDescriptor} resources
@@ -30,7 +35,12 @@ export function encoder_prepare_shader_bindings_defaults(target, context, resour
                 const binding = encoder_prepare_shader_binding(context, resource.default_value, resource);
 
                 target[resource_name] = binding;
+            } else if (resource.transient_default) {
+                target[resource_name] = context.encoder.allocateTransientBuffer(
+                    GPUBufferUsage.STORAGE,
+                    resource.buffer_type.aligned_size
+                );
             }
         }
     }
-}
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Threads in one workgroup of the screen-space contact shadow pass, and the pixels one workgroup
+ * walks along a single ray toward the light's position on screen. The threads of a workgroup sit
+ * one pixel apart on that ray, so each thread's samples are its neighbours' depth reads, shared
+ * through workgroup memory rather than read again.
+ *
+ * 64 is Bend Studio's: the only width their released code was tested with. It does not depend on
+ * the subgroup size (on the 4090 it is two 32-wide subgroups), because the sharing goes through
+ * workgroup memory behind a barrier.
+ *
+ * @type {number}
+ */
+export const CONTACT_SHADOW_WAVE_SIZE: number;
+//# sourceMappingURL=CONTACT_SHADOW_WAVE_SIZE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CONTACT_SHADOW_WAVE_SIZE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/CONTACT_SHADOW_WAVE_SIZE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,uCAFU,MAAM,CAE2B"}

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

@@ -0,0 +1,13 @@
+/**
+ * Threads in one workgroup of the screen-space contact shadow pass, and the pixels one workgroup
+ * walks along a single ray toward the light's position on screen. The threads of a workgroup sit
+ * one pixel apart on that ray, so each thread's samples are its neighbours' depth reads, shared
+ * through workgroup memory rather than read again.
+ *
+ * 64 is Bend Studio's: the only width their released code was tested with. It does not depend on
+ * the subgroup size (on the 4090 it is two 32-wide subgroups), because the sharing goes through
+ * workgroup memory behind a barrier.
+ *
+ * @type {number}
+ */
+export const CONTACT_SHADOW_WAVE_SIZE = 64;

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

@@ -0,0 +1,65 @@
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * 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: number;
+/**
+ * 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: Float32Array;
+    /**
+     * {@link CONTACT_SHADOW_DISPATCH_STRIDE} words per dispatch: workgroups x, y, z, wave offset x, y.
+     *
+     * @type {Int32Array}
+     */
+    dispatches: Int32Array;
+    /**
+     * Dispatches in use, from the front of {@link dispatches}.
+     *
+     * @type {number}
+     */
+    count: number;
+    /**
+     * 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: ArrayLike<number>, width: number, height: number): void;
+    #private;
+}
+//# sourceMappingURL=ContactShadowDispatchList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ContactShadowDispatchList.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/contact/ContactShadowDispatchList.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;GAIG;AACH,kDAFU,MAAM,CAE2C;AAE3D;;;;;;;;;;;;;GAaG;AACH;IACI;;;;;;OAMG;IACH,kBAFU,YAAY,CAEiB;IAEvC;;;;OAIG;IACH,YAFU,UAAU,CAEwE;IAE5F;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAkCV;;;;;;;;OAQG;IACH,wBANW,UAAU,MAAM,CAAC,SAGjB,MAAM,UACN,MAAM,QAsJhB;;CACJ"}

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);
+        }
+    }
+}