@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/graphics3/VolumetricLightMap.js

@@ -0,0 +1,160 @@
+import { assert } from "../../core/assert.js";
+import { Base64 } from "../../core/binary/base64/Base64.js";
+import { is_array_buffer_equals } from "../../core/collection/array/typed/is_array_buffer_equals.js";
+
+/**
+ * A baked volumetric lightmap, as the bytes the GPU wants and nothing else.
+ *
+ * **The scene has one of these, and this component is which one.** Shade keeps a single
+ * `Brick4LightMap` per scene — one buffer, read by every indirect-lighting pass while the renderer
+ * is in Brick4 mode — so a level's lightmap is a property of the level, not of a thing standing in
+ * it. Making it a component is what gives it a lifetime an entity already has: it arrives when the
+ * level's entity is built, it is saved with it, and it goes away when the entity does. See
+ * {@link VolumetricLightMapSystem3} for what happens when two entities claim the scene at once.
+ *
+ * **The payload is opaque here on purpose.** It is brick4's own GPU structure — the format
+ * `brick4_to_gpu_structure` writes and the indirect-lighting shaders read — and everything inside
+ * it, the node layout, the probe section, the SH encoding, is the renderer's business. This
+ * component neither validates it nor knows how to make one; a bake writes it, a load reads it off
+ * disk, and this carries it.
+ *
+ * **It is not placed by the entity's transform, and does not need one.** A brick4 structure begins
+ * with the world-space bounds it was baked against, so the map already knows where it is. Moving
+ * the entity that carries it moves nothing.
+ *
+ * @see VolumetricLightMapSystem3
+ * @see Brick4LightMap
+ */
+export class VolumetricLightMap {
+
+    /**
+     * @type {ArrayBuffer|null}
+     */
+    #data = null;
+
+    /**
+     * @type {number}
+     */
+    #version = 0;
+
+    /**
+     * The baked structure, or `null` while there isn't one.
+     *
+     * `null` is a normal state, not a broken one: the component says the entity carries the scene's
+     * lightmap, and the bytes may still be loading. A `null` map lights the scene with nothing.
+     *
+     * @returns {ArrayBuffer|null}
+     */
+    get data() {
+        return this.#data;
+    }
+
+    /**
+     * @param {ArrayBuffer|null} value
+     */
+    set data(value) {
+        if (value !== null) {
+            assert.isInstanceOf(value, ArrayBuffer, 'data');
+        }
+
+        this.#data = value;
+
+        this.#version++;
+    }
+
+    /**
+     * Bumped every time {@link data} is assigned.
+     *
+     * What the system watches to decide whether the GPU is behind. A megabyte-scale upload per frame
+     * would be the alternative, and comparing the buffers to avoid it costs a full read of both.
+     *
+     * **Assignment is the only thing that moves this.** Writing into the `ArrayBuffer` in place goes
+     * unnoticed — publish such a change by assigning `data` again, even to the same buffer.
+     *
+     * @returns {number}
+     */
+    get version() {
+        return this.#version;
+    }
+
+    /**
+     * @param {*} json
+     * @returns {VolumetricLightMap}
+     */
+    static fromJSON(json) {
+        const r = new VolumetricLightMap();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+
+    /**
+     * The bytes, base64'd.
+     *
+     * A lightmap runs to megabytes and base64 adds a third on top of that, so this is the expensive
+     * way to move one and the binary adapter is the cheap one. It exists because a blueprint that
+     * silently dropped the map would be worse than a large blueprint.
+     *
+     * @see VolumetricLightMapSerializationAdapter
+     */
+    toJSON() {
+        return {
+            data: this.#data === null ? null : Base64.encode(this.#data)
+        };
+    }
+
+    /**
+     * @param {string|null} [data]
+     */
+    fromJSON({ data = null }) {
+        if (data === null) {
+            this.data = null;
+
+            return;
+        }
+
+        assert.isString(data, 'data');
+
+        this.data = Base64.decode(data);
+    }
+
+    /**
+     * The byte length, and deliberately not the bytes.
+     *
+     * Hashing megabytes to answer "are these two the same component" is not a trade worth making,
+     * and a hash is allowed to collide. {@link equals} is the one that reads the buffer.
+     *
+     * @returns {number}
+     */
+    hash() {
+        const data = this.#data;
+
+        return data === null ? 0 : data.byteLength;
+    }
+
+    /**
+     * @param {VolumetricLightMap} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        const a = this.#data;
+        const b = other.data;
+
+        if (a === null || b === null) {
+            return a === b;
+        }
+
+        if (a.byteLength !== b.byteLength) {
+            return false;
+        }
+
+        return is_array_buffer_equals(a, 0, b, 0, a.byteLength);
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+VolumetricLightMap.typeName = "VolumetricLightMap";

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

@@ -0,0 +1,32 @@
+/**
+ * The lightmap's bytes, verbatim.
+ *
+ * There is nothing to encode: what the component holds is already the renderer's own binary
+ * structure, and re-describing its fields here would be a second copy of a layout
+ * {@link brick4_to_gpu_structure} owns. So the format is a presence byte, a length, and the block.
+ *
+ * The presence byte is what keeps "no map yet" distinct from "a map of zero bytes" across a save.
+ * Both light the scene with nothing, but only one of them is a state the component can be put back
+ * into, and a round trip that quietly turned one into the other would be a round trip that lied.
+ *
+ * **The block is native-endian**, because that is what `brick4_to_gpu_structure` writes and what the
+ * GPU reads back out of it. A save is therefore as portable as the bake it came from — which is to
+ * say little-endian, like every platform WebGPU runs on.
+ */
+export class VolumetricLightMapSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof VolumetricLightMap;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VolumetricLightMap} value
+     */
+    serialize(buffer: BinaryBuffer, value: VolumetricLightMap): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VolumetricLightMap} value
+     */
+    deserialize(buffer: BinaryBuffer, value: VolumetricLightMap): void;
+}
+import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { VolumetricLightMap } from "./VolumetricLightMap.js";
+//# sourceMappingURL=VolumetricLightMapSerializationAdapter.d.ts.map

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

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

