@woosh/meep-engine 2.163.10 → 2.164.0

package/src/engine/sound/simulation/render/FoaProbeReverbRenderer.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A directional (first-order ambisonic / FOA) acoustic reverb send bus — the spatial counterpart of
+ * {@link ProbeReverbRenderer}. It renders the probe-baked reverb as a B-format field (`W` omni + `X/Y/Z`
+ * dipoles) steered by each band's baked ARRIVAL DIRECTION, and decodes it to stereo through two virtual
+ * cardioids that turn with the listener — so the reverb leans toward the open door / off the near wall and
+ * stays world-anchored as the head rotates.
+ *
+ * Graph (per B-format channel a double-buffered convolver pair for click-free probe-cell crossfades):
+ * ```
+ *   input ─┬─► conv[set][W] ─► wet[set][W] ─► busW ─┬─► (0.5)         ──► Lsum ─► merger.0 ─┐
+ *          ├─► conv[set][X] ─► wet[set][X] ─► busX ─┼─► (0.5·lookL.x) ──► Lsum               ├─► output ─► dest
+ *          ├─► conv[set][Y] ─► wet[set][Y] ─► busY ─┼─► …                  Rsum ─► merger.1 ─┘
+ *          └─► conv[set][Z] ─► wet[set][Z] ─► busZ ─┴─► (0.5·lookR.*) ──► Rsum
+ * ```
+ *
+ * Key idea — **rotate the decoder, not the soundfield.** For first order, decoding world-frame B-format
+ * with a look direction rotated INTO world space is identical to rotating the soundfield by the inverse and
+ * decoding with a fixed look — but it costs only the six directional decode gains per frame (the `X/Y/Z`
+ * weights for L and R) instead of a full 3×3 signal-rotation stage and a re-convolution. The convolvers are
+ * touched only when the listener crosses into a new probe cell.
+ *
+ * The decode target is stereo (two cardioids); the fixed decode is isolated in {@link #updateDecode} so a
+ * binaural/HRTF decoder can replace it later without touching the encode/rotate path.
+ *
+ * Tunables are plain settable fields (no opaque config bag). WebAudio-touching but ECS-agnostic.
+ */
+export class FoaProbeReverbRenderer {
+    /**
+     * @param {BaseAudioContext} audio_context
+     * @param {AudioNode} destination where the wet output mixes (e.g. the master / engine destination)
+     */
+    constructor(audio_context: BaseAudioContext, destination: AudioNode);
+    /**
+     * IR envelope exponent (higher = faster fade).
+     * @type {number}
+     */
+    decayPower: number;
+    /**
+     * Crossfade duration (seconds) when the reverb changes — long enough to be click-free.
+     * @type {number}
+     */
+    crossfadeSeconds: number;
+    /**
+     * Loudest-band decay below this (seconds) is treated as "no reverb": the wet field crossfades to silence.
+     * @type {number}
+     */
+    minDecay: number;
+    /**
+     * The node sources / a sopra bus send their post-fader copy into.
+     * @returns {AudioNode}
+     */
+    get input(): AudioNode;
+    /**
+     * The wet output (already connected to the destination).
+     * @returns {AudioNode}
+     */
+    get output(): AudioNode;
+    /**
+     * @param {AcousticProbeField} probeField the baked probe volume the reverb reads from
+     */
+    setProbeField(probeField: AcousticProbeField): void;
+    /**
+     * Drive the reverb from the listener pose. Re-bakes the B-format IR only when the listener crosses into
+     * a new probe cell; steers the decode toward the baked arrival directions every call (cheap). No-op if
+     * no field is set.
+     * PRECONDITION: `orientation` is the listener's world orientation as a unit quaternion `{x, y, z, w}`.
+     * @param {number} x listener world x
+     * @param {number} y listener world y
+     * @param {number} z listener world z
+     * @param {{x:number,y:number,z:number,w:number}} orientation listener world orientation (unit quaternion)
+     */
+    update(x: number, y: number, z: number, orientation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    }): void;
+    #private;
+}
+//# sourceMappingURL=FoaProbeReverbRenderer.d.ts.map

package/src/engine/sound/simulation/render/FoaProbeReverbRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoaProbeReverbRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/FoaProbeReverbRenderer.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAsHI;;;OAGG;IACH,2BAHW,gBAAgB,eAChB,SAAS,EAkEnB;IAzLD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,UAFU,MAAM,CAEA;IA2KhB;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,oDAGC;IAED;;;;;;;;;OASG;IACH,UALW,MAAM,KACN,MAAM,KACN,MAAM,eACN;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAkB/C;;CAkEJ"}

