pelican-engine 0.0.0-stage → 0.3.1

package/lib/renderer/postprocess.js

@@ -0,0 +1,494 @@
+import * as THREE from "three/webgpu";
+import * as TSL from "three/tsl";
+import { typedGraphToTSL } from "./graph-tsl.js";
+const fail = (code, message) => {
+    throw Error("TC_POSTPROCESS_" + code + ": " + message);
+};
+// Three's public getter copies a Vector4 with additional depth-range properties.
+class ViewportSnapshot extends THREE.Vector4 {
+    minDepth = 0;
+    maxDepth = 1;
+    copy(v) {
+        super.copy(v);
+        const range = v;
+        this.minDepth = range.minDepth ?? 0;
+        this.maxDepth = range.maxDepth ?? 1;
+        return this;
+    }
+}
+/** Private presentation owner. Call only after renderer.init(); never expose to games. */
+export function createPostProcessComposer(renderer, width, height, definitions, textures, buffers, managedTextures) {
+    const backend = renderer.backend;
+    const device = backend.device;
+    // currentSamples is zero at the final output-conversion stage, not the scene's MSAA count.
+    const samples = renderer.samples;
+    if (![width, height].every((n) => Number.isSafeInteger(n) && n > 0))
+        fail("CAPABILITY", "Positive integer target dimensions are required.");
+    if (!Number.isSafeInteger(samples) || samples < 0)
+        fail("CAPABILITY", "Cannot determine the renderer's actual MSAA samples.");
+    if (backend.isWebGPUBackend) {
+        const limits = device?.limits;
+        if (!limits ||
+            limits.maxColorAttachments < 3 ||
+            limits.maxColorAttachmentBytesPerSample < 24 ||
+            Math.max(width, height) > limits.maxTextureDimension2D ||
+            ![0, 1, 4].includes(samples))
+            fail("CAPABILITY", "Device cannot render three full-size rgba16float attachments at the current MSAA count.");
+    }
+    else if (backend.isWebGLBackend) {
+        const gl = backend.gl ?? fail("CAPABILITY", "WebGL2 backend is not initialized.");
+        if (!gl.getExtension("EXT_color_buffer_float") ||
+            gl.getParameter(gl.MAX_COLOR_ATTACHMENTS) < 3 ||
+            gl.getParameter(gl.MAX_DRAW_BUFFERS) < 3 ||
+            Math.max(width, height) > gl.getParameter(gl.MAX_TEXTURE_SIZE) ||
+            Math.max(width, height) > gl.getParameter(gl.MAX_RENDERBUFFER_SIZE))
+            fail("CAPABILITY", "WebGL2 requires EXT_color_buffer_float and three full-size rgba16float attachments.");
+        if (samples > 1 &&
+            !gl.getInternalformatParameter(gl.RENDERBUFFER, gl.RGBA16F, gl.SAMPLES).includes(samples))
+            fail("CAPABILITY", "WebGL2 cannot preserve the current MSAA count for rgba16float.");
+    }
+    else
+        fail("CAPABILITY", "An initialized Three WebGPU or WebGL2 backend is required.");
+    const ids = new Set();
+    const allowed = new Set(["uv", "screenSize", "texelSize"]);
+    for (const d of definitions) {
+        if (!d.id || d.id.startsWith("scene.") || ids.has(d.id))
+            fail("GRAPH", "Duplicate or reserved pass ID: " + d.id);
+        ids.add(d.id);
+    }
+    const earlier = new Set(["scene.color", "scene.normal", "scene.depth"]);
+    for (const d of definitions) {
+        if (d.graph.outputType !== "vec4")
+            fail("GRAPH", d.id + " must output vec4.");
+        for (const name of d.graph.requiredInputs ?? [])
+            if (!allowed.has(name))
+                fail("GRAPH", "Unsupported input: " + name);
+        // Check nodes as well as metadata so material inputs cannot leak in.
+        for (const n of d.graph.nodes) {
+            if (n.op === "input" && !allowed.has(n.name))
+                fail("GRAPH", "Unsupported input: " + n.name);
+            if (n.op === "readBuffer" && !Object.hasOwn(d.graph.bufferTypes ?? {}, n.buffer))
+                fail("GRAPH", "Buffer reads require a declared postprocess slot.");
+            if (n.op === "sampleFrame" && !earlier.has(n.channel))
+                fail("GRAPH", "Forward or unknown frame channel: " + n.channel);
+            if (n.op === "sampleHistory" && !ids.has(n.channel))
+                fail("GRAPH", "Unknown history pass: " + n.channel);
+        }
+        earlier.add(d.id);
+    }
+    let disposed = false, allocated = 0, released = 0, frames = 0, failures = 0;
+    let resets = 0, resetReason = "initial", lastMode;
+    const resources = [];
+    const own = (value) => {
+        resources.push(value);
+        allocated++;
+        return value;
+    };
+    const release = () => {
+        for (const resource of resources.splice(0).reverse()) {
+            resource.dispose();
+            released++;
+        }
+    };
+    const active = () => {
+        if (disposed)
+            fail("DISPOSED", "Composer is disposed.");
+        if (renderer.backend !== backend ||
+            (backend.isWebGPUBackend && backend.device !== device))
+            fail("CAPABILITY", "Renderer device changed; dispose and recreate the composer.");
+    };
+    const target = (name, count = 1, scene = false) => {
+        const t = own(new THREE.RenderTarget(width, height, {
+            count,
+            type: THREE.HalfFloatType,
+            format: THREE.RGBAFormat,
+            colorSpace: THREE.LinearSRGBColorSpace,
+            depthBuffer: scene,
+            stencilBuffer: false,
+            samples: scene ? samples : 0,
+            minFilter: THREE.NearestFilter,
+            magFilter: THREE.NearestFilter,
+            generateMipmaps: false,
+        }));
+        t.texture.name = name;
+        return t;
+    };
+    const material = (name) => {
+        const m = own(new THREE.NodeMaterial());
+        m.name = name;
+        m.toneMapped = false;
+        m.depthTest = m.depthWrite = false;
+        m.blending = THREE.NoBlending;
+        return m;
+    };
+    const passes = [];
+    try {
+        const source = target("output", 3, true);
+        source.textures[1].name = "normal";
+        source.textures[2].name = "linearDepth";
+        // Three's generated sky mesh is a real mesh, but not a surface hit.
+        const isBackground = (builder) => builder.object.name === "Background.mesh" &&
+            builder.material.name === "Background.material";
+        const rasterMRT = TSL.mrt({
+            output: TSL.output,
+            normal: TSL.Fn((builder) => isBackground(builder) ? TSL.vec4(0) : TSL.vec4(TSL.normalWorld, 1))(),
+            // "depth" is reserved by NodeMaterial.setupDepth for hardware depth writes.
+            linearDepth: TSL.Fn((builder) => isBackground(builder)
+                ? TSL.vec4(0)
+                : TSL.vec4(TSL.max(TSL.positionWorld.sub(TSL.cameraPosition).length(), 1e-7), 0, 0, 1))(),
+        });
+        rasterMRT.setClearColor("normal", 0, 0);
+        rasterMRT.setClearColor("linearDepth", 0, 0);
+        const zero = own(new THREE.DataTexture(new Uint16Array(4), 1, 1, THREE.RGBAFormat, THREE.HalfFloatType));
+        zero.colorSpace = THREE.LinearSRGBColorSpace;
+        zero.generateMipmaps = false;
+        zero.needsUpdate = true;
+        zero.name = "$postprocess.zero";
+        const timeUniform = TSL.uniform(0);
+        const makeUniform = (value, type) => {
+            const v = Array.isArray(value)
+                ? type === "vec2"
+                    ? new THREE.Vector2().fromArray(value)
+                    : type === "vec3"
+                        ? new THREE.Vector3().fromArray(value)
+                        : new THREE.Vector4().fromArray(value)
+                : value;
+            return TSL.uniform(v, type);
+        };
+        for (const d of definitions) {
+            const p = {
+                definition: d,
+                targets: [target(d.id + ":0"), target(d.id + ":1")],
+                material: material("PostProcess:" + d.id),
+                parameters: new Map((d.graph.parameters ?? []).map((v) => [
+                    v.name,
+                    makeUniform(v.default, v.type),
+                ])),
+                frame: [],
+                history: [],
+                read: 0,
+                valid: false,
+                enabled: d.enabled,
+                revision: undefined,
+            };
+            passes.push(p);
+            p.material.name = "$post." + d.id;
+            if (Object.keys(d.graph.bufferTypes ?? {}).length) {
+                if (!buffers)
+                    throw new Error("TC_RENDER_BUFFER_CAPABILITY: Postprocess storage slots require a managed WebGPU bridge.");
+                buffers.prepare(p.material, d.graph.bufferTypes);
+            }
+            if (Object.keys(d.graph.textureSlots ?? {}).length) {
+                if (!managedTextures)
+                    throw new Error("TC_RENDER_TEXTURE_CAPABILITY: Postprocess texture slots require a managed WebGPU bridge.");
+                managedTextures.prepare(p.material, d.graph.textureSlots);
+            }
+            const sample = (bindings, channel, uv) => {
+                const n = TSL.texture(zero, uv);
+                n.updateMatrix = false;
+                n.mergeable = false;
+                bindings.push({ channel, node: n });
+                return n.level(TSL.float(0));
+            };
+            p.material.fragmentNode = typedGraphToTSL(d.graph, timeUniform, p.parameters, textures, {
+                inputs: {
+                    uv: TSL.uv(0),
+                    screenSize: TSL.uniform(new THREE.Vector2(width, height)),
+                    texelSize: TSL.uniform(new THREE.Vector2(1 / width, 1 / height)),
+                },
+                sampleFrame: (channel, uv) => sample(p.frame, channel, uv),
+                sampleHistory: (channel, uv) => sample(p.history, channel, uv),
+                readBuffer: (name, index, type) => {
+                    if (!buffers)
+                        throw new Error("TC_RENDER_BUFFER_CAPABILITY: Postprocess storage slots require a managed WebGPU bridge.");
+                    return buffers.node(p.material, name, index, type, true);
+                },
+                sampleTextureSlot: (name, uv) => {
+                    if (!managedTextures)
+                        throw new Error("TC_RENDER_TEXTURE_CAPABILITY: Postprocess texture slots require a managed WebGPU bridge.");
+                    return managedTextures.node(p.material, name, uv, d.graph.textureSlots[name]);
+                },
+            });
+        }
+        const finalTexture = TSL.texture(source.texture, TSL.uv(0));
+        finalTexture.updateMatrix = false;
+        finalTexture.mergeable = false;
+        const finalMaterial = material("PostProcess:Output");
+        const traceExposure = TSL.uniform(1);
+        const quad = new THREE.QuadMesh(finalMaterial);
+        let finalKey = "";
+        // Scope all mutations, including QuadMesh.render's non-finally vertexNode assignment.
+        const scoped = (run) => {
+            const state = {
+                target: renderer.getRenderTarget(),
+                face: renderer.getActiveCubeFace(),
+                mip: renderer.getActiveMipmapLevel(),
+                mrt: renderer.getMRT(),
+                clear: renderer.getClearColor(new THREE.Color()),
+                alpha: renderer.getClearAlpha(),
+                depth: renderer.reversedDepthBuffer
+                    ? 1 - renderer.getClearDepth()
+                    : renderer.getClearDepth(),
+                stencil: renderer.getClearStencil(),
+                viewport: renderer.getViewport(new ViewportSnapshot()),
+                scissor: renderer.getScissor(new THREE.Vector4()),
+                scissorTest: renderer.getScissorTest(),
+                auto: renderer.autoClear,
+                color: renderer.autoClearColor,
+                autoDepth: renderer.autoClearDepth,
+                autoStencil: renderer.autoClearStencil,
+                tone: renderer.toneMapping,
+                exposure: renderer.toneMappingExposure,
+                space: renderer.outputColorSpace,
+                xr: renderer.xr.enabled,
+            };
+            try {
+                renderer.xr.enabled = false;
+                renderer.toneMapping = THREE.NoToneMapping;
+                renderer.toneMappingExposure = 1;
+                renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
+                renderer.setScissorTest(false);
+                renderer.autoClear =
+                    renderer.autoClearColor =
+                        renderer.autoClearDepth =
+                            true;
+                renderer.autoClearStencil = false;
+                run();
+            }
+            finally {
+                renderer.setRenderTarget(state.target, state.face, state.mip);
+                renderer.setMRT(state.mrt);
+                renderer.setClearColor(state.clear, state.alpha);
+                renderer.setClearDepth(state.depth);
+                renderer.setClearStencil(state.stencil);
+                renderer.setViewport(state.viewport.x, state.viewport.y, state.viewport.z, state.viewport.w, state.viewport.minDepth, state.viewport.maxDepth);
+                renderer.setScissor(state.scissor);
+                renderer.setScissorTest(state.scissorTest);
+                renderer.autoClear = state.auto;
+                renderer.autoClearColor = state.color;
+                renderer.autoClearDepth = state.autoDepth;
+                renderer.autoClearStencil = state.autoStencil;
+                renderer.toneMapping = state.tone;
+                renderer.toneMappingExposure = state.exposure;
+                renderer.outputColorSpace = state.space;
+                renderer.xr.enabled = state.xr;
+            }
+        };
+        const draw = (m) => {
+            quad.material = m;
+            const vertex = m.vertexNode;
+            try {
+                quad.render(renderer);
+            }
+            finally {
+                m.vertexNode = vertex;
+            }
+        };
+        const resetHistory = (reason = "explicit") => {
+            active();
+            for (const p of passes)
+                p.valid = false;
+            resets++;
+            resetReason = reason;
+        };
+        return {
+            captureRaster(scene, camera) {
+                active();
+                scoped(() => {
+                    renderer.setRenderTarget(source);
+                    renderer.setMRT(rasterMRT);
+                    renderer.setClearDepth(1);
+                    renderer.render(scene, camera);
+                });
+            },
+            traceTargets() {
+                active();
+                if (!backend.isWebGPUBackend)
+                    return fail("CAPABILITY", "Raw trace targets require WebGPU.");
+                let result;
+                scoped(() => {
+                    renderer.initRenderTarget(source);
+                    const [color, normal, depth] = source.textures.map((t) => backend.get(t).texture);
+                    if (!color || !normal || !depth)
+                        fail("CAPABILITY", "Three did not allocate the three native HDR attachments.");
+                    result = { color: color, normal: normal, depth: depth };
+                });
+                return result;
+            },
+            present(owner, time, settings) {
+                active();
+                if (!Number.isFinite(Math.fround(time)))
+                    fail("STATE", "Time must fit finite f32.");
+                const states = owner.states();
+                const byId = new Map(states.map((s) => [s.id, s]));
+                if (byId.size !== passes.length ||
+                    states.length !== passes.length ||
+                    passes.some((p) => !byId.has(p.definition.id)))
+                    fail("STATE", "Owner pass IDs do not match the compiled definitions.");
+                const revisions = owner.historyRevisions();
+                if (lastMode !== undefined && lastMode !== settings.mode)
+                    resetHistory("mode");
+                lastMode = settings.mode;
+                if (passes.some((p) => !p.enabled && byId.get(p.definition.id).enabled))
+                    resetHistory("reenable");
+                for (const p of passes) {
+                    const id = p.definition.id, revision = revisions[id];
+                    if (!Number.isSafeInteger(revision) || revision < 0)
+                        fail("STATE", "Missing history revision: " + id);
+                    if (p.revision !== revision)
+                        p.valid = false;
+                    p.revision = revision;
+                    p.enabled = byId.get(id).enabled;
+                }
+                timeUniform.value = time;
+                const savedTone = renderer.toneMapping, savedSpace = renderer.outputColorSpace;
+                try {
+                    scoped(() => {
+                        renderer.setMRT(null);
+                        renderer.setClearColor(0, 0);
+                        const channels = new Map([
+                            ["scene.color", source.textures[0]],
+                            ["scene.normal", source.textures[1]],
+                            ["scene.depth", source.textures[2]],
+                        ]);
+                        let upstream = source.texture;
+                        for (const p of passes) {
+                            if (!p.enabled) {
+                                channels.set(p.definition.id, upstream);
+                                continue;
+                            }
+                            const output = p.targets[1 - p.read];
+                            for (const b of p.frame) {
+                                const t = channels.get(b.channel);
+                                if (!t || t === output.texture)
+                                    fail("GRAPH", "Unsafe frame attachment: " + b.channel);
+                                b.node.value = t;
+                            }
+                            for (const b of p.history) {
+                                const previous = passes.find((v) => v.definition.id === b.channel);
+                                const t = previous.valid
+                                    ? previous.targets[previous.read].texture
+                                    : zero;
+                                if (t === output.texture)
+                                    fail("GRAPH", "Unsafe history attachment: " + b.channel);
+                                b.node.value = t;
+                            }
+                            const values = byId.get(p.definition.id).parameters;
+                            for (const definition of p.definition.graph.parameters ?? []) {
+                                const value = values[definition.name] ?? definition.default;
+                                const uniform = p.parameters.get(definition.name);
+                                const valid = definition.type === "bool"
+                                    ? typeof value === "boolean"
+                                    : definition.type === "float"
+                                        ? typeof value === "number" &&
+                                            Number.isFinite(Math.fround(value))
+                                        : Array.isArray(value) &&
+                                            value.length === Number(definition.type.slice(3)) &&
+                                            value.every((n) => typeof n === "number" &&
+                                                Number.isFinite(Math.fround(n)));
+                                if (!valid)
+                                    fail("STATE", "Invalid parameter: " +
+                                        p.definition.id +
+                                        ":" +
+                                        definition.name);
+                                if (Array.isArray(value))
+                                    uniform.value.fromArray(value);
+                                else
+                                    uniform.value = value;
+                            }
+                            renderer.setRenderTarget(output);
+                            draw(p.material);
+                            upstream = output.texture;
+                            channels.set(p.definition.id, upstream);
+                        }
+                        finalTexture.value = upstream;
+                        // Explicit output transform; automatic renderer transforms remain disabled.
+                        const tracedBeauty = settings.mode !== "raster" && settings.debug === "beauty";
+                        const rasterBeauty = settings.mode === "raster" && settings.debug === "beauty";
+                        const tone = rasterBeauty ? savedTone : THREE.NoToneMapping;
+                        const key = tone + ":" + savedSpace + ":" + tracedBeauty + ":" + rasterBeauty;
+                        if (finalKey !== key) {
+                            let color = finalTexture.level(TSL.float(0));
+                            if (!rasterBeauty) {
+                                const exposed = TSL.max(color.rgb.mul(traceExposure), 0);
+                                // Match TRACE_PRESENT_SHADER, not Three's matrix-based ACES operator.
+                                const rgb = tracedBeauty
+                                    ? TSL.clamp(exposed
+                                        .mul(exposed.mul(2.51).add(0.03))
+                                        .div(exposed.mul(exposed.mul(2.43).add(0.59)).add(0.14)), 0, 1)
+                                    : exposed;
+                                color = TSL.vec4(rgb, color.a);
+                            }
+                            finalMaterial.fragmentNode = TSL.renderOutput(color, tone, savedSpace);
+                            finalMaterial.needsUpdate = true;
+                            finalKey = key;
+                        }
+                        traceExposure.value = settings.exposure;
+                        renderer.toneMappingExposure = rasterBeauty ? settings.exposure : 1;
+                        renderer.setRenderTarget(null);
+                        renderer.setViewport(0, 0, width / renderer.getPixelRatio(), height / renderer.getPixelRatio());
+                        draw(finalMaterial);
+                    });
+                    // Commit only after the final draw AND state restoration succeeded.
+                    for (const p of passes)
+                        if (p.enabled) {
+                            p.read = 1 - p.read;
+                            p.valid = true;
+                        }
+                    frames++;
+                }
+                catch (error) {
+                    failures++;
+                    throw error;
+                }
+            },
+            resetHistory,
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                release();
+            },
+            inspect() {
+                return {
+                    disposed,
+                    width,
+                    height,
+                    samples,
+                    format: "rgba16float",
+                    sourceAttachments: ["output", "normal", "linearDepth"],
+                    frames,
+                    failures,
+                    resets,
+                    resetReason,
+                    resources: {
+                        allocated,
+                        released,
+                        live: allocated - released,
+                        targets: disposed ? 0 : 1 + passes.length * 2,
+                        textures: disposed ? 0 : 4 + passes.length * 2,
+                    },
+                    passes: passes.map((p) => ({
+                        id: p.definition.id,
+                        enabled: p.enabled,
+                        historyValid: p.valid,
+                        read: p.read,
+                        revision: p.revision,
+                        frameBindings: p.frame.map((b) => ({
+                            channel: b.channel,
+                            texture: b.node.value.name,
+                        })),
+                        historyBindings: p.history.map((b) => ({
+                            channel: b.channel,
+                            texture: b.node.value.name,
+                        })),
+                    })),
+                };
+            },
+        };
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}