package/src/engine/graphics3/VolumetricLightMapSerializationAdapter.js

@@ -0,0 +1,67 @@
+import { BinaryClassSerializationAdapter } from "../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { VolumetricLightMap } from "./VolumetricLightMap.js";
+
+/**
+ * The lightmap's bytes, verbatim.
+ *
+ * There is nothing to encode: what the component holds is already the renderer's own binary
+ * structure, and re-describing its fields here would be a second copy of a layout
+ * {@link brick4_to_gpu_structure} owns. So the format is a presence byte, a length, and the block.
+ *
+ * The presence byte is what keeps "no map yet" distinct from "a map of zero bytes" across a save.
+ * Both light the scene with nothing, but only one of them is a state the component can be put back
+ * into, and a round trip that quietly turned one into the other would be a round trip that lied.
+ *
+ * **The block is native-endian**, because that is what `brick4_to_gpu_structure` writes and what the
+ * GPU reads back out of it. A save is therefore as portable as the bake it came from — which is to
+ * say little-endian, like every platform WebGPU runs on.
+ */
+export class VolumetricLightMapSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = VolumetricLightMap;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VolumetricLightMap} value
+     */
+    serialize(buffer, value) {
+        const data = value.data;
+
+        if (data === null) {
+            buffer.writeUint8(0);
+
+            return;
+        }
+
+        buffer.writeUint8(1);
+
+        const byte_length = data.byteLength;
+
+        buffer.writeUintVar(byte_length);
+
+        buffer.writeBytes(new Uint8Array(data), 0, byte_length);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {VolumetricLightMap} value
+     */
+    deserialize(buffer, value) {
+        const present = buffer.readUint8();
+
+        if (present === 0) {
+            value.data = null;
+
+            return;
+        }
+
+        const byte_length = buffer.readUintVar();
+
+        const bytes = new Uint8Array(byte_length);
+
+        buffer.readBytes(bytes, 0, byte_length);
+
+        value.data = bytes.buffer;
+    }
+}

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

