@zephyr3d/scene 0.9.21 → 0.9.23

package/dist/render/rendergraph/executor.js

@@ -11,113 +11,74 @@ const DEFAULT_PROFILING_OPTIONS = {
     maxPendingFrames: 3,
     label: 'RenderGraph'
 };
-/**
- * Executes a compiled render graph with automatic resource lifecycle management.
- *
- * The executor allocates transient textures before their first use and releases
- * them after their last use, using the provided {@link RGTextureAllocator}.
- *
- * Usage:
- * ```ts
- * const executor = new RenderGraphExecutor(myAllocator, backbufferWidth, backbufferHeight);
- * executor.setImportedTexture(backbufferHandle, actualBackbufferTexture);
- * executor.execute(compiledGraph);
- * ```
- *
- * @typeParam TTexture - The concrete texture type (e.g. `Texture2D`).
- * @public
- */ class RenderGraphExecutor {
+/** Executes compiled graphs with automatic resource lifetimes. @public */ class RenderGraphExecutor {
     static _defaultProfilingOptions = false;
     static _latestProfileResult = null;
     static _latestPendingProfileFrame = null;
     static _latestResolvedProfileSerial = 0;
     static _nextProfileSerial = 0;
-    /** @internal */ _allocator;
-    /** @internal */ _backbufferWidth;
-    /** @internal */ _backbufferHeight;
-    /** @internal */ _importedTextures = new Map();
-    /** @internal */ _allocatedTextures = new Map();
-    /** @internal */ _allocatedFramebuffers = new Map();
-    /** @internal */ _importedTextureAliases = new Map();
-    /** @internal */ _transientTextureAliases = new Map();
-    /** @internal */ _resolvedImportedTextures = new Map();
-    /** @internal */ _cleanupCallbacks = [];
-    /** @internal */ _profilingOptions;
-    /** @internal */ _pendingProfileFrames = [];
-    /** @internal */ _latestProfileResult = null;
-    /** @internal */ _latestResolvedProfileSerial = 0;
+    _allocator;
+    _backbufferWidth;
+    _backbufferHeight;
+    _importedTextures = new Map();
+    _allocatedTextures = new Map();
+    _allocatedFramebuffers = new Map();
+    _importedTextureAliases = new Map();
+    _transientTextureAliases = new Map();
+    _resolvedImportedTextures = new Map();
+    _cleanupCallbacks = [];
+    _profilingOptions;
+    _pendingProfileFrames = [];
+    _latestProfileResult = null;
+    _latestResolvedProfileSerial = 0;
+    _textureAffinityCache;
     constructor(allocator, backbufferWidth, backbufferHeight, options){
         this._allocator = allocator;
         this._backbufferWidth = backbufferWidth;
         this._backbufferHeight = backbufferHeight;
         this._profilingOptions = this._normalizeProfilingOptions(options?.profiling ?? RenderGraphExecutor._defaultProfilingOptions, options?.device);
+        this._textureAffinityCache = options?.textureAffinityCache ?? null;
     }
-    /**
-   * Set the default profiling options used by newly constructed render graph executors.
-   */ static setDefaultProfilingOptions(options) {
+    /** Set profiling defaults for new executors. */ static setDefaultProfilingOptions(options) {
         RenderGraphExecutor._defaultProfilingOptions = options;
     }
-    /**
-   * Get the latest resolved profile result from any render graph executor.
-   */ static getLatestProfileResult() {
+    /** Return the latest resolved result from any executor. */ static getLatestProfileResult() {
         return RenderGraphExecutor._latestProfileResult;
     }
-    /**
-   * Resolve the latest pending render graph profile result from any executor.
-   */ static resolveProfileResult() {
+    /** Resolve the latest pending result from any executor. */ static resolveProfileResult() {
         return RenderGraphExecutor._latestPendingProfileFrame?.resolvePromise ?? Promise.resolve(RenderGraphExecutor._latestProfileResult);
     }
-    /**
-   * Enable, disable, or update timestamp profiling for this executor.
-   */ setProfilingOptions(options) {
+    /** Update timestamp profiling for this executor. */ setProfilingOptions(options) {
         this._profilingOptions = this._normalizeProfilingOptions(options, this._profilingOptions.device);
     }
-    /**
-   * Get the latest resolved profile result produced by this executor.
-   */ getLatestProfileResult() {
+    /** Return this executor's latest resolved profile. */ getLatestProfileResult() {
         return this._latestProfileResult;
     }
-    /**
-   * Resolve the latest pending profile result produced by this executor.
-   */ resolveProfileResult() {
+    /** Resolve this executor's latest pending profile. */ resolveProfileResult() {
         return this._pendingProfileFrames[this._pendingProfileFrames.length - 1]?.resolvePromise ?? Promise.resolve(this._latestProfileResult);
     }
-    /**
-   * Update the backbuffer dimensions used for 'backbuffer-relative' sizing.
-   */ setBackbufferSize(width, height) {
+    /** Update dimensions used for backbuffer-relative resources. */ setBackbufferSize(width, height) {
         this._backbufferWidth = width;
         this._backbufferHeight = height;
     }
-    /**
-   * Register an imported (external) texture so it can be resolved during execution.
-   *
-   * @param handle - The handle returned from {@link RenderGraph.importTexture}.
-   * @param texture - The actual GPU texture object.
-   */ setImportedTexture(handle, texture) {
+    /** Bind an imported texture for execution. */ setImportedTexture(handle, texture) {
         this._importedTextures.set(handle._id, texture);
     }
-    /**
-   * Execute the compiled graph with full resource lifecycle management.
-   *
-   * For each pass in topological order:
-   * 1. Allocate any transient resources whose lifetime begins at this pass
-   * 2. Invoke the pass's execute callback with a context that resolves handles
-   * 3. Release any transient resources whose lifetime ends at this pass
-   *
-   * @param compiled - The compiled graph from {@link RenderGraph.compile}.
-   */ execute(compiled) {
+    /** Execute a compiled graph and manage its transient resources. */ execute(compiled, bindings) {
+        if (bindings?.importedTextures) {
+            for (const [handle, texture] of bindings.importedTextures){
+                this.setImportedTexture(handle, texture);
+            }
+        }
         this._cleanupCallbacks.length = 0;
         this._resolveImportedTextureAliases(compiled);
         const profileFrame = this._beginProfileFrame();
-        // Build per-pass allocation and release schedules
-        const allocateAt = new Map(); // passIndex -> transient texture resourceIds to allocate
-        const releaseAt = new Map(); // passIndex -> transient texture resourceIds to release
-        const allocateFramebufferAt = new Map(); // passIndex -> framebuffer resourceIds to allocate
-        const releaseFramebufferAt = new Map(); // passIndex -> framebuffer resourceIds to release
-        // Transient write-versions (builder.write on a transient) alias the same
-        // physical texture as the original resource: merge their lifetimes by
-        // physicalId so one texture is allocated at the first use of any version
-        // and released after the last use of any version.
+        const affinityEntries = new Map();
+        const allocateAt = new Map();
+        const releaseAt = new Map();
+        const allocateFramebufferAt = new Map();
+        const releaseFramebufferAt = new Map();
+        // Merge lifetimes of versions sharing one physical texture.
         this._transientTextureAliases.clear();
         const transientSchedules = new Map();
         for (const [resId, lifetime] of compiled.lifetimes){
@@ -132,7 +93,8 @@ const DEFAULT_PROFILING_OPTIONS = {
                     transientSchedules.set(physicalId, {
                         firstUse: lifetime.firstUse,
                         lastUse: lifetime.lastUse,
-                        desc: lifetime.resource.desc
+                        desc: lifetime.resource.desc,
+                        allocationKey: lifetime.resource.allocationKey
                     });
                 }
             } else if (lifetime.resource.kind === 'framebuffer') {
@@ -161,17 +123,24 @@ const DEFAULT_PROFILING_OPTIONS = {
         try {
             for(let i = 0; i < compiled.orderedPasses.length; i++){
                 const pass = compiled.orderedPasses[i];
-                // Allocate resources that start at this pass
                 const toAllocate = allocateAt.get(i);
                 if (toAllocate) {
                     for (const resId of toAllocate){
                         const schedule = transientSchedules.get(resId);
                         const size = this._resolveSize(schedule.desc);
-                        const texture = this._allocator.allocate(schedule.desc, size);
+                        const descriptorSignature = this._getTextureDescriptorSignature(schedule.desc, size);
+                        const preferred = schedule.allocationKey ? this._textureAffinityCache?.getPreferredTexture(schedule.allocationKey, descriptorSignature) : undefined;
+                        const texture = this._allocator.allocate(schedule.desc, size, preferred);
                         this._allocatedTextures.set(resId, texture);
+                        if (schedule.allocationKey) {
+                            affinityEntries.set(schedule.allocationKey, {
+                                texture,
+                                descriptorSignature
+                            });
+                        }
                     }
                 }
-                // Allocate framebuffer views after their texture attachments are available.
+                // Allocate framebuffers after their attachments.
                 const framebuffersToAllocate = allocateFramebufferAt.get(i);
                 if (framebuffersToAllocate) {
                     for (const resId of framebuffersToAllocate){
@@ -181,8 +150,7 @@ const DEFAULT_PROFILING_OPTIONS = {
                         this._allocatedFramebuffers.set(resId, framebuffer);
                     }
                 }
-                // Execute the pass with exception safety for resource cleanup.
-                // Release errors must not hide the original pass execution error.
+                // Preserve pass errors ahead of release errors.
                 let passError = null;
                 const passProfile = this._beginPassProfileScope(profileFrame, pass);
                 try {
@@ -224,7 +192,6 @@ const DEFAULT_PROFILING_OPTIONS = {
                         }
                     }
                 }
-                // Release resources that end at this pass (always runs even if pass throws)
                 const toRelease = releaseAt.get(i);
                 if (toRelease) {
                     for (const resId of toRelease){
@@ -265,6 +232,9 @@ const DEFAULT_PROFILING_OPTIONS = {
                     }
                 }
             }
+            if (completed && !executionError && !cleanupError) {
+                this._textureAffinityCache?.replace(affinityEntries);
+            }
             if (executionError) {
                 throw executionError;
             }
@@ -273,12 +243,9 @@ const DEFAULT_PROFILING_OPTIONS = {
             }
         }
     }
-    /**
-   * Clear imported texture registrations and any leftover allocated textures.
-   * Call this after execution or when resetting for a new frame.
-   */ reset() {
+    /** Release remaining resources and clear imported bindings. */ reset() {
         this._runCleanupCallbacks();
-        // Release any textures that weren't released (shouldn't happen in normal flow)
+        // Handles aborted execution and allocator failures.
         for (const framebuffer of this._allocatedFramebuffers.values()){
             this._releaseFramebuffer(framebuffer);
         }
@@ -292,8 +259,7 @@ const DEFAULT_PROFILING_OPTIONS = {
         this._transientTextureAliases.clear();
         this._resolvedImportedTextures.clear();
     }
-    // ─── Private ────────────────────────────────────────────────────────
-    /** @internal */ _normalizeProfilingOptions(options, fallbackDevice) {
+    _normalizeProfilingOptions(options, fallbackDevice) {
         const source = typeof options === 'object' ? options : {};
         const enabled = typeof options === 'boolean' ? options : source.enabled ?? true;
         return {
@@ -308,7 +274,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             device: source.device ?? fallbackDevice
         };
     }
-    /** @internal */ _getProfilingDevice() {
+    _getProfilingDevice() {
         if (this._profilingOptions.device) {
             return this._profilingOptions.device;
         }
@@ -318,7 +284,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             return null;
         }
     }
-    /** @internal */ _beginProfileFrame() {
+    _beginProfileFrame() {
         if (!this._profilingOptions.enabled) {
             return null;
         }
@@ -358,20 +324,20 @@ const DEFAULT_PROFILING_OPTIONS = {
         }
         return frame;
     }
-    /** @internal */ _beginPassProfileScope(frame, pass) {
+    _beginPassProfileScope(frame, pass) {
         if (!frame || !this._profilingOptions.pass && !this._profilingOptions.subpass) {
             return null;
         }
         return this._beginProfileScope(frame, frame.root, 'pass', pass.name, this._profilingOptions.pass);
     }
-    /** @internal */ _beginSubpassProfileScope(frame, passScope, pass, subpassName) {
+    _beginSubpassProfileScope(frame, passScope, pass, subpassName) {
         if (!frame || !this._profilingOptions.subpass) {
             return null;
         }
         const parent = passScope ?? frame.root;
         return this._beginProfileScope(frame, parent, 'subpass', subpassName, true, `${pass.name}/${subpassName}`);
     }
-    /** @internal */ _beginProfileScope(frame, parent, type, name, queryEnabled, queryLabel) {
+    _beginProfileScope(frame, parent, type, name, queryEnabled, queryLabel) {
         const status = frame.supported && !queryEnabled ? 'resolved' : frame.supported ? 'pending' : 'unsupported';
         const result = {
             name,
@@ -393,7 +359,7 @@ const DEFAULT_PROFILING_OPTIONS = {
         }
         return scope;
     }
-    /** @internal */ _beginTimestampScope(frame, scope, label) {
+    _beginTimestampScope(frame, scope, label) {
         if (!frame.supported || !frame.device) {
             scope.result.status = 'unsupported';
             scope.result.message = 'GPU timestamp queries are not supported';
@@ -413,7 +379,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             scope.result.message = 'GPU timestamp query was not started';
         }
     }
-    /** @internal */ _endProfileScope(frame, scope) {
+    _endProfileScope(frame, scope) {
         if (!frame || !frame.device || !scope || scope.ended) {
             return;
         }
@@ -422,7 +388,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             frame.device.endTimestampQuery(scope.queryId);
         }
     }
-    /** @internal */ _finishProfileFrame(frame) {
+    _finishProfileFrame(frame) {
         if (!frame) {
             return;
         }
@@ -451,14 +417,14 @@ const DEFAULT_PROFILING_OPTIONS = {
         });
         this._trackPendingProfileFrame(frame);
     }
-    /** @internal */ _trackPendingProfileFrame(frame) {
+    _trackPendingProfileFrame(frame) {
         this._pendingProfileFrames.push(frame);
         while(this._pendingProfileFrames.length > this._profilingOptions.maxPendingFrames){
             this._pendingProfileFrames.shift();
         }
         RenderGraphExecutor._latestPendingProfileFrame = frame;
     }
-    /** @internal */ _publishProfileResult(frame) {
+    _publishProfileResult(frame) {
         this._pendingProfileFrames = this._pendingProfileFrames.filter((pending)=>pending !== frame);
         if (frame.serial >= this._latestResolvedProfileSerial) {
             this._latestResolvedProfileSerial = frame.serial;
@@ -472,13 +438,13 @@ const DEFAULT_PROFILING_OPTIONS = {
             RenderGraphExecutor._latestPendingProfileFrame = null;
         }
     }
-    /** @internal */ _applyTimestampResult(scope, result) {
+    _applyTimestampResult(scope, result) {
         scope.result.queryId = result.id;
         scope.result.durationMs = result.durationMs;
         scope.result.status = result.status;
         scope.result.message = result.message;
     }
-    /** @internal */ _aggregateProfileStatus(scope) {
+    _aggregateProfileStatus(scope) {
         const statuses = [];
         const collect = (node)=>{
             statuses.push(node.status);
@@ -503,7 +469,7 @@ const DEFAULT_PROFILING_OPTIONS = {
         }
         return 'resolved';
     }
-    /** @internal */ _resolveSize(desc) {
+    _resolveSize(desc) {
         const mode = desc.sizeMode ?? 'backbuffer-relative';
         if (mode === 'absolute') {
             return {
@@ -511,7 +477,6 @@ const DEFAULT_PROFILING_OPTIONS = {
                 height: desc.height ?? 1
             };
         }
-        // backbuffer-relative: width/height are scale factors (default 1.0)
         const scaleX = desc.width ?? 1.0;
         const scaleY = desc.height ?? 1.0;
         return {
@@ -519,7 +484,16 @@ const DEFAULT_PROFILING_OPTIONS = {
             height: Math.max(1, Math.floor(this._backbufferHeight * scaleY))
         };
     }
-    /** @internal */ _resolveImportedTextureAliases(compiled) {
+    _getTextureDescriptorSignature(desc, size) {
+        return JSON.stringify([
+            desc.format,
+            size.width,
+            size.height,
+            desc.mipLevels ?? 1,
+            desc.arrayLayers ?? null
+        ]);
+    }
+    _resolveImportedTextureAliases(compiled) {
         this._importedTextureAliases.clear();
         this._resolvedImportedTextures.clear();
         const physicalToTexture = new Map();
@@ -546,7 +520,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             }
         }
     }
-    /** @internal */ _runCleanupCallbacks() {
+    _runCleanupCallbacks() {
         let error = null;
         while(this._cleanupCallbacks.length > 0){
             const callback = this._cleanupCallbacks.pop();
@@ -560,7 +534,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             throw error;
         }
     }
-    /** @internal */ _createFramebuffer(desc, autoCleanup = true) {
+    _createFramebuffer(desc, autoCleanup = true) {
         if (!this._allocator.allocateFramebuffer || !this._allocator.releaseFramebuffer) {
             throw new Error('RenderGraphExecutor: framebuffer allocation is not supported by this allocator.');
         }
@@ -572,13 +546,13 @@ const DEFAULT_PROFILING_OPTIONS = {
         }
         return framebuffer;
     }
-    /** @internal */ _releaseFramebuffer(framebuffer) {
+    _releaseFramebuffer(framebuffer) {
         if (!this._allocator.releaseFramebuffer) {
             throw new Error('RenderGraphExecutor: framebuffer release is not supported by this allocator.');
         }
         this._allocator.releaseFramebuffer(framebuffer);
     }
-    /** @internal */ _resolveFramebufferDesc(desc, accessScope) {
+    _resolveFramebufferDesc(desc, accessScope) {
         const resolveAttachment = (attachment)=>{
             if (attachment instanceof RGHandle) {
                 if (accessScope) {
@@ -595,7 +569,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             depthAttachment: resolveAttachment(desc.depthAttachment)
         };
     }
-    /** @internal */ _resolveResource(handle) {
+    _resolveResource(handle) {
         const imported = this._importedTextures.get(handle._id);
         if (imported !== undefined) {
             return imported;
@@ -615,7 +589,7 @@ const DEFAULT_PROFILING_OPTIONS = {
         if (allocated !== undefined) {
             return allocated;
         }
-        // Transient write-versions resolve to the physical texture of the original.
+        // Written versions alias the original physical texture.
         const transientAlias = this._transientTextureAliases.get(handle._id);
         if (transientAlias !== undefined) {
             const aliased = this._allocatedTextures.get(transientAlias);
@@ -625,7 +599,7 @@ const DEFAULT_PROFILING_OPTIONS = {
         }
         throw new Error(`RenderGraphExecutor: cannot resolve resource "${handle.name}" (id=${handle._id}). ` + `It may not have been allocated yet or was already released.`);
     }
-    /** @internal */ _createAccessScope(pass) {
+    _createAccessScope(pass) {
         const accessibleIds = new Set();
         const textureIds = new Set();
         const framebufferIds = new Set();
@@ -652,7 +626,7 @@ const DEFAULT_PROFILING_OPTIONS = {
             framebufferIds
         };
     }
-    /** @internal */ _assertDeclaredAccess(accessScope, handle, access) {
+    _assertDeclaredAccess(accessScope, handle, access) {
         if (!accessScope.accessibleIds.has(handle._id)) {
             throw new Error(`RenderGraphExecutor: pass "${accessScope.passName}" tried to access ${access} "${handle.name}" ` + `without declaring a read/write dependency.`);
         }
@@ -663,13 +637,13 @@ const DEFAULT_PROFILING_OPTIONS = {
             throw new Error(`RenderGraphExecutor: pass "${accessScope.passName}" tried to access "${handle.name}" as a framebuffer, ` + `but it is not a framebuffer resource.`);
         }
     }
-    /** @internal */ _wrapSubpassError(passName, subpassName, error) {
+    _wrapSubpassError(passName, subpassName, error) {
         const message = error instanceof Error ? error.message : String(error);
         const wrapped = new Error(`RenderGraphExecutor: pass "${passName}" subpass "${subpassName}" failed: ${message}`);
         wrapped.cause = error;
         return wrapped;
     }
-    /** @internal */ _createContext(accessScope) {
+    _createContext(accessScope) {
         const self = this;
         return {
             getTexture (handle) {