@woosh/meep-engine 3.47.0 → 3.49.0

package/src/engine/physics/cloth/solver/constraint/cloth_contact_row.js

@@ -22,6 +22,7 @@ import {
     CVA_H_ZZ,
     CVA_TRUST
 } from "../cloth_vertex_accumulator.js";
+import { CLOTH_CONTACT_GAMMA, CLOTH_CONTACT_RAMP_RATIO } from "../cloth_solver_constants.js";
 
 /**
  * # Contact — the collision row and its friction row, which are one contact
@@ -80,6 +81,21 @@ import {
  * never act at all. The current force is already computed, already
  * non-negative, and makes a cloth land on a slope and stay there at 1×1.
  *
+ * ## The normal penalty ramps in the contact's own units
+ *
+ * `k ← min(k + ratio·k_max·|C|/offset, k_max)`, `offset = thickness + inflation`:
+ * the penalty gains {@link CLOTH_CONTACT_RAMP_RATIO} of its band per contact
+ * offset of violation per iteration, rather than `β·|C|` newtons per metre.
+ * A contact against a **sweeping** collider — a thigh into a skirt — has to
+ * produce an arresting force within the iteration budget, and a ramp in N/m²
+ * that was gentle on a landing sheet was, on a 20 g particle at two substeps,
+ * 0.003 of the band per offset: the row sat at the floor while its multiplier
+ * was rebuilt from a quarter every substep, and the limb showed through. The
+ * ratio keeps the measured shape — a grazing contact ramps gently, a real
+ * interpenetration is at the ceiling within an iteration — and it keeps it
+ * for every mass, substep count and thickness. `β` still ramps friction.
+ * `MEASUREMENTS.md` §67.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -329,12 +345,14 @@ export function cloth_contact_accumulate(accumulator, state, particle, table) {
  *
  * @param {ClothState} state
  * @param {number} alpha
- * @param {number} gamma
+ * @param {number} gamma the multiplier's decay, with `alpha`
  * @param {number} k_min_ratio
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [penalty_gamma] the contact's own decay of both penalties per
+ *   substep — {@link CLOTH_CONTACT_GAMMA}, and why a contact has one
  */
-export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared) {
+export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max_ratio, inverse_h_squared, penalty_gamma = CLOTH_CONTACT_GAMMA) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -374,8 +392,11 @@ export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max
             lambda[slot] *= decay;
             friction_lambda[slot] *= decay;
 
-            penalty[slot] = clamp(penalty[slot] * gamma, lo, hi);
-            friction_penalty[slot] = clamp(friction_penalty[slot] * gamma, lo, hi);
+            // Both penalties decay by the contact's own `penalty_gamma`, the multipliers above by
+            // `α·γ`: a quiet row sinks back to the floor while its multiplier carries the load, and a
+            // violated one re-climbs within an iteration (the module docblock).
+            penalty[slot] = clamp(penalty[slot] * penalty_gamma, lo, hi);
+            friction_penalty[slot] = clamp(friction_penalty[slot] * penalty_gamma, lo, hi);
         }
     }
 }
