@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/render/frame-graph.js

@@ -0,0 +1,594 @@
+// ============================================================================
+// FrameGraph — RDG-style render pass orchestration
+// Topologically-sorted passes, transient resource allocation, lifetime-based
+// aliasing, single command encoder per frame.
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+import { TrackedRenderPass } from "./tracked-render-pass.js";
+const log = createLogger();
+// ─── Handles & Descriptors ─────────────────────────────────────────────────
+export class TextureHandle {
+    id;
+    name;
+    constructor(id, name) {
+        this.id = id;
+        this.name = name;
+    }
+}
+// ─── Pass Type ─────────────────────────────────────────────────────────────
+export var PassType;
+(function (PassType) {
+    /** Graph begins/ends the render pass with declared attachments; ctx.pass is a TrackedRenderPass. */
+    PassType["Render"] = "render";
+    /** Pass manages its own encoders; ctx.pass is null. */
+    PassType["Custom"] = "custom";
+})(PassType || (PassType = {}));
+// ─── Builder (used during setup phase) ─────────────────────────────────────
+export class FrameGraphBuilder {
+    colorAttachments = [];
+    depthAttachmentDesc = null;
+    _reads = new Set();
+    _writes = new Set();
+    colorAttachment(desc) {
+        this.colorAttachments.push(desc);
+        this._writes.add(desc.handle.id);
+    }
+    depthAttachment(desc) {
+        this.depthAttachmentDesc = desc;
+        if (desc.depthReadOnly) {
+            this._reads.add(desc.handle.id);
+        }
+        else {
+            this._writes.add(desc.handle.id);
+        }
+    }
+    read(handle) {
+        this._reads.add(handle.id);
+    }
+    write(handle) {
+        this._writes.add(handle.id);
+    }
+    get reads() { return this._reads; }
+    get writes() { return this._writes; }
+}
+export class SlotRegistry {
+    slotOrder = [];
+    slotIndex = {};
+    entries = [];
+    setSlotOrder(slots) {
+        this.slotOrder = [...slots];
+        this.slotIndex = {};
+        this.slotOrder.forEach((s, i) => { this.slotIndex[s] = i; });
+    }
+    registerPass(slot, pass) {
+        this.entries.push({ slot, pass, order: this.slotIndex[slot] ?? this.slotOrder.length });
+    }
+    unregisterPass(name) {
+        this.entries = this.entries.filter(e => e.pass.name !== name);
+    }
+    clear() {
+        this.entries = [];
+    }
+    getEntries() {
+        return this.entries
+            .filter(e => this.slotOrder.includes(e.slot))
+            .sort((a, b) => {
+            const oa = a.order;
+            const ob = b.order;
+            if (oa !== ob)
+                return oa - ob;
+            return 0;
+        });
+    }
+    isEmpty() {
+        return this.getEntries().length === 0;
+    }
+}
+// ─── Frame Graph ───────────────────────────────────────────────────────────
+export class FrameGraph {
+    passes = [];
+    resources = new Map();
+    nextHandleId = 0;
+    compiled = false;
+    executionOrder = [];
+    dirty = true;
+    surfaceWidth = 0;
+    surfaceHeight = 0;
+    physicalTextures = [];
+    aliasing = new Map(); // resource name -> physical texture name
+    slotRegistry = new SlotRegistry();
+    /** Imported (external) resources dedupe by name so "color"/"depth" are
+     *  well-known handles shared between the renderer and game passes. */
+    importedByName = new Map();
+    importTexture(name, texture) {
+        const existing = this.importedByName.get(name);
+        if (existing) {
+            if (texture)
+                this.setImportedTexture(existing, texture);
+            return existing;
+        }
+        const handle = new TextureHandle(this.nextHandleId++, name);
+        this.resources.set(handle.id, {
+            name,
+            texture: texture ?? null,
+            external: true,
+        });
+        this.importedByName.set(name, handle);
+        return handle;
+    }
+    /** Update the GPUTexture backing an imported handle (e.g. swapchain color). */
+    setImportedTexture(handle, texture) {
+        const resource = this.resources.get(handle.id);
+        if (!resource || !resource.external) {
+            throw new Error(`FrameGraph: "${handle.name}" is not an imported texture`);
+        }
+        resource.texture = texture;
+        resource.externalView = undefined;
+        resource.cachedView = undefined;
+    }
+    /** Import an externally-created view directly (e.g. XR offscreen color view). */
+    importTextureView(name, view) {
+        const existing = this.importedByName.get(name);
+        if (existing) {
+            if (view)
+                this.setImportedTextureView(existing, view);
+            return existing;
+        }
+        const handle = new TextureHandle(this.nextHandleId++, name);
+        this.resources.set(handle.id, {
+            name,
+            texture: null,
+            externalView: view,
+            external: true,
+        });
+        this.importedByName.set(name, handle);
+        return handle;
+    }
+    /** Update the GPUTextureView backing an imported view handle. */
+    setImportedTextureView(handle, view) {
+        const resource = this.resources.get(handle.id);
+        if (!resource || !resource.external) {
+            throw new Error(`FrameGraph: "${handle.name}" is not an imported view`);
+        }
+        resource.externalView = view;
+        resource.cachedView = undefined;
+    }
+    createTransient(name, desc) {
+        const handle = new TextureHandle(this.nextHandleId++, name);
+        this.resources.set(handle.id, {
+            name,
+            texture: null,
+            external: false,
+            desc,
+            width: desc.width,
+            height: desc.height,
+        });
+        return handle;
+    }
+    /** Direct graph registration. Use SlotRegistry for slot-based ordering. */
+    addPass(pass) {
+        const builder = new FrameGraphBuilder();
+        pass.setup(builder);
+        this.passes.push({ pass, builder });
+        this.dirty = true;
+    }
+    getSlotRegistry() {
+        return this.slotRegistry;
+    }
+    /** Re-register all passes from the slot registry. Call after slot/pass changes. */
+    refreshFromSlots() {
+        this.passes = [];
+        for (const { slot, pass } of this.slotRegistry.getEntries()) {
+            const builder = new FrameGraphBuilder();
+            pass.setup(builder);
+            this.passes.push({ pass, builder, slot });
+        }
+        this.dirty = true;
+    }
+    markDirty() {
+        this.dirty = true;
+    }
+    /**
+     * Remove all registered passes. Imported/transient resources are preserved.
+     * Used by renderers that rebuild the pass list each frame (e.g. when the
+     * pass set is dynamic per-viewport).
+     */
+    clearPasses() {
+        this.passes.length = 0;
+        this.dirty = true;
+    }
+    isDirty() {
+        return this.dirty;
+    }
+    compile(device, surfaceWidth, surfaceHeight) {
+        if (this.passes.length === 0) {
+            this.compiled = true;
+            this.dirty = false;
+            return;
+        }
+        this.surfaceWidth = surfaceWidth;
+        this.surfaceHeight = surfaceHeight;
+        // Pool the previous compile's physical textures — resources whose specs
+        // are unchanged get the same GPUTexture back instead of a destroy+alloc
+        // cycle (pass-list churn would otherwise thrash VRAM on every recompile).
+        const pool = this.physicalTextures;
+        this.physicalTextures = [];
+        this.aliasing.clear();
+        // Resolve sizes for all transient resources.
+        for (const resource of this.resources.values()) {
+            if (!resource.external && resource.desc) {
+                resource.width = resource.width || surfaceWidth;
+                resource.height = resource.height || surfaceHeight;
+            }
+        }
+        // Topological sort (this also sets execution order).
+        this.executionOrder = this.topologicalSort();
+        // Compute resource lifetimes over the sorted execution order.
+        this.computeLifetimes();
+        // Allocate transient textures with lifetime-based aliasing, reusing
+        // pooled textures from the previous compile where specs match.
+        this.allocatePhysicalTextures(device, pool);
+        // Pooled textures that no resource claimed are now garbage.
+        pool.forEach((pt) => { pt.texture.destroy(); ; });
+        // Validate
+        this.validate();
+        this.compiled = true;
+        this.dirty = false;
+    }
+    execute(ctx) {
+        if (!this.compiled)
+            return undefined;
+        // Run passes sequentially on the shared encoder.
+        for (let i = 0; i < this.executionOrder.length; i++) {
+            const entry = this.executionOrder[i];
+            if (entry.pass.passType === PassType.Render) {
+                this.executeRenderPass(ctx, entry, i);
+            }
+            else {
+                this.executeCustomPass(ctx, entry);
+            }
+        }
+        return undefined; // caller submits the shared encoder
+    }
+    /** Reusable TrackedRenderPass wrappers — one per execution slot, avoiding
+     *  an allocation per pass per frame. */
+    trackedPassPool = [];
+    executeRenderPass(ctx, entry, slot) {
+        const { pass, builder } = entry;
+        const colorAttachments = builder.colorAttachments.map(a => ({
+            view: this.getTextureView(a.handle),
+            loadOp: a.loadOp,
+            storeOp: a.storeOp,
+            clearValue: a.clearValue ?? { r: 0, g: 0, b: 0, a: 1 },
+        }));
+        let depthAttachment;
+        if (builder.depthAttachmentDesc) {
+            const da = builder.depthAttachmentDesc;
+            depthAttachment = {
+                view: this.getTextureView(da.handle),
+                depthLoadOp: da.depthLoadOp,
+                depthStoreOp: da.depthStoreOp,
+                depthClearValue: da.depthClearValue ?? 1.0,
+                depthReadOnly: da.depthReadOnly ?? false,
+            };
+        }
+        const renderPass = ctx.encoder.beginRenderPass({
+            colorAttachments,
+            depthStencilAttachment: depthAttachment,
+        });
+        let tracked = this.trackedPassPool[slot];
+        if (!tracked) {
+            tracked = this.trackedPassPool[slot] = new TrackedRenderPass(renderPass);
+        }
+        else {
+            tracked.resetForReuse(renderPass);
+        }
+        // Mutate the shared ctx rather than `{...ctx}` per pass — a fresh spread
+        // per pass per frame was measurable GC churn (~N objects/frame).
+        ctx.pass = tracked;
+        pass.execute(ctx);
+        tracked.end();
+        ctx.pass = null;
+        // Caller (GameRenderer) aggregates draw call stats from the tracked pass.
+        ctx.lastPassStats = {
+            name: pass.name,
+            drawCalls: tracked.drawCalls,
+            triangles: tracked.triangles,
+            pipelineSwitches: tracked.pipelineSwitches,
+            bindGroupChanges: tracked.bindGroupChanges,
+            bufferRebinds: tracked.bufferRebinds,
+        };
+    }
+    executeCustomPass(ctx, entry) {
+        const { pass } = entry;
+        ctx.pass = null;
+        pass.execute(ctx);
+    }
+    getTextureView(handle) {
+        const resource = this.resources.get(handle.id);
+        if (!resource) {
+            throw new Error(`FrameGraph: unresolved texture "${handle.name}"`);
+        }
+        if (resource.externalView) {
+            return resource.externalView;
+        }
+        if (!resource.texture) {
+            throw new Error(`FrameGraph: unresolved texture "${handle.name}"`);
+        }
+        if (!resource.cachedView) {
+            resource.cachedView = resource.texture.createView();
+        }
+        return resource.cachedView;
+    }
+    getTexture(handle) {
+        const resource = this.resources.get(handle.id);
+        if (!resource || !resource.texture) {
+            throw new Error(`FrameGraph: unresolved texture "${handle.name}"`);
+        }
+        return resource.texture;
+    }
+    getPassOrder() {
+        return this.executionOrder.map(e => e.pass.name);
+    }
+    /** All registered passes (registration order). Used by device-loss recovery to re-prepare pipelines on a new device. */
+    getPasses() {
+        return this.passes.map(e => e.pass);
+    }
+    getAliasing() {
+        return new Map(this.aliasing);
+    }
+    /**
+     * Drop all GPU objects bound to a (lost) device: physical texture pool and
+     * every cached/transient view. Call before the next compile() on a new
+     * device so transient resources get fresh allocations instead of reusing
+     * dead-device textures from the pool.
+     */
+    invalidatePhysicalResources() {
+        this.physicalTextures = [];
+        for (const resource of this.resources.values()) {
+            resource.cachedView = undefined;
+            if (!resource.external)
+                resource.texture = null;
+        }
+        this.compiled = false;
+        this.dirty = true;
+    }
+    computeLifetimes() {
+        // Initialize lifetimes with invalid indices.
+        for (const resource of this.resources.values()) {
+            if (resource.external || !resource.desc)
+                continue;
+            resource.lifetime = { first: Infinity, last: -1 };
+        }
+        for (let i = 0; i < this.executionOrder.length; i++) {
+            const { builder } = this.executionOrder[i];
+            const all = new Set([...builder.reads, ...builder.writes]);
+            for (const id of all.values()) {
+                const resource = this.resources.get(id);
+                if (!resource || resource.external || !resource.lifetime)
+                    continue;
+                resource.lifetime.first = Math.min(resource.lifetime.first, i);
+                resource.lifetime.last = Math.max(resource.lifetime.last, i);
+            }
+        }
+        // Unused transients have no lifetime.
+        for (const resource of this.resources.values()) {
+            if (resource.lifetime && resource.lifetime.last === -1) {
+                resource.lifetime = undefined;
+            }
+        }
+    }
+    allocatePhysicalTextures(device, pool) {
+        this.physicalTextures = [];
+        const transients = [];
+        for (const resource of this.resources.values()) {
+            if (!resource.external && resource.lifetime) {
+                transients.push(resource);
+            }
+        }
+        // Sort by first-use to allocate alias-compatible resources into physical textures.
+        transients.sort((a, b) => (a.lifetime.first - b.lifetime.first));
+        const specMatches = (pt, w, h, desc, sampleCount) => pt.width === w &&
+            pt.height === h &&
+            pt.format === desc.format &&
+            (pt.usage & desc.usage) === desc.usage &&
+            pt.sampleCount === sampleCount;
+        transients.forEach((resource) => {
+            const w = resource.width || this.surfaceWidth;
+            const h = resource.height || this.surfaceHeight;
+            const desc = resource.desc;
+            const sampleCount = desc.sampleCount ?? 1;
+            // Find a compatible physical texture whose lifetime has ended before this resource starts.
+            // Usage compatibility: the physical texture's usage must be a superset of the
+            // resource's required usage (i.e. it must support all flags the resource needs).
+            let reused = null;
+            for (let _i = 0, _it = this.physicalTextures, _n = _it.length; _i < _n; _i++) {
+                const pt = _it[_i];
+                if (specMatches(pt, w, h, desc, sampleCount) && pt.lastUsed < resource.lifetime.first) {
+                    reused = pt;
+                    break;
+                }
+            }
+            // No intra-frame alias — try a pooled texture from the previous compile.
+            if (!reused) {
+                const pi = pool.findIndex((pt) => specMatches(pt, w, h, desc, sampleCount));
+                if (pi >= 0) {
+                    reused = pool.splice(pi, 1)[0];
+                    this.physicalTextures.push(reused);
+                }
+            }
+            if (reused) {
+                resource.physicalTexture = reused.texture;
+                resource.texture = reused.texture;
+                // The texture may differ from the previous compile's — drop the stale view.
+                resource.cachedView = undefined;
+                this.aliasing.set(resource.name, reused.name);
+                reused.lastUsed = resource.lifetime.last;
+            }
+            else {
+                const name = `${resource.name}_phys`;
+                const texture = device.createTexture({
+                    size: [w, h],
+                    format: desc.format,
+                    usage: desc.usage,
+                    sampleCount,
+                });
+                this.physicalTextures.push({
+                    texture,
+                    name,
+                    width: w,
+                    height: h,
+                    format: desc.format,
+                    usage: desc.usage,
+                    sampleCount,
+                    lastUsed: resource.lifetime.last,
+                });
+                resource.physicalTexture = texture;
+                resource.texture = texture;
+                resource.cachedView = undefined;
+                this.aliasing.set(resource.name, name);
+            }
+        });
+    }
+    destroyPhysicalTextures() {
+        this.physicalTextures.forEach((pt) => {
+            pt.texture.destroy();
+        });
+        this.physicalTextures = [];
+    }
+    topologicalSort() {
+        // Build dependency edges per resource, tracking ALL accesses — not just
+        // "last writer wins". For each read at registration index i of resource R:
+        //   - RAW: depends on the last writer ≤ i (its data source); if no writer
+        //     precedes i, it binds to the first writer > i — the pass that will
+        //     produce the data it reads.
+        //   - WAR: the reader must run before the next writer after its bound
+        //     producer, so that writer doesn't clobber the data first.
+        //   - WAW: consecutive writers keep registration order.
+        // Collapsing writers to the last one (the old approach) could order a
+        // sandwiched reader after the later writer (wrong data) or synthesize a
+        // false dependency cycle that silently fell back to registration order.
+        const n = this.passes.length;
+        const adj = Array.from({ length: n }, () => new Set());
+        const addEdge = (from, to) => {
+            if (from !== to)
+                adj[from].add(to);
+        };
+        const writers = new Map(); // resourceId -> writer indices (ascending)
+        const readsOf = new Map(); // resourceId -> reader indices (ascending)
+        for (let i = 0; i < n; i++) {
+            const { reads, writes } = this.passes[i].builder;
+            for (const readId of reads.values()) {
+                let list = readsOf.get(readId);
+                if (!list)
+                    readsOf.set(readId, (list = []));
+                list.push(i);
+            }
+            for (const writeId of writes.values()) {
+                let list = writers.get(writeId);
+                if (!list)
+                    writers.set(writeId, (list = []));
+                list.push(i);
+            }
+        }
+        // WAW edges between consecutive writers.
+        for (const ws of writers.values()) {
+            for (let k = 1; k < ws.length; k++)
+                addEdge(ws[k - 1], ws[k]);
+        }
+        for (const [resId, readers] of readsOf.entries()) {
+            const ws = writers.get(resId);
+            if (!ws || ws.length === 0)
+                continue; // no producer — validate() reports it
+            readers.forEach((i) => {
+                // Bound producer: last writer at-or-before i, else first writer after i.
+                let bound = -1;
+                for (let _i = 0, _it = ws, _n = _it.length; _i < _n; _i++) {
+                    const wIdx = _it[_i];
+                    if (wIdx <= i)
+                        bound = wIdx;
+                    else
+                        break;
+                }
+                const boundPos = bound === -1 ? 0 : ws.indexOf(bound);
+                const producer = bound === -1 ? ws[0] : bound;
+                addEdge(producer, i); // RAW
+                // WAR: next writer after the bound producer must wait for this reader.
+                const next = ws[boundPos + 1];
+                if (next !== undefined)
+                    addEdge(i, next);
+            });
+        }
+        const inDegree = new Array(n).fill(0);
+        for (let i = 0; i < n; i++) {
+            for (const to of adj[i].values())
+                inDegree[to]++;
+        }
+        // Kahn's algorithm, preserving registration order for ties. The queue is
+        // kept sorted by binary insertion instead of re-sorting every iteration
+        // (the old sort+shift loop was O(n²·log n) per compile).
+        const queue = [];
+        const pushSorted = (v) => {
+            let lo = 0, hi = queue.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                if (queue[mid] < v)
+                    lo = mid + 1;
+                else
+                    hi = mid;
+            }
+            queue.splice(lo, 0, v);
+        };
+        for (let i = 0; i < n; i++) {
+            if (inDegree[i] === 0)
+                pushSorted(i);
+        }
+        const result = [];
+        while (queue.length > 0) {
+            const idx = queue.shift();
+            result.push(idx);
+            for (const neighbor of adj[idx].values()) {
+                if (--inDegree[neighbor] === 0)
+                    pushSorted(neighbor);
+            }
+        }
+        if (result.length !== n) {
+            log.error("frame-graph", "Cycle detected in render graph, falling back to registration order");
+            return this.passes;
+        }
+        return result.map(i => this.passes[i]);
+    }
+    validate() {
+        const produced = new Set();
+        const errors = [];
+        this.executionOrder.forEach((entry) => {
+            for (const readId of entry.builder.reads.values()) {
+                if (!produced.has(readId) && !this.resources.get(readId)?.external) {
+                    errors.push(`Pass "${entry.pass.name}" reads "${this.resources.get(readId)?.name ?? readId}" before it is produced`);
+                }
+            }
+            for (const writeId of entry.builder.writes.values()) {
+                produced.add(writeId);
+            }
+        });
+        if (errors.length > 0) {
+            log.warn("frame-graph", `Validation errors:\n${errors.join("\n")}`);
+        }
+    }
+    destroy() {
+        this.destroyPhysicalTextures();
+        for (const resource of this.resources.values()) {
+            if (resource.external && resource.texture) {
+                // External textures are owned by the caller; just drop references.
+                resource.texture = null;
+            }
+            resource.cachedView = undefined;
+        }
+        this.resources.clear();
+        this.passes = [];
+        this.executionOrder = [];
+        this.compiled = false;
+        this.dirty = true;
+        this.aliasing.clear();
+    }
+}