@woosh/meep-engine 3.0.0 → 3.0.2

package/src/engine/graphics/particles/particular/engine/shader/ShaderManager.js

@@ -1,514 +1,135 @@
-import {
-    ClampToEdgeWrapping,
-    DataTexture,
-    LinearFilter,
-    LinearMipMapLinearFilter,
-    Matrix4,
-    RGBAFormat,
-    UnsignedByteType,
-    Vector2 as ThreeVector2
-} from "three";
-import { assert } from "../../../../../../core/assert.js";
-import { HashMap } from "../../../../../../core/collection/map/HashMap.js";
-import Vector2 from "../../../../../../core/geom/Vector2.js";
-import { ManagedAtlas } from "../../../../texture/atlas/ManagedTextureAtlas.js";
-import { writeSample2DDataToDataTexture } from "../../../../texture/sampler/writeSampler2DDataToDataTexture.js";
-import { ParticleEmitterFlag } from "../emitter/ParticleEmitterFlag.js";
-import { make_particle_billboard_shader } from "../renderers/billboard/ParticleBillboardMaterial.js";
-import { MaterialRecord } from "./MaterialRecord.js";
-
-const EMITTER_MATERIAL_FLAGS =
-    ParticleEmitterFlag.DepthSoftDisabled
-    | ParticleEmitterFlag.DepthReadDisabled
-    | ParticleEmitterFlag.AlignOnVelocity
-    | ParticleEmitterFlag.Lit
-;
-
-/**
- *
- * @param {ParticleEmitter} emitter
- * @returns {number}
- */
-function computeEmitterMaterialHash(emitter) {
-
-    return (emitter.flags & EMITTER_MATERIAL_FLAGS);
-}
-
-/**
- *
- * @param {ParticleEmitter} a
- * @param {ParticleEmitter} b
- * @returns {boolean}
- */
-function computeEmitterMaterialEquality(a, b) {
-    const aFlags = a.flags & EMITTER_MATERIAL_FLAGS;
-    const bFlags = b.flags & EMITTER_MATERIAL_FLAGS;
-
-    return (aFlags === bFlags);
-}
-
-
-/**
- * Used for placeholder texture value
- * @readonly
- * @type {Uint8Array}
- */
-const FOUR_BYTE_UINT8_ARRAY = new Uint8Array(4);
-
-/**
- * @returns {DataTexture}
- */
-function buildDataTexture(
-    {
-        anisotropy = 4,
-        generateMipmaps = false,
-        minFilter = LinearFilter,
-        magFilter = LinearFilter
-    }
-) {
-    const result = new DataTexture(FOUR_BYTE_UINT8_ARRAY, 1, 1, RGBAFormat);
-
-    result.type = UnsignedByteType;
-    result.flipY = false;
-    result.wrapS = ClampToEdgeWrapping;
-    result.wrapT = ClampToEdgeWrapping;
-
-    result.minFilter = minFilter;
-    result.magFilter = magFilter;
-
-    // possibly not-power-of-two
-    result.generateMipmaps = generateMipmaps;
-
-    result.repeat.set(1, 1);
-
-    result.anisotropy = anisotropy;
-
-    result.needsUpdate = true;
-
-    return result;
-}
-
-export class ShaderManager {
-    /**
-     *
-     * @type {Map<ParticleLayer, Reference<AtlasPatch>>}
-     */
-    #sprite_references = new Map();
-
-    /**
-     *
-     * @type {Texture|null}
-     */
-    depthTexture = null;
-
-    /**
-     * Number of unused records to keep, this allows reused of records avoiding shader recompilation
-     * @type {number}
-     */
-    recordGraveyardSize = 10;
-
-    /**
-     *
-     * @param {AssetManager} asset_manager
-     * @param {MaterialManager} material_manager
-     * @constructor
-     */
-    constructor(asset_manager, material_manager) {
-       assert.defined(asset_manager, "asset_manager");
-       assert.defined(material_manager, "material_manager");
-
-        /**
-         *
-         * @type {MaterialManager}
-         * @private
-         */
-        this.__material_manager = material_manager;
-
-        /**
-         *
-         * @type {ManagedAtlas}
-         */
-        this.spriteAtlas = new ManagedAtlas(asset_manager);
-
-        /**
-         *
-         * @type {DataTexture|null}
-         */
-        this.spriteTexture = buildDataTexture({
-            generateMipmaps: true,
-            minFilter: LinearMipMapLinearFilter,
-            magFilter: LinearFilter,
-            anisotropy: 0 // sprites are always facing the screen, anisotropic filtering would be pointless
-        });
-
-        this.spriteTexture.name = 'Sprite sheet';
-
-        /**
-         * material map is identified by parameter hash
-         * @readonly
-         * @private
-         * @type {HashMap<ParticleEmitter, MaterialRecord>}
-         */
-        this.materialMap = new HashMap({
-            keyHashFunction: computeEmitterMaterialHash,
-            keyEqualityFunction: computeEmitterMaterialEquality
-        });
-
-        /**
-         * @readonly
-         * @private
-         * @type {HashMap<ParticleEmitter, MaterialRecord>}
-         */
-        this.recordGraveyard = new HashMap({
-            keyHashFunction: computeEmitterMaterialHash,
-            keyEqualityFunction: computeEmitterMaterialEquality
-        });
-
-        /**
-         *
-         * @type {Vector2}
-         */
-        this.viewportSize = new Vector2(0, 0);
-
-        //watch atlas updates
-        this.spriteAtlas.atlas.on.painted.add(this.updateSpriteTexture, this);
-
-        /**
-         * Common shader uniforms, inherited by every material and updated centrally (here)
-         * @private
-         */
-        this.__common_uniforms = {
-            tSpriteAtlas: {
-                value: this.spriteTexture
-            },
-            tDepth: {
-                value: null
-            },
-            resolution: {
-                value: new ThreeVector2()
-            },
-            projectionMatrix: {
-                value: null
-            },
-            modelViewMatrix: {
-                value: null
-            },
-            cameraNear: {
-                value: 0
-            },
-            cameraFar: {
-                value: 0
-            },
-            uViewInverse: { type: 'm4', value: new Matrix4() },
-            uProjectionInverse: { type: 'm4', value: new Matrix4() },
-        };
-
-        // debugAtlas(this.spriteAtlas.atlas, { scale: new Vector2(1, 1) });
-    }
-
-    /**
-     * Should be called before using shaders managed by this
-     */
-    update() {
-        this.spriteAtlas.atlas.update();
-    }
-
-
-    /**
-     * @private
-     */
-    updateSpriteTexture() {
-        // console.time("ShaderManager.updateSpriteTexture");
-
-        const atlas = this.spriteAtlas.atlas.sampler;
-
-        const dataTexture = this.spriteTexture;
-
-        writeSample2DDataToDataTexture(atlas, dataTexture);
-
-        this.materialMap.forEach(function (entry) {
-
-            const emitters = entry.emitters;
-            const emitter_count = emitters.length;
-
-            for (let i = 0; i < emitter_count; i++) {
-                const emitter = emitters[i];
-                //mark sprites for an update
-                emitter.setFlag(ParticleEmitterFlag.SpritesNeedUpdate);
-            }
-
-        });
-
-        // console.timeEnd("ShaderManager.updateSpriteTexture");
-    }
-
-    /**
-     * @private
-     * @returns {Reference<Material>}
-     * @param {ParticleEmitter} emitter
-     */
-    buildMaterial(emitter) {
-        const lights_enabled = emitter.getFlag(ParticleEmitterFlag.Lit);
-
-        const shader = make_particle_billboard_shader({ lights: lights_enabled });
-
-        shader.uniforms = Object.assign(shader.uniforms, this.__common_uniforms);
-
-        // write defines
-        const defs = shader.defines;
-
-        defs.DEPTH_READ_ENABLED = !emitter.getFlag(ParticleEmitterFlag.DepthReadDisabled);
-        defs.DEPTH_SOFT_ENABLED = !emitter.getFlag(ParticleEmitterFlag.DepthSoftDisabled);
-        defs.ALIGN_DIRECTION_ENABLED = emitter.getFlag(ParticleEmitterFlag.AlignOnVelocity);
-
-        return this.__material_manager.obtain(shader);
-    }
-
-    /**
-     *
-     * @param {ParticleEmitter} emitter
-     */
-    register(emitter) {
-        const spriteAtlas = this.spriteAtlas;
-
-        // load sprites
-        const particle_layers = emitter.layers;
-        const layer_count = particle_layers.length;
-
-        for (let i = 0; i < layer_count; i++) {
-            const layer = particle_layers.get(i);
-
-            const patchPromise = spriteAtlas.acquire(layer.imageURL);
-
-            patchPromise.then(ref => {
-                this.#sprite_references.set(layer, ref);
-                layer.setAtlasPatch(ref.getValue());
-            });
-
-            patchPromise.catch((e) => {
-                console.warn(`Failed to load sprite '${layer.imageURL}':`, e);
-            });
-        }
-
-        // obtain material
-        let material, entry;
-        if (this.materialMap.has(emitter)) {
-            entry = this.materialMap.get(emitter);
-
-            // the record is in use again, so it is no longer a candidate for the graveyard eviction in
-            // `cleanup`, which releases the material reference the record still hands to live emitters
-            this.recordGraveyard.delete(emitter);
-
-            material = entry.material;
-        } else {
-
-            // entry is not in the cache, create it
-            entry = createShaderEntry(emitter, this);
-
-            material = entry.material;
-
-            this.materialMap.set(emitter, entry);
-        }
-
-        entry.lastAccessTime = performance.now();
-
-        entry.count++;
-
-        entry.emitters.push(emitter);
-
-        // assign material
-        emitter.mesh.material = material;
-    }
-
-    /**
-     * Perform intenal cleanup, remove unused material records
-     */
-    cleanup() {
-        const recordGraveyardSize = this.recordGraveyardSize;
-
-        while (this.recordGraveyard.size > recordGraveyardSize) {
-            let bestAccessTime = Infinity;
-            let bestKey = null;
-
-            this.recordGraveyard.forEach(function (value, key) {
-                if (value.lastAccessTime < bestAccessTime) {
-                    bestAccessTime = value.lastAccessTime;
-                    bestKey = key;
-                }
-            });
-
-            const evicted = this.recordGraveyard.get(bestKey);
-
-            if (!this.recordGraveyard.delete(bestKey)) {
-                console.error(`Failed to remove record from the graveyard`, bestKey, this.recordGraveyard);
-
-                this.recordGraveyard.verifyHashes(console.error);
-
-                console.warn('Recomputing hashes ... ');
-
-                this.recordGraveyard.rebuild();
-                this.materialMap.rebuild();
-            }
-
-            this.materialMap.delete(bestKey);
-
-            // the record is leaving both maps, so this is the last chance to hand the material back;
-            // only unused records reach the graveyard, `register` takes a resurrected one back out of it
-            evicted.material_reference.release();
-        }
-    }
-
-    /**
-     *
-     * @param {ParticleEmitter} emitter
-     */
-    deregister(emitter) {
-        const entry = this.materialMap.get(emitter);
-
-        if (entry === undefined) {
-            console.error(`Attempted to deregister emitter that was not registered (not found in materialMap). Request ignored.`, emitter);
-            return;
-        }
-
-        entry.count--;
-
-        //release material
-        const spriteAtlas = this.spriteAtlas;
-
-        //release sprites
-        const particle_layers = emitter.layers;
-        const layer_count = particle_layers.length;
-        for (let i = 0; i < layer_count; i++) {
-            const layer = particle_layers.get(i);
-
-            // TODO deal with the case where we remove the layer before sprite is loaded
-            const ref = this.#sprite_references.get(layer);
-
-            if (ref !== undefined) {
-                ref.release();
-
-                // the reference is spent, and the map is what keeps the layer reachable
-                this.#sprite_references.delete(layer);
-            }
-
-            layer.setAtlasPatch(null); // clear patch
-        }
-
-        if (entry.count <= 0) {
-            //last usage removed
-            this.recordGraveyard.set(emitter, entry);
-            this.cleanup();
-
-        } else {
-            //remove reference to material from the entry
-            const emitterIndex = entry.emitters.indexOf(emitter);
-
-            if (emitterIndex === -1) {
-                console.warn('Emitter was not found in the shader manager');
-                return;
-            }
-
-            //remove
-            entry.emitters.splice(emitterIndex, 1);
-        }
-    }
-
-    /**
-     *
-     * @param {Camera} camera THREE.js Camera object
-     */
-    setCamera(camera) {
-        this.camera = camera;
-
-        const projectionMatrix = camera.projectionMatrix;
-        const modelViewMatrix = (new Matrix4()).multiplyMatrices(camera.matrixWorldInverse, camera.matrixWorld);
-        const cameraNear = camera.near;
-        const cameraFar = camera.far;
-
-        const uniforms = this.__common_uniforms;
-
-        uniforms.projectionMatrix.value = projectionMatrix;
-        uniforms.modelViewMatrix.value = modelViewMatrix;
-        uniforms.cameraNear.value = cameraNear;
-        uniforms.cameraFar.value = cameraFar;
-
-        uniforms.uProjectionInverse.value.copy(camera.projectionMatrixInverse);
-        uniforms.uViewInverse.value.copy(camera.matrixWorld);
-    }
-
-    /**
-     *
-     * @param {Texture} texture
-     */
-    setDepthTexture(texture) {
-        this.depthTexture = texture;
-
-        this.__common_uniforms.tDepth.value = texture;
-
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     */
-    setViewportSize(x, y) {
-        this.viewportSize.set(x, y);
-
-        this.__common_uniforms.resolution.value.set(x, y);
-    }
-
-    /**
-     * Hand back every resource this manager acquired.
-     *
-     * Materials are given back to the {@link MaterialManager} rather than disposed here: the compiled
-     * material is shared by content hash with every other consumer that asked for the same shader, so the
-     * manager is the only thing that can know when the last user is gone. Releasing is therefore safe
-     * whichever way the teardown ordering falls, even for a material a live mesh still points at.
-     *
-     * The manager is left able to re-acquire, so a system that starts up again gets working materials and
-     * a working sprite sheet without being rebuilt.
-     */
-    dispose() {
-        // the graveyard is a subset of `materialMap` - `deregister` adds an unused record to the graveyard
-        // without taking it out of the material map, and `cleanup` is what drops it from both
-        this.materialMap.forEach(record => {
-            record.material_reference.release();
-        });
-
-        this.materialMap.clear();
-        this.recordGraveyard.clear();
-
-        for (const reference of this.#sprite_references.values()) {
-            reference.release();
-        }
-
-        this.#sprite_references.clear();
-
-        this.spriteTexture.dispose();
-    }
-}
-
-/**
- *
- * @param {ParticleEmitter} emitter
- * @param {ShaderManager} shaderManager
- * @returns {MaterialRecord}
- */
-function createShaderEntry(emitter, shaderManager) {
-    const entry = new MaterialRecord();
-    entry.count = 0;
-    entry.parameters = emitter.parameters;
-
-    const material_reference = shaderManager.buildMaterial(emitter);
-
-    entry.material_reference = material_reference;
-    entry.material = material_reference.getValue();
-
-    //link all signal bindings
-    entry.signalBindings.forEach(function (b) {
-        b.link();
-    });
-
-    return entry;
-}
+import { assert } from "../../../../../../core/assert.js";
+import { ManagedAtlas } from "../../../../texture/atlas/ManagedTextureAtlas.js";
+import { ParticleEmitterFlag } from "../emitter/ParticleEmitterFlag.js";
+
+/**
+ * The sprite sheet the particle system draws from.
+ *
+ * **Every emitter's layers share one atlas**, so a hundred effects using the same puff of smoke pay
+ * for one image; a layer holds a reference to the patch it was given and hands it back when the
+ * emitter is deregistered, and the atlas repacks when the set of patches changes.
+ *
+ * The class used to carry a second job — a compiled shader per emitter, keyed on the four flags
+ * that change the shader, with a graveyard of unused records to avoid recompiling. That was three's
+ * `ShaderMaterial`, and it is gone: the particles are drawn by a Shade pass that owns its own
+ * pipeline and reads the atlas sampler directly.
+ */
+export class ShaderManager {
+    /**
+     * The atlas patch each registered layer holds, so that deregistering can give it back.
+     *
+     * @type {Map<ParticleLayer, Reference<AtlasPatch>>}
+     */
+    #sprite_references = new Map();
+
+    /**
+     * The emitters currently drawing from the atlas. A repack has to reach all of them, and a
+     * layer does not know which emitter it belongs to.
+     *
+     * @type {Set<ParticleEmitter>}
+     */
+    #emitters = new Set();
+
+    /**
+     * @param {AssetManager} asset_manager
+     */
+    constructor(asset_manager) {
+        assert.defined(asset_manager, "asset_manager");
+
+        /**
+         *
+         * @type {ManagedAtlas}
+         */
+        this.spriteAtlas = new ManagedAtlas(asset_manager);
+
+        this.spriteAtlas.atlas.on.painted.add(this.#handleAtlasPainted, this);
+    }
+
+    /**
+     * Should be called before using the sprite sheet.
+     */
+    update() {
+        this.spriteAtlas.atlas.update();
+    }
+
+    /**
+     * A repack moves every patch, so every particle already carrying UVs is carrying the wrong ones.
+     */
+    #handleAtlasPainted() {
+        for (const emitter of this.#emitters) {
+            emitter.setFlag(ParticleEmitterFlag.SpritesNeedUpdate);
+        }
+    }
+
+    /**
+     * Take out a reference to every sprite the emitter's layers name.
+     *
+     * @param {ParticleEmitter} emitter
+     */
+    register(emitter) {
+        const spriteAtlas = this.spriteAtlas;
+
+        this.#emitters.add(emitter);
+
+        const particle_layers = emitter.layers;
+        const layer_count = particle_layers.length;
+
+        for (let i = 0; i < layer_count; i++) {
+            const layer = particle_layers.get(i);
+
+            const patchPromise = spriteAtlas.acquire(layer.imageURL);
+
+            patchPromise.then(ref => {
+                this.#sprite_references.set(layer, ref);
+                layer.setAtlasPatch(ref.getValue());
+            });
+
+            patchPromise.catch((e) => {
+                console.warn(`Failed to load sprite '${layer.imageURL}':`, e);
+            });
+        }
+    }
+
+    /**
+     * Hand back every sprite the emitter's layers hold.
+     *
+     * @param {ParticleEmitter} emitter
+     */
+    deregister(emitter) {
+        this.#emitters.delete(emitter);
+
+        const particle_layers = emitter.layers;
+        const layer_count = particle_layers.length;
+
+        for (let i = 0; i < layer_count; i++) {
+            const layer = particle_layers.get(i);
+
+            // TODO deal with the case where we remove the layer before sprite is loaded
+            const ref = this.#sprite_references.get(layer);
+
+            if (ref !== undefined) {
+                ref.release();
+
+                // the reference is spent, and the map is what keeps the layer reachable
+                this.#sprite_references.delete(layer);
+            }
+
+            layer.setAtlasPatch(null); // clear patch
+        }
+    }
+
+    /**
+     * Hand back every sprite this manager acquired.
+     *
+     * The manager is left able to re-acquire, so a system that starts up again gets a working
+     * sprite sheet without being rebuilt.
+     */
+    dispose() {
+        for (const reference of this.#sprite_references.values()) {
+            reference.release();
+        }
+
+        this.#sprite_references.clear();
+        this.#emitters.clear();
+    }
+}

package/src/engine/graphics/render/layers/RenderLayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderLayer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/layers/RenderLayer.js"],"names":[],"mappings":"AAKA;IAEI;;;OAGG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,MAFU,SAAO,IAAI,CAET;IAEZ;;;;OAIG;IACH,SAFU,OAAO,CAED;IAEhB;;;OAGG;IACH,2CAAgC;IAEhC;;;;;OAKG;IACH,YAFU,oBAAoB,MAAM,QAAQ,CAAC,CAEe;IAU5D;;;OAGG;IACH,0BAEC;IAdD;;;OAGG;IACH,uBAEC;IAUD;;;;;;;;;OASG;IACH,qDALW,MAAM,OACN,MAAM,mBACC,MAAM,OAAO,MAAM,KAAK,IAAI,uBAK7C;IAED;;;;;;OAMG;IACH,6BALW,MAAM,QAAQ,EAAE,sBAChB,MAAM,qBAEJ,MAAM,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,8BAFmB;QAAC,IAAI,EAAC,MAAM,CAAC;QAAA,GAAG,EAAC,MAAM,CAAA;KAAC,WAAU,UAAU,MAAM,CAAC,kBAAiB,MAAM,kBAAiB,MAAM,kBAAiB,MAAM,kBAAiB,MAAM,KAAK,IAAI,CAEhJ;CAC9B;iCA3FgC,uBAAuB;oCADpB,sCAAsC"}
+{"version":3,"file":"RenderLayer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/render/layers/RenderLayer.js"],"names":[],"mappings":"AAKA;IAEI;;;OAGG;IACH,OAFU,gBAAgB,CAEK;IAE/B;;;OAGG;IACH,MAFU,SAAO,IAAI,CAET;IAEZ;;;;OAIG;IACH,SAFU,OAAO,CAED;IAEhB;;;OAGG;IACH,2CAAgC;IAEhC;;;;;OAKG;IACH,YAFU,mCAAmC,CAEmB;IAUhE;;;OAGG;IACH,0BAEC;IAdD;;;OAGG;IACH,uBAEC;IAUD;;;;;;;;;OASG;IACH,qDALW,MAAM,OACN,MAAM,mBACC,MAAM,OAAO,MAAM,KAAK,IAAI,uBAK7C;IAED;;;;;;OAMG;IACH,6BALW,gBAAgB,sBAChB,MAAM,qBAEJ,MAAM,CAIlB;IAED;;;;;;;;;;;OAWG;IACH,8BAFmB;QAAC,IAAI,EAAC,MAAM,CAAC;QAAA,GAAG,EAAC,MAAM,CAAA;KAAC,WAAU,UAAU,MAAM,CAAC,kBAAiB,MAAM,kBAAiB,MAAM,kBAAiB,MAAM,kBAAiB,MAAM,KAAK,IAAI,CAEhJ;CAC9B;iCA3FgC,uBAAuB;oCADpB,sCAAsC"}