@@ -392,11 +413,13 @@ export function cloth_contact_warm_start(state, alpha, gamma, k_min_ratio, k_max
  *
  * @param {ClothState} state
  * @param {Float32Array|Float64Array} table
- * @param {number} beta
+ * @param {number} beta the friction row's ramp, N/m²
  * @param {number} k_max_ratio
  * @param {number} inverse_h_squared
+ * @param {number} [ramp_ratio] the normal row's ramp, as the fraction of the
+ *   band gained per contact offset of violation per iteration
  */
-export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inverse_h_squared) {
+export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inverse_h_squared, ramp_ratio = CLOTH_CONTACT_RAMP_RATIO) {
     const particle_count = state.particle_count;
 
     const collider = state.contact_collider;
@@ -446,7 +469,9 @@ export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inver
 
             const distance = NORMAL[3];
 
-            const c = radius + table[r + CCR_INFLATION] - distance;
+            const offset = radius + table[r + CCR_INFLATION];
+
+            const c = offset - distance;
 
             const k = penalty[slot];
 
@@ -456,7 +481,10 @@ export function cloth_contact_dual_update(state, table, beta, k_max_ratio, inver
 
             lambda[slot] = normal_force;
 
-            const ramped = k + beta * Math.abs(c);
+            // The band per offset of violation, whether or not the row is
+            // active (the module docblock); a zero offset divides to
+            // `Infinity` or `NaN`, and either comparison below lands on `k_max`.
+            const ramped = k + ramp_ratio * k_max * Math.abs(c) / offset;
 
             penalty[slot] = ramped < k_max ? ramped : k_max;
 

package/src/engine/physics/cloth/solver/constraint/cloth_self_row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_self_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_self_row.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;GAUG;AACH,4EAJW,MAAM,GAEJ,MAAM,CA4FlB;AAED;;;;;;GAMG;AACH,mDAJW,YAAY,+BAEZ,MAAM,QAyBhB;AA/LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEuB"}
+{"version":3,"file":"cloth_self_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/physics/cloth/solver/constraint/cloth_self_row.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;GAUG;AACH,4EAJW,MAAM,GAEJ,MAAM,CA8FlB;AAED;;;;;;GAMG;AACH,mDAJW,YAAY,+BAEZ,MAAM,QAyBhB;AAjMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AACH,iCAFU,MAAM,CAEuB"}

package/src/engine/physics/cloth/solver/constraint/cloth_self_row.js

@@ -94,8 +94,7 @@ export function cloth_self_accumulate_scratch(state, stiffness) {
 
     const pair = state.self_pair;
     const position = state.position;
-
-    const radius = state.self_radius * 2;
+    const self_radius = state.self_radius;
 
     let active = 0;
 
@@ -103,6 +102,9 @@ export function cloth_self_accumulate_scratch(state, stiffness) {
         const i = pair[p * 2];
         const j = pair[p * 2 + 1];
 
+        // `r_i + r_j`, each particle's own (`ClothState#self_radius`)
+        const radius = self_radius[i] + self_radius[j];
+
         const a = i * 3;
         const b = j * 3;
 

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

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#440@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#445@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#440@#clear_field"(fluid: FluidComponent): void;
+    static "__#445@#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
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#440@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#445@#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
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#440@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#445@#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 Transform64> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/device/mock/SoftwareGPUDevice.d.ts

@@ -230,6 +230,21 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase implements GPUDevic
      * @returns {GPUComputePipeline}
      */
     createComputePipeline(descriptor: GPUComputePipelineDescriptor): GPUComputePipeline;
+    /**
+     * The asynchronous form of {@link createRenderPipeline}. There is nothing to compile here, so the
+     * handle is already made when the promise is returned, and the promise is already resolved.
+     *
+     * @param {GPURenderPipelineDescriptor} descriptor
+     * @returns {Promise<GPURenderPipeline>}
+     */
+    createRenderPipelineAsync(descriptor: GPURenderPipelineDescriptor): Promise<GPURenderPipeline>;
+    /**
+     * The asynchronous form of {@link createComputePipeline} — see {@link createRenderPipelineAsync}.
+     *
+     * @param {GPUComputePipelineDescriptor} descriptor
+     * @returns {Promise<GPUComputePipeline>}
+     */
+    createComputePipelineAsync(descriptor: GPUComputePipelineDescriptor): Promise<GPUComputePipeline>;
     /**
      * The next tick. Shared by every query set this device made, so two of them still order against
      * each other.

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+QA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;OAQG;IACH;QAP+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAuBrC;IAvDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAiCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WA7sBa,mBAAiB,IAAI;;sCA9QG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+QA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;OAQG;IACH;QAP+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAuBrC;IAvDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAiCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAED;;;;;;OAMG;IACH,oEAFa,0BAA0B,CAItC;IAED;;;;;OAKG;IACH,sEAFa,2BAA2B,CAIvC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WAluBa,mBAAiB,IAAI;;sCA9QG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -924,6 +924,27 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
         return new SoftwareGPUComputePipeline(descriptor);
     }
 
+    /**
+     * The asynchronous form of {@link createRenderPipeline}. There is nothing to compile here, so the
+     * handle is already made when the promise is returned, and the promise is already resolved.
+     *
+     * @param {GPURenderPipelineDescriptor} descriptor
+     * @returns {Promise<GPURenderPipeline>}
+     */
+    createRenderPipelineAsync(descriptor) {
+        return Promise.resolve(new SoftwareGPURenderPipeline(descriptor));
+    }
+
+    /**
+     * The asynchronous form of {@link createComputePipeline} — see {@link createRenderPipelineAsync}.
+     *
+     * @param {GPUComputePipelineDescriptor} descriptor
+     * @returns {Promise<GPUComputePipeline>}
+     */
+    createComputePipelineAsync(descriptor) {
+        return Promise.resolve(new SoftwareGPUComputePipeline(descriptor));
+    }
+
     /**
      * The device's monotonic counter, which is what a timestamp query records here. See
      * {@link SoftwareGPUQuerySet} for why these are not measurements.

package/src/shade/device/pipeline/ComputePipelineManager.d.ts

@@ -2,6 +2,7 @@
  * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 export class ComputePipelineManager {
     /**
@@ -16,15 +17,34 @@ export class ComputePipelineManager {
      * @returns {PipelineLayoutManager}
      */
     get layouts(): import("./PipelineLayoutManager.js").PipelineLayoutManager;
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count(): number;
     /**
      *
      * @param {ComputePipelineDescriptor} descriptor
      * @returns {GPUComputePipeline}
      */
     obtain(descriptor: ComputePipelineDescriptor): GPUComputePipeline;
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way. If `obtain`
+     * makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor: ComputePipelineDescriptor): Promise<void>;
     #private;
 }
 export type ComputePipelineDescriptor = import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor;
 export type ShaderModuleCompiler = import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler;
 export type PipelineLayoutManager = import("./PipelineLayoutManager.js").PipelineLayoutManager;
+export type PipelineEnquiry = import("./PipelineEnquiry.js").PipelineEnquiry;
 //# sourceMappingURL=ComputePipelineManager.d.ts.map

package/src/shade/device/pipeline/ComputePipelineManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputePipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/ComputePipelineManager.js"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;IA+BI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IAtCD;;;OAGG;IACH,0EAEC;IA8DD;;;;OAIG;IACH,mBAHW,yBAAyB,sBAQnC;;CAEJ;wCAhGY,OAAO,gEAAgE,EAAE,yBAAyB;mCAClG,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB"}
+{"version":3,"file":"ComputePipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/ComputePipelineManager.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;IA+CI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IAtDD;;;OAGG;IACH,0EAEC;IAoBD;;;;OAIG;IACH,4BAEC;IAyDD;;;;OAIG;IACH,mBAHW,yBAAyB,sBAQnC;IAED;;;;;;;;;;OAUG;IACH,oBAHW,yBAAyB,GACvB,QAAQ,IAAI,CAAC,CAwCzB;;CAEJ;wCA1KY,OAAO,gEAAgE,EAAE,yBAAyB;mCAClG,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;8BAC1D,OAAO,sBAAsB,EAAE,eAAe"}

package/src/shade/device/pipeline/ComputePipelineManager.js

@@ -5,6 +5,7 @@ import { HashMap } from "../../../core/collection/map/HashMap.js";
  * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
 export class ComputePipelineManager {
@@ -37,6 +38,22 @@ export class ComputePipelineManager {
      */
     #cache = new HashMap();
 
+    /**
+     * Compilations {@link prepare} started that have not finished.
+     *
+     * @type {HashMap<ComputePipelineDescriptor, Promise<void>>}
+     */
+    #pending = new HashMap();
+
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count() {
+        return this.#pending.size;
+    }
+
 
     /**
      *
@@ -62,18 +79,17 @@ export class ComputePipelineManager {
     /**
      *
      * @param {ComputePipelineDescriptor} descriptor
-     * @returns {GPUComputePipeline}
+     * @returns {GPUComputePipelineDescriptor}
      */
-    #create(descriptor) {
+    #gpu_descriptor(descriptor) {
 
         const shaders = this.#shaders;
 
         const layouts = this.#layouts;
-        const device = this.#device;
 
         const stage = descriptor.compute;
 
-        const gpu_descriptor = {
+        return {
             label: descriptor.label,
             layout: layouts.obtainPipelineLayout(descriptor.layout),
             compute: {
@@ -82,8 +98,15 @@ export class ComputePipelineManager {
                 constants: stage.constants
             },
         };
+    }
 
-        return device.createComputePipeline(gpu_descriptor);
+    /**
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {GPUComputePipeline}
+     */
+    #create(descriptor) {
+        return this.#device.createComputePipeline(this.#gpu_descriptor(descriptor));
     }
 
     /**
@@ -98,4 +121,55 @@ export class ComputePipelineManager {
         return this.#cache.getOrCompute(descriptor, this.#create, this);
     }
 
-}
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way. If `obtain`
+     * makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {ComputePipelineDescriptor} descriptor
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor) {
+        assert.defined(descriptor, 'descriptor');
+        assert.equal(descriptor.isComputePipelineDescriptor, true, 'descriptor.isComputePipelineDescriptor !== true');
+
+        const cache = this.#cache;
+
+        if (cache.has(descriptor)) {
+            return Promise.resolve();
+        }
+
+        const pending = this.#pending;
+
+        const existing = pending.get(descriptor);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const gpu_descriptor = this.#gpu_descriptor(descriptor);
+
+        const compilation = this.#device.createComputePipelineAsync(gpu_descriptor).then(
+            (pipeline) => {
+                pending.delete(descriptor);
+
+                if (!cache.has(descriptor)) {
+                    cache.set(descriptor, pipeline);
+                }
+            },
+            (error) => {
+                pending.delete(descriptor);
+
+                console.error(`Failed to create "${descriptor.label}" pipeline: `, error.message, gpu_descriptor);
+            }
+        );
+
+        pending.set(descriptor, compilation);
+
+        return compilation;
+    }
+
+}

package/src/shade/device/pipeline/PipelineEnquiry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
+ */
+/**
+ * The pipelines a renderer is about to draw with, gathered before it draws, so that they can be
+ * compiled all at once and off the thread that presents frames.
+ *
+ * Left to themselves, pipelines are made the first time a frame obtains them, and a browser compiles
+ * a pipeline made that way on the GPU process's main thread, one after another — the thread that also
+ * presents the page. A cold first frame of a single lit cube spent 3.4 s there on 54 pipelines. Made
+ * asynchronously, the same 54 compiled on the browser's worker pool in ~1.0 s, as long as the
+ * slowest of them took.
+ *
+ * Whoever owns a pass puts into this the descriptor that pass will hand to `obtain` — the same
+ * object, or one equal to it — for the configuration it is in now. An offer is speculative: one that
+ * turns out not to be drawn with costs a compile on a worker and nothing more, and a pipeline that
+ * nobody offered is still made the old way, the first time a frame obtains it. Offering the same
+ * pipeline twice is harmless; it compiles once.
+ *
+ * Who answers, and how:
+ * - a `graph_*` pass exports `enquire_<pass>_pipelines(enquiry)` beside itself, offering what it
+ *   dispatches and asking the passes it calls, so each list sits next to the code it predicts;
+ * - an object the renderer already holds when it asks answers through its own `enquirePipelines`;
+ * - a class whose instances come later — one per scene or per view — answers through a static
+ *   `enquirePipelines`, for all of them.
+ */
+export class PipelineEnquiry {
+    /**
+     * @param {GPUDevice} device
+     * @returns {PipelineEnquiry}
+     */
+    static from(device: GPUDevice): PipelineEnquiry;
+    /**
+     * The device the pipelines are for. Some descriptors are built from its limits, which is how an
+     * offer comes out equal to the descriptor the pass builds for itself.
+     *
+     * @type {GPUDevice}
+     */
+    device: GPUDevice;
+    /**
+     * @type {RenderPipelineDescriptor[]}
+     */
+    render: RenderPipelineDescriptor[];
+    /**
+     * @type {ComputePipelineDescriptor[]}
+     */
+    compute: ComputePipelineDescriptor[];
+}
+export type RenderPipelineDescriptor = import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor;
+export type ComputePipelineDescriptor = import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor;
+//# sourceMappingURL=PipelineEnquiry.d.ts.map

package/src/shade/device/pipeline/PipelineEnquiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineEnquiry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/PipelineEnquiry.js"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAmBI;;;OAGG;IACH,gCAFa,eAAe,CAU3B;IA9BD;;;;;OAKG;IACH,kBAAO;IAEP;;OAEG;IACH,QAFU,wBAAwB,EAAE,CAExB;IAEZ;;OAEG;IACH,SAFU,yBAAyB,EAAE,CAExB;CAehB;uCA3DY,OAAO,8DAA8D,EAAE,wBAAwB;wCAC/F,OAAO,gEAAgE,EAAE,yBAAyB"}

package/src/shade/device/pipeline/PipelineEnquiry.js

@@ -0,0 +1,63 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * @typedef {import("../../descriptor/pipeline/render/RenderPipelineDescriptor.js").RenderPipelineDescriptor} RenderPipelineDescriptor
+ * @typedef {import("../../descriptor/pipeline/compute/ComputePipelineDescriptor.js").ComputePipelineDescriptor} ComputePipelineDescriptor
+ */
+
+/**
+ * The pipelines a renderer is about to draw with, gathered before it draws, so that they can be
+ * compiled all at once and off the thread that presents frames.
+ *
+ * Left to themselves, pipelines are made the first time a frame obtains them, and a browser compiles
+ * a pipeline made that way on the GPU process's main thread, one after another — the thread that also
+ * presents the page. A cold first frame of a single lit cube spent 3.4 s there on 54 pipelines. Made
+ * asynchronously, the same 54 compiled on the browser's worker pool in ~1.0 s, as long as the
+ * slowest of them took.
+ *
+ * Whoever owns a pass puts into this the descriptor that pass will hand to `obtain` — the same
+ * object, or one equal to it — for the configuration it is in now. An offer is speculative: one that
+ * turns out not to be drawn with costs a compile on a worker and nothing more, and a pipeline that
+ * nobody offered is still made the old way, the first time a frame obtains it. Offering the same
+ * pipeline twice is harmless; it compiles once.
+ *
+ * Who answers, and how:
+ * - a `graph_*` pass exports `enquire_<pass>_pipelines(enquiry)` beside itself, offering what it
+ *   dispatches and asking the passes it calls, so each list sits next to the code it predicts;
+ * - an object the renderer already holds when it asks answers through its own `enquirePipelines`;
+ * - a class whose instances come later — one per scene or per view — answers through a static
+ *   `enquirePipelines`, for all of them.
+ */
+export class PipelineEnquiry {
+    /**
+     * The device the pipelines are for. Some descriptors are built from its limits, which is how an
+     * offer comes out equal to the descriptor the pass builds for itself.
+     *
+     * @type {GPUDevice}
+     */
+    device;
+
+    /**
+     * @type {RenderPipelineDescriptor[]}
+     */
+    render = [];
+
+    /**
+     * @type {ComputePipelineDescriptor[]}
+     */
+    compute = [];
+
+    /**
+     * @param {GPUDevice} device
+     * @returns {PipelineEnquiry}
+     */
+    static from(device) {
+        assert.defined(device, 'device');
+
+        const r = new PipelineEnquiry();
+
+        r.device = device;
+
+        return r;
+    }
+}

package/src/shade/device/pipeline/RenderPipelineManager.d.ts

@@ -1,6 +1,7 @@
 /**
  * @typedef {import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler} ShaderModuleCompiler
  * @typedef {import("./PipelineLayoutManager.js").PipelineLayoutManager} PipelineLayoutManager
+ * @typedef {import("./PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 export class RenderPipelineManager {
     /**
@@ -15,6 +16,12 @@ export class RenderPipelineManager {
      * @returns {PipelineLayoutManager}
      */
     get layouts(): import("./PipelineLayoutManager.js").PipelineLayoutManager;
+    /**
+     * How many pipelines {@link prepare} is still compiling.
+     *
+     * @returns {number}
+     */
+    get pending_count(): number;
     /**
      *
      * @param {RenderPipelineDescriptor} descriptor
@@ -22,9 +29,23 @@ export class RenderPipelineManager {
      * @returns {GPURenderPipeline}
      */
     obtain(descriptor: RenderPipelineDescriptor, actual_color_attachments?: GPUTextureFormat[]): GPURenderPipeline;
+    /**
+     * Compile the pipeline for `descriptor` off the thread that presents frames, into the cache
+     * {@link obtain} reads — see {@link PipelineEnquiry} for why.
+     *
+     * Nothing new starts for a descriptor that is cached or already compiling. A pipeline that fails
+     * is reported and left out of the cache, so `obtain` makes it again the old way and reports it
+     * again. If `obtain` makes it while it is still compiling here, the one `obtain` made is kept.
+     *
+     * @param {RenderPipelineDescriptor} descriptor exactly as {@link obtain} will be asked for it:
+     * after any rewrite for the attachments it is drawn into
+     * @returns {Promise<void>} settles once the pipeline is cached or has failed; never rejects
+     */
+    prepare(descriptor: RenderPipelineDescriptor): Promise<void>;
     #private;
 }
 export type ShaderModuleCompiler = import("../shader/ShaderModuleCompiler.js").ShaderModuleCompiler;
 export type PipelineLayoutManager = import("./PipelineLayoutManager.js").PipelineLayoutManager;
+export type PipelineEnquiry = import("./PipelineEnquiry.js").PipelineEnquiry;
 import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
 //# sourceMappingURL=RenderPipelineManager.d.ts.map

package/src/shade/device/pipeline/RenderPipelineManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderPipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/RenderPipelineManager.js"],"names":[],"mappings":"AAKA;;;GAGG;AAGH;IA8BI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IArCD;;;OAGG;IACH,0EAEC;IA2FD;;;;;OAKG;IACH,mBAJW,wBAAwB,6BACxB,kBAAkB,qBAgB5B;;CAEJ;mCAtIY,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;yCAL9B,8DAA8D"}
+{"version":3,"file":"RenderPipelineManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/pipeline/RenderPipelineManager.js"],"names":[],"mappings":"AAKA;;;;GAIG;AAGH;IA8CI;;;;;OAKG;IACH,wCAHW,qBAAqB,WACrB,oBAAoB,EAc9B;IArDD;;;OAGG;IACH,0EAEC;IAoBD;;;;OAIG;IACH,4BAEC;IA4FD;;;;;OAKG;IACH,mBAJW,wBAAwB,6BACxB,kBAAkB,qBAgB5B;IAED;;;;;;;;;;;OAWG;IACH,oBAJW,wBAAwB,GAEtB,QAAQ,IAAI,CAAC,CAuCzB;;CAEJ;mCAtNY,OAAO,mCAAmC,EAAE,oBAAoB;oCAChE,OAAO,4BAA4B,EAAE,qBAAqB;8BAC1D,OAAO,sBAAsB,EAAE,eAAe;yCANlB,8DAA8D"}