@woosh/meep-engine 2.45.2 → 2.46.1

package/engine/graphics/render/frame_graph/GraphNode.js

@@ -1,22 +0,0 @@
-export class GraphNode {
-    /**
-     *
-     * @type {string}
-     */
-    name = "";
-    /**
-     *
-     * @type {number}
-     */
-    id = 0;
-    /**
-     *
-     * @type {number}
-     */
-    version = 0;
-    /**
-     *
-     * @type {number}
-     */
-    ref_count = 0;
-}

package/engine/graphics/render/frame_graph/IRenderContext.js

@@ -1,8 +0,0 @@
-//
-
-/**
- * Abstracts rendering context, such as "WebGLRenderer" in THREE.js or WebGL/WebGPU
- */
-export class IRenderContext {
-//TODO implement
-}

package/engine/graphics/render/frame_graph/RenderGraph.js

@@ -1,409 +0,0 @@
-import { RenderGraphBuilder } from "./RenderGraphBuilder.js";
-import { RenderPassNode } from "./RenderPassNode.js";
-import { ResourceNode } from "./ResourceNode.js";
-import { assert } from "../../../../core/assert.js";
-import LineBuilder from "../../../../core/codegen/LineBuilder.js";
-import { RenderPassResources } from "./RenderPassResources.js";
-import { ResourceEntry } from "./ResourceEntry.js";
-
-/**
- * Based on the Frostbite's GDC paper "FrameGraph: Extensible Rendering Architecture in Frostbite" by Yuriy O'Donnell
- * @see https://github.com/skaarj1989/FrameGraph
- */
-export class RenderGraph {
-    /**
-     *
-     * @type {RenderPass[]}
-     * @private
-     */
-    __passes = [];
-
-    /**
-     *
-     * @type {RenderPassNode[]}
-     * @private
-     */
-    __pass_nodes = [];
-
-    /**
-     *
-     * @type {ResourceNode[]}
-     * @private
-     */
-    __resource_nodes = [];
-
-    /**
-     *
-     * @type {ResourceEntry[]}
-     * @private
-     */
-    __resource_registry = [];
-
-    /**
-     *
-     * @param {number} id Resource Node ID
-     * @returns {ResourceEntry}
-     */
-    getResourceEntry(id) {
-        const node = this.getResourceNode(id);
-
-        return this.__resource_registry[node.resource_id];
-    }
-
-    /**
-     *
-     * @param {number} id
-     * @returns {ResourceNode}
-     */
-    getResourceNode(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        const nodes = this.__resource_nodes;
-        const node_count = nodes.length;
-        for (let i = 0; i < node_count; i++) {
-            const node = nodes[i];
-            if (node.id === id) {
-                return node;
-            }
-        }
-
-        throw new Error(`Resource Node ${id} not found`);
-    }
-
-    /**
-     * @template T
-     * @param {number} id resource ID
-     * @returns {T}
-     */
-    getDescriptor(id) {
-        return this.getResourceEntry(id).resource_descriptor;
-    }
-
-    /**
-     * @template T
-     * @param {string} name
-     * @param {T} descriptor
-     */
-    create_resource(name, descriptor) {
-        const resource = this._createResourceEntry(descriptor);
-
-        return this._createResourceNode(name, resource.resource_id).id;
-    }
-
-    /**
-     * @template T
-     * @param {T} descriptor
-     * @return {ResourceEntry}
-     * @private
-     */
-    _createResourceEntry(descriptor) {
-
-        const entry = new ResourceEntry();
-
-        entry.resource_id = this.__resource_registry.length;
-        entry.resource_descriptor = descriptor;
-
-        this.__resource_registry.push(entry);
-
-        return entry;
-    }
-
-    /**
-     *
-     * @param {string} name
-     * @param {number} resource_id
-     * @return {ResourceNode}
-     * @private
-     */
-    _createResourceNode(name, resource_id) {
-        assert.isNonNegativeInteger(resource_id, 'resource_id');
-
-        const n = new ResourceNode();
-
-        const id = this.__resource_nodes.length;
-
-        n.id = id;
-        n.name = name;
-        n.resource_id = resource_id;
-
-        this.__resource_nodes[id] = n;
-
-        return n;
-    }
-
-    /**
-     *
-     * @param {number} res
-     * @returns {number}
-     */
-    clone_resource(res) {
-        const node = this.getResourceNode(res);
-
-        const entry = this.__resource_registry[node.resource_id];
-
-        entry.resource_version++;
-
-        const clone_node = new ResourceNode();
-        clone_node.id = this.__resource_nodes.length;
-        clone_node.name = node.name;
-        clone_node.resource_id = node.resource_id;
-        clone_node.version = entry.resource_version;
-
-        this.__resource_nodes.push(clone_node);
-
-        return clone_node.id;
-    }
-
-    /**
-     * @template T
-     * @param {string} name
-     * @param {TextureDescriptor} description
-     * @param {T} resource
-     * @returns {number}
-     */
-    import_resource(name, description, resource) {
-        const record = this._createResourceEntry(description);
-
-        record.resource = resource;
-
-        record.imported = true;
-
-        return this._createResourceNode(name, record.resource_id).id;
-    }
-
-    /**
-     * @returns {boolean}
-     * @param id
-     */
-    is_valid_resource(id) {
-        const node = this.getResourceNode(id);
-        const record = this.getResourceEntry(id);
-
-        return node.version === record.resource_version;
-    }
-
-    /**
-     * @template T
-     * @param {RenderPass} pass
-     * @returns {T} resources/handles returned by {@link RenderPass#setup}
-     */
-    add(pass) {
-
-        const pass_nodes = this.__pass_nodes;
-
-        const builder = new RenderGraphBuilder();
-        const node = new RenderPassNode();
-
-        node.id = pass_nodes.length;
-        node.name = pass.name;
-        node.pass = pass;
-
-        pass_nodes.push(node);
-
-        builder.init(this, node);
-
-        const result = pass.setup(builder, pass.inputs);
-
-        this.__passes.push(pass);
-
-        node.data = result;
-
-        return result;
-    }
-
-    compile() {
-        const pass_nodes = this.__pass_nodes;
-
-        // wire resources of passes
-        const pass_node_count = pass_nodes.length;
-        const resource_nodes = this.__resource_nodes;
-
-        for (let i = 0; i < pass_node_count; i++) {
-            const pass = pass_nodes[i];
-
-            // mask pass as having number of references equal to number of resources it writes to
-            pass.ref_count = pass.resource_writes.length;
-
-            for (const id of pass.resource_reads) {
-                const read_node = resource_nodes[id];
-
-                read_node.ref_count++;
-            }
-
-            for (const id of pass.resource_writes) {
-                const written_node = resource_nodes[id];
-
-                written_node.producer = pass;
-            }
-        }
-
-        // perform culling
-        /**
-         *
-         * @type {ResourceNode[]}
-         */
-        const unreferenced_resources = [];
-
-        for (const node of resource_nodes) {
-            if (node.ref_count === 0) {
-                unreferenced_resources.push(node);
-            }
-        }
-
-        while (unreferenced_resources.length > 0) {
-            const unreferenced_resource = unreferenced_resources.pop();
-
-            const producer = unreferenced_resource.producer;
-
-            if (producer === null || producer.has_side_effects) {
-                continue;
-            }
-
-            assert.greaterThanOrEqual(producer.ref_count, 1, 'must have at least one reference'); // Why?
-
-            // disconnect unreferenced resource from producer
-            producer.ref_count--;
-
-            if (producer.ref_count === 0) {
-
-                // producer is no longer referenced
-
-                for (const id of producer.resource_reads) {
-                    const node = resource_nodes[id];
-
-                    // disconnect producer from all its reads (upstream)
-                    node.ref_count--;
-
-                    if (node.ref_count === 0) {
-                        // resource is no longer referenced
-                        unreferenced_resources.push(node);
-                    }
-                }
-            }
-        }
-
-        // calculate lifetimes
-        for (const pass of pass_nodes) {
-            if (pass.ref_count === 0) {
-                // unused pass
-                continue;
-            }
-
-            for (const id of pass.resource_creates) {
-                this.getResourceEntry(id).producer = pass;
-            }
-
-            for (const id of pass.resource_writes) {
-                this.getResourceEntry(id).last = pass;
-            }
-
-            for (const id of pass.resource_reads) {
-                this.getResourceEntry(id).last = pass;
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {IRenderContext} context
-     */
-    execute(context) {
-        const pass_nodes = this.__pass_nodes;
-        const pass_node_count = pass_nodes.length;
-        for (let i = 0; i < pass_node_count; i++) {
-            const node = pass_nodes[i];
-
-            if (!node.can_execute()) {
-                continue;
-            }
-
-            for (const id of node.resource_creates) {
-                // allocate resource
-                this.getResourceEntry(id).create();
-            }
-
-            const resources = new RenderPassResources();
-            resources.init(this, node);
-
-            // execute pass
-            node.pass.execute(node.data, resources, context);
-
-            for (const entry of this.__resource_registry) {
-                if (entry.last === node && entry.isTransient()) {
-                    // this was the last user of the resource and the resource is transient (no external usage)
-                    entry.destroy();
-                }
-            }
-
-        }
-    }
-
-    /**
-     * @see https://en.wikipedia.org/wiki/DOT_(graph_description_language)
-     * @return {string}
-     */
-    exportToDot() {
-        const out = new LineBuilder();
-
-        out.add("digraph FrameGraph {");
-        out.indent();
-        out.add("graph [style=invis, rankdir=\"TB\" ordering=out, splines=spline]");
-        out.add("node [shape=record, fontname=\"helvetica\", fontsize=10, margin=\"0.2,0.03\"]");
-
-
-        // -- Define pass nodes
-
-        out.add("");
-        out.add("# Pass Nodes");
-        for (const node of this.__pass_nodes) {
-            out.add(`P${node.id} [label=<{ {<B>${node.name}</B>} | {${(node.has_side_effects ? "&#x2605; " : "")} Refs: ${node.ref_count}<BR/> Index: ${node.id}} }> style=\"rounded,filled\", fillcolor=${(node.ref_count > 0 || node.has_side_effects) ? "orange" : "lightgray"}]`);
-        }
-
-        // -- Define resource nodes
-
-        out.add("");
-        out.add("# Resource Nodes");
-        for (const node of this.__resource_nodes) {
-            const entry = this.__resource_registry[node.resource_id];
-            out.add(`R${entry.resource_id}_${node.version} [label=<{ {<B>${node.name}</B>${node.version > 0 ? `<FONT>v${node.version}</FONT>` : ""}<BR/>${entry.toString()}} | {Index: ${entry.resource_id}<BR/> Refs : ${node.ref_count} } }> style=filled, fillcolor=${entry.isImported() ? "lightsteelblue" : "skyblue"}]`);
-        }
-
-        // -- Each pass node points to resource that it writes
-
-        out.add("");
-        out.add("# Resource Writes");
-        for (const node of this.__pass_nodes) {
-            out.add(`P${node.id} -> {`);
-            out.indent();
-            for (const id of node.resource_writes) {
-                const written = this.__resource_nodes[id];
-                out.add(`R${written.resource_id}_${written.version} `);
-            }
-            out.dedent();
-            out.add("} [color=orangered]");
-        }
-
-        // -- Each resource node points to pass where it's consumed
-
-        out.add("");
-        out.add("# Resource Reads");
-
-        for (const node of this.__resource_nodes) {
-            out.add(`R${node.resource_id}_${node.version} -> {`);
-            out.indent();
-            // find all readers of this resource node
-            for (const pass of this.__pass_nodes) {
-                for (const id of pass.resource_reads)
-                    if (id === node.id) {
-                        out.add(`P${pass.id} `);
-                    }
-            }
-            out.dedent();
-            out.add("} [color=olivedrab3]");
-        }
-        // -- Clusters:
-        out.dedent();
-        out.add("}");
-        return out.build();
-    }
-}

package/engine/graphics/render/frame_graph/RenderGraphBuilder.js

@@ -1,77 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-
-export class RenderGraphBuilder {
-    /**
-     *
-     * @type {RenderGraph}
-     * @private
-     */
-    __graph = null;
-    /**
-     *
-     * @type {RenderPassNode}
-     * @private
-     */
-    __node = null;
-
-    /**
-     *
-     * @param {RenderGraph} graph
-     * @param {RenderPassNode} node
-     */
-    init(graph, node) {
-        this.__graph = graph;
-        this.__node = node;
-    }
-
-    /**
-     *
-     * @param {string} name
-     * @param {TextureDescriptor} descriptor
-     * @returns {number} resource ID
-     */
-    create(name, descriptor) {
-        const node = this.__graph.create_resource(name, descriptor);
-
-        // remember resource
-        this.__node.resource_creates.push(node);
-
-        return node;
-    }
-
-    /**
-     *
-     * @param {number} resource
-     * @returns {number}
-     */
-    read(resource) {
-        assert.isNonNegativeInteger(resource, 'resource');
-
-        return this.__node.read(resource);
-    }
-
-    /**
-     *
-     * @param {number} resource
-     * @returns {number}
-     */
-    write(resource) {
-        const graph = this.__graph;
-        const node = this.__node;
-
-        if (graph.getResourceEntry(resource).isImported()) {
-            // comes from outside the graph, and we write to it. That's a side effect
-            node.has_side_effects = true;
-        }
-
-        if (node.creates(resource)) {
-            return node.write(resource);
-        } else {
-            // writing to a resource produces a renamed handle
-            node.read(resource);
-
-            return node.write(graph.clone_resource(resource));
-        }
-
-    }
-}

package/engine/graphics/render/frame_graph/RenderPass.js

@@ -1,50 +0,0 @@
-const DEFAULT_FLAGS = 0;
-
-/**
- * @template DATA
- */
-export class RenderPass {
-
-    /**
-     * Used for debug and visualisation
-     * @type {string}
-     */
-    name = "Render Pass";
-
-    /**
-     *
-     * @type {number|RenderPassFlags}
-     */
-    flags = DEFAULT_FLAGS;
-
-
-    /**
-     * Arbitrary dictionary of data
-     * @type {Object<number>}
-     */
-    inputs = {};
-
-    constructor(inputs = {}) {
-        this.inputs = inputs;
-    }
-
-
-    /**
-     *
-     * @param {RenderGraphBuilder} builder
-     * @param {Object<number>} inputs
-     * @returns {Object<number>}
-     */
-    setup(builder, inputs) {
-        throw new Error('Not Implemented');
-    }
-
-    /**
-     * @param {DATA} data
-     * @param {RenderPassResources} resources
-     * @param {IRenderContext} render_context
-     */
-    execute(data, resources, render_context) {
-        throw new Error('Not Implemented');
-    }
-}

package/engine/graphics/render/frame_graph/RenderPassFlags.js

@@ -1,6 +0,0 @@
-export const RenderPassFlags = {
-    /**
-     * Render pass hidden effects, accessing data from outside
-     */
-    HasSideEffects: 1
-};

package/engine/graphics/render/frame_graph/RenderPassNode.js

@@ -1,103 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import { GraphNode } from "./GraphNode.js";
-
-export class RenderPassNode extends GraphNode {
-    /**
-     *
-     * @type {RenderPass|null}
-     */
-    pass = null;
-
-
-    /**
-     *
-     * @type {boolean}
-     */
-    has_side_effects = false;
-
-    /**
-     *
-     * @type {null}
-     */
-    data = null;
-
-    /**
-     * IDs of created resources
-     * @type {number[]}
-     */
-    resource_creates = [];
-    /**
-     * IDs of created resources
-     * @type {number[]}
-     */
-    resource_reads = [];
-    /**
-     * IDs of created resources
-     * @type {number[]}
-     */
-    resource_writes = [];
-
-    /**
-     *
-     * @param {number} id
-     * @return {boolean}
-     */
-    creates(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        return this.resource_creates.includes(id);
-    }
-
-    /**
-     *
-     * @param {number} id
-     * @return {boolean}
-     */
-    reads(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        return this.resource_reads.includes(id);
-    }
-
-    /**
-     *
-     * @param {number} id
-     * @return {boolean}
-     */
-    writes(id) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        return this.resource_writes.includes(id);
-    }
-
-    write(resource) {
-        if (this.writes(resource)) {
-            return resource;
-        }
-
-        this.resource_writes.push(resource);
-        return resource;
-    }
-
-    /**
-     *
-     * @param {number} resource
-     */
-    read(resource) {
-        if (this.reads(resource)) {
-            return resource;
-        }
-
-        this.resource_reads.push(resource);
-
-        return resource;
-    }
-
-    /**
-     *
-     * @return {boolean}
-     */
-    can_execute() {
-        return this.ref_count > 0 || this.has_side_effects;
-    }
-}