@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/optimizer/pass_share_subexpressions.js

@@ -0,0 +1,151 @@
+import { VM_OP, VM_OPERAND, vm_dest_width, vm_encode_word0 } from "../isa/ParticleVMISA.js";
+import {
+    ParticleValueNumbering,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_SHARE_SUBEXPRESSIONS = "share_subexpressions";
+
+/**
+ * Recognise an instruction that recomputes something a register already holds, and read the register
+ * instead.
+ *
+ * Two executions of a shareable opcode over equal operands produce equal results, so the second is
+ * a copy of the first — and where the two write the same register, it is not even that: the register
+ * already holds the answer and the instruction goes entirely.
+ *
+ * Equality is by value number rather than by register: the same expression computed from registers
+ * that have since been copied about still matches, and a register overwritten since fails the match
+ * without any separate invalidation. It is the machinery `pass_propagate_copies` uses, asked a
+ * different question.
+ *
+ * ## What is not shared
+ *
+ * `LOAD_ATTR` reads the record, which a `STORE_ATTR` in between may have changed, and `RANDOM` reads
+ * the RNG, which every draw changes. Neither is shareable, so neither is ever considered here — the
+ * `shareable` column of {@link ./particle_vm_semantics.js} is the whole of the rule, which is what
+ * keeps the aliasing question from having to be answered a second time in this file.
+ *
+ * `ADD`, `MUL` and `CMP_EQ` match with their operands either way round. `MIN` and `MAX` do not,
+ * although they look just as commutative: `min(-0, 0)` and `min(0, -0)` are different registers'
+ * worth of zero, and the record is compared to the bit.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_share_subexpressions(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const values = new ParticleValueNumbering(context.register_slots);
+
+    /** @type {Map<string, {base: number, ids: number[]}>} expression -> where its result was left */
+    const available = new Map();
+
+    /** @type {number[][]} */
+    const out = [];
+
+    let changed = false;
+
+    for (const instruction of decoded) {
+        const span = instruction.write === null ? 0 : vm_dest_width(instruction.op, instruction.width);
+        const key = is_shareable(instruction) && span > 0 ? expression_key(instruction, values) : null;
+        const previous = key === null ? undefined : available.get(key);
+
+        let shared = false;
+
+        if (previous !== undefined && values.holds(previous.base, previous.ids)) {
+            const replacement = share(instruction, previous, span);
+
+            if (replacement !== null) {
+                for (const words of replacement) {
+                    out.push(words);
+                    values.publish(words);
+                }
+
+                shared = true;
+                changed = true;
+            }
+        }
+
+        if (!shared) {
+            out.push(instruction.words);
+            values.publish(instruction.words);
+        }
+
+        // Recorded after the write, so an expression that overwrites one of its own sources names
+        // the register as it stands once the instruction has run.
+        if (key !== null && !shared) {
+            available.set(key, { base: instruction.write.base, ids: values.ids_of(instruction.write.base, span) });
+        }
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * `MOV` is shareable in the sense the semantics table means, but it is not shared here: replacing
+ * one copy with another copy is no gain, and `pass_propagate_copies` — which reads THROUGH copies —
+ * would immediately rewrite the result back, leaving the two passes trading the same instruction
+ * between them for as many sweeps as they are given.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @returns {boolean}
+ */
+function is_shareable(instruction) {
+    return instruction.semantics.shareable && instruction.op !== VM_OP.MOV;
+}
+
+/** Opcodes whose two register operands may be matched either way round. */
+const COMMUTATIVE = new Set([VM_OP.ADD, VM_OP.MUL, VM_OP.CMP_EQ]);
+
+/**
+ * What makes two executions the same one: the opcode, the width, every immediate, and the value
+ * numbers behind every lane an operand reads.
+ *
+ * @returns {string|null} `null` when an operand reaches outside the file, which is nothing to match
+ */
+function expression_key(instruction, values) {
+    /** @type {Map<number, string>} */
+    const operands = new Map();
+
+    for (const read of instruction.reads) {
+        const ids = values.ids_of(read.base, read.span);
+
+        if (ids === null) {
+            return null;
+        }
+
+        operands.set(read.operand, ids.join(","));
+    }
+
+    /** @type {string[]} */
+    const parts = [];
+
+    for (let slot = 0; slot < 3; slot++) {
+        parts.push(
+            instruction.meta.operands[slot] === VM_OPERAND.REG
+                ? `r${operands.get(slot)}`
+                : `i${instruction.words[2 + slot]}`
+        );
+    }
+
+    if (COMMUTATIVE.has(instruction.op)) {
+        parts.sort();
+    }
+
+    return `${instruction.op}.${instruction.width}|${parts.join("|")}`;
+}
+
+/**
+ * @returns {number[][]|null} what to emit instead — nothing at all when the result is already in the
+ *   destination, otherwise a copy of it — or `null` when the copy would not be a legal instruction
+ */
+function share(instruction, previous, span) {
+    if (previous.base === instruction.write.base) {
+        return [];
+    }
+
+    const words = [vm_encode_word0(VM_OP.MOV, span), instruction.write.base, previous.base, 0, 0];
+
+    return particle_instruction_is_well_formed(words) ? [words] : null;
+}

package/src/shade/renderer/particles/particle_test_fixtures.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared scaffolding for the particle specs that run shaders under the WGSL emulator.
+ *
+ * An emitter is a scene node, so a shader that reads one needs two databases laid out the way the
+ * GPU would hold them: the scene's (for the node's world matrix) and the particle system's (for the
+ * emitter row). Both are real `GPUDatabase`s on the software device, filled through the real
+ * {@link GPUSceneContext} and {@link EmitterRegistry}, and serialised by
+ * {@link gpu_database_words} — so a spec exercises the actual writers, and the only thing standing
+ * in for the GPU is the upload.
+ */
+/**
+ * @typedef {object} ParticleSceneFixture
+ * @property {SoftwareGPUDevice} device
+ * @property {GraphicsContext} graphics
+ * @property {Scene} scene
+ * @property {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
+ * @property {EmitterRegistry} registry
+ */
+/**
+ * A scene with a GPU context and an emitter registry, both on a fresh software device.
+ *
+ * @returns {ParticleSceneFixture}
+ */
+export function particle_scene_fixture(): ParticleSceneFixture;
+/**
+ * Put an emitter in the scene and register it, the way the system does: the node gets its
+ * `transforms` row from the scene context's sweep, and the emitter record points at that row.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or what {@link ParticleEmitter.from} accepts
+ * @param {import("../scene/Node3D.js").Node3D} [parent] node to hang the emitter under, itself already in the scene
+ * @returns {ParticleEmitter}
+ */
+export function place_emitter(fixture: ParticleSceneFixture, config: ParticleEmitter | object, parent?: import("../scene/Node3D.js").Node3D): ParticleEmitter;
+/**
+ * The two databases as the `array<u32>` buffers the particle shaders bind. Call after the last
+ * change to either; it flushes both.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @returns {{scene_database: Uint32Array, emitter_database: Uint32Array}}
+ */
+export function particle_database_words(fixture: ParticleSceneFixture): {
+    scene_database: Uint32Array;
+    emitter_database: Uint32Array;
+};
+/**
+ * An `array<atomic<u32>>` the way the emulator models one: a `{value}` object per word.
+ *
+ * @param {number} length
+ * @param {number} [fill]
+ * @returns {{value: number}[]}
+ */
+export function atomic_words(length: number, fill?: number): {
+    value: number;
+}[];
+/**
+ * A counters buffer, every slot zero.
+ *
+ * @returns {{value: number}[]}
+ */
+export function particle_counters(): {
+    value: number;
+}[];
+/**
+ * One emitter's GPU-owned state, read back out of the serialised database.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @returns {{generation: number, accumulator: number, age: number, sleep: number, pending: number}}
+ */
+export function emitter_state_read(emitter_database: Uint32Array, row: number): {
+    generation: number;
+    accumulator: number;
+    age: number;
+    sleep: number;
+    pending: number;
+};
+/**
+ * Overwrite some of one emitter's state fields in the serialised database — what a previous tick
+ * would have left there.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @param {{generation?: number, accumulator?: number, age?: number, sleep?: number, pending?: number}} fields
+ */
+export function emitter_state_write(emitter_database: Uint32Array, row: number, fields: {
+    generation?: number;
+    accumulator?: number;
+    age?: number;
+    sleep?: number;
+    pending?: number;
+}): void;
+/**
+ * A `{count, elements}` collection as the emulator binds one — the shape both the emitter tick's
+ * output and the emit pass's input take.
+ *
+ * @param {number} count
+ * @param {ArrayLike<number>} [elements] defaults to `count` zeros
+ * @returns {{count: number, elements: Uint32Array}}
+ */
+export function u32_collection(count: number, elements?: ArrayLike<number>): {
+    count: number;
+    elements: Uint32Array;
+};
+/**
+ * The CSDLDF scan's stand-in: inclusive prefix sums over a collection's elements, in place, the
+ * count left alone.
+ *
+ * @param {{count: number, elements: Uint32Array}} collection
+ * @returns {{count: number, elements: Uint32Array}} the same object
+ */
+export function inclusive_scan(collection: {
+    count: number;
+    elements: Uint32Array;
+}): {
+    count: number;
+    elements: Uint32Array;
+};
+export type ParticleSceneFixture = {
+    device: SoftwareGPUDevice;
+    graphics: GraphicsContext;
+    scene: Scene;
+    scene_context: import("../scene/GPUSceneContext.js").GPUSceneContext;
+    registry: EmitterRegistry;
+};
+import { ParticleEmitter } from "./runtime/ParticleEmitter.js";
+import { SoftwareGPUDevice } from "../../device/mock/SoftwareGPUDevice.js";
+import { GraphicsContext } from "../GraphicsContext.js";
+import { Scene } from "../scene/Scene.js";
+import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
+//# sourceMappingURL=particle_test_fixtures.d.ts.map

