@woosh/meep-engine 3.11.1 → 3.11.3

package/src/engine/graphics3/ParticipatingMediaSystem3.js

@@ -0,0 +1,184 @@
+import { assert } from "../../core/assert.js";
+import { isArrayEqualStrict } from "../../core/collection/array/isArrayEqualStrict.js";
+import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+
+/**
+ * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
+ *
+ * The same shape as {@link LightSystem3}: the ECS says what exists and where, and this keeps the
+ * renderer's own objects in step. A {@link ParticipatingMediaVolume} is a unit cube posed by a
+ * transform, so an entity's `Transform` is the volume — position, size and orientation with no
+ * translation step in between.
+ *
+ * **The transform is taken as world-space, with no hierarchy applied**, which is what the volume
+ * model can express: a volume is an oriented box in the scene and Shade has no parent chain to walk
+ * for it. Parenting a fog volume to a moving entity therefore leaves the fog where the child's own
+ * transform puts it. The lights are placed the same way, for the same reason.
+ *
+ * **Changes are polled once a frame rather than subscribed to.** A `Transform` announces itself and
+ * nothing else here does — a density tuned by an editor slider, a particle spec swapped wholesale
+ * for a different Mie solution — so subscribing would cover one field in three and the other two
+ * would still have to be polled. Two paths that have to agree, where one does the whole job. It
+ * costs about two dozen float comparisons per volume per frame and a scene holds volumes in the
+ * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
+ * change is visible within a frame rather than instantly.
+ *
+ * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
+ * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
+ * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
+ * frame it decides nothing has to happen.
+ *
+ * @see ParticipatingMedia the component
+ * @see SceneVolumetrics what the volumes are handed to
+ */
+export class ParticipatingMediaSystem3 extends System {
+
+    dependencies = [ParticipatingMedia, Transform];
+
+    /**
+     * @type {GraphicsEngine3}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {Map<number, {component: ParticipatingMedia, transform: Transform, volume: ParticipatingMediaVolume}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#graphics.set_scene(this.#scene);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(component, transform, entity) {
+        const volume = new ParticipatingMediaVolume();
+
+        participating_media_volume_write(volume, component, transform);
+
+        this.#scene.volumetrics.add(volume);
+
+        this.#entries.set(entity, { component, transform, volume });
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        const volumetrics = this.#scene.volumetrics;
+
+        for (const entry of this.#entries.values()) {
+            const volume = entry.volume;
+
+            if (participating_media_volume_is_current(volume, entry.component, entry.transform)) {
+                continue;
+            }
+
+            participating_media_volume_write(volume, entry.component, entry.transform);
+
+            volumetrics.invalidate();
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#scene.volumetrics.remove(entry.volume);
+
+        this.#entries.delete(entity);
+    }
+}
+
+/**
+ * Copy what the component and its transform say onto the volume Shade will render.
+ *
+ * The particle spec is **copied, not referenced**: two entities are routinely built from the same
+ * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
+ * retune the other's.
+ *
+ * @param {ParticipatingMediaVolume} volume Shade's
+ * @param {ParticipatingMedia} component meep's
+ * @param {Transform} transform where the box is
+ */
+export function participating_media_volume_write(volume, component, transform) {
+    volume.density = component.density;
+    volume.fade_distance = component.fade_distance;
+
+    volume.particle_spec.copy(component.particle_spec);
+
+    volume.transform.copy(transform);
+}
+
+/**
+ * Whether the volume already says what the component and transform say.
+ *
+ * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
+ * scene's volumetrics table a trip to the GPU.
+ *
+ * **The transform is compared by its matrix rather than by `Transform.equals`**, because the matrix
+ * is the entire transform the GPU is given — the volume's position, rotation and scale are never
+ * read on their own. That makes this exactly the question worth asking, "would the upload differ",
+ * and it catches a transform posed by writing its matrix, which comparing position, rotation and
+ * scale would not.
+ *
+ * @param {ParticipatingMediaVolume} volume
+ * @param {ParticipatingMedia} component
+ * @param {Transform} transform
+ * @returns {boolean}
+ */
+export function participating_media_volume_is_current(volume, component, transform) {
+    return volume.density === component.density
+        && volume.fade_distance === component.fade_distance
+        && isArrayEqualStrict(volume.transform.matrix, transform.matrix)
+        && volume.particle_spec.equals(component.particle_spec);
+}

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

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#354@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#356@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#354@#clear_field"(fluid: FluidComponent): void;
+    static "__#356@#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 "__#354@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#356@#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 "__#354@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#356@#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/descriptor/pipeline/PipelineLayoutDescriptor.d.ts

@@ -12,12 +12,13 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      * @param {GPUShaderStage|number} stage
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      */
-    static forStage(stage: GPUShaderStage | number, bindings: (BufferBindingLayout | SamplerBindingLayout | TextureBindingLayout | StorageTextureBindingLayout | ExternalTextureBindingLayout)[][]): PipelineLayoutDescriptor;
+    static forStage(stage: GPUShaderStage | number, bindings: (BufferBindingLayout | SamplerBindingLayout | TextureBindingLayout | StorageTextureBindingLayout | ExternalTextureBindingLayout)[][], immediate_size?: number): PipelineLayoutDescriptor;
     /**
      *
      * @param {BindGroupLayoutDescriptor[]} bind_groups
+     * @param {number} [immediate_size] bytes of immediate data, 0 when the shader declares none
      */
-    static from(bind_groups: BindGroupLayoutDescriptor[]): PipelineLayoutDescriptor;
+    static from(bind_groups: BindGroupLayoutDescriptor[], immediate_size?: number): PipelineLayoutDescriptor;
     /**
      *
      * @param {JSONPipelineLayoutDescriptor} json
@@ -29,6 +30,19 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      * @type {BindGroupLayoutDescriptor[]}
      */
     bindGroupLayouts: BindGroupLayoutDescriptor[];
+    /**
+     * Bytes of immediate data the pipelines using this layout read, 0 when they read none.
+     *
+     * Not a bind group and not a binding — immediate data is part of the shader interface without
+     * being part of its resource interface, so it hangs off the layout itself.
+     *
+     * Must be a multiple of 4 and no larger than the device's `maxImmediateSize`; both are
+     * validated where the layout is created, not here, because this descriptor never sees a device.
+     *
+     * @see https://www.w3.org/TR/webgpu/#dom-gpupipelinelayoutdescriptor-immediatesize
+     * @type {number}
+     */
+    immediateSize: number;
     /**
      *
      * @param {JSONPipelineLayoutDescriptor} json

package/src/shade/descriptor/pipeline/PipelineLayoutDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PipelineLayoutDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;GAEG;AACH;IAQI;;;;OAIG;IACH,uBAHW,iBAAe,MAAM,YACrB,CAAC,8HAAsH,CAAC,EAAE,EAAE,4BAgBtI;IAGD;;;OAGG;IACH,yBAFW,yBAAyB,EAAE,4BAsBrC;IAED;;;;OAIG;IACH,gDAFY,wBAAwB,CAQnC;IAjED;;;OAGG;IACH,kBAFU,yBAAyB,EAAE,CAEhB;IAgErB;;;OAGG;IACH,8CAQC;IASD,4BAOC;IAED;;;OAGG;IACH,YAFW,wBAAwB,QAKlC;IAED;;;OAGG;IACH,SAFY,wBAAwB,CAQnC;IAGL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;CAN5D;;qCAnIoC,4BAA4B;0CADvB,yCAAyC"}
+{"version":3,"file":"PipelineLayoutDescriptor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;GAEG;AACH;IAsBI;;;;OAIG;IACH,uBAHW,iBAAe,MAAM,YACrB,CAAC,8HAAsH,CAAC,EAAE,EAAE,qDAgBtI;IAGD;;;;OAIG;IACH,yBAHW,yBAAyB,EAAE,mBAC3B,MAAM,4BAyBhB;IAED;;;;OAIG;IACH,gDAFY,wBAAwB,CAQnC;IAnFD;;;OAGG;IACH,kBAFU,yBAAyB,EAAE,CAEhB;IAErB;;;;;;;;;;;OAWG;IACH,eAFU,MAAM,CAEC;IAoEjB;;;OAGG;IACH,8CASC;IAYD,4BAQC;IAED;;;OAGG;IACH,YAFW,wBAAwB,QAMlC;IAED;;;OAGG;IACH,SAFY,wBAAwB,CAQnC;IAGL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;CAN5D;;qCA3JoC,4BAA4B;0CADvB,yCAAyC"}

package/src/shade/descriptor/pipeline/PipelineLayoutDescriptor.js

@@ -24,12 +24,26 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
      */
     bindGroupLayouts = []
 
+    /**
+     * Bytes of immediate data the pipelines using this layout read, 0 when they read none.
+     *
+     * Not a bind group and not a binding — immediate data is part of the shader interface without
+     * being part of its resource interface, so it hangs off the layout itself.
+     *
+     * Must be a multiple of 4 and no larger than the device's `maxImmediateSize`; both are
+     * validated where the layout is created, not here, because this descriptor never sees a device.
+     *
+     * @see https://www.w3.org/TR/webgpu/#dom-gpupipelinelayoutdescriptor-immediatesize
+     * @type {number}
+     */
+    immediateSize = 0
+
     /**
      *
      * @param {GPUShaderStage|number} stage
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      */
-    static forStage(stage, bindings) {
+    static forStage(stage, bindings, immediate_size = 0) {
         assert.isArray(bindings, 'bindings');
 
         const bind_group_count = bindings.length;
@@ -42,20 +56,24 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
             bind_groups[i] = BindGroupLayoutDescriptor.forStage(stage, "", binding_set);
         }
 
-        return PipelineLayoutDescriptor.from(bind_groups);
+        return PipelineLayoutDescriptor.from(bind_groups, immediate_size);
     }
 
 
     /**
      *
      * @param {BindGroupLayoutDescriptor[]} bind_groups
+     * @param {number} [immediate_size] bytes of immediate data, 0 when the shader declares none
      */
-    static from(bind_groups) {
+    static from(bind_groups, immediate_size = 0) {
 
         assert.isArray(bind_groups, 'bind_groups');
+        assert.isNonNegativeInteger(immediate_size, 'immediate_size');
 
         const r = new PipelineLayoutDescriptor();
 
+        r.immediateSize = immediate_size;
+
         const count = bind_groups.length;
 
         for (let i = 0; i < count; i++) {
@@ -98,12 +116,16 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
         const bindGroupLayouts = json.bindGroupLayouts ?? [];
 
         this.bindGroupLayouts = bindGroupLayouts.map(BindGroupLayoutDescriptor.fromJSON);
+        this.immediateSize = json.immediateSize ?? 0;
     }
 
     hash() {
         return combine_hash(
             super.hash(),
-            computeHashArray(this.bindGroupLayouts, invokeObjectHash)
+            computeHashArray(this.bindGroupLayouts, invokeObjectHash),
+            // two layouts that differ only in immediate size are different layouts; leaving this out
+            // would alias them in the manager's cache and hand a pipeline someone else's budget
+            this.immediateSize
         );
     }
 
@@ -113,6 +135,7 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
         }
 
         return super.equals(other)
+            && this.immediateSize === other.immediateSize
             && isArrayEqual(this.bindGroupLayouts, other.bindGroupLayouts);
     }
 
@@ -123,6 +146,7 @@ export class PipelineLayoutDescriptor extends ObjectDescriptorBase {
     copy(other) {
         super.copy(other);
         this.bindGroupLayouts = other.bindGroupLayouts.map(optional_clone);
+        this.immediateSize = other.immediateSize;
     }
 
     /**

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

@@ -12,7 +12,7 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      * @param {Object<number>} [constants]
      */
-    static simplified({ label, code, bindings, constants }: string): ComputePipelineDescriptor;
+    static simplified({ label, code, bindings, constants, immediate_size }: string): ComputePipelineDescriptor;
     /**
      *
      * @param {GPUComputePipelineDescriptor} json

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,wDALW,MAAM,6BAsBhB;IAED;;;OAGG;IACH,+EAMC;IAxDD,2BAAkC;IA0DlC;;;OAGG;IACH,mDAMC;IAED;;;;OAIG;IACH,cAHW,yBAAyB,GACxB,OAAO,CAMlB;IAUL;;;OAGG;IACH,sCAFU,OAAO,CAE8C;CAN9D;uCA7FsC,8BAA8B;kCAEnC,yBAAyB;yCADlB,gCAAgC"}
+{"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"}

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

@@ -34,7 +34,7 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
      * @param {(BufferBindingLayout|SamplerBindingLayout|TextureBindingLayout|StorageTextureBindingLayout|ExternalTextureBindingLayout)[][]} bindings
      * @param {Object<number>} [constants]
      */
-    static simplified({ label = "", code, bindings, constants }) {
+    static simplified({ label = "", code, bindings, constants, immediate_size = 0 }) {
         assert.isString(label, 'label');
 
         const r = new ComputePipelineDescriptor();
@@ -42,7 +42,10 @@ export class ComputePipelineDescriptor extends PipelineDescriptorBase {
         r.label = label;
         r.compute.module = ShaderModuleDescriptor.fromCode(code);
 
-        r.layout = PipelineLayoutDescriptor.forStage(GPUShaderStage.COMPUTE, bindings);
+        // `immediate_size` must travel with the bindings: a shader that reads immediate data whose
+        // layout declares none is a pipeline-creation error on a real device, and the two numbers are
+        // derived from the same descriptor
+        r.layout = PipelineLayoutDescriptor.forStage(GPUShaderStage.COMPUTE, bindings, immediate_size);
 
         if(constants !== undefined){
             assert.isObject(constants,'constants');