package/src/engine/sound/simulation/render/FoaProbeReverbRenderer.js

@@ -0,0 +1,354 @@
+import { assert } from "../../../../core/assert.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { seededRandom } from "../../../../core/math/random/seededRandom.js";
+import { FADE_EPSILON, rampGain } from "../../sopra/util/fadeOutAndStop.js";
+import { foaReverbImpulseResponse } from "./foaReverbImpulseResponse.js";
+
+// B-format channel order in the convolver / bus arrays
+const W = 0, X = 1, Y = 2, Z = 3;
+const CHANNELS = 4;
+
+// The two virtual cardioid look directions in the LISTENER's local frame (+X = listener's right). A
+// first-order cardioid pointing along `look` decodes B-format as 0.5·W + 0.5·(look · XYZ): full toward
+// `look`, nulled away from it. Opposite ±X looks give the widest first-order stereo image. (If the engine's
+// listener right-axis is not +X, flip these — it is the only convention dependency.)
+const LEFT_LOOK_LOCAL = [-1, 0, 0];
+const RIGHT_LOOK_LOCAL = [1, 0, 0];
+
+// W's fixed decode weight into each ear; the directional weight (the other 0.5) is steered per frame.
+const OMNI_DECODE = 0.5;
+
+// per-frame decode-gain ramp — short enough to track head motion, long enough to never click
+const DECODE_RAMP_SECONDS = 0.05;
+
+/**
+ * A directional (first-order ambisonic / FOA) acoustic reverb send bus — the spatial counterpart of
+ * {@link ProbeReverbRenderer}. It renders the probe-baked reverb as a B-format field (`W` omni + `X/Y/Z`
+ * dipoles) steered by each band's baked ARRIVAL DIRECTION, and decodes it to stereo through two virtual
+ * cardioids that turn with the listener — so the reverb leans toward the open door / off the near wall and
+ * stays world-anchored as the head rotates.
+ *
+ * Graph (per B-format channel a double-buffered convolver pair for click-free probe-cell crossfades):
+ * ```
+ *   input ─┬─► conv[set][W] ─► wet[set][W] ─► busW ─┬─► (0.5)         ──► Lsum ─► merger.0 ─┐
+ *          ├─► conv[set][X] ─► wet[set][X] ─► busX ─┼─► (0.5·lookL.x) ──► Lsum               ├─► output ─► dest
+ *          ├─► conv[set][Y] ─► wet[set][Y] ─► busY ─┼─► …                  Rsum ─► merger.1 ─┘
+ *          └─► conv[set][Z] ─► wet[set][Z] ─► busZ ─┴─► (0.5·lookR.*) ──► Rsum
+ * ```
+ *
+ * Key idea — **rotate the decoder, not the soundfield.** For first order, decoding world-frame B-format
+ * with a look direction rotated INTO world space is identical to rotating the soundfield by the inverse and
+ * decoding with a fixed look — but it costs only the six directional decode gains per frame (the `X/Y/Z`
+ * weights for L and R) instead of a full 3×3 signal-rotation stage and a re-convolution. The convolvers are
+ * touched only when the listener crosses into a new probe cell.
+ *
+ * The decode target is stereo (two cardioids); the fixed decode is isolated in {@link #updateDecode} so a
+ * binaural/HRTF decoder can replace it later without touching the encode/rotate path.
+ *
+ * Tunables are plain settable fields (no opaque config bag). WebAudio-touching but ECS-agnostic.
+ */
+export class FoaProbeReverbRenderer {
+    /**
+     * IR envelope exponent (higher = faster fade).
+     * @type {number}
+     */
+    decayPower = 2;
+
+    /**
+     * Crossfade duration (seconds) when the reverb changes — long enough to be click-free.
+     * @type {number}
+     */
+    crossfadeSeconds = 0.5;
+
+    /**
+     * Loudest-band decay below this (seconds) is treated as "no reverb": the wet field crossfades to silence.
+     * @type {number}
+     */
+    minDecay = 0.05;
+
+    /**
+     * @type {BaseAudioContext}
+     */
+    #ctx;
+
+    /**
+     * @type {GainNode}
+     */
+    #input;
+
+    /**
+     * @type {GainNode}
+     */
+    #output;
+
+    /**
+     * Two sets (double-buffer) of four B-format convolvers each: `#convolvers[set][channel]`. `normalize` is
+     * OFF — the IR carries the calibrated W-vs-XYZ levels itself ({@link foaReverbImpulseResponse}).
+     * @type {ConvolverNode[][]}
+     */
+    #convolvers = [[], []];
+
+    /**
+     * Per-set, per-channel crossfade wet gains: `#wets[set][channel]`. The active set's four ramp up, the
+     * other set's four ramp down, together.
+     * @type {GainNode[][]}
+     */
+    #wets = [[], []];
+
+    /**
+     * The four post-crossfade B-format channel buses (W, X, Y, Z) the decoder reads.
+     * @type {GainNode[]}
+     */
+    #buses = [];
+
+    /**
+     * Per-channel decode gains into the left / right ear. `[W]` is the fixed omni weight; `[X|Y|Z]` are
+     * steered per frame from the rotated look direction.
+     * @type {GainNode[]}
+     */
+    #decodeL = [];
+    #decodeR = [];
+
+    /**
+     * Index (0/1) of the set currently faded in.
+     * @type {number}
+     */
+    #active = 0;
+
+    /**
+     * Nearest probe index of the last bake, or -1 (none yet / empty field). The IR is a per-probe property,
+     * so it is re-baked exactly when this changes — not on every listener move within a cell.
+     * @type {number}
+     */
+    #currentProbe = -1;
+
+    /**
+     * Set by {@link setProbeField} to force a re-bake on the next {@link update} even when the nearest
+     * probe index is unchanged — in particular so swapping in an EMPTY field (whose nearest index is also
+     * -1, like the initial state) still mutes the previous field's reverb instead of leaving it playing.
+     * @type {boolean}
+     */
+    #dirty = false;
+
+    /**
+     * @type {Float32Array}
+     */
+    #scratchBands = new Float32Array(3);
+
+    /**
+     * @type {Float32Array}
+     */
+    #scratchDirs = new Float32Array(9);
+
+    /**
+     * @type {Float32Array}
+     */
+    #tmpDir = new Float32Array(3);
+
+    /**
+     * @type {Float32Array}
+     */
+    #lookL = new Float32Array(3);
+
+    /**
+     * @type {Float32Array}
+     */
+    #lookR = new Float32Array(3);
+
+    /**
+     * @type {function():number}
+     */
+    #random = seededRandom(1);
+
+    /**
+     * @type {AcousticProbeField|null}
+     */
+    #probeField = null;
+
+    /**
+     * @param {BaseAudioContext} audio_context
+     * @param {AudioNode} destination where the wet output mixes (e.g. the master / engine destination)
+     */
+    constructor(audio_context, destination) {
+        assert.defined(audio_context, 'audio_context');
+        assert.defined(destination, 'destination');
+
+        this.#ctx = audio_context;
+
+        const ctx = audio_context;
+
+        this.#input = ctx.createGain();
+        this.#output = ctx.createGain();
+
+        for (let ch = 0; ch < CHANNELS; ch++) {
+            this.#buses[ch] = ctx.createGain();
+        }
+
+        // double-buffered convolver/wet pairs, input → conv → wet → bus
+        for (let set = 0; set < 2; set++) {
+            for (let ch = 0; ch < CHANNELS; ch++) {
+                const conv = ctx.createConvolver();
+                conv.normalize = false;
+
+                const wet = ctx.createGain();
+                wet.gain.setValueAtTime(0, 0); // silent until faded in
+
+                this.#input.connect(conv);
+                conv.connect(wet);
+                wet.connect(this.#buses[ch]);
+
+                this.#convolvers[set][ch] = conv;
+                this.#wets[set][ch] = wet;
+            }
+        }
+
+        // decode: each bus → an L gain and an R gain → the per-ear sums
+        const lSum = ctx.createGain();
+        const rSum = ctx.createGain();
+
+        for (let ch = 0; ch < CHANNELS; ch++) {
+            const dl = ctx.createGain();
+            const dr = ctx.createGain();
+
+            this.#buses[ch].connect(dl);
+            dl.connect(lSum);
+            this.#buses[ch].connect(dr);
+            dr.connect(rSum);
+
+            this.#decodeL[ch] = dl;
+            this.#decodeR[ch] = dr;
+        }
+
+        // W's decode weight is fixed; the directional weights start at 0 until the first update steers them
+        this.#decodeL[W].gain.setValueAtTime(OMNI_DECODE, 0);
+        this.#decodeR[W].gain.setValueAtTime(OMNI_DECODE, 0);
+        for (let ch = X; ch <= Z; ch++) {
+            this.#decodeL[ch].gain.setValueAtTime(0, 0);
+            this.#decodeR[ch].gain.setValueAtTime(0, 0);
+        }
+
+        // L/R → stereo, out to the destination
+        const merger = ctx.createChannelMerger(2);
+        lSum.connect(merger, 0, 0);
+        rSum.connect(merger, 0, 1);
+        merger.connect(this.#output);
+        this.#output.connect(destination);
+    }
+
+    /**
+     * The node sources / a sopra bus send their post-fader copy into.
+     * @returns {AudioNode}
+     */
+    get input() {
+        return this.#input;
+    }
+
+    /**
+     * The wet output (already connected to the destination).
+     * @returns {AudioNode}
+     */
+    get output() {
+        return this.#output;
+    }
+
+    /**
+     * @param {AcousticProbeField} probeField the baked probe volume the reverb reads from
+     */
+    setProbeField(probeField) {
+        this.#probeField = probeField;
+        this.#dirty = true; // force a re-bake on the next update even if the nearest index is unchanged
+    }
+
+    /**
+     * Drive the reverb from the listener pose. Re-bakes the B-format IR only when the listener crosses into
+     * a new probe cell; steers the decode toward the baked arrival directions every call (cheap). No-op if
+     * no field is set.
+     * PRECONDITION: `orientation` is the listener's world orientation as a unit quaternion `{x, y, z, w}`.
+     * @param {number} x listener world x
+     * @param {number} y listener world y
+     * @param {number} z listener world z
+     * @param {{x:number,y:number,z:number,w:number}} orientation listener world orientation (unit quaternion)
+     */
+    update(x, y, z, orientation) {
+        const field = this.#probeField;
+
+        if (field === null) {
+            return;
+        }
+
+        const i = field.nearestIndex(x, y, z);
+
+        if (this.#dirty || i !== this.#currentProbe) {
+            this.#dirty = false;
+            this.#currentProbe = i;
+            this.#rebake(field, i);
+        }
+
+        this.#updateDecode(orientation);
+    }
+
+    /**
+     * Re-bake the B-format IR for probe `i` (or mute if `i < 0` / below {@link minDecay}) into the inactive
+     * convolver set and crossfade to it.
+     * @param {AcousticProbeField} field
+     * @param {number} i nearest probe index, or -1 for an empty field
+     */
+    #rebake(field, i) {
+        const bands = this.#scratchBands;
+        const dirs = this.#scratchDirs;
+
+        let audible = false;
+
+        if (i >= 0) {
+            for (let band = 0; band < 3; band++) {
+                bands[band] = field.reverbBand(i, band);
+                field.reverbDirection(i, band, this.#tmpDir);
+                dirs[band * 3] = this.#tmpDir[0];
+                dirs[band * 3 + 1] = this.#tmpDir[1];
+                dirs[band * 3 + 2] = this.#tmpDir[2];
+            }
+
+            audible = Math.max(bands[0], bands[1], bands[2]) >= this.minDecay;
+        }
+
+        const inactive = 1 - this.#active;
+
+        if (audible) {
+            const ir = foaReverbImpulseResponse(this.#ctx, bands, dirs, this.decayPower, this.#random);
+            this.#convolvers[inactive][W].buffer = ir.w;
+            this.#convolvers[inactive][X].buffer = ir.x;
+            this.#convolvers[inactive][Y].buffer = ir.y;
+            this.#convolvers[inactive][Z].buffer = ir.z;
+        }
+
+        const cf = this.crossfadeSeconds;
+        const target = audible ? 1 : FADE_EPSILON;
+
+        for (let ch = 0; ch < CHANNELS; ch++) {
+            rampGain(this.#wets[this.#active][ch].gain, FADE_EPSILON, cf, this.#ctx);
+            rampGain(this.#wets[inactive][ch].gain, target, cf, this.#ctx);
+        }
+
+        this.#active = inactive;
+    }
+
+    /**
+     * Steer the stereo decode toward the baked arrival directions for the current listener orientation:
+     * rotate the two local cardioid look directions into world space and set the six directional decode
+     * gains (the W weights are fixed). Click-safe ramps; runs every frame, no re-convolution.
+     * @param {{x:number,y:number,z:number,w:number}} q listener world orientation (unit quaternion)
+     */
+    #updateDecode(q) {
+        v3_quaternion_apply(this.#lookL, 0, LEFT_LOOK_LOCAL[0], LEFT_LOOK_LOCAL[1], LEFT_LOOK_LOCAL[2], q.x, q.y, q.z, q.w);
+        v3_quaternion_apply(this.#lookR, 0, RIGHT_LOOK_LOCAL[0], RIGHT_LOOK_LOCAL[1], RIGHT_LOOK_LOCAL[2], q.x, q.y, q.z, q.w);
+
+        const ctx = this.#ctx;
+        const ramp = DECODE_RAMP_SECONDS;
+
+        for (let axis = 0; axis < 3; axis++) {
+            const ch = X + axis; // X, Y, Z
+            rampGain(this.#decodeL[ch].gain, OMNI_DECODE * this.#lookL[axis], ramp, ctx);
+            rampGain(this.#decodeR[ch].gain, OMNI_DECODE * this.#lookR[axis], ramp, ctx);
+        }
+    }
+}

package/src/engine/sound/simulation/render/ProbeReverbRenderer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * An acoustic-owned reverb send bus, separate from sopra's static `ReverbEffect` (which is left
+ * untouched). Renders the probe-baked reverb: each frame {@link update} reads the nearest probe's decay
+ * at the listener and, when it changes meaningfully, re-bakes the IR into the INACTIVE of a
+ * double-buffered `ConvolverNode` pair and equal-power crossfades to it — so crossing probe cells does
+ * not click.
+ *
+ * Graph: `input → [convolverA → wetA, convolverB → wetB] → output → destination`. Sources / a sopra bus
+ * send a post-fader copy into {@link input}; {@link output} mixes into the destination. WebAudio-touching
+ * but ECS-agnostic.
+ *
+ * Tunables are plain settable fields (no opaque config bag).
+ */
+export class ProbeReverbRenderer {
+    /**
+     * @param {BaseAudioContext} audioContext
+     * @param {AudioNode} destination where the wet output mixes (e.g. the master / engine destination)
+     */
+    constructor(audioContext: BaseAudioContext, destination: AudioNode);
+    /**
+     * IR envelope exponent (higher = faster fade).
+     * @type {number}
+     */
+    decayPower: number;
+    /**
+     * Crossfade duration (seconds) when the reverb changes — long enough to be click-free.
+     * @type {number}
+     */
+    crossfadeSeconds: number;
+    /**
+     * Minimum change in decay (seconds) that triggers a re-bake + crossfade — avoids churning the
+     * convolver on tiny listener moves.
+     * @type {number}
+     */
+    changeThreshold: number;
+    /**
+     * Decay below this (seconds) is treated as "no reverb": the wet level crossfades to 0.
+     * @type {number}
+     */
+    minDecay: number;
+    /**
+     * The node sources / a sopra bus send their post-fader copy into.
+     * @returns {AudioNode}
+     */
+    get input(): AudioNode;
+    /**
+     * The wet output (already connected to the destination).
+     * @returns {AudioNode}
+     */
+    get output(): AudioNode;
+    /**
+     * @param {AcousticProbeField} probeField the baked probe volume the reverb reads from
+     */
+    setProbeField(probeField: AcousticProbeField): void;
+    /**
+     * Drive the reverb from the listener position via the bound probe field. No-op if no field is set.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    update(x: number, y: number, z: number): void;
+    /**
+     * Set the reverb decay as a single broadband RT60 (broadcast to all three bands).
+     * @param {number} decaySeconds
+     */
+    setDecay(decaySeconds: number): void;
+    /**
+     * Set the per-band reverb RT60 `[low, mid, high]`, crossfading the convolver pair if it changed
+     * meaningfully. Below `minDecay` (loudest band) the reverb fades toward silence.
+     * @param {Float32Array|number[]} bands per-band RT60 seconds
+     */
+    setBands(bands: Float32Array | number[]): void;
+    #private;
+}
+//# sourceMappingURL=ProbeReverbRenderer.d.ts.map

package/src/engine/sound/simulation/render/ProbeReverbRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProbeReverbRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/render/ProbeReverbRenderer.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH;IAsFI;;;OAGG;IACH,0BAHW,gBAAgB,eAChB,SAAS,EA8BnB;IArHD;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,UAFU,MAAM,CAEA;IAgGhB;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;OAEG;IACH,oDAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,KACN,MAAM,QAShB;IAED;;;OAGG;IACH,uBAFW,MAAM,QAOhB;IAED;;;;OAIG;IACH,gBAFW,YAAY,GAAC,MAAM,EAAE,QAwC/B;;CACJ"}