package/src/shade/renderer/particles/particle_test_fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_test_fixtures.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/particle_test_fixtures.js"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AAEH;;;;GAIG;AACH,0CAFa,oBAAoB,CAUhC;AAED;;;;;;;;GAQG;AACH,uCALW,oBAAoB,UACpB,eAAe,GAAC,MAAM,WACtB,OAAO,oBAAoB,EAAE,MAAM,GACjC,eAAe,CAkB3B;AAED;;;;;;GAMG;AACH,iDAHW,oBAAoB,GAClB;IAAC,cAAc,EAAE,WAAW,CAAC;IAAC,gBAAgB,EAAE,WAAW,CAAA;CAAC,CAUxE;AAED;;;;;;GAMG;AACH,qCAJW,MAAM,SACN,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,CAI7B;AAED;;;;GAIG;AACH,qCAFa;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,CAI7B;AA2BD;;;;;;GAMG;AACH,qDAJW,WAAW,OACX,MAAM,GACJ;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAalG;AAED;;;;;;;GAOG;AACH,sDAJW,WAAW,OACX,MAAM,UACN;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,QAWrG;AAED;;;;;;;GAOG;AACH,sCAJW,MAAM,aACN,UAAU,MAAM,CAAC,GACf;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAC,CAIlD;AAED;;;;;;GAMG;AACH,2CAHW;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAC,GACpC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAC,CAWlD;;YAlLa,iBAAiB;cACjB,eAAe;WACf,KAAK;mBACL,OAAO,6BAA6B,EAAE,eAAe;cACrD,eAAe;;gCAnBG,8BAA8B;kCAT5B,wCAAwC;gCAC1C,uBAAuB;sBAEjC,mBAAmB;gCAKT,8BAA8B"}

