@woosh/meep-engine 3.43.0 → 3.44.0

package/src/shade/renderer/geometry/primitives/make_cone_geometry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @typedef {import("../Geometry.js").Geometry} Geometry
+ */
+/**
+ * The axis runs along Y with the apex at the top, and the body is centred on the origin.
+ *
+ * A cone is a cylinder whose top radius is zero, exactly as three's `ConeGeometry` is, so this is
+ * {@link make_cylinder_geometry} under its own name; the apex handling lives there.
+ *
+ * @param {number} [radius] radius of the base
+ * @param {number} [height]
+ * @param {number} [radialSegments] segments around the axis
+ * @param {number} [heightSegments] segments along the axis
+ * @param {boolean} [openEnded] leave the base off, which makes the surface a hollow shell rather than a solid
+ * @param {number} [thetaStart]
+ * @param {number} [thetaLength] how much of the turn to build, in radians
+ * @returns {Geometry}
+ */
+export function make_cone_geometry(radius?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number): Geometry;
+export type Geometry = import("../Geometry.js").Geometry;
+//# sourceMappingURL=make_cone_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_cone_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_cone_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cone_geometry.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,4CATW,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CAgBpB;uBAhCY,OAAO,gBAAgB,EAAE,QAAQ"}

package/src/shade/renderer/geometry/primitives/make_cone_geometry.js

@@ -0,0 +1,36 @@
+import { make_cylinder_geometry } from "./make_cylinder_geometry.js";
+
+/**
+ * @typedef {import("../Geometry.js").Geometry} Geometry
+ */
+
+/**
+ * The axis runs along Y with the apex at the top, and the body is centred on the origin.
+ *
+ * A cone is a cylinder whose top radius is zero, exactly as three's `ConeGeometry` is, so this is
+ * {@link make_cylinder_geometry} under its own name; the apex handling lives there.
+ *
+ * @param {number} [radius] radius of the base
+ * @param {number} [height]
+ * @param {number} [radialSegments] segments around the axis
+ * @param {number} [heightSegments] segments along the axis
+ * @param {boolean} [openEnded] leave the base off, which makes the surface a hollow shell rather than a solid
+ * @param {number} [thetaStart]
+ * @param {number} [thetaLength] how much of the turn to build, in radians
+ * @returns {Geometry}
+ */
+export function make_cone_geometry(
+    radius = 1,
+    height = 1,
+    radialSegments = 8,
+    heightSegments = 1,
+    openEnded = false,
+    thetaStart = 0,
+    thetaLength = Math.PI * 2
+) {
+    const geo = make_cylinder_geometry(0, radius, height, radialSegments, heightSegments, openEnded, thetaStart, thetaLength);
+
+    geo.name = "Cone";
+
+    return geo;
+}

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.d.ts

@@ -4,7 +4,7 @@
  * `Geometry` carries no multi-material groups, so the torso and the two caps are one index run
  * rather than three; three's cylinder splits them only to address a material array.
  *
