@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/render/rendergraph/rendergraph.js

@@ -1,103 +1,86 @@
 import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
 
-/**
- * Render Graph — declarative, configurable render pipeline.
- *
- * Usage:
- * ```ts
- * const graph = new RenderGraph();
- * let backbuffer = graph.importTexture('backbuffer');
- *
- * let linearDepth: RGHandle;
- * graph.addPass('DepthPrepass', (builder) => {
- *   linearDepth = builder.createTexture({ format: 'r32f', label: 'linearDepth' });
- *   builder.setExecute(() => { ... });
- * });
- *
- * graph.addPass('LightPass', (builder) => {
- *   builder.read(linearDepth);
- *   backbuffer = builder.write(backbuffer);
- *   builder.setExecute(() => { ... });
- * });
- *
- * const compiled = graph.compile([backbuffer]);
- * graph.execute(compiled);
- * graph.reset();
- * ```
- *
- * @public
- */ class RenderGraph {
-    /** @internal */ _nextResourceId = 0;
-    /** @internal */ _resources = new Map();
-    /** @internal */ _passes = [];
-    /** @internal */ _compiled = null;
-    // ─── Graph Building ─────────────────────────────────────────────────
-    /**
-   * Import an external (persistent) texture into the graph.
-   *
-   * Imported resources are not allocated or released by the graph.
-   * Typically used for the backbuffer or any texture that outlives a single frame.
-   *
-   * @param name - Debug label for the imported resource.
-   * @returns A handle referencing the imported resource.
-   */ importTexture(name) {
+/** Declarative render pass and resource dependency graph. @public */ class RenderGraph {
+    _nextResourceId = 0;
+    _resources = new Map();
+    _passes = [];
+    _compiled = null;
+    _lastWriterByPhysicalId = new Map();
+    /** Deduplicates warnings across per-frame graph instances. */ static _warnedCulledPasses = new Set();
+    /** Import an external texture that the graph does not own. */ importTexture(name) {
         const id = this._nextResourceId++;
         const resource = new RGResource(id, name, 'imported', null);
         this._resources.set(id, resource);
         this._compiled = null;
-        return new RGHandle(id, name);
+        return new RGHandle(id, name, 'texture');
     }
     /**
-   * Add a render pass to the graph.
-   *
-   * The setup callback receives a {@link RGPassBuilder} to declare resource
-   * dependencies. Call `builder.setExecute(fn)` inside setup to provide the
-   * execution callback.
-   *
-   * @param name - Debug label for the pass.
-   * @param setup - Setup callback that declares resources and sets the execute function.
+   * Add a pass. The setup callback declares dependencies and execution.
    */ addPass(name, setup) {
-        const pass = new RGPass(this._passes.length, name);
+        let nameOccurrence = 0;
+        for (const existing of this._passes){
+            if (existing.name === name) {
+                nameOccurrence++;
+            }
+        }
+        const pass = new RGPass(this._passes.length, name, nameOccurrence);
         const builder = this._createBuilder(pass);
-        const data = setup(builder);
-        pass.data = data;
-        this._passes.push(pass);
-        this._compiled = null;
-        return data;
+        const initialResourceIds = new Set(this._resources.keys());
+        try {
+            const data = setup(builder);
+            pass.data = data;
+            this._passes.push(pass);
+            this._compiled = null;
+            return data;
+        } catch (error) {
+            for (const id of this._resources.keys()){
+                if (!initialResourceIds.has(id)) {
+                    this._resources.delete(id);
+                }
+            }
+            for (const resource of this._resources.values()){
+                for(let i = resource.consumers.length - 1; i >= 0; i--){
+                    if (resource.consumers[i] === pass) {
+                        resource.consumers.splice(i, 1);
+                    }
+                }
+                if (resource.nextWriter === pass) {
+                    resource.nextWriter = null;
+                }
+            }
+            // Remove WAR edges added to existing passes before setup failed.
+            for (const existing of this._passes){
+                for(let i = existing.warDependencies.length - 1; i >= 0; i--){
+                    if (existing.warDependencies[i] === pass) {
+                        existing.warDependencies.splice(i, 1);
+                    }
+                }
+            }
+            this._lastWriterByPhysicalId.clear();
+            for (const resource of this._resources.values()){
+                if (resource.producer) {
+                    this._lastWriterByPhysicalId.set(resource.physicalId, resource.producer);
+                }
+            }
+            throw error;
+        }
     }
-    // ─── Compilation ────────────────────────────────────────────────────
     /**
-   * Compile the render graph.
-   *
-   * Performs dead-pass culling, topological sorting, and resource lifetime analysis.
-   *
-   * @param outputs - Handles of resources that must be produced (graph sinks).
-   *   If a resource was passed to {@link RGPassBuilder.write}, use the returned
-   *   post-write handle here, not the original handle.
-   *   Passes that do not contribute to these outputs (directly or transitively)
-   *   are culled, unless marked as side-effect passes.
-   * @returns The compiled graph ready for execution.
+   * Cull dead passes, sort dependencies, and calculate resource lifetimes.
+   * Outputs must be their latest written versions.
    */ compile(outputs) {
         this._validateOutputs(outputs);
-        // 1. Mark alive passes via backward traversal from outputs + side-effect passes
         this._cullDeadPasses(outputs);
-        // 2. Topological sort of alive passes
         const ordered = this._topologicalSort();
-        // 3. Resource lifetime analysis
         const lifetimes = this._analyzeLifetimes(ordered);
+        this._validateAllocationKeys(lifetimes);
         this._compiled = {
             orderedPasses: ordered,
             lifetimes
         };
         return this._compiled;
     }
-    /**
-   * Execute a compiled render graph (simple mode, no resource management).
-   *
-   * For automatic resource allocation/release, use {@link RenderGraphExecutor} instead.
-   *
-   * @param compiled - The compiled graph from {@link RenderGraph.compile}.
-   */ execute(compiled) {
+    /** @internal Test-only callback runner; resource-managed code uses RenderGraphExecutor. */ execute(compiled) {
         const noopCtx = {
             getTexture () {
                 throw new Error('RenderGraph.execute(): resource resolution not available. Use RenderGraphExecutor for managed execution.');
@@ -108,9 +91,7 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             createFramebuffer () {
                 throw new Error('RenderGraph.execute(): framebuffer allocation not available. Use RenderGraphExecutor for managed execution.');
             },
-            deferCleanup () {
-            // No-op in unmanaged execution mode.
-            }
+            deferCleanup () {}
         };
         for (const pass of compiled.orderedPasses){
             if (pass.subpasses.length > 0) {
@@ -122,18 +103,13 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             }
         }
     }
-    /**
-   * Reset the graph for the next frame.
-   *
-   * Clears all passes, transient resources, and compiled state.
-   * Imported resources are also cleared — re-import them each frame.
-   */ reset() {
+    /** Clear all passes, resources, and compiled state. */ reset() {
         this._passes.length = 0;
         this._resources.clear();
         this._nextResourceId = 0;
         this._compiled = null;
+        this._lastWriterByPhysicalId.clear();
     }
-    // ─── Accessors (for testing / debugging) ────────────────────────────
     /** @internal */ getResource(handle) {
         return this._resources.get(handle._id);
     }
@@ -143,27 +119,18 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
     /** @internal */ get resources() {
         return this._resources;
     }
-    // ─── Private: Builder ───────────────────────────────────────────────
-    /** @internal */ _createBuilder(pass) {
+    _createBuilder(pass) {
         const graph = this;
+        const textureLabelOccurrences = new Map();
         return {
             read (handle) {
                 const res = graph._resources.get(handle._id);
                 if (!res) {
                     throw new Error(`RenderGraph: unknown resource "${handle.name}" (id=${handle._id})`);
                 }
-                // Validate that transient resources have a producer
-                if (res.kind === 'transient' && !res.producer) {
-                    throw new Error(`RenderGraph: pass "${pass.name}" attempts to read transient resource "${res.name}" ` + `which has no producer. Ensure the resource is created before being read.`);
-                }
-                if (!pass.reads.includes(res)) {
-                    pass.reads.push(res);
-                }
-                if (!res.consumers.includes(pass)) {
-                    res.consumers.push(pass);
-                }
+                graph._declareRead(pass, res);
             },
-            write (handle) {
+            write (handle, options) {
                 const res = graph._resources.get(handle._id);
                 if (!res) {
                     throw new Error(`RenderGraph: unknown resource "${handle.name}" (id=${handle._id})`);
@@ -174,32 +141,62 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 if (res.kind === 'framebuffer') {
                     throw new Error(`RenderGraph: pass "${pass.name}" attempts to write framebuffer "${res.name}". ` + `Create a new framebuffer view instead.`);
                 }
+                const discard = options?.load === 'discard';
+                const previousWriter = graph._lastWriterByPhysicalId.get(res.physicalId);
+                if (previousWriter && previousWriter !== pass) {
+                    const dependencies = discard ? pass.orderingDependencies : pass.dependencies;
+                    if (!dependencies.includes(previousWriter)) {
+                        dependencies.push(previousWriter);
+                    }
+                }
+                // WAR orders live readers before the overwrite without retaining them.
                 for (const consumer of res.consumers){
-                    if (consumer !== pass && !pass.dependencies.includes(consumer)) {
-                        pass.dependencies.push(consumer);
+                    if (consumer !== pass && !pass.warDependencies.includes(consumer)) {
+                        pass.warDependencies.push(consumer);
                     }
                 }
-                if (res.producer && res.producer !== pass && !pass.dependencies.includes(res.producer)) {
-                    pass.dependencies.push(res.producer);
+                if (res.producer && res.producer !== pass) {
+                    const dependencies = discard ? pass.orderingDependencies : pass.dependencies;
+                    if (!dependencies.includes(res.producer)) {
+                        dependencies.push(res.producer);
+                    }
                 }
                 const id = graph._nextResourceId++;
                 const versionName = `${res.name}@${pass.name}`;
-                const version = new RGResource(id, versionName, res.kind, res.desc, res.physicalId);
+                const version = new RGResource(id, versionName, res.kind, res.desc, res.physicalId, res.allocationKey);
                 version.producer = pass;
+                // WAW edges make the first overwrite sufficient for stale readers.
+                if (!res.nextWriter) {
+                    res.nextWriter = pass;
+                }
                 graph._resources.set(id, version);
+                graph._lastWriterByPhysicalId.set(res.physicalId, pass);
                 if (!pass.writes.includes(version)) {
                     pass.writes.push(version);
                 }
-                return new RGHandle(id, versionName);
+                return new RGHandle(id, versionName, 'texture');
             },
             createTexture (desc) {
+                if (desc.allocationKey !== undefined && desc.allocationKey.length === 0) {
+                    throw new Error(`RenderGraph: pass "${pass.name}" specified an empty texture allocationKey.`);
+                }
                 const id = graph._nextResourceId++;
                 const name = desc.label ?? `_tex_${id}`;
-                const res = new RGResource(id, name, 'transient', desc);
+                const labelKey = desc.label ?? '<unnamed>';
+                const labelOccurrence = textureLabelOccurrences.get(labelKey) ?? 0;
+                textureLabelOccurrences.set(labelKey, labelOccurrence + 1);
+                const allocationKey = desc.allocationKey ?? `rg:${JSON.stringify([
+                    pass.name,
+                    pass.nameOccurrence,
+                    desc.label ?? null,
+                    labelOccurrence
+                ])}`;
+                const res = new RGResource(id, name, 'transient', desc, id, allocationKey);
                 res.producer = pass;
                 graph._resources.set(id, res);
+                graph._lastWriterByPhysicalId.set(res.physicalId, pass);
                 pass.writes.push(res);
-                return new RGHandle(id, name);
+                return new RGHandle(id, name, 'texture');
             },
             createToken (name) {
                 const id = graph._nextResourceId++;
@@ -208,7 +205,7 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 res.producer = pass;
                 graph._resources.set(id, res);
                 pass.writes.push(res);
-                return new RGHandle(id, tokenName);
+                return new RGHandle(id, tokenName, 'token');
             },
             createFramebuffer (desc) {
                 const id = graph._nextResourceId++;
@@ -216,9 +213,10 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 const res = new RGResource(id, name, 'framebuffer', desc);
                 res.producer = pass;
                 graph._resources.set(id, res);
+                graph._lastWriterByPhysicalId.set(res.physicalId, pass);
                 pass.writes.push(res);
                 graph._declareFramebufferAttachmentDeps(pass, desc);
-                return new RGHandle(id, name);
+                return new RGHandle(id, name, 'framebuffer');
             },
             sideEffect () {
                 pass.hasSideEffect = true;
@@ -237,8 +235,21 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             }
         };
     }
-    // ─── Private: Dead Pass Culling ─────────────────────────────────────
-    /** @internal */ _validateOutputs(outputs) {
+    _validateAllocationKeys(lifetimes) {
+        const physicalByKey = new Map();
+        for (const lifetime of lifetimes.values()){
+            const resource = lifetime.resource;
+            if (resource.kind !== 'transient' || !resource.allocationKey) {
+                continue;
+            }
+            const existingPhysicalId = physicalByKey.get(resource.allocationKey);
+            if (existingPhysicalId !== undefined && existingPhysicalId !== resource.physicalId) {
+                throw new Error(`RenderGraph: transient allocationKey "${resource.allocationKey}" is used by multiple resources. ` + 'Use a unique allocationKey for each logical texture.');
+            }
+            physicalByKey.set(resource.allocationKey, resource.physicalId);
+        }
+    }
+    _validateOutputs(outputs) {
         const latestVersions = new Map();
         for (const res of this._resources.values()){
             const current = latestVersions.get(res.physicalId);
@@ -257,12 +268,10 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             }
         }
     }
-    /** @internal */ _cullDeadPasses(outputs) {
-        // Start with all passes marked dead
+    _cullDeadPasses(outputs) {
         for (const pass of this._passes){
             pass.alive = false;
         }
-        // Seed: resources that are requested outputs
         const neededResources = new Set();
         const stack = [];
         const markResourceNeeded = (res)=>{
@@ -279,6 +288,7 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             for (const dep of pass.reads){
                 markResourceNeeded(dep);
             }
+            // WAR dependencies order passes but do not propagate liveness.
             for (const dependency of pass.dependencies){
                 markPassAlive(dependency);
             }
@@ -290,14 +300,11 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             }
             markResourceNeeded(res);
         }
-        // Seed: side-effect passes (always alive) — push their read dependencies
         for (const pass of this._passes){
             if (pass.hasSideEffect) {
                 markPassAlive(pass);
             }
         }
-        // Backward traversal: for each needed resource, mark its producer alive
-        // and recursively mark the producer's read dependencies as needed
         while(stack.length > 0){
             const res = stack.pop();
             const producer = res.producer;
@@ -305,8 +312,30 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 markPassAlive(producer);
             }
         }
+        // Warn when an ordering-only pass may have omitted sideEffect or an output.
+        for (const pass of this._passes){
+            if (!pass.alive && !pass.hasSideEffect && pass.warDependencies.length > 0 && !RenderGraph._warnedCulledPasses.has(pass.name)) {
+                RenderGraph._warnedCulledPasses.add(pass.name);
+                console.warn(`RenderGraph: pass "${pass.name}" was culled but is referenced by WAR ` + `ordering edges. If its work must run, call sideEffect() or route its ` + `output into a compile() sink.`);
+            }
+        }
     }
-    /** @internal */ _declareFramebufferAttachmentDeps(pass, desc) {
+    _declareRead(pass, res) {
+        if (res.kind === 'transient' && !res.producer) {
+            throw new Error(`RenderGraph: pass "${pass.name}" attempts to read transient resource "${res.name}" ` + `which has no producer. Ensure the resource is created before being read.`);
+        }
+        if (!pass.reads.includes(res)) {
+            pass.reads.push(res);
+        }
+        if (!res.consumers.includes(pass)) {
+            res.consumers.push(pass);
+        }
+        // A stale-version read must precede its first overwrite.
+        if (res.nextWriter && res.nextWriter !== pass && !res.nextWriter.warDependencies.includes(pass)) {
+            res.nextWriter.warDependencies.push(pass);
+        }
+    }
+    _declareFramebufferAttachmentDeps(pass, desc) {
         const declare = (attachment)=>{
             if (attachment instanceof RGHandle) {
                 const res = this._resources.get(attachment._id);
@@ -317,12 +346,7 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                     throw new Error(`RenderGraph: framebuffer attachment "${res.name}" must be a texture resource, got ${res.kind}.`);
                 }
                 if (res.producer !== pass) {
-                    if (!pass.reads.includes(res)) {
-                        pass.reads.push(res);
-                    }
-                    if (!res.consumers.includes(pass)) {
-                        res.consumers.push(pass);
-                    }
+                    this._declareRead(pass, res);
                 }
             }
         };
@@ -334,13 +358,11 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
         }
         declare(desc.depthAttachment);
     }
-    // ─── Private: Topological Sort (Kahn's Algorithm) ───────────────────
-    /** @internal */ _topologicalSort() {
+    _topologicalSort() {
         const alivePasses = this._passes.filter((p)=>p.alive);
         if (alivePasses.length === 0) {
             return [];
         }
-        // Build adjacency: producer -> consumers (only among alive passes)
         const aliveSet = new Set(alivePasses);
         const inDegree = new Map();
         const adjacency = new Map();
@@ -362,8 +384,13 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             for (const dependency of pass.dependencies){
                 addEdge(dependency, pass);
             }
+            for (const dependency of pass.orderingDependencies){
+                addEdge(dependency, pass);
+            }
+            for (const dependency of pass.warDependencies){
+                addEdge(dependency, pass);
+            }
         }
-        // For each resource, its producer has an edge to each of its consumers
         for (const res of this._resources.values()){
             if (!res.producer || !aliveSet.has(res.producer)) {
                 continue;
@@ -372,7 +399,6 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 addEdge(res.producer, consumer);
             }
         }
-        // Kahn's algorithm
         const queue = [];
         for (const pass of alivePasses){
             if (inDegree.get(pass) === 0) {
@@ -392,7 +418,6 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
             }
         }
         if (result.length !== alivePasses.length) {
-            // Find passes that are part of the cycle (those with non-zero in-degree)
             const cycleParticipants = [];
             for (const [pass, degree] of inDegree){
                 if (degree > 0) {
@@ -403,10 +428,8 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
         }
         return result;
     }
-    // ─── Private: Resource Lifetime Analysis ────────────────────────────
-    /** @internal */ _analyzeLifetimes(orderedPasses) {
+    _analyzeLifetimes(orderedPasses) {
         const lifetimes = new Map();
-        // Build pass -> order index map
         const orderMap = new Map();
         for(let i = 0; i < orderedPasses.length; i++){
             orderMap.set(orderedPasses[i], i);
@@ -414,13 +437,11 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
         for (const res of this._resources.values()){
             let first = Infinity;
             let last = -Infinity;
-            // Producer
             if (res.producer && orderMap.has(res.producer)) {
                 const idx = orderMap.get(res.producer);
                 first = Math.min(first, idx);
                 last = Math.max(last, idx);
             }
-            // Consumers
             for (const consumer of res.consumers){
                 if (orderMap.has(consumer)) {
                     const idx = orderMap.get(consumer);
@@ -436,11 +457,7 @@ import { RGHandle, RGPass, RGResource, RGSubpass } from './types.js';
                 });
             }
         }
-        // A pass that reads a framebuffer implicitly reads its attachment textures:
-        // extend each RGHandle attachment's lifetime to cover the framebuffer's
-        // lifetime so the executor never releases a backing texture while a later
-        // pass can still render through the framebuffer. Framebuffers cannot be
-        // attachments of other framebuffers, so a single propagation pass suffices.
+        // Attachment textures must outlive every framebuffer use.
         for (const lifetime of lifetimes.values()){
             const res = lifetime.resource;
             if (res.kind !== 'framebuffer' || !res.desc) {