@@ -0,0 +1,98 @@
+/**
+ * The bytes the scene's lightmap buffer should hold for a given claim.
+ *
+ * **A claim with nothing usable in it is still a claim.** A component whose bake has not finished
+ * loading holds `null`, and one whose file turned out to be empty holds a zero-length buffer —
+ * neither is a structure the shader can traverse, and neither can simply be handed to
+ * `Brick4LightMap.upload`: it copies what it is given and no more, so a zero-length upload writes
+ * nothing at all and leaves the previous level's lighting exactly where it was. Both therefore
+ * resolve to an empty map, which is a real structure that lights nothing.
+ *
+ * @param {VolumetricLightMap|null} map `null` when nothing claims the scene
+ * @returns {ArrayBuffer}
+ */
+export function volumetric_light_map_payload(map: VolumetricLightMap | null): ArrayBuffer;
+/**
+ * Whether the scene's lightmap buffer is already holding what the claim says it should.
+ *
+ * The whole of what {@link VolumetricLightMapSystem3.update} decides, and true on all but a handful
+ * of frames in a session — an upload is a state change, and there are only so many of those.
+ *
+ * **A claim is identified by the component, not by its bytes.** Comparing the buffers would answer
+ * the same question and cost a full read of a megabyte-scale map to do it; the version is what makes
+ * a component that swapped its bytes distinguishable from one that did not.
+ *
+ * **No claim and nothing uploaded is current; no claim after an upload is not.** That asymmetry is
+ * the unlink: a buffer nobody has written to holds nothing, and a buffer holding the last level's
+ * lighting has to be given an empty map before it holds nothing too.
+ *
+ * @param {VolumetricLightMap|null} active what claims the scene now
+ * @param {VolumetricLightMap|null} uploaded what the buffer was last given, `null` for none
+ * @param {number} uploaded_version {@link VolumetricLightMap.version} as of that upload
+ * @returns {boolean}
+ */
+export function volumetric_light_map_is_current(active: VolumetricLightMap | null, uploaded: VolumetricLightMap | null, uploaded_version: number): boolean;
+/**
+ * Feeds the scene's baked volumetric lightmap to the GPU, and takes it away again.
+ *
+ * **The whole system is one buffer's worth of state.** Shade keeps a single `Brick4LightMap` on the
+ * scene's GPU context; a `VolumetricLightMap` component is a claim on it. So unlike the systems
+ * around it there is no per-entity object to build and place — there is one upload, and the work is
+ * deciding when it has to happen.
+ *
+ * **A scene has one lightmap, so a second claim waits rather than wins.** {@link active} is the
+ * *first* component to link and stays that way until it unlinks, at which point the next in line
+ * takes over. The alternative — last writer wins — makes the scene's lighting depend on the order
+ * entities happened to be built in, which is not a thing a level author controls. Swapping one map
+ * for another is therefore: remove the old component, add the new one.
+ *
+ * **The upload is decided in {@link update}, not in {@link link}.** A lightmap arrives whenever its
+ * level does, including before the renderer has a device — `scene_context` answers `null` until one
+ * exists, and answers with a *different* context after a restart, whose buffer is empty again. Both
+ * are the same question asked once a frame: is what the GPU holds still what the components say. A
+ * link is therefore eventually consistent, by at most one frame.
+ *
+ * **Unlinking uploads an empty map rather than leaving the last one there.** There is no way to
+ * un-upload — the shader reads the buffer unconditionally in Brick4 mode — so a component that
+ * removed itself and left the scene lit exactly as before would make the lifetime a fiction. A
+ * claim carrying nothing usable resolves the same way; see {@link volumetric_light_map_payload}.
+ *
+ * **What this does not do is turn Brick4 on.** Which indirect-lighting technique a frame uses is the
+ * renderer's setting, and a scene in IBL or LPV mode never reads this buffer no matter what is in
+ * it. Uploading a lightmap is necessary for Brick4 lighting and not sufficient for it.
+ *
+ * @see VolumetricLightMap
+ */
+export class VolumetricLightMapSystem3 extends System<any> {
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine3, scene: Scene);
+    dependencies: (typeof VolumetricLightMap)[];
+    /**
+     * The component the scene is lit from, or `null` when nothing claims it.
+     *
+     * Read-only — it follows the entities. What the GPU holds catches up with this on the next
+     * {@link update}.
+     *
+     * @returns {VolumetricLightMap|null}
+     */
+    get active(): VolumetricLightMap;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    link(map: VolumetricLightMap, entity: number): void;
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    unlink(map: VolumetricLightMap, entity: number): void;
+    #private;
+}
+import { VolumetricLightMap } from "./VolumetricLightMap.js";
+import { System } from "../ecs/System.js";
+//# sourceMappingURL=VolumetricLightMapSystem3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VolumetricLightMapSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/VolumetricLightMapSystem3.js"],"names":[],"mappings":"AAoNA;;;;;;;;;;;;GAYG;AACH,kDAHW,kBAAkB,GAAC,IAAI,GACrB,WAAW,CAUvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wDALW,kBAAkB,GAAC,IAAI,YACvB,kBAAkB,GAAC,IAAI,oBACvB,MAAM,GACJ,OAAO,CAQnB;AA7PD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAyDI;;;OAGG;IACH,qDAQC;IAnED,4CAAoC;IAyCpC;;;;;;;OAOG;IACH,iCAIC;IAgBD,2CAEC;IAED,4CAUC;IAED;;;OAGG;IACH,UAHW,kBAAkB,UAClB,MAAM,QAIhB;IAED;;;OAGG;IACH,YAHW,kBAAkB,UAClB,MAAM,QAYhB;;CA+DJ;mCA7MkC,yBAAyB;uBADrC,kBAAkB"}

