@woosh/meep-engine 3.11.3 → 3.13.0

package/src/engine/graphics3/shade_camera_projection_ray.js

@@ -1,77 +1,77 @@
-import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
-import { v3_matrix4_multiply } from "../../core/geom/vec3/v3_matrix4_multiply.js";
-
-/**
- * @type {Float32Array}
- */
-const SCRATCH_INVERSE = new Float32Array(16);
-
-/**
- * @type {Float32Array}
- */
-const SCRATCH_CLIP = new Float32Array(3);
-
-/**
- * @type {Float32Array}
- */
-const SCRATCH_WORLD = new Float32Array(3);
-
-/**
- * Where along the ray the unprojected point is taken.
- *
- * Any depth strictly inside the frustum names a point on the same ray, so this only has to avoid the
- * two ends. It matters that it avoids them: the perspective camera projects with an **infinite
- * reverse-Z**, where clip depth 0 is the far plane at infinity and unprojecting it divides by zero.
- * Half-way is finite under that projection and under a conventional one alike, which is what keeps
- * this a single expression rather than a branch on {@link Camera#isReverseZ}.
- *
- * @type {number}
- */
-const SAMPLE_DEPTH = 0.5;
-
-/**
- * A ray from the eye through a point on the viewport, in world space.
- *
- * The camera's matrices are read as they stand, so they have to be current — `camera.update()` is
- * what composes the view-projection this inverts, and a camera moved since then produces a ray for
- * where it used to be.
- *
- * `x` and `y` are **clip-space**, in −1…1 with +Y up, which is what
- * `GraphicsEngine3.normalizeViewportPoint` produces from pixels.
- *
- * The origin is the camera's own position, which is right for a perspective camera and is also what
- * the three-based engine did for both kinds. A true orthographic pick wants parallel rays from the
- * near plane instead; nothing asks for one, and this would quietly answer the perspective question if
- * something did.
- *
- * @param {Camera} camera Shade's
- * @param {number} x clip space, −1…1
- * @param {number} y clip space, −1…1, +Y up
- * @param {Vector3} out_source written with the ray's origin
- * @param {Vector3} out_direction written with a unit direction
- */
-export function shade_camera_projection_ray(camera, x, y, out_source, out_direction) {
-    m4_invert(SCRATCH_INVERSE, camera.view_projection_matrix);
-
-    SCRATCH_CLIP[0] = x;
-    SCRATCH_CLIP[1] = y;
-    SCRATCH_CLIP[2] = SAMPLE_DEPTH;
-
-    v3_matrix4_multiply(SCRATCH_WORLD, 0, SCRATCH_CLIP, 0, SCRATCH_INVERSE);
-
-    const position = camera.transform.position;
-
-    const origin_x = position.x;
-    const origin_y = position.y;
-    const origin_z = position.z;
-
-    out_source.set(origin_x, origin_y, origin_z);
-
-    out_direction.set(
-        SCRATCH_WORLD[0] - origin_x,
-        SCRATCH_WORLD[1] - origin_y,
-        SCRATCH_WORLD[2] - origin_z
-    );
-
-    out_direction.normalize();
-}
+import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
+import { v3_matrix4_multiply } from "../../core/geom/vec3/v3_matrix4_multiply.js";
+
+/**
+ * @type {Float32Array}
+ */
+const SCRATCH_INVERSE = new Float32Array(16);
+
+/**
+ * @type {Float32Array}
+ */
+const SCRATCH_CLIP = new Float32Array(3);
+
+/**
+ * @type {Float32Array}
+ */
+const SCRATCH_WORLD = new Float32Array(3);
+
+/**
+ * Where along the ray the unprojected point is taken.
+ *
+ * Any depth strictly inside the frustum names a point on the same ray, so this only has to avoid the
+ * two ends. It matters that it avoids them: the perspective camera projects with an **infinite
+ * reverse-Z**, where clip depth 0 is the far plane at infinity and unprojecting it divides by zero.
+ * Half-way is finite under that projection and under a conventional one alike, which is what keeps
+ * this a single expression rather than a branch on {@link Camera#isReverseZ}.
+ *
+ * @type {number}
+ */
+const SAMPLE_DEPTH = 0.5;
+
+/**
+ * A ray from the eye through a point on the viewport, in world space.
+ *
+ * The camera's matrices are read as they stand, so they have to be current — `camera.update()` is
+ * what composes the view-projection this inverts, and a camera moved since then produces a ray for
+ * where it used to be.
+ *
+ * `x` and `y` are **clip-space**, in −1…1 with +Y up, which is what
+ * `GraphicsEngine.normalizeViewportPoint` produces from pixels.
+ *
+ * The origin is the camera's own position, which is right for a perspective camera and is also what
+ * the three-based engine did for both kinds. A true orthographic pick wants parallel rays from the
+ * near plane instead; nothing asks for one, and this would quietly answer the perspective question if
+ * something did.
+ *
+ * @param {Camera} camera Shade's
+ * @param {number} x clip space, −1…1
+ * @param {number} y clip space, −1…1, +Y up
+ * @param {Vector3} out_source written with the ray's origin
+ * @param {Vector3} out_direction written with a unit direction
+ */
+export function shade_camera_projection_ray(camera, x, y, out_source, out_direction) {
+    m4_invert(SCRATCH_INVERSE, camera.view_projection_matrix);
+
+    SCRATCH_CLIP[0] = x;
+    SCRATCH_CLIP[1] = y;
+    SCRATCH_CLIP[2] = SAMPLE_DEPTH;
+
+    v3_matrix4_multiply(SCRATCH_WORLD, 0, SCRATCH_CLIP, 0, SCRATCH_INVERSE);
+
+    const position = camera.transform.position;
+
+    const origin_x = position.x;
+    const origin_y = position.y;
+    const origin_z = position.z;
+
+    out_source.set(origin_x, origin_y, origin_z);
+
+    out_direction.set(
+        SCRATCH_WORLD[0] - origin_x,
+        SCRATCH_WORLD[1] - origin_y,
+        SCRATCH_WORLD[2] - origin_z
+    );
+
+    out_direction.normalize();
+}

