@woosh/meep-engine 3.11.1 → 3.11.2

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

@@ -0,0 +1,111 @@
+/**
+ * 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 {
+    /**
+     * @param {*} json
+     * @returns {ParticipatingMedia}
+     */
+    static fromJSON(json: any): 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: number;
+    /**
+     * 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;
+    /**
+     * 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: number;
+    /**
+     * @param {number} value
+     */
+    set target_extinction(arg: number);
+    /**
+     * 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(): number;
+    toJSON(): {
+        density: number;
+        fade_distance: number;
+        particle_spec: {
+            scattering: number[];
+            extinction: number[];
+            radius: number;
+            g: number;
+        };
+    };
+    /**
+     * @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, fade_distance, particle_spec }?: number): void;
+    /**
+     * **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(): number;
+    /**
+     * @param {ParticipatingMedia} other
+     * @returns {boolean}
+     */
+    equals(other: ParticipatingMedia): boolean;
+}
+export namespace ParticipatingMedia {
+    let typeName: string;
+}
+import { VolumetricsParticleSpec } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+//# sourceMappingURL=ParticipatingMedia.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticipatingMedia.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMedia.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAyEI;;;OAGG;IACH,4BAFa,kBAAkB,CAQ9B;IAjFD;;;;;;;;OAQG;IACH,SAFU,MAAM,CAEU;IAE1B;;;;;;;;OAQG;IACH,eAFU,uBAAuB,CAE8C;IAE/E;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEsB;IAmBtC;;OAEG;IACH,mCAgBC;IApCD;;;;;;;;;;;;OAYG;IACH,gCAEC;IAmCD;;;;;;;;;MAaC;IAED;;;;;;OAMG;IACH,qDANW,MAAM,QA2BhB;IAED;;;;;;;OAOG;IACH,QAFa,MAAM,CAUlB;IAED;;;OAGG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAMnB;CACJ;;kBAIS,MAAM;;wCAjMT,8DAA8D"}

package/src/engine/graphics3/ParticipatingMedia.js

@@ -0,0 +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";

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

@@ -0,0 +1,34 @@
+/**
+ * Ten numbers, all of them `float64`.
+ *
+ * **The width is the whole design decision here, and it is not the usual one.** Component adapters
+ * around this one write `float32`, which is what the GPU reads anyway — but a participating medium
+ * is authored at the two far ends of the exponent range at once: cross-sections run to 1e-16 and the
+ * particle counts that pay for them run to 1e16. `float32` holds both magnitudes comfortably and
+ * keeps about seven digits of each, so a round trip through it moves every one of these values a
+ * little. Nothing about the rendered picture would change. What would change is that
+ * `ParticipatingMedia.equals` stops answering `true` across a save, and a level that reloads into
+ * components which merely *look* like the ones that were saved is a level whose blueprints stop
+ * matching. Ten doubles is eighty bytes; that is the price of the round trip being exact.
+ *
+ * **`target_extinction` is not in the format** because it is not in the component — it is
+ * {@link ParticipatingMedia.density} read through the particle spec, and both of its inputs are
+ * here.
+ */
+export class ParticipatingMediaSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof ParticipatingMedia;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticipatingMedia} value
+     */
+    serialize(buffer: BinaryBuffer, value: ParticipatingMedia): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticipatingMedia} value
+     */
+    deserialize(buffer: BinaryBuffer, value: ParticipatingMedia): void;
+}
+import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+//# sourceMappingURL=ParticipatingMediaSerializationAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticipatingMediaSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH;;IAEI,iCAA2B;IAG3B;;;OAGG;IACH,uCAFW,kBAAkB,QAkB5B;IAED;;;OAGG;IACH,yCAFW,kBAAkB,QAsB5B;CACJ;gDAxE+C,0DAA0D;mCACvE,yBAAyB"}

package/src/engine/graphics3/ParticipatingMediaSerializationAdapter.js

@@ -0,0 +1,73 @@
+import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+
+/**
+ * Ten numbers, all of them `float64`.
+ *
+ * **The width is the whole design decision here, and it is not the usual one.** Component adapters
+ * around this one write `float32`, which is what the GPU reads anyway — but a participating medium
+ * is authored at the two far ends of the exponent range at once: cross-sections run to 1e-16 and the
+ * particle counts that pay for them run to 1e16. `float32` holds both magnitudes comfortably and
+ * keeps about seven digits of each, so a round trip through it moves every one of these values a
+ * little. Nothing about the rendered picture would change. What would change is that
+ * `ParticipatingMedia.equals` stops answering `true` across a save, and a level that reloads into
+ * components which merely *look* like the ones that were saved is a level whose blueprints stop
+ * matching. Ten doubles is eighty bytes; that is the price of the round trip being exact.
+ *
+ * **`target_extinction` is not in the format** because it is not in the component — it is
+ * {@link ParticipatingMedia.density} read through the particle spec, and both of its inputs are
+ * here.
+ */
+export class ParticipatingMediaSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = ParticipatingMedia;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticipatingMedia} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.density);
+        buffer.writeFloat64(value.fade_distance);
+
+        const spec = value.particle_spec;
+
+        for (let i = 0; i < 3; i++) {
+            buffer.writeFloat64(spec.scattering[i]);
+        }
+
+        for (let i = 0; i < 3; i++) {
+            buffer.writeFloat64(spec.extinction[i]);
+        }
+
+        buffer.writeFloat64(spec.radius);
+        buffer.writeFloat64(spec.g);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticipatingMedia} value
+     */
+    deserialize(buffer, value) {
+        value.density = buffer.readFloat64();
+        value.fade_distance = buffer.readFloat64();
+
+        const spec = value.particle_spec;
+
+        /*
+         In place, which is safe because a spec owns its arrays: every route into one —
+         `fromJSON`, `copy`, `clone` — slices what it was given rather than keeping the reference.
+        */
+        for (let i = 0; i < 3; i++) {
+            spec.scattering[i] = buffer.readFloat64();
+        }
+
+        for (let i = 0; i < 3; i++) {
+            spec.extinction[i] = buffer.readFloat64();
+        }
+
+        spec.radius = buffer.readFloat64();
+        spec.g = buffer.readFloat64();
+    }
+}

package/src/engine/graphics3/ParticipatingMediaSystem3.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 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<any> {
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine3, 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=ParticipatingMediaSystem3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticipatingMediaSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem3.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,qDASC;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"}