package/src/shade/renderer/particles/particle_test_fixtures.js

@@ -0,0 +1,203 @@
+import { SoftwareGPUDevice } from "../../device/mock/SoftwareGPUDevice.js";
+import { GraphicsContext } from "../GraphicsContext.js";
+import { gpu_database_words } from "../buffer/table/gpu_database_words.js";
+import { Scene } from "../scene/Scene.js";
+import { SceneManager } from "../scene/SceneManager.js";
+import { PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
+import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "./data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_EMITTER_STATE_STRUCT } from "./data/PARTICLE_EMITTER_STATE.js";
+import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
+import { ParticleEmitter } from "./runtime/ParticleEmitter.js";
+
+/**
+ * Shared scaffolding for the particle specs that run shaders under the WGSL emulator.
+ *
+ * An emitter is a scene node, so a shader that reads one needs two databases laid out the way the
+ * GPU would hold them: the scene's (for the node's world matrix) and the particle system's (for the
+ * emitter row). Both are real `GPUDatabase`s on the software device, filled through the real
+ * {@link GPUSceneContext} and {@link EmitterRegistry}, and serialised by
+ * {@link gpu_database_words} — so a spec exercises the actual writers, and the only thing standing
+ * in for the GPU is the upload.
+ */
+
+/**
+ * @typedef {object} ParticleSceneFixture
+ * @property {SoftwareGPUDevice} device
+ * @property {GraphicsContext} graphics
+ * @property {Scene} scene
+ * @property {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
+ * @property {EmitterRegistry} registry
+ */
+
+/**
+ * A scene with a GPU context and an emitter registry, both on a fresh software device.
+ *
+ * @returns {ParticleSceneFixture}
+ */
+export function particle_scene_fixture() {
+    const device = new SoftwareGPUDevice({ requiredFeatures: ["subgroups"] });
+    const graphics = new GraphicsContext(device);
+    const scene = new Scene();
+    const scene_context = new SceneManager(graphics).obtain(scene);
+    const registry = new EmitterRegistry(device);
+
+    return { device, graphics, scene, scene_context, registry };
+}
+
+/**
+ * Put an emitter in the scene and register it, the way the system does: the node gets its
+ * `transforms` row from the scene context's sweep, and the emitter record points at that row.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or what {@link ParticleEmitter.from} accepts
+ * @param {import("../scene/Node3D.js").Node3D} [parent] node to hang the emitter under, itself already in the scene
+ * @returns {ParticleEmitter}
+ */
+export function place_emitter(fixture, config, parent) {
+    const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
+
+    if (parent !== undefined) {
+        parent.addChild(emitter);
+        parent.updateMatrices();
+    }
+
+    fixture.scene.add(emitter);
+    fixture.scene_context.build();
+
+    const transform_row = fixture.scene_context.id_mapping.get(emitter.id);
+
+    fixture.registry.add(emitter, transform_row);
+
+    return emitter;
+}
+
+/**
+ * The two databases as the `array<u32>` buffers the particle shaders bind. Call after the last
+ * change to either; it flushes both.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @returns {{scene_database: Uint32Array, emitter_database: Uint32Array}}
+ */
+export function particle_database_words(fixture) {
+    fixture.scene_context.build();
+    fixture.registry.flush();
+
+    return {
+        scene_database: gpu_database_words(fixture.scene_context.scene_database, fixture.graphics),
+        emitter_database: gpu_database_words(fixture.registry.database, fixture.graphics),
+    };
+}
+
+/**
+ * An `array<atomic<u32>>` the way the emulator models one: a `{value}` object per word.
+ *
+ * @param {number} length
+ * @param {number} [fill]
+ * @returns {{value: number}[]}
+ */
+export function atomic_words(length, fill = 0) {
+    return Array.from({ length }, () => ({ value: fill }));
+}
+
+/**
+ * A counters buffer, every slot zero.
+ *
+ * @returns {{value: number}[]}
+ */
+export function particle_counters() {
+    return atomic_words(PARTICLE_COUNTER_COUNT);
+}
+
+/**
+ * Where a row of the `emitter_state` table sits in the serialised database, in words — the same
+ * arithmetic the table's generated readers do.
+ *
+ * @param {Uint32Array} emitter_database the database as {@link particle_database_words} lays it out
+ * @param {number} row
+ * @returns {number}
+ */
+function emitter_state_base(emitter_database, row) {
+    const descriptor = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+    const per_page = descriptor.elements_per_page;
+    const page_address = emitter_database[descriptor.page_lookup_address + Math.floor(row / per_page)];
+
+    if (page_address === 0xffffffff) {
+        throw new Error(`emitter state row ${row} is on a page the database has not allocated`);
+    }
+
+    return page_address + descriptor.page_header_words + (row % per_page) * (descriptor.packed_element_size_bytes / 4);
+}
+
+/** @type {Object<string, number>} word offset of each state field within its row */
+const STATE_FIELD_WORD = Object.fromEntries(
+    PARTICLE_EMITTER_STATE_STRUCT.fields.map((field) => [field.name, field.offset / 4]),
+);
+
+/**
+ * One emitter's GPU-owned state, read back out of the serialised database.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @returns {{generation: number, accumulator: number, age: number, sleep: number, pending: number}}
+ */
+export function emitter_state_read(emitter_database, row) {
+    const base = emitter_state_base(emitter_database, row);
+    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
+
+    return {
+        generation: emitter_database[base + STATE_FIELD_WORD.generation],
+        accumulator: floats[base + STATE_FIELD_WORD.accumulator],
+        age: floats[base + STATE_FIELD_WORD.age],
+        sleep: floats[base + STATE_FIELD_WORD.sleep],
+        pending: emitter_database[base + STATE_FIELD_WORD.pending],
+    };
+}
+
+/**
+ * Overwrite some of one emitter's state fields in the serialised database — what a previous tick
+ * would have left there.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @param {{generation?: number, accumulator?: number, age?: number, sleep?: number, pending?: number}} fields
+ */
+export function emitter_state_write(emitter_database, row, fields) {
+    const base = emitter_state_base(emitter_database, row);
+    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
+
+    if (fields.generation !== undefined) emitter_database[base + STATE_FIELD_WORD.generation] = fields.generation;
+    if (fields.accumulator !== undefined) floats[base + STATE_FIELD_WORD.accumulator] = fields.accumulator;
+    if (fields.age !== undefined) floats[base + STATE_FIELD_WORD.age] = fields.age;
+    if (fields.sleep !== undefined) floats[base + STATE_FIELD_WORD.sleep] = fields.sleep;
+    if (fields.pending !== undefined) emitter_database[base + STATE_FIELD_WORD.pending] = fields.pending;
+}
+
+/**
+ * A `{count, elements}` collection as the emulator binds one — the shape both the emitter tick's
+ * output and the emit pass's input take.
+ *
+ * @param {number} count
+ * @param {ArrayLike<number>} [elements] defaults to `count` zeros
+ * @returns {{count: number, elements: Uint32Array}}
+ */
+export function u32_collection(count, elements) {
+    return { count, elements: elements === undefined ? new Uint32Array(count) : Uint32Array.from(elements) };
+}
+
+/**
+ * The CSDLDF scan's stand-in: inclusive prefix sums over a collection's elements, in place, the
+ * count left alone.
+ *
+ * @param {{count: number, elements: Uint32Array}} collection
+ * @returns {{count: number, elements: Uint32Array}} the same object
+ */
+export function inclusive_scan(collection) {
+    let running = 0;
+
+    for (let i = 0; i < collection.count; i++) {
+        running += collection.elements[i];
+        collection.elements[i] = running;
+    }
+
+    return collection;
+}