package/src/engine/graphics3/shade_node_to_entity_composition.d.ts

@@ -12,7 +12,7 @@
  *
  * **Geometry and material are shared, not copied.** Two entities placing the same model name the
  * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
- * in the scene, which is `ShadedGeometrySystem3`'s business. That is the whole reason a static model
+ * in the scene, which is `ShadedGeometrySystem`'s business. That is the whole reason a static model
  * needs no clone of the bundle at all.
  *
  * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices

package/src/engine/graphics3/shade_node_to_entity_composition.js

@@ -1,84 +1,84 @@
-import { Name } from "../ecs/name/Name.js";
-import { EntityNode } from "../ecs/parent/EntityNode.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { transform_copy_from_t64 } from "../ecs/transform/transform_copy_from_t64.js";
-import { DrawMode } from "../graphics/ecs/mesh-v2/DrawMode.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-
-/**
- * Turn a loaded model's node tree into entities.
- *
- * **This is what a hierarchy is in an ECS** (D47). meep has no scene graph to hand a model to: it
- * has entities, `EntityNode` to parent them, and `ShadedGeometry` for the ones that draw. A model
- * file is therefore not a thing an entity *holds* — it is a shape an entity's descendants take, and
- * this function is where the file stops being the renderer's tree and becomes the dataset's.
- *
- * It is `three_object_to_entity_composition` with the source swapped: the same output, built from
- * Shade's `Node3D`s instead of three's `Object3D`s. The two exist side by side for as long as both
- * renderers do.
- *
- * **Geometry and material are shared, not copied.** Two entities placing the same model name the
- * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
- * in the scene, which is `ShadedGeometrySystem3`'s business. That is the whole reason a static model
- * needs no clone of the bundle at all.
- *
- * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices
- * are deformed against a skeleton the renderer owns and the GPU poses, and making those joints
- * entities is a design this program does not do (D47). A `SkinnedMesh` node therefore contributes
- * its transform and its name and no geometry, and whatever placed the model keeps drawing it the way
- * Phase 4 built.
- *
- * @param {Node3D} node
- * @returns {EntityNode}
- */
-export function shade_node_to_entity_composition(node) {
-    const result = new EntityNode();
-
-    // the hierarchy's own transform: what this node is, relative to its parent
-    transform_copy_from_t64(result.transform, node.transform_local);
-
-    const entity = result.entity;
-
-    entity.add(transform_copy_from_t64(new Transform(), node.transform_global));
-    entity.add(new Name(node.name));
-
-    if (node.isMesh === true && node.isSkinnedMesh !== true) {
-        entity.add(ShadedGeometry.from(node.geometry, node.material, DrawMode.Triangles));
-    }
-
-    const children = node.children;
-
-    for (let i = 0; i < children.length; i++) {
-        result.addChild(shade_node_to_entity_composition(children[i]));
-    }
-
-    return result;
-}
-
-/**
- * The same, for everything a loader produced.
- *
- * A bundle can carry more than one scene — glTF allows it — and the entity that placed the file owns
- * all of them, so they become children of one root rather than several compositions nobody joins.
- *
- * @param {SceneBundle} bundle
- * @returns {EntityNode}
- */
-export function shade_bundle_to_entity_composition(bundle) {
-    const scenes = bundle.scenes;
-
-    if (scenes.length === 1) {
-        return shade_node_to_entity_composition(scenes[0]);
-    }
-
-    const root = new EntityNode();
-
-    root.entity.add(new Transform());
-    root.entity.add(new Name(""));
-
-    for (let i = 0; i < scenes.length; i++) {
-        root.addChild(shade_node_to_entity_composition(scenes[i]));
-    }
-
-    return root;
-}
+import { Name } from "../ecs/name/Name.js";
+import { EntityNode } from "../ecs/parent/EntityNode.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { transform_copy_from_t64 } from "../ecs/transform/transform_copy_from_t64.js";
+import { DrawMode } from "../graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+
+/**
+ * Turn a loaded model's node tree into entities.
+ *
+ * **This is what a hierarchy is in an ECS** (D47). meep has no scene graph to hand a model to: it
+ * has entities, `EntityNode` to parent them, and `ShadedGeometry` for the ones that draw. A model
+ * file is therefore not a thing an entity *holds* — it is a shape an entity's descendants take, and
+ * this function is where the file stops being the renderer's tree and becomes the dataset's.
+ *
+ * It is `three_object_to_entity_composition` with the source swapped: the same output, built from
+ * Shade's `Node3D`s instead of three's `Object3D`s. The two exist side by side for as long as both
+ * renderers do.
+ *
+ * **Geometry and material are shared, not copied.** Two entities placing the same model name the
+ * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
+ * in the scene, which is `ShadedGeometrySystem`'s business. That is the whole reason a static model
+ * needs no clone of the bundle at all.
+ *
+ * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices
+ * are deformed against a skeleton the renderer owns and the GPU poses, and making those joints
+ * entities is a design this program does not do (D47). A `SkinnedMesh` node therefore contributes
+ * its transform and its name and no geometry, and whatever placed the model keeps drawing it the way
+ * Phase 4 built.
+ *
+ * @param {Node3D} node
+ * @returns {EntityNode}
+ */
+export function shade_node_to_entity_composition(node) {
+    const result = new EntityNode();
+
+    // the hierarchy's own transform: what this node is, relative to its parent
+    transform_copy_from_t64(result.transform, node.transform_local);
+
+    const entity = result.entity;
+
+    entity.add(transform_copy_from_t64(new Transform(), node.transform_global));
+    entity.add(new Name(node.name));
+
+    if (node.isMesh === true && node.isSkinnedMesh !== true) {
+        entity.add(ShadedGeometry.from(node.geometry, node.material, DrawMode.Triangles));
+    }
+
+    const children = node.children;
+
+    for (let i = 0; i < children.length; i++) {
+        result.addChild(shade_node_to_entity_composition(children[i]));
+    }
+
+    return result;
+}
+
+/**
+ * The same, for everything a loader produced.
+ *
+ * A bundle can carry more than one scene — glTF allows it — and the entity that placed the file owns
+ * all of them, so they become children of one root rather than several compositions nobody joins.
+ *
+ * @param {SceneBundle} bundle
+ * @returns {EntityNode}
+ */
+export function shade_bundle_to_entity_composition(bundle) {
+    const scenes = bundle.scenes;
+
+    if (scenes.length === 1) {
+        return shade_node_to_entity_composition(scenes[0]);
+    }
+
+    const root = new EntityNode();
+
+    root.entity.add(new Transform());
+    root.entity.add(new Name(""));
+
+    for (let i = 0; i < scenes.length; i++) {
+        root.addChild(shade_node_to_entity_composition(scenes[i]));
+    }
+
+    return root;
+}

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#356@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#360@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#356@#clear_field"(fluid: FluidComponent): void;
+    static "__#360@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#356@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#360@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#356@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#360@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/RENDERER_CONTRACT.md