package/src/engine/graphics3/VolumetricLightMapSystem3.js

@@ -0,0 +1,261 @@
+import { assert } from "../../core/assert.js";
+import {
+    brick4_empty_gpu_structure
+} from "../../shade/renderer/global_illumination/brick4/cpu/brick4_empty_gpu_structure.js";
+import { System } from "../ecs/System.js";
+import { VolumetricLightMap } from "./VolumetricLightMap.js";
+
+/**
+ * Feeds the scene's baked volumetric lightmap to the GPU, and takes it away again.
+ *
+ * **The whole system is one buffer's worth of state.** Shade keeps a single `Brick4LightMap` on the
+ * scene's GPU context; a `VolumetricLightMap` component is a claim on it. So unlike the systems
+ * around it there is no per-entity object to build and place — there is one upload, and the work is
+ * deciding when it has to happen.
+ *
+ * **A scene has one lightmap, so a second claim waits rather than wins.** {@link active} is the
+ * *first* component to link and stays that way until it unlinks, at which point the next in line
+ * takes over. The alternative — last writer wins — makes the scene's lighting depend on the order
+ * entities happened to be built in, which is not a thing a level author controls. Swapping one map
+ * for another is therefore: remove the old component, add the new one.
+ *
+ * **The upload is decided in {@link update}, not in {@link link}.** A lightmap arrives whenever its
+ * level does, including before the renderer has a device — `scene_context` answers `null` until one
+ * exists, and answers with a *different* context after a restart, whose buffer is empty again. Both
+ * are the same question asked once a frame: is what the GPU holds still what the components say. A
+ * link is therefore eventually consistent, by at most one frame.
+ *
+ * **Unlinking uploads an empty map rather than leaving the last one there.** There is no way to
+ * un-upload — the shader reads the buffer unconditionally in Brick4 mode — so a component that
+ * removed itself and left the scene lit exactly as before would make the lifetime a fiction. A
+ * claim carrying nothing usable resolves the same way; see {@link volumetric_light_map_payload}.
+ *
+ * **What this does not do is turn Brick4 on.** Which indirect-lighting technique a frame uses is the
+ * renderer's setting, and a scene in IBL or LPV mode never reads this buffer no matter what is in
+ * it. Uploading a lightmap is necessary for Brick4 lighting and not sufficient for it.
+ *
+ * @see VolumetricLightMap
+ */
+export class VolumetricLightMapSystem3 extends System {
+
+    dependencies = [VolumetricLightMap];
+
+    /**
+     * @type {GraphicsEngine3}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * Every entity claiming the scene's lightmap, oldest first.
+     *
+     * @type {{entity: number, component: VolumetricLightMap}[]}
+     */
+    #entries = [];
+
+    /**
+     * The context the buffer currently holding {@link #uploaded} belongs to.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * Whose bytes the GPU is holding, `null` when it is holding none.
+     *
+     * @type {VolumetricLightMap|null}
+     */
+    #uploaded = null;
+
+    /**
+     * {@link VolumetricLightMap.version} as of that upload. A component can replace its bytes
+     * without ever leaving the scene, and this is how that is noticed.
+     *
+     * @type {number}
+     */
+    #uploaded_version = -1;
+
+    /**
+     * The component the scene is lit from, or `null` when nothing claims it.
+     *
+     * Read-only — it follows the entities. What the GPU holds catches up with this on the next
+     * {@link update}.
+     *
+     * @returns {VolumetricLightMap|null}
+     */
+    get active() {
+        const entries = this.#entries;
+
+        return entries.length === 0 ? null : entries[0].component;
+    }
+
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+    }
+
+    async shutdown(entityManager) {
+        this.#entries.length = 0;
+
+        if (this.#uploaded !== null) {
+            // the renderer outlives the entity manager, so the scene is left unlit rather than lit
+            // by a level that is no longer loaded
+            this.#sync();
+        }
+
+        this.#forget();
+    }
+
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    link(map, entity) {
+        this.#entries.push({ entity, component: map });
+    }
+
+    /**
+     * @param {VolumetricLightMap} map
+     * @param {number} entity
+     */
+    unlink(map, entity) {
+        const entries = this.#entries;
+
+        const index = entries.findIndex(entry => entry.entity === entity);
+
+        if (index === -1) {
+            return;
+        }
+
+        entries.splice(index, 1);
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        this.#sync();
+    }
+
+    /**
+     * Bring the scene's lightmap buffer in line with what the components say.
+     *
+     * Does nothing at all in the common case, which is every frame after the one that uploaded.
+     */
+    #sync() {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            /*
+             No device — before the first start, or after a stop. Nothing can be uploaded while this
+             holds, and nothing has to be undone: the buffer that held the last upload was destroyed
+             with the context that owned it.
+            */
+            this.#forget();
+
+            return;
+        }
+
+        if (context !== this.#context) {
+            /*
+             A restart, which is the same event seen from the other side. The new context's buffer
+             has never been written to, so a claim that survived the restart uploads again below and
+             a scene with no claim is left alone rather than being cleared to a state it is already
+             in.
+            */
+            this.#forget();
+
+            this.#context = context;
+        }
+
+        const active = this.active;
+
+        if (volumetric_light_map_is_current(active, this.#uploaded, this.#uploaded_version)) {
+            return;
+        }
+
+        context.volumetric_light_map.upload(volumetric_light_map_payload(active));
+
+        this.#uploaded = active;
+        this.#uploaded_version = active === null ? -1 : active.version;
+    }
+
+    /**
+     * Drop the record of what the GPU is holding, without touching the GPU.
+     *
+     * Also drops this system's last reference to a component that has left the scene, which for a
+     * lightmap is megabytes.
+     */
+    #forget() {
+        this.#context = null;
+        this.#uploaded = null;
+        this.#uploaded_version = -1;
+    }
+}
+
+/**
+ * The bytes the scene's lightmap buffer should hold for a given claim.
+ *
+ * **A claim with nothing usable in it is still a claim.** A component whose bake has not finished
+ * loading holds `null`, and one whose file turned out to be empty holds a zero-length buffer —
+ * neither is a structure the shader can traverse, and neither can simply be handed to
+ * `Brick4LightMap.upload`: it copies what it is given and no more, so a zero-length upload writes
+ * nothing at all and leaves the previous level's lighting exactly where it was. Both therefore
+ * resolve to an empty map, which is a real structure that lights nothing.
+ *
+ * @param {VolumetricLightMap|null} map `null` when nothing claims the scene
+ * @returns {ArrayBuffer}
+ */
+export function volumetric_light_map_payload(map) {
+    const data = map === null ? null : map.data;
+
+    if (data === null || data.byteLength === 0) {
+        return brick4_empty_gpu_structure();
+    }
+
+    return data;
+}
+
+/**
+ * Whether the scene's lightmap buffer is already holding what the claim says it should.
+ *
+ * The whole of what {@link VolumetricLightMapSystem3.update} decides, and true on all but a handful
+ * of frames in a session — an upload is a state change, and there are only so many of those.
+ *
+ * **A claim is identified by the component, not by its bytes.** Comparing the buffers would answer
+ * the same question and cost a full read of a megabyte-scale map to do it; the version is what makes
+ * a component that swapped its bytes distinguishable from one that did not.
+ *
+ * **No claim and nothing uploaded is current; no claim after an upload is not.** That asymmetry is
+ * the unlink: a buffer nobody has written to holds nothing, and a buffer holding the last level's
+ * lighting has to be given an empty map before it holds nothing too.
+ *
+ * @param {VolumetricLightMap|null} active what claims the scene now
+ * @param {VolumetricLightMap|null} uploaded what the buffer was last given, `null` for none
+ * @param {number} uploaded_version {@link VolumetricLightMap.version} as of that upload
+ * @returns {boolean}
+ */
+export function volumetric_light_map_is_current(active, uploaded, uploaded_version) {
+    if (active === null) {
+        return uploaded === null;
+    }
+
+    return active === uploaded && active.version === uploaded_version;
+}