@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/descriptor/pipeline/render/RenderPipelineDescriptor.js

@@ -1,172 +1,176 @@
-import { assert } from "../../../../core/assert.js";
-import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
-import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
-import { optional_clone } from "../../../../core/model/object/optional_clone.js";
-import { objectsEqual } from "../../../../core/function/objectsEqual.js";
-import { optional_hash } from "../../../../core/model/object/optional_hash.js";
-import { PipelineDescriptorBase } from "../PipelineDescriptorBase.js";
-import { DepthStencilState } from "./DepthStencilState.js";
-import { FragmentState } from "./FragmentState.js";
-import { MultisampleState } from "./MultisampleState.js";
-import { PrimitiveState } from "./PrimitiveState.js";
-import { VertexState } from "./VertexState.js";
-
-
-/**
- * Wraps {@link GPURenderPipelineDescriptor}
- * This wrapper exists to simplify caching, as we have explicit normalized descriptors with equality and hash methods
- * NOTE: this object can be passed directly to WebGPU and is expected to work
- * NOTE: descriptors should be treated as immutable to avoid problems with cache
- * @see https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor
- */
-export class RenderPipelineDescriptor extends PipelineDescriptorBase {
-    /**
-     *
-     * @type {VertexState}
-     */
-    vertex = new VertexState();
-
-    /**
-     * @type {PrimitiveState}
-     */
-    primitive = new PrimitiveState();
-
-    /**
-     * @type {DepthStencilState|undefined}
-     */
-    depthStencil;
-
-    /**
-     * @type {MultisampleState}
-     */
-    multisample = new MultisampleState();
-
-    /**
-     * If undefined "no-color-output" mode is enabled
-     * @type {FragmentState|undefined}
-     */
-    fragment;
-
-
-    /**
-     *
-     * @param {} json
-     */
-    static from(json) {
-        const r = new RenderPipelineDescriptor();
-
-        r.fromJSON(json);
-
-        return r;
-    }
-
-    /**
-     *
-     * @param {GPURenderPipelineDescriptor} json
-     */
-    fromJSON(json) {
-        super.fromJSON(json);
-
-        assert.defined(json.vertex, '.vertex');
-
-        this.vertex.fromJSON(json.vertex);
-
-        if (json.fragment === undefined) {
-            this.fragment = undefined;
-        } else {
-            this.fragment = FragmentState.fromJSON(json.fragment);
-        }
-
-        if (json.primitive === undefined) {
-            this.primitive = new PrimitiveState();
-        } else {
-            this.primitive.fromJSON(json.primitive);
-        }
-
-        this.multisample.fromJSON(json.multisample);
-
-        if (json.depthStencil === undefined) {
-            this.depthStencil = undefined;
-        } else {
-
-            this.depthStencil = DepthStencilState.from(json.depthStencil);
-        }
-
-    }
-
-    /**
-     *
-     * @param {RenderPipelineDescriptor} other
-     * @return {boolean}
-     */
-    equals(other) {
-        if (this === other) {
-            return true;
-        }
-
-        if (!this.vertex.equals(other.vertex)) {
-            return false;
-        }
-
-        if (!this.primitive.equals(other.primitive)) {
-            return false;
-        }
-
-        if (!objectsEqual(this.depthStencil, other.depthStencil)) {
-            return false;
-        }
-
-        if (!this.multisample.equals(other.multisample)) {
-            return false;
-        }
-
-        if (!objectsEqual(this.fragment, other.fragment)) {
-            return false;
-        }
-
-        return super.equals(other);
-    }
-
-    /**
-     * Hash code, 32bit integer
-     * @returns {number}
-     */
-    hash() {
-        return hash_mix2(
-            hash_mix3(
-                super.hash(),
-                this.vertex.hash(),
-                this.primitive.hash()
-            ),
-            optional_hash(this.fragment)
-        );
-    }
-
-    /**
-     *
-     * @param {RenderPipelineDescriptor} other
-     */
-    copy(other) {
-        super.copy(other);
-
-        this.vertex.copy(other.vertex);
-        this.fragment = optional_clone(other.fragment);
-        this.primitive.copy(other.primitive);
-        this.depthStencil = optional_clone(other.depthStencil);
-        this.multisample.copy(other.multisample);
-    }
-
-    /**
-     *
-     * @return {RenderPipelineDescriptor}
-     */
-    clone() {
-        const r = new RenderPipelineDescriptor();
-
-        r.copy(this);
-
-        return r;
-    }
-}
-
-RenderPipelineDescriptor.prototype.isRenderPipelineDescriptor = true;
+import { assert } from "../../../../core/assert.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { optional_clone } from "../../../../core/model/object/optional_clone.js";
+import { objectsEqual } from "../../../../core/function/objectsEqual.js";
+import { optional_hash } from "../../../../core/model/object/optional_hash.js";
+import { PipelineDescriptorBase } from "../PipelineDescriptorBase.js";
+import { DepthStencilState } from "./DepthStencilState.js";
+import { FragmentState } from "./FragmentState.js";
+import { MultisampleState } from "./MultisampleState.js";
+import { PrimitiveState } from "./PrimitiveState.js";
+import { VertexState } from "./VertexState.js";
+
+
+/**
+ * Wraps {@link GPURenderPipelineDescriptor}
+ * This wrapper exists to simplify caching, as we have explicit normalized descriptors with equality and hash methods
+ * NOTE: this object can be passed directly to WebGPU and is expected to work
+ * NOTE: descriptors should be treated as immutable to avoid problems with cache
+ * @see https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor
+ */
+export class RenderPipelineDescriptor extends PipelineDescriptorBase {
+    /**
+     *
+     * @type {VertexState}
+     */
+    vertex = new VertexState();
+
+    /**
+     * @type {PrimitiveState}
+     */
+    primitive = new PrimitiveState();
+
+    /**
+     * @type {DepthStencilState|undefined}
+     */
+    depthStencil;
+
+    /**
+     * @type {MultisampleState}
+     */
+    multisample = new MultisampleState();
+
+    /**
+     * If undefined "no-color-output" mode is enabled
+     * @type {FragmentState|undefined}
+     */
+    fragment;
+
+
+    /**
+     *
+     * @param {} json
+     */
+    static from(json) {
+        const r = new RenderPipelineDescriptor();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+
+    /**
+     *
+     * @param {GPURenderPipelineDescriptor} json
+     */
+    fromJSON(json) {
+        super.fromJSON(json);
+
+        assert.defined(json.vertex, '.vertex');
+
+        this.vertex.fromJSON(json.vertex);
+
+        if (json.fragment === undefined) {
+            this.fragment = undefined;
+        } else {
+            this.fragment = FragmentState.fromJSON(json.fragment);
+        }
+
+        if (json.primitive === undefined) {
+            this.primitive = new PrimitiveState();
+        } else {
+            this.primitive.fromJSON(json.primitive);
+        }
+
+        this.multisample.fromJSON(json.multisample);
+
+        if (json.depthStencil === undefined) {
+            this.depthStencil = undefined;
+        } else {
+
+            this.depthStencil = DepthStencilState.from(json.depthStencil);
+        }
+
+    }
+
+    /**
+     *
+     * @param {RenderPipelineDescriptor} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+
+        if (!this.vertex.equals(other.vertex)) {
+            return false;
+        }
+
+        if (!this.primitive.equals(other.primitive)) {
+            return false;
+        }
+
+        if (!objectsEqual(this.depthStencil, other.depthStencil)) {
+            return false;
+        }
+
+        if (!this.multisample.equals(other.multisample)) {
+            return false;
+        }
+
+        if (!objectsEqual(this.fragment, other.fragment)) {
+            return false;
+        }
+
+        return super.equals(other);
+    }
+
+    /**
+     * Hash code, 32bit integer
+     * @returns {number}
+     */
+    hash() {
+        return hash_mix3(
+            hash_mix3(
+                super.hash(),
+                this.vertex.hash(),
+                this.primitive.hash()
+            ),
+            optional_hash(this.depthStencil),
+            hash_mix2(
+                this.multisample.hash(),
+                optional_hash(this.fragment)
+            )
+        );
+    }
+
+    /**
+     *
+     * @param {RenderPipelineDescriptor} other
+     */
+    copy(other) {
+        super.copy(other);
+
+        this.vertex.copy(other.vertex);
+        this.fragment = optional_clone(other.fragment);
+        this.primitive.copy(other.primitive);
+        this.depthStencil = optional_clone(other.depthStencil);
+        this.multisample.copy(other.multisample);
+    }
+
+    /**
+     *
+     * @return {RenderPipelineDescriptor}
+     */
+    clone() {
+        const r = new RenderPipelineDescriptor();
+
+        r.copy(this);
+
+        return r;
+    }
+}
+
+RenderPipelineDescriptor.prototype.isRenderPipelineDescriptor = true;

package/src/shade/descriptor/pipeline/render/StencilFaceState.d.ts

@@ -24,6 +24,10 @@ export class StencilFaceState implements GPUStencilFaceState {
      * @return {boolean}
      */
     equals(other: StencilFaceState): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
     /**
      *
      * @param {GPUStencilFaceState} json

package/src/shade/descriptor/pipeline/render/StencilFaceState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StencilFaceState.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/render/StencilFaceState.js"],"names":[],"mappings":"AAAA;;GAEG;AACH,yCAFe,mBAAmB;IAI9B;;OAEG;IACH,4BAAkB;IAClB;;OAEG;IACH,iCAAoB;IACpB;;OAEG;IACH,4BAAe;IACf;;OAEG;IACH,4BAAe;IAEf;;;;OAIG;IACH,cAHW,gBAAgB,GACf,OAAO,CAQlB;IAED;;;OAGG;IACH,2CAwBC;IAED;;;OAGG;IACH,YAFW,gBAAgB,QAO1B;IAED;;;OAGG;IACH,SAFY,gBAAgB,CAQ3B;CACJ"}
+{"version":3,"file":"StencilFaceState.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/pipeline/render/StencilFaceState.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,yCAFe,mBAAmB;IAI9B;;OAEG;IACH,4BAAkB;IAClB;;OAEG;IACH,iCAAoB;IACpB;;OAEG;IACH,4BAAe;IACf;;OAEG;IACH,4BAAe;IAEf;;;;OAIG;IACH,cAHW,gBAAgB,GACf,OAAO,CAQlB;IAED;;OAEG;IACH,QAFa,MAAM,CAalB;IAED;;;OAGG;IACH,2CAwBC;IAED;;;OAGG;IACH,YAFW,gBAAgB,QAO1B;IAED;;;OAGG;IACH,SAFY,gBAAgB,CAQ3B;CACJ"}

package/src/shade/descriptor/pipeline/render/StencilFaceState.js

@@ -1,88 +1,107 @@
-/**
- * @implements GPUStencilFaceState
- */
-export class StencilFaceState {
-
-    /**
-     * @type {GPUCompareFunction}
-     */
-    compare = "always"
-    /**
-     * @type {GPUStencilOperation}
-     */
-    depthFailOp = "keep"
-    /**
-     * @type {GPUStencilOperation}
-     */
-    failOp = "keep"
-    /**
-     * @type {GPUStencilOperation}
-     */
-    passOp = "keep"
-
-    /**
-     *
-     * @param {StencilFaceState} other
-     * @return {boolean}
-     */
-    equals(other) {
-        return this.compare === other.compare
-            && this.depthFailOp === other.depthFailOp
-            && this.failOp === other.failOp
-            && this.passOp === other.passOp
-            ;
-    }
-
-    /**
-     *
-     * @param {GPUStencilFaceState} json
-     */
-    fromJSON(json = {}) {
-        if (json.compare !== undefined) {
-            this.compare = json.compare;
-        } else {
-            this.compare = "always";
-        }
-
-        if (json.depthFailOp !== undefined) {
-            this.depthFailOp = json.depthFailOp;
-        } else {
-            this.depthFailOp = "keep";
-        }
-
-        if (json.failOp !== undefined) {
-            this.failOp = json.failOp;
-        } else {
-            this.failOp = "keep";
-        }
-
-        if (json.passOp !== undefined) {
-            this.passOp = json.passOp;
-        } else {
-            this.passOp = "keep";
-        }
-    }
-
-    /**
-     *
-     * @param {StencilFaceState} other
-     */
-    copy(other) {
-        this.compare = other.compare;
-        this.depthFailOp = other.depthFailOp;
-        this.failOp = other.failOp;
-        this.passOp = other.passOp;
-    }
-
-    /**
-     *
-     * @return {StencilFaceState}
-     */
-    clone() {
-        const r = new StencilFaceState();
-
-        r.copy(this);
-
-        return r;
-    }
-}
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
+
+/**
+ * @implements GPUStencilFaceState
+ */
+export class StencilFaceState {
+
+    /**
+     * @type {GPUCompareFunction}
+     */
+    compare = "always"
+    /**
+     * @type {GPUStencilOperation}
+     */
+    depthFailOp = "keep"
+    /**
+     * @type {GPUStencilOperation}
+     */
+    failOp = "keep"
+    /**
+     * @type {GPUStencilOperation}
+     */
+    passOp = "keep"
+
+    /**
+     *
+     * @param {StencilFaceState} other
+     * @return {boolean}
+     */
+    equals(other) {
+        return this.compare === other.compare
+            && this.depthFailOp === other.depthFailOp
+            && this.failOp === other.failOp
+            && this.passOp === other.passOp
+            ;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return hash_mix2(
+            hash_mix2(
+                computeStringHash(this.compare),
+                computeStringHash(this.depthFailOp)
+            ),
+            hash_mix2(
+                computeStringHash(this.failOp),
+                computeStringHash(this.passOp)
+            )
+        );
+    }
+
+    /**
+     *
+     * @param {GPUStencilFaceState} json
+     */
+    fromJSON(json = {}) {
+        if (json.compare !== undefined) {
+            this.compare = json.compare;
+        } else {
+            this.compare = "always";
+        }
+
+        if (json.depthFailOp !== undefined) {
+            this.depthFailOp = json.depthFailOp;
+        } else {
+            this.depthFailOp = "keep";
+        }
+
+        if (json.failOp !== undefined) {
+            this.failOp = json.failOp;
+        } else {
+            this.failOp = "keep";
+        }
+
+        if (json.passOp !== undefined) {
+            this.passOp = json.passOp;
+        } else {
+            this.passOp = "keep";
+        }
+    }
+
+    /**
+     *
+     * @param {StencilFaceState} other
+     */
+    copy(other) {
+        this.compare = other.compare;
+        this.depthFailOp = other.depthFailOp;
+        this.failOp = other.failOp;
+        this.passOp = other.passOp;
+    }
+
+    /**
+     *
+     * @return {StencilFaceState}
+     */
+    clone() {
+        const r = new StencilFaceState();
+
+        r.copy(this);
+
+        return r;
+    }
+}

package/src/shade/playground/particle_ecs/README.md

@@ -86,11 +86,11 @@ have shown.
 
 Change anything and the fire changes. What happens is worth knowing, because it is the reason a live
 edit is safe: the document recompiles and the entity's `ParticleEffect` component is **removed and
-added back**, not mutated. An edit can change the attribute layout, and a layout change repoints
-every word of a particle record — replacing the component retires the emitter's table row and takes
-its generation with it, so the particles running the old program are killed rather than reinterpreted
-under the new one. The effect restarts; for a fire that is what you wanted to see anyway. An effect
-that does not compile leaves the previous one burning and says so in the toolbar.
+added back**, not mutated. An edit can change the particle field layout, and a layout change
+repoints every word of a particle record — replacing the component retires the emitter's table row
+and takes its generation with it, so the particles running the old program are killed rather than
+reinterpreted under the new one. The effect restarts; for a fire that is what you wanted to see
+anyway. An effect that does not compile leaves the previous one burning and says so in the toolbar.
 
 **The round trip is the point.** Each effect *is* a saved document — `effects/flame.json` and its
 three siblings, which is what `bonfire_effects.js` loads. Press **Download**, drop the file over the
@@ -100,8 +100,8 @@ authoring code to keep in step, because the file the editor writes is the file t
 
 Two things to know before editing one:
 
-- **One store per attribute per phase.** Every store runs and nothing orders them, so a second store
-  does not refine the first, it replaces it. That is how the smoke's drag silently ate its own
+- **One store per particle field per phase.** Every store runs and nothing orders them, so a second
+  store does not refine the first, it replaces it. That is how the smoke's drag silently ate its own
   velocity integration — the picture only looked slightly wrong — until the editor's validator was
   pointed at it. The graph editor calls it an error and `bonfire.spec.js` pins that none of the four
   has one; nothing on the runtime path checks.
@@ -188,7 +188,8 @@ device:
   budget, and the reason it is a test rather than a comment: one program needing more than the
   register file holds swaps emit and simulate for storage-backed variants *for the whole system*, so
   an effect that grows past it does not slow itself down, it slows down every effect in the scene,
-- the render channels resolve to attributes that exist, and the blend modes are what each effect is,
+- the render channels resolve to particle fields that exist, and the blend modes are what each
+  effect is,
 - every entity built carries a `Transform64` and exactly one more component,
 - the sky averages a hundredth of daylight and its brightest texel is where `MOON_DIRECTION` points,
   so the shadows on the ground fall away from the moon that is actually in the map.

package/src/shade/playground/particle_ecs/bonfire_editor.js

@@ -22,9 +22,9 @@ import {
  *
  * The document recompiles and the entity's component is **replaced** — removed and added back — not
  * mutated. That is deliberate and it is the reason a live edit is safe at all: an edit can change the
- * attribute layout, and a layout change repoints every word of a particle record. Replacing the
- * component retires the emitter's table row and takes its generation with it, so the particles that
- * were running the old program are killed on the next simulate rather than being reinterpreted
+ * particle field layout, and a layout change repoints every word of a particle record. Replacing
+ * the component retires the emitter's table row and takes its generation with it, so the particles
+ * that were running the old program are killed on the next simulate rather than being reinterpreted
  * under the new one. Mutating `effect.program` in place would keep the row, keep the particles, and
  * read their records through a layout that no longer describes them.
  *

package/src/shade/playground/particle_ecs/bonfire_effects.d.ts

@@ -73,7 +73,7 @@ export function bonfire_sprite_urls(textures?: object): {
  *
  * ## They are documents, not code
  *
- * Each is a {@link ParticleEffectDocument} saved as JSON in `effects/`: the per-particle attribute
+ * Each is a {@link ParticleEffectDocument} saved as JSON in `effects/`: the particle field
  * declarations, the INIT and UPDATE node graphs with the positions they were arranged at, and the
  * emitter settings. That is the whole effect, and it is what the editor opens — press `E` on the
  * page, change something, download the result, drop it over the file, reload. There is no porting
@@ -91,7 +91,7 @@ export function bonfire_sprite_urls(textures?: object): {
  *
  * - **INIT** places the particle, gives it a velocity, and rolls its lifetime, its base size and a
  *   personal `seed`. There is no built-in age or lifetime — the effect declares what it needs, which
- *   is why `age` and `life` are ordinary attributes.
+ *   is why `age` and `life` are ordinary particle fields.
  * - **UPDATE** advances the age, kills the particle when it runs out, integrates the forces, and
  *   drives the drawn size and colour from `age / life` through a ramp — a curve for the size and a
  *   gradient for the colour, both written into the program as arithmetic rather than sampled from a
@@ -99,10 +99,10 @@ export function bonfire_sprite_urls(textures?: object): {
  *
  * Two things are worth knowing before editing one:
  *
- * - **One store per attribute per phase.** Every store runs and nothing orders them, so a second
- *   store does not refine the first, it replaces it — which is how the smoke's drag silently ate its
- *   own velocity integration until the editor's validator was pointed at it. The graph editor calls
- *   that an error; nothing at runtime does.
+ * - **One store per particle field per phase.** Every store runs and nothing orders them, so a
+ *   second store does not refine the first, it replaces it — which is how the smoke's drag silently
+ *   ate its own velocity integration until the editor's validator was pointed at it. The graph
+ *   editor calls that an error; nothing at runtime does.
  * - **The register budget is shared.** The VM keeps its file in shader registers, and one program
  *   needing more than `PARTICLE_VM_FAST_REGISTER_SLOTS` swaps emit and simulate for storage-backed
  *   variants *for the whole system* — so an effect that grows past it slows down every effect in the