@@ -541,7 +541,8 @@ frame or is removed and re-added keeps its buffers.
 | `internal_resolution_scale` | render internally below output resolution; `DynamicResolutionScaling` drives it from frame time |
 | `pixel_ratio`, `output_resolution`, `aspect_ratio`, `resize(x, y)` | |
 | `motion_blur`, `dof`, `dof_unreal`, `nss`, `restir_di`, `path_tracer` | sub-objects with their own settings |
-| `frame_count`, `add_debug_frame(n)` | |
+| `frame_count` | |
+| `profile_session` | assign a `GPUProfileSession` to record GPU timings; null when nothing is profiling |
 
 ---
 

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.d.ts

@@ -19,6 +19,23 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      */
     static fromJSON(json: GPUComputePipelineDescriptor): ComputePipelineDescriptor;
     compute: ProgrammableStage;
+    /**
+     * `[x, y, z]` of this pipeline's `@workgroup_size`.
+     *
+     * Read once, when the code is set, and kept — the source cannot change under a descriptor
+     * without going back through one of the factories, each of which reads it again. So every
+     * consumer downstream, a profile capture included, gets the number for free.
+     *
+     * Frozen, because it is handed out by reference to per-pass profile records and a descriptor
+     * that outlives a whole capture must not be mutable through one of them.
+     *
+     * Takes no part in {@link equals} or {@link hash}: it is derived from `compute.module`, which
+     * both already cover, and a cache key computed two ways is a cache that can disagree with
+     * itself.
+     *
+     * @returns {readonly number[]}
+     */
+    get workgroup_size(): readonly number[];
     /**
      *
      * @param {GPUComputePipelineDescriptor} json
@@ -35,6 +52,7 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      * @type {boolean}
      */
     readonly isComputePipelineDescriptor: boolean;
