@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/ParticipatingMedia.js

@@ -1,203 +1,203 @@
-import { assert } from "../../core/assert.js";
-import { combine_hash } from "../../core/collection/array/combine_hash.js";
-import { rgb_to_luminance } from "../../core/color/rgb_to_luminance.js";
-import { computeHashFloat } from "../../core/primitives/numbers/computeHashFloat.js";
-import {
-    VOLUMETRIC_PARTICLE_SPEC_FOG,
-    VolumetricsParticleSpec
-} from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
-
-/**
- * Particles per cubic metre of dense fog, which is what a medium is until it is told otherwise.
- * @type {number}
- */
-const DEFAULT_DENSITY = 3e7;
-
-/**
- * @type {number}
- */
-const DEFAULT_FADE_DISTANCE = 0.1;
-
-/**
- * A box of fog, smoke, dust or cloud that an entity carries around.
- *
- * **What is in here is the medium; the {@link Transform} beside it is the box.** Shade's
- * {@link ParticipatingMediaVolume} is a unit cube centred on the origin, posed by a transform — so
- * position, size and orientation are already an ECS concept and there is nothing to restate. Which
- * is also why this component does nothing on its own: {@link ParticipatingMediaSystem3} links it
- * against a `Transform` and only that pair becomes a volume.
- *
- * **Three numbers, in two different currencies.** {@link particle_spec} is what a single particle
- * does to light — a Mie solution, physical and reusable — and {@link density} is how many of them
- * there are per cubic metre. The pair is what makes smoke and fog different things rather than the
- * same fog at two strengths. Authoring in raw density means knowing the cross-sections, so
- * {@link target_extinction} exists to author the other way round: say how much light the medium
- * should swallow and let the particle decide the count.
- *
- * @see ParticipatingMediaSystem3 what turns this into something the renderer draws
- * @see ParticipatingMediaVolume the renderer's own object
- */
-export class ParticipatingMedia {
-
-    /**
-     * Particles per cubic metre.
-     *
-     * Physically a count, so the numbers are large — the default is dense fog — and the useful range
-     * depends entirely on {@link particle_spec}: a cloud droplet blocks far more light than a haze
-     * particle, so the same count of them is a very different medium.
-     *
-     * @type {number}
-     */
-    density = DEFAULT_DENSITY;
-
-    /**
-     * What one particle of this medium does to light.
-     *
-     * Defaults to fog. The generated `MIE_PARTICLES_STANDARD_PRECOMPUTED` library is where the
-     * physically meaningful values live — `VolumetricsParticleSpec.fromMeep` converts an entry of it
-     * into one of these.
-     *
-     * @type {VolumetricsParticleSpec}
-     */
-    particle_spec = VolumetricsParticleSpec.fromJSON(VOLUMETRIC_PARTICLE_SPEC_FOG);
-
-    /**
-     * How far in from the box's faces the medium fades out, in metres.
-     *
-     * **World-space, and deliberately not scaled by the transform**, so a 0.5 here is half a metre
-     * of softness whether the volume is a metre across or a hundred. Zero gives the box hard edges,
-     * which is visible as a straight line across the screen wherever the box crosses the view.
-     *
-     * @type {number}
-     */
-    fade_distance = DEFAULT_FADE_DISTANCE;
-
-    /**
-     * The medium's extinction per metre, which is {@link density} expressed in what it does rather
-     * than in how many particles it took.
-     *
-     * The point of it is that it is comparable across particles: a smoke volume and a fog volume set
-     * to the same target extinction swallow the same amount of light, while the same *density* in
-     * both would differ by orders of magnitude.
-     *
-     * **Derived, not stored** — writing it sets {@link density}, and changing `particle_spec`
-     * afterwards therefore changes what reading it back gives. The density is what survives a save.
-     *
-     * @returns {number}
-     */
-    get target_extinction() {
-        return this.density * rgb_to_luminance(...this.particle_spec.extinction);
-    }
-
-    /**
-     * @param {number} value
-     */
-    set target_extinction(value) {
-        assert.isNumber(value, 'target_extinction');
-        assert.isFinite(value, 'target_extinction');
-
-        const density = value / rgb_to_luminance(...this.particle_spec.extinction);
-
-        /*
-         Catches the one way this goes wrong: a particle spec that extinguishes nothing. A default-
-         constructed `VolumetricsParticleSpec` has zero cross-sections, and asking such a medium to
-         reach any extinction at all needs infinitely many of its particles. Rejecting it here names
-         the mistake; letting it through puts an `Infinity` in the GPU table, where it becomes a
-         screenful of NaN several passes later.
-        */
-        assert.isFinite(density, 'the density this target_extinction implies (the particle spec extinguishes nothing)');
-
-        this.density = density;
-    }
-
-    /**
-     * @param {*} json
-     * @returns {ParticipatingMedia}
-     */
-    static fromJSON(json) {
-        const r = new ParticipatingMedia();
-
-        r.fromJSON(json);
-
-        return r;
-    }
-
-    toJSON() {
-        const spec = this.particle_spec;
-
-        return {
-            density: this.density,
-            fade_distance: this.fade_distance,
-            particle_spec: {
-                scattering: spec.scattering.slice(),
-                extinction: spec.extinction.slice(),
-                radius: spec.radius,
-                g: spec.g
-            }
-        };
-    }
-
-    /**
-     * @param {number} [density]
-     * @param {number} [fade_distance]
-     * @param {object} [particle_spec] omitted resets the medium to fog rather than leaving whatever
-     * the component already held — a load has to determine the whole component, or an instance being
-     * reused would carry the previous level's particle into the next one
-     */
-    fromJSON({
-                 density = DEFAULT_DENSITY,
-                 fade_distance = DEFAULT_FADE_DISTANCE,
-                 particle_spec
-             }) {
-        assert.isNumber(density, 'density');
-        assert.isFinite(density, 'density');
-        assert.greaterThanOrEqual(density, 0, 'density must not be negative');
-
-        assert.isNumber(fade_distance, 'fade_distance');
-        assert.isFinite(fade_distance, 'fade_distance');
-        assert.greaterThanOrEqual(fade_distance, 0, 'fade_distance must not be negative');
-
-        this.density = density;
-        this.fade_distance = fade_distance;
-
-        if (particle_spec === undefined) {
-            this.particle_spec.copy(VOLUMETRIC_PARTICLE_SPEC_FOG);
-        } else {
-            this.particle_spec.fromJSON(particle_spec);
-        }
-    }
-
-    /**
-     * **The cross-sections and the radius are left out of this on purpose.** They run to 1e-16 and
-     * 1e-6, and {@link computeHashFloat} collapses anything that small to zero, so mixing them in
-     * would cost a multiply and buy no dispersion at all. A hash is allowed to collide;
-     * {@link equals} is the exact one.
-     *
-     * @returns {number}
-     */
-    hash() {
-        const spec = this.particle_spec;
-
-        return combine_hash(
-            computeHashFloat(this.density),
-            computeHashFloat(this.fade_distance),
-            computeHashFloat(spec.g)
-        );
-    }
-
-    /**
-     * @param {ParticipatingMedia} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return this.density === other.density
-            && this.fade_distance === other.fade_distance
-            && this.particle_spec.equals(other.particle_spec);
-    }
-}
-
-/**
- * @readonly
- * @type {string}
- */
-ParticipatingMedia.typeName = "ParticipatingMedia";
+import { assert } from "../../core/assert.js";
+import { combine_hash } from "../../core/collection/array/combine_hash.js";
+import { rgb_to_luminance } from "../../core/color/rgb_to_luminance.js";
+import { computeHashFloat } from "../../core/primitives/numbers/computeHashFloat.js";
+import {
+    VOLUMETRIC_PARTICLE_SPEC_FOG,
+    VolumetricsParticleSpec
+} from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+
+/**
+ * Particles per cubic metre of dense fog, which is what a medium is until it is told otherwise.
+ * @type {number}
+ */
+const DEFAULT_DENSITY = 3e7;
+
+/**
+ * @type {number}
+ */
+const DEFAULT_FADE_DISTANCE = 0.1;
+
+/**
+ * A box of fog, smoke, dust or cloud that an entity carries around.
+ *
+ * **What is in here is the medium; the {@link Transform} beside it is the box.** Shade's
+ * {@link ParticipatingMediaVolume} is a unit cube centred on the origin, posed by a transform — so
+ * position, size and orientation are already an ECS concept and there is nothing to restate. Which
+ * is also why this component does nothing on its own: {@link ParticipatingMediaSystem} links it
+ * against a `Transform` and only that pair becomes a volume.
+ *
+ * **Three numbers, in two different currencies.** {@link particle_spec} is what a single particle
+ * does to light — a Mie solution, physical and reusable — and {@link density} is how many of them
+ * there are per cubic metre. The pair is what makes smoke and fog different things rather than the
+ * same fog at two strengths. Authoring in raw density means knowing the cross-sections, so
+ * {@link target_extinction} exists to author the other way round: say how much light the medium
+ * should swallow and let the particle decide the count.
+ *
+ * @see ParticipatingMediaSystem what turns this into something the renderer draws
+ * @see ParticipatingMediaVolume the renderer's own object
+ */
+export class ParticipatingMedia {
+
+    /**
+     * Particles per cubic metre.
+     *
+     * Physically a count, so the numbers are large — the default is dense fog — and the useful range
+     * depends entirely on {@link particle_spec}: a cloud droplet blocks far more light than a haze
+     * particle, so the same count of them is a very different medium.
+     *
+     * @type {number}
+     */
+    density = DEFAULT_DENSITY;
+
+    /**
+     * What one particle of this medium does to light.
+     *
+     * Defaults to fog. The generated `MIE_PARTICLES_STANDARD_PRECOMPUTED` library is where the
+     * physically meaningful values live — `VolumetricsParticleSpec.fromMeep` converts an entry of it
+     * into one of these.
+     *
+     * @type {VolumetricsParticleSpec}
+     */
+    particle_spec = VolumetricsParticleSpec.fromJSON(VOLUMETRIC_PARTICLE_SPEC_FOG);
+
+    /**
+     * How far in from the box's faces the medium fades out, in metres.
+     *
+     * **World-space, and deliberately not scaled by the transform**, so a 0.5 here is half a metre
+     * of softness whether the volume is a metre across or a hundred. Zero gives the box hard edges,
+     * which is visible as a straight line across the screen wherever the box crosses the view.
+     *
+     * @type {number}
+     */
+    fade_distance = DEFAULT_FADE_DISTANCE;
+
+    /**
+     * The medium's extinction per metre, which is {@link density} expressed in what it does rather
+     * than in how many particles it took.
+     *
+     * The point of it is that it is comparable across particles: a smoke volume and a fog volume set
+     * to the same target extinction swallow the same amount of light, while the same *density* in
+     * both would differ by orders of magnitude.
+     *
+     * **Derived, not stored** — writing it sets {@link density}, and changing `particle_spec`
+     * afterwards therefore changes what reading it back gives. The density is what survives a save.
+     *
+     * @returns {number}
+     */
+    get target_extinction() {
+        return this.density * rgb_to_luminance(...this.particle_spec.extinction);
+    }
+
+    /**
+     * @param {number} value
+     */
+    set target_extinction(value) {
+        assert.isNumber(value, 'target_extinction');
+        assert.isFinite(value, 'target_extinction');
+
+        const density = value / rgb_to_luminance(...this.particle_spec.extinction);
+
+        /*
+         Catches the one way this goes wrong: a particle spec that extinguishes nothing. A default-
+         constructed `VolumetricsParticleSpec` has zero cross-sections, and asking such a medium to
+         reach any extinction at all needs infinitely many of its particles. Rejecting it here names
+         the mistake; letting it through puts an `Infinity` in the GPU table, where it becomes a
+         screenful of NaN several passes later.
+        */
+        assert.isFinite(density, 'the density this target_extinction implies (the particle spec extinguishes nothing)');
+
+        this.density = density;
+    }
+
+    /**
+     * @param {*} json
+     * @returns {ParticipatingMedia}
+     */
+    static fromJSON(json) {
+        const r = new ParticipatingMedia();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+
+    toJSON() {
+        const spec = this.particle_spec;
+
+        return {
+            density: this.density,
+            fade_distance: this.fade_distance,
+            particle_spec: {
+                scattering: spec.scattering.slice(),
+                extinction: spec.extinction.slice(),
+                radius: spec.radius,
+                g: spec.g
+            }
+        };
+    }
+
+    /**
+     * @param {number} [density]
+     * @param {number} [fade_distance]
+     * @param {object} [particle_spec] omitted resets the medium to fog rather than leaving whatever
+     * the component already held — a load has to determine the whole component, or an instance being
+     * reused would carry the previous level's particle into the next one
+     */
+    fromJSON({
+                 density = DEFAULT_DENSITY,
+                 fade_distance = DEFAULT_FADE_DISTANCE,
+                 particle_spec
+             }) {
+        assert.isNumber(density, 'density');
+        assert.isFinite(density, 'density');
+        assert.greaterThanOrEqual(density, 0, 'density must not be negative');
+
+        assert.isNumber(fade_distance, 'fade_distance');
+        assert.isFinite(fade_distance, 'fade_distance');
+        assert.greaterThanOrEqual(fade_distance, 0, 'fade_distance must not be negative');
+
+        this.density = density;
+        this.fade_distance = fade_distance;
+
+        if (particle_spec === undefined) {
+            this.particle_spec.copy(VOLUMETRIC_PARTICLE_SPEC_FOG);
+        } else {
+            this.particle_spec.fromJSON(particle_spec);
+        }
+    }
+
+    /**
+     * **The cross-sections and the radius are left out of this on purpose.** They run to 1e-16 and
+     * 1e-6, and {@link computeHashFloat} collapses anything that small to zero, so mixing them in
+     * would cost a multiply and buy no dispersion at all. A hash is allowed to collide;
+     * {@link equals} is the exact one.
+     *
+     * @returns {number}
+     */
+    hash() {
+        const spec = this.particle_spec;
+
+        return combine_hash(
+            computeHashFloat(this.density),
+            computeHashFloat(this.fade_distance),
+            computeHashFloat(spec.g)
+        );
+    }
+
+    /**
+     * @param {ParticipatingMedia} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.density === other.density
+            && this.fade_distance === other.fade_distance
+            && this.particle_spec.equals(other.particle_spec);
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+ParticipatingMedia.typeName = "ParticipatingMedia";

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

@@ -0,0 +1,87 @@
+/**
+ * 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: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform): void;
+/**
+ * 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: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform): boolean;
+/**
+ * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
+ *
+ * The same shape as {@link LightSystem}: 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 ParticipatingMediaSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine, scene: Scene);
+    dependencies: (typeof Transform | typeof ParticipatingMedia)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(component: ParticipatingMedia, transform: Transform, entity: number): void;
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component: ParticipatingMedia, transform: Transform, entity: number): void;
+    #private;
+}
+import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { System } from "../ecs/System.js";
+//# sourceMappingURL=ParticipatingMediaSystem.d.ts.map

package/src/engine/graphics3/ParticipatingMediaSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticipatingMediaSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem.js"],"names":[],"mappings":"AA6IA;;;;;;;;;;GAUG;AACH,yDAJW,wBAAwB,aACxB,kBAAkB,aAClB,SAAS,QASnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8DALW,wBAAwB,aACxB,kBAAkB,aAClB,SAAS,GACP,OAAO,CAOnB;AAhLD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAmBI;;;OAGG;IACH,oDASC;IA9BD,+DAA+C;IAgC/C,2CAIC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,kBAAkB,aAClB,SAAS,UACT,MAAM,QAUhB;IAED;;;;OAIG;IACH,kBAJW,kBAAkB,aAClB,SAAS,UACT,MAAM,QAIhB;;CAmCJ;yCAzIwC,8DAA8D;mCAGpE,yBAAyB;0BADlC,+BAA+B;uBADlC,kBAAkB"}