- * @param {number} [radiusTop]
+ * @param {number} [radiusTop] zero makes a cone, which is what `make_cone_geometry` does
  * @param {number} [radiusBottom]
  * @param {number} [height]
  * @param {number} [radialSegments] segments around the axis

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_cylinder_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cylinder_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,mDAVW,MAAM,iBACN,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CA6NpB;yBA9OwB,gBAAgB"}
+{"version":3,"file":"make_cylinder_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_cylinder_geometry.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,mDAVW,MAAM,iBACN,MAAM,WACN,MAAM,mBACN,MAAM,mBACN,MAAM,cACN,OAAO,eACP,MAAM,gBACN,MAAM,GACJ,QAAQ,CAgQpB;yBAjRwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_cylinder_geometry.js

@@ -8,7 +8,7 @@ import { StandardAttributes } from "../StandardAttributes.js";
  * `Geometry` carries no multi-material groups, so the torso and the two caps are one index run
  * rather than three; three's cylinder splits them only to address a material array.
  *
- * @param {number} [radiusTop]
+ * @param {number} [radiusTop] zero makes a cone, which is what `make_cone_geometry` does
  * @param {number} [radiusBottom]
  * @param {number} [height]
  * @param {number} [radialSegments] segments around the axis
@@ -31,7 +31,8 @@ export function make_cylinder_geometry(
 
     /*
      A port of three's `CylinderGeometry` onto `Geometry`: the same parameterisation and the same
-     winding, writing meep attributes instead of three ones.
+     winding, writing meep attributes instead of three ones. It departs at a cone's apex, see
+     `generateTorso`.
 
      Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
     */
@@ -56,6 +57,7 @@ export function make_cylinder_geometry(
 
     let index = 0;
     const indexArray = [];
+    const apexRows = [];
     const halfHeight = height / 2;
 
     // generate geometry
@@ -98,9 +100,21 @@ export function make_cylinder_geometry(
 
             const radius = v * (radiusBottom - radiusTop) + radiusTop;
 
-            for (let x = 0; x <= radialSegments; x++) {
+            // A row of zero radius is a cone's apex, where three's grid would put two corners of
+            // every segment's upper triangle on the same point and lean the other one's apex normal
+            // toward one edge. Instead the apex holds one vertex per segment, turned to the middle of
+            // that segment, and each segment draws just the one triangle that has area. The `u` is
+            // offset the same way, as three's own sphere does at its poles.
+            const apex = radius === 0;
 
-                const u = x / radialSegments;
+            apexRows.push(apex);
+
+            const rowVertexCount = apex ? radialSegments : radialSegments + 1;
+            const uOffset = apex ? 0.5 : 0;
+
+            for (let x = 0; x < rowVertexCount; x++) {
+
+                const u = (x + uOffset) / radialSegments;
 
                 const theta = u * thetaLength + thetaStart;
 
@@ -143,13 +157,34 @@ export function make_cylinder_geometry(
 
                 const a = indexArray[y][x];
                 const b = indexArray[y + 1][x];
-                const c = indexArray[y + 1][x + 1];
-                const d = indexArray[y][x + 1];
 
-                // faces
+                if (apexRows[y] && apexRows[y + 1]) {
+
+                    // both rows on the axis, so the band has no area
+
+                } else if (apexRows[y]) {
+
+                    // `a` is the segment's apex vertex and stands in for `d` as well
+
+                    indices.push(b, indexArray[y + 1][x + 1], a);
+
+                } else if (apexRows[y + 1]) {
+
+                    // `b` is the segment's apex vertex and stands in for `c` as well
+
+                    indices.push(a, b, indexArray[y][x + 1]);
+
+                } else {
+
+                    const c = indexArray[y + 1][x + 1];
+                    const d = indexArray[y][x + 1];
+
+                    // faces
+
+                    indices.push(a, b, d);
+                    indices.push(b, c, d);
 
-                indices.push(a, b, d);
-                indices.push(b, c, d);
+                }
 
             }
 

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A sphere of rings of latitude and meridians of longitude, centred on the origin with its poles on
+ * the Y axis. The texture coordinates are equirectangular: `u` runs once around the axis and `v`
+ * from the south pole (0) to the north pole (1).
+ *
+ * The two angular intervals cut a partial sphere: `phi` turns about the Y axis and `theta` runs
+ * down from the north pole, so a `thetaLength` of `Math.PI / 2` is a dome.
+ *
+ * @param {number} [radius]
+ * @param {number} [widthSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments from pole to pole, at least 2
+ * @param {number} [phiStart]
+ * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+ * @param {number} [thetaStart] where to start, in radians down from the north pole
+ * @param {number} [thetaLength] how far toward the south pole to build, in radians; stops at the pole
+ * @returns {Geometry}
+ */
+export function make_uv_sphere_geometry(radius?: number, widthSegments?: number, heightSegments?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number): Geometry;
+import { Geometry } from "../Geometry.js";
+//# sourceMappingURL=make_uv_sphere_geometry.d.ts.map

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_uv_sphere_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;GAgBG;AACH,iDATW,MAAM,kBACN,MAAM,mBACN,MAAM,aACN,MAAM,cACN,MAAM,eACN,MAAM,gBACN,MAAM,GACJ,QAAQ,CAkKpB;yBA5LwB,gBAAgB"}

package/src/shade/renderer/geometry/primitives/make_uv_sphere_geometry.js

@@ -0,0 +1,190 @@
+import { Attribute } from "../Attribute.js";
+import { Geometry } from "../Geometry.js";
+import { StandardAttributes } from "../StandardAttributes.js";
+
+/**
+ * How far short of `Math.PI`, in radians, a theta interval may end and still close at the south
+ * pole: four ulps of pi, room for the rounding of a sum of two or three rounded angles.
+ *
+ * @type {number}
+ */
+const SOUTH_POLE_TOLERANCE = 8 * Number.EPSILON;
+
+/**
+ * A sphere of rings of latitude and meridians of longitude, centred on the origin with its poles on
+ * the Y axis. The texture coordinates are equirectangular: `u` runs once around the axis and `v`
+ * from the south pole (0) to the north pole (1).
+ *
+ * The two angular intervals cut a partial sphere: `phi` turns about the Y axis and `theta` runs
+ * down from the north pole, so a `thetaLength` of `Math.PI / 2` is a dome.
+ *
+ * @param {number} [radius]
+ * @param {number} [widthSegments] segments around the axis, at least 3
+ * @param {number} [heightSegments] segments from pole to pole, at least 2
+ * @param {number} [phiStart]
+ * @param {number} [phiLength] how much of the turn about the axis to build, in radians
+ * @param {number} [thetaStart] where to start, in radians down from the north pole
+ * @param {number} [thetaLength] how far toward the south pole to build, in radians; stops at the pole
+ * @returns {Geometry}
+ */
+export function make_uv_sphere_geometry(
+    radius = 1,
+    widthSegments = 32,
+    heightSegments = 16,
+    phiStart = 0,
+    phiLength = Math.PI * 2,
+    thetaStart = 0,
+    thetaLength = Math.PI
+) {
+
+    /*
+     A port of three's `SphereGeometry` onto `Geometry`: the same parameterisation and the same
+     winding, writing meep attributes instead of three ones. It departs at the poles, see below.
+
+     Derived from three.js (https://github.com/mrdoob/three.js), Copyright (c) 2010-2024 three.js authors, MIT licence.
+    */
+
+    const geo = new Geometry();
+
+    geo.name = "UVSphere";
+
+    // segments
+
+    widthSegments = Math.max(3, Math.floor(widthSegments));
+    heightSegments = Math.max(2, Math.floor(heightSegments));
+
+    // three clamps only its triangle selection to the south pole; clamping the rows too keeps a
+    // long `thetaLength` from folding the last band back over the sphere
+    let thetaEnd = Math.min(thetaStart + thetaLength, Math.PI);
+
+    // an interval meant to end at the pole is the sum of two rounded angles, and lands short of
+    // `Math.PI` often enough (`Math.PI / 6 + Math.PI / 6 * 5` is an ulp short) that within a few
+    // ulps it is taken to mean the pole
+    if (Math.PI - thetaEnd <= SOUTH_POLE_TOLERANCE) {
+        thetaEnd = Math.PI;
+    }
+
+    // A ring at a pole is a single point. Three's grid still gives it a vertex per meridian, which
+    // puts two corners of every polar triangle on the same point. Here a pole holds one vertex per
+    // segment, turned to the middle of that segment, and each segment draws just the one triangle
+    // that has area. A pole's normal is the axis whichever way it is turned, so only its `u` moves.
+    const northPole = thetaStart === 0;
+    const southPole = thetaEnd === Math.PI;
+
+    // buffers
+
+    const indices = [];
+    const vertices = [];
+    const normals = [];
+    const uvs = [];
+
+    // helper variables
+
+    let index = 0;
+    const grid = [];
+
+    // generate vertices, normals and uvs
+
+    for (let iy = 0; iy <= heightSegments; iy++) {
+
+        const verticesRow = [];
+
+        const v = iy / heightSegments;
+
+        const atNorthPole = iy === 0 && northPole;
+        const atSouthPole = iy === heightSegments && southPole;
+        const pole = atNorthPole || atSouthPole;
+
+        // `Math.sin(Math.PI)` is not zero, so a pole is put on the axis rather than computed onto it
+
+        const theta = thetaStart + v * (thetaEnd - thetaStart);
+
+        const sinTheta = pole ? 0 : Math.sin(theta);
+        const cosTheta = atNorthPole ? 1 : (atSouthPole ? -1 : Math.cos(theta));
+
+        const rowVertexCount = pole ? widthSegments : widthSegments + 1;
+        const uOffset = pole ? 0.5 : 0;
+
+        for (let ix = 0; ix < rowVertexCount; ix++) {
+
+            const u = (ix + uOffset) / widthSegments;
+
+            const phi = phiStart + u * phiLength;
+
+            // normal, the direction from the centre, which is what the vertex is scaled from; taking
+            // it from the angles rather than normalising the vertex keeps it defined at radius zero
+
+            const normal_x = -Math.cos(phi) * sinTheta;
+            const normal_y = cosTheta;
+            const normal_z = Math.sin(phi) * sinTheta;
+
+            normals.push(normal_x, normal_y, normal_z);
+
+            // vertex
+
+            vertices.push(radius * normal_x, radius * normal_y, radius * normal_z);
+
+            // uv
+
+            uvs.push(u, 1 - v);
+
+            verticesRow.push(index++);
+
+        }
+
+        grid.push(verticesRow);
+
+    }
+
+    // indices
+
+    for (let iy = 0; iy < heightSegments; iy++) {
+
+        const upper = grid[iy];
+        const lower = grid[iy + 1];
+
+        // at least two segments from pole to pole, so a band never has a pole on both sides
+        const upperIsPole = iy === 0 && northPole;
+        const lowerIsPole = iy + 1 === heightSegments && southPole;
+
+        for (let ix = 0; ix < widthSegments; ix++) {
+
+            if (upperIsPole) {
+
+                // the segment's pole vertex stands in for both upper corners
+
+                indices.push(upper[ix], lower[ix], lower[ix + 1]);
+
+            } else if (lowerIsPole) {
+
+                // the segment's pole vertex stands in for both lower corners
+
+                indices.push(upper[ix + 1], upper[ix], lower[ix]);
+
+            } else {
+
+                const a = upper[ix + 1];
+                const b = upper[ix];
+                const c = lower[ix];
+                const d = lower[ix + 1];
+
+                // faces
+
+                indices.push(a, b, d);
+                indices.push(b, c, d);
+
+            }
+
+        }
+
+    }
+
+    // build geometry
+
+    geo.index = Attribute.from(new Uint32Array(indices), 1, 'index');
+    geo.addAttribute(Attribute.from(new Float32Array(vertices), 3, StandardAttributes.Position));
+    geo.addAttribute(Attribute.from(new Float32Array(normals), 3, StandardAttributes.Normal));
+    geo.addAttribute(Attribute.from(new Float32Array(uvs), 2, StandardAttributes.TextureCoordinates0));
+
+    return geo;
+}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_vgeo_expand_instances_to_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAX+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACO,OAAO;IACb,MAAM;IACjC,MAAM,CA4TlB"}
+{"version":3,"file":"graph_vgeo_expand_instances_to_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAX+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACO,OAAO;IACb,MAAM;IACjC,MAAM,CA6TlB"}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js

@@ -5,8 +5,12 @@ import {
     graph_build_indirect_dispatch_command,
     INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
 } from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
-import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
 import { RasterizationCollectionType } from "../../../rasterize/expand/RasterizationCollectionType.js";
+import { graph_create_buffer } from "../../../shader/graph/graph_create_buffer.js";
 import { shader_vgeo_cut_collect } from "./cut/shader_vgeo_cut_collect.js";
 import { shader_vgeo_cut_queue_prepare } from "./cut/shader_vgeo_cut_queue_prepare.js";
 import { shader_vgeo_cut_queue_remainder } from "./cut/shader_vgeo_cut_queue_remainder.js";
@@ -186,7 +190,8 @@ export function graph_vgeo_expand_instances_to_meshlets({
      */
     const prefix_sums = graph_prefix_scan_csdldf({
         graph,
-        data: collect_data.claim_widths,
+        input: collect_data.claim_widths,
+        output: graph_create_buffer(graph, "vg claim offsets", prefix_scan_csdldf_output_descriptor(instance_capacity)),
         element_max_count: instance_capacity,
     });
 

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.d.ts

@@ -1,25 +1,43 @@
+/**
+ * A transient {@link graph_prefix_scan_csdldf} output for up to `element_max_count` elements: the count, padded to 16
+ * bytes, then the sums in whole vec4 blocks. The scan writes the count itself, so nothing needs clearing.
+ *
+ * @param {number} element_max_count
+ * @returns {BufferResourceDescriptor}
+ */
+export function prefix_scan_csdldf_output_descriptor(element_max_count: number): BufferResourceDescriptor;
 /**
  * Indirect pass.
- * Input data is expected to be counts in form:
+ * Inclusive prefix sums of `input` into `output`.
+ * Both are expected in the form:
  * ```wgsl
  *  struct InputData{
  *     count:u32,
  *     elements: array<u32> // counts: [count0, count1, count2, ... countN-1]
  *  }
  * ```
- * Data is modified in-place, elements are replaced with prefix sums.
- * Make sure to set `element_max_count` to be at least equal to the number of elements in the input, otherwise an incomplete scan will be performed.
- * The penalty for `element_max_count` being too big is fairly small, requiring more memory for the pass and a larger `bufferClear` region.
+ * `output` receives the input's count and, for each of its elements, the sum of the elements up to and including it.
+ * `input` is never written: the scan's fallback re-reads a tile's inputs while other tiles are writing their sums, so
+ * the two cannot be one buffer.
+ *
+ * The work follows the input's count, read on the device; `element_max_count` sizes only the memory — the spine, and
+ * what `output` must hold — so make it at least the most elements the input can carry, otherwise an incomplete scan will
+ * be performed. Where a count records demand and runs past a soft limit — a culled collection does — that is what the
+ * buffer holds, not the limit. The penalty for `element_max_count` being too big is fairly small: a larger spine to clear.
  *
  * @param {Object} options
  * @param {FrameGraph} options.graph
- * @param {number} options.data buffer resource ID, array<u32> first position must be "count". The buffer must be 16-byte aligned.
+ * @param {number} options.input buffer resource ID, array<u32> first position must be "count". The buffer must be 16-byte aligned.
+ * @param {number} options.output buffer resource ID of the same layout, at least `16 + ⌈element_max_count / 4⌉ · 16` bytes;
+ * see {@link prefix_scan_csdldf_output_descriptor}
  * @param {number} [options.element_max_count=1,048,576] how many elements might be in the input, this is a limit
- * @returns {number} buffer resource ID with prefix sums, this is rewritten input. The first position (count) is untouched.
+ * @returns {number} buffer resource ID of the written output
  */
-export function graph_prefix_scan_csdldf({ graph, data, element_max_count, }: {
+export function graph_prefix_scan_csdldf({ graph, input, output, element_max_count, }: {
     graph: FrameGraph;
-    data: number;
+    input: number;
+    output: number;
     element_max_count?: number;
 }): number;
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
 //# sourceMappingURL=graph_prefix_scan_csdldf.d.ts.map

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAL+B,KAAK;IACT,IAAI,EAApB,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACJ,MAAM,CAgFlB"}
+{"version":3,"file":"graph_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,wEAHW,MAAM,GACJ,wBAAwB,CAMpC;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAP+B,KAAK;IACT,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IAEW,iBAAiB,GAAlC,MAAM;IACJ,MAAM,CAwElB;yCA3HwC,sDAAsD"}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js

@@ -3,51 +3,74 @@ import { round_up } from "../../../../../core/math/round_up.js";
 import { warn_limited } from "../../../../util/warn_limited.js";
 import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
 import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../../indirect/IndirectComputeCommandBuildPass.js";
 import {
-    build_indirect_compute_dispatch_command,
-    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
-} from "../../indirect/IndirectComputeCommandBuildPass.js";
-import { PREFIX_SCAN_CSDLDF_PARTITION_SIZE, shader_prefix_scan_csdldf } from "./shader_prefix_scan_csdldf.js";
+    WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION
+} from "../../indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import {
+    PREFIX_SCAN_CSDLDF_PARTITION_SIZE,
+    shader_prefix_scan_csdldf,
+    shader_prefix_scan_csdldf_prepare
+} from "./shader_prefix_scan_csdldf.js";
+
+/**
+ * A transient {@link graph_prefix_scan_csdldf} output for up to `element_max_count` elements: the count, padded to 16
+ * bytes, then the sums in whole vec4 blocks. The scan writes the count itself, so nothing needs clearing.
+ *
+ * @param {number} element_max_count
+ * @returns {BufferResourceDescriptor}
+ */
+export function prefix_scan_csdldf_output_descriptor(element_max_count) {
+    assert.isNonNegativeInteger(element_max_count, 'element_max_count');
+
+    return BufferResourceDescriptor.from(16 + Math.max(1, Math.ceil(element_max_count / 4)) * 16, GPUBufferUsage.STORAGE);
+}
 
 
 /**
  * Indirect pass.
- * Input data is expected to be counts in form:
+ * Inclusive prefix sums of `input` into `output`.
+ * Both are expected in the form:
  * ```wgsl
  *  struct InputData{
  *     count:u32,
  *     elements: array<u32> // counts: [count0, count1, count2, ... countN-1]
  *  }
  * ```
- * Data is modified in-place, elements are replaced with prefix sums.
- * Make sure to set `element_max_count` to be at least equal to the number of elements in the input, otherwise an incomplete scan will be performed.
- * The penalty for `element_max_count` being too big is fairly small, requiring more memory for the pass and a larger `bufferClear` region.
+ * `output` receives the input's count and, for each of its elements, the sum of the elements up to and including it.
+ * `input` is never written: the scan's fallback re-reads a tile's inputs while other tiles are writing their sums, so
+ * the two cannot be one buffer.
+ *
+ * The work follows the input's count, read on the device; `element_max_count` sizes only the memory — the spine, and
+ * what `output` must hold — so make it at least the most elements the input can carry, otherwise an incomplete scan will
+ * be performed. Where a count records demand and runs past a soft limit — a culled collection does — that is what the
+ * buffer holds, not the limit. The penalty for `element_max_count` being too big is fairly small: a larger spine to clear.
  *
  * @param {Object} options
  * @param {FrameGraph} options.graph
- * @param {number} options.data buffer resource ID, array<u32> first position must be "count". The buffer must be 16-byte aligned.
+ * @param {number} options.input buffer resource ID, array<u32> first position must be "count". The buffer must be 16-byte aligned.
+ * @param {number} options.output buffer resource ID of the same layout, at least `16 + ⌈element_max_count / 4⌉ · 16` bytes;
+ * see {@link prefix_scan_csdldf_output_descriptor}
  * @param {number} [options.element_max_count=1,048,576] how many elements might be in the input, this is a limit
- * @returns {number} buffer resource ID with prefix sums, this is rewritten input. The first position (count) is untouched.
+ * @returns {number} buffer resource ID of the written output
  */
 export function graph_prefix_scan_csdldf({
                                              graph,
-                                             data,
+                                             input,
+                                             output,
                                              element_max_count = 1048576,
                                          }) {
 
     assert.isNonNegativeInteger(element_max_count, 'element_max_count');
 
-    if (element_max_count <= 0) {
-        console.warn("element_max_count <= 0, returning input");
-
-        return data;
-    }
-
     // TODO run a special prefix scan if element_max_count fits into a single group
 
-
     const group_count = Math.ceil(element_max_count / PREFIX_SCAN_CSDLDF_PARTITION_SIZE);
 
+    if (group_count > WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION) {
+        warn_limited(`group_count(=${group_count} > MAX_DISPATCH_SIZE(=${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}). Prefix scan likely incomplete`);
+    }
+
     const pass_data = {};
 
     /**
@@ -58,41 +81,35 @@ export function graph_prefix_scan_csdldf({
      */
     function execute(pass_data, resources, context) {
 
-        const data = resources.get(pass_data.data);
-        const partition_descriptor_buffer = resources.get(pass_data.partition_descriptor_buffer);
-        const command = resources.get(pass_data.command);
-
         const encoder = context.encoder;
 
-        const MAX_DISPATCH_SIZE = encoder.device.limits.maxComputeWorkgroupsPerDimension;
+        const scan_in = resources.get(pass_data.input);
+        const scan_out = resources.get(pass_data.output);
+        const command = resources.get(pass_data.command);
 
-        if (group_count > MAX_DISPATCH_SIZE) {
-            warn_limited(`group_count(=${group_count} > MAX_DISPATCH_SIZE(=${MAX_DISPATCH_SIZE}). Prefix scan likely incomplete`);
-        }
+        assert.notEqual(scan_in, scan_out, 'input and output must be different buffers');
+        assert.greaterThanOrEqual(scan_out.size, 16 + Math.ceil(element_max_count / 4) * 16, 'output is too small for element_max_count');
 
-        build_indirect_compute_dispatch_command(
-            PREFIX_SCAN_CSDLDF_PARTITION_SIZE,
+        shader_prefix_scan_csdldf_prepare.dispatch({
             encoder,
-            data,
-            0,
-            command,
-            0,
-        );
+            bindings: { scan_in, scan_out, command },
+        });
 
         shader_prefix_scan_csdldf.dispatchIndirect({
             encoder,
             command,
             bindings: {
-                scan_in: data,
-                spine: partition_descriptor_buffer,
+                scan_in,
+                scan_out,
+                spine: resources.get(pass_data.partition_descriptor_buffer),
             }
         });
     }
 
     const pass = graph.add("prefix sum", pass_data, execute);
 
-    pass.read(data);
-    pass_data.data = pass.write(data);
+    pass_data.input = pass.read(input);
+    pass_data.output = pass.write(pass.read(output));
 
     pass_data.command = pass.create("command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
 
@@ -106,5 +123,5 @@ export function graph_prefix_scan_csdldf({
         )
     );
 
-    return pass_data.data;
-}
+    return pass_data.output;
+}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.d.ts

@@ -23,5 +23,12 @@ export const PREFIX_SCAN_CSDLDF_HEADER_WORDS: number;
  * @type {ComputeShader}
  */
 export const shader_prefix_scan_csdldf: ComputeShader;
+/**
+ * One thread ahead of {@link shader_prefix_scan_csdldf}: the scan's dispatch, a workgroup per partition of the input's
+ * count, and the output's count. The output gets its count here rather than from the scan's first tile because an input
+ * of no elements dispatches no tile at all.
+ * @type {ComputeShader}
+ */
+export const shader_prefix_scan_csdldf_prepare: ComputeShader;
 import { ComputeShader } from "../../../shader/ComputeShader.js";
 //# sourceMappingURL=shader_prefix_scan_csdldf.d.ts.map

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,gDAFU,MAAM,CAEsC;AAOtD;;;;;;;;;;GAUG;AACH,8CAFU,MAAM,CAE6E;AA0S7F;;;;;GAKG;AACH,wCAFU,aAAa,CAMpB;8BA9U2B,kCAAkC"}
+{"version":3,"file":"shader_prefix_scan_csdldf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,gDAFU,MAAM,CAEsC;AAOtD;;;;;;;;;;GAUG;AACH,8CAFU,MAAM,CAE6E;AAmT7F;;;;;GAKG;AACH,wCAFU,aAAa,CAMpB;AAQH;;;;;GAKG;AACH,gDAFU,aAAa,CAkBpB;8BArX2B,kCAAkC"}