package/lib/renderer/render-buffers.js

@@ -0,0 +1,132 @@
+import * as THREE from "three/webgpu";
+import * as TSL from "three/tsl";
+const fail = (code, message) => { throw new Error("TC_RENDER_BUFFER_" + code + ": " + message + " Repair: Use a live matching WebGPU buffer binding and recreate resources after device replacement."); };
+/** Three owns render attributes; the executor owns source buffers. Every update is a GPU copy. */
+export function createRenderBufferBridge(renderer, source, resources) {
+    const backend = renderer.backend;
+    const device = backend.device;
+    const entries = new Map();
+    let disposed = false, copies = 0, copyBytes = 0, allocations = 0, released = 0;
+    const active = () => {
+        if (disposed)
+            fail("DISPOSED", "Render buffer bridge was disposed.");
+        if (renderer.backend !== backend || backend.isWebGLBackend || !device || backend.device !== device)
+            fail("CAPABILITY", "Managed GPU render slots require the initialized WebGPU backend.");
+    };
+    const disposeAttribute = (attribute) => {
+        attribute.dispose();
+        // Before a material's first render, Three's Attributes owner has no listener yet.
+        if (backend.has(attribute))
+            backend.destroyAttribute(attribute);
+        released++;
+    };
+    const makeAttribute = (count) => {
+        if (!Number.isSafeInteger(count) || count < 1 || count * 16 > device.limits.maxStorageBufferBindingSize || count * 16 > device.limits.maxBufferSize)
+            fail("COUNT", "Render storage count exceeds actual GPU limits.");
+        const attribute = new THREE.StorageBufferAttribute(count, 4);
+        attribute.name = "Pelican controlled render slot";
+        try {
+            backend.createStorageAttribute(attribute);
+        }
+        catch (error) {
+            attribute.dispose();
+            if (backend.has(attribute))
+                backend.destroyAttribute(attribute);
+            throw error;
+        }
+        allocations++;
+        return attribute;
+    };
+    const get = (material, name, type) => {
+        active();
+        const descriptor = resources(material.name)[name] ?? fail("UNBOUND", material.name + ":" + name);
+        if (descriptor.type !== type)
+            fail("TYPE", material.name + ":" + name);
+        let slots = entries.get(material);
+        if (!slots) {
+            slots = new Map();
+            entries.set(material, slots);
+        }
+        let entry = slots.get(name);
+        if (!entry) {
+            const attribute = makeAttribute(descriptor.values.length);
+            entry = { material, name, type, count: descriptor.values.length, length: TSL.uniform(descriptor.values.length), attribute, node: TSL.storage(attribute, "vec4", descriptor.values.length).toReadOnly() };
+            slots.set(name, entry);
+        }
+        return entry;
+    };
+    return {
+        node(material, name, index, type, robust = false) {
+            const entry = get(material, name, type);
+            const value = entry.node.element(TSL.uint(robust ? TSL.clamp(index, 0, entry.length.sub(1)) : index));
+            const typed = type === "bool" ? value.x.notEqual(0) : type === "float" ? value.x : type === "vec2" ? value.xy : type === "vec3" ? value.xyz : value;
+            if (!robust)
+                return typed;
+            const valid = index.greaterThanEqual(0).and(index.lessThan(entry.length)).and(index.equal(index.floor()));
+            const zero = type === "bool" ? TSL.bool(false) : type === "float" ? TSL.float(0) : type === "vec2" ? TSL.vec2(0) : type === "vec3" ? TSL.vec3(0) : TSL.vec4(0);
+            return TSL.select(valid, typed, zero);
+        },
+        prepare(material, names) {
+            for (const [name, type] of Object.entries(names))
+                get(material, name, type);
+        },
+        update() {
+            if (!entries.size)
+                return;
+            active();
+            const executor = source() ?? fail("CAPABILITY", "No managed compute GPU owner is attached.");
+            const planned = [];
+            for (const [material, slots] of entries) {
+                const values = resources(material.name);
+                for (const entry of slots.values()) {
+                    const descriptor = values[entry.name] ?? fail("UNBOUND", material.name + ":" + entry.name);
+                    if (descriptor.type !== entry.type)
+                        fail("TYPE", material.name + ":" + entry.name);
+                    planned.push({ entry, descriptor });
+                }
+            }
+            const encoder = device.createCommandEncoder({ label: "Pelican compute-to-render copies" });
+            const committed = [];
+            for (const { entry, descriptor } of planned) {
+                if (entry.key === descriptor.key && entry.revision === descriptor.revision)
+                    continue;
+                const view = executor.resident(descriptor);
+                if (view.type !== entry.type || view.count !== descriptor.values.length || view.revision !== descriptor.revision || !(view.buffer.usage & GPUBufferUsage.COPY_SRC))
+                    fail("RESOURCE", "Executor returned a mismatched committed resource.");
+                if (entry.count !== view.count) {
+                    const attribute = makeAttribute(view.count);
+                    disposeAttribute(entry.attribute);
+                    entry.attribute = attribute;
+                    entry.count = view.count;
+                    entry.length.value = view.count;
+                    entry.node.value = attribute;
+                    entry.node.bufferCount = view.count;
+                    entry.material.needsUpdate = true;
+                }
+                const target = backend.get(entry.attribute).buffer ?? fail("RESOURCE", "Three did not allocate the destination render attribute.");
+                if (target === view.buffer)
+                    fail("RESOURCE", "Compute source and Three render destination must have different owners.");
+                encoder.copyBufferToBuffer(view.buffer, 0, target, 0, view.count * 16);
+                committed.push({ entry, key: descriptor.key, revision: descriptor.revision, bytes: view.count * 16 });
+            }
+            if (committed.length)
+                device.queue.submit([encoder.finish()]);
+            for (const item of committed) {
+                item.entry.key = item.key;
+                item.entry.revision = item.revision;
+                copies++;
+                copyBytes += item.bytes;
+            }
+        },
+        inspect() { return { disposed, slots: [...entries.values()].reduce((count, slots) => count + slots.size, 0), allocations, released, liveAttributes: allocations - released, gpuCopies: copies, gpuCopyBytes: copyBytes, cpuResultUploads: 0, bindings: [...entries.values()].flatMap(slots => [...slots.values()].map(entry => ({ material: entry.material.name, name: entry.name, type: entry.type, count: entry.count, key: entry.key, revision: entry.revision }))) }; },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const slots of entries.values())
+                for (const entry of slots.values())
+                    disposeAttribute(entry.attribute);
+            entries.clear();
+        },
+    };
+}