+    #private;
 }
 import { PipelineDescriptorBase } from "../PipelineDescriptorBase.js";
 import { ProgrammableStage } from "../ProgrammableStage.js";

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputePipelineDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js"],"names":[],"mappings":"AAQA;IAGI;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,UACN,wBAAwB,6BAalC;IAED;;;;;OAKG;IACH,wEALW,MAAM,6BAyBhB;IAED;;;OAGG;IACH,+EAMC;IA3DD,2BAAkC;IA6DlC;;;OAGG;IACH,mDAMC;IAED;;;;OAIG;IACH,cAHW,yBAAyB,GACxB,OAAO,CAMlB;IAUL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;CAN9D;uCAhGsC,8BAA8B;kCAEnC,yBAAyB;yCADlB,gCAAgC"}
+{"version":3,"file":"ComputePipelineDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js"],"names":[],"mappings":"AAqBA;IAuDI;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,UACN,wBAAwB,6BAelC;IAED;;;;;OAKG;IACH,wEALW,MAAM,6BA2BhB;IAED;;;OAGG;IACH,+EAMC;IAnHD,2BAAkC;IAOlC;;;;;;;;;;;;;;;OAeG;IACH,wCAEC;IA4FD;;;OAGG;IACH,mDAUC;IAED;;;;OAIG;IACH,cAHW,yBAAyB,GACxB,OAAO,CAMlB;IAUL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;;CAN9D;uCAtKsC,8BAA8B;kCAEnC,yBAAyB;yCADlB,gCAAgC"}

package/src/shade/descriptor/pipeline/compute/ComputePipelineDescriptor.js

@@ -1,14 +1,79 @@
 import { assert } from "../../../../core/assert.js";
 import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import {
+    compute_infer_workgroup_size_from_source
+} from "../../../renderer/shader/util/compute_infer_workgroup_size_from_source.js";
 import { GPUShaderStage } from "../../GPUShaderStage.js";
 import { PipelineDescriptorBase } from "../PipelineDescriptorBase.js";
 import { PipelineLayoutDescriptor } from "../PipelineLayoutDescriptor.js";
 import { ProgrammableStage } from "../ProgrammableStage.js";
 import { ShaderModuleDescriptor } from "../ShaderModuleDescriptor.js";
 
+/**
+ * What {@link ComputePipelineDescriptor#workgroup_size} reads before any code has been set.
+ *
+ * Not a fallback for unreadable source — that throws. This is the value of a descriptor that has
+ * been constructed and not yet given a shader, which is a state only `new` produces.
+ *
+ * @type {readonly number[]}
+ */
+const WORKGROUP_SIZE_UNSET = Object.freeze([0, 0, 0]);
+
 export class ComputePipelineDescriptor extends PipelineDescriptorBase {
     compute = new ProgrammableStage();
 
+    /**
+     * @type {readonly number[]}
+     */
+    #workgroup_size = WORKGROUP_SIZE_UNSET;
+
+    /**
+     * `[x, y, z]` of this pipeline's `@workgroup_size`.
+     *
+     * Read once, when the code is set, and kept — the source cannot change under a descriptor
+     * without going back through one of the factories, each of which reads it again. So every
+     * consumer downstream, a profile capture included, gets the number for free.
+     *
+     * Frozen, because it is handed out by reference to per-pass profile records and a descriptor
+     * that outlives a whole capture must not be mutable through one of them.
+     *
+     * Takes no part in {@link equals} or {@link hash}: it is derived from `compute.module`, which
+     * both already cover, and a cache key computed two ways is a cache that can disagree with
+     * itself.
+     *
+     * @returns {readonly number[]}
+     */
+    get workgroup_size() {
+        return this.#workgroup_size;
+    }
+
+    /**
+     * Read the workgroup size out of the code just assigned to {@link compute}, and **throw** if it
+     * cannot be read.
+     *
+     * Loud, and at construction. Every consumer of this number divides a thread count by it, so a
+     * guess that is wrong silently dispatches the wrong fraction of the workload — and a descriptor
+     * that cannot state its own workgroup size is one nobody downstream can use correctly. Better
+     * that it cannot be built than that it be built and dealt with.
+     *
+     * @returns {void}
+     */
+    #read_workgroup_size() {
+        const code = this.compute.module.code;
+
+        try {
+            this.#workgroup_size = Object.freeze(compute_infer_workgroup_size_from_source(code));
+        } catch (e) {
+            const error = new Error(
+                `Compute pipeline '${this.label}' has no readable workgroup size: ${e.message}`
+            );
+
+            error.cause = e;
+
+            throw error;
+        }
+    }
+
     /**
      *
      * @param {string} label
@@ -24,6 +89,8 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
         r.label = label;
         r.compute.module = ShaderModuleDescriptor.fromCode(code);
 
+        r.#read_workgroup_size();
+
         return r;
 
     }
@@ -53,6 +120,8 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
             r.compute.constants = constants;
         }
 
+        r.#read_workgroup_size();
+
         return r;
     }
 
@@ -78,6 +147,10 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
         assert.isObject(json.compute, 'json.compute');
 
         this.compute.fromJSON(json.compute);
+
+        // `fromJSON` replaces the module in place, so the size read for whatever was here before is
+        // now the wrong shader's. Read it again rather than leaving a stale divisor behind.
+        this.#read_workgroup_size();
     }
 
     /**