@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/render-plugin.js

@@ -0,0 +1,633 @@
+import { YaliError } from '@yali-engine/core';
+import { OrbitCamera } from "./camera.js";
+import { DebugLines, DebugLinesPass } from "./debug-lines.js";
+import { acquireGpu } from "./device.js";
+import { InstanceExtractor } from "./extract.js";
+import { MaterialStore, MeshStore, registerMeshComponent } from "./meshes.js";
+import { DEVICE_FILTER, collectDeviceProfile, selectTier } from "./device-profile.js";
+import { FrameGraph } from "./frame-graph.js";
+import { GpuHealth } from "./gpu-health.js";
+import { GpuTimer } from "./gpu-timer.js";
+import { PipelineCache } from "./pipeline-cache.js";
+import { Environment } from "./environment.js";
+import { ClusteredLights, registerLightComponent } from "./lights.js";
+import { SunShadows } from "./shadows.js";
+import { SceneRenderer } from "./scene.js";
+import { pickFamily, TextureStore } from "./textures.js";
+import { ToneMapper } from "./tonemap.js";
+import { gradingDefaults } from "./post-options.js";
+import { Viewport } from "./viewport.js";
+/** Shadow cascades, their size and the shadow distance per tier (ADR-0068): T0's two 1024² cascades over 150 m are ~0.2 m texels at the far end. */
+const SHADOW_DEFAULTS = {
+    t0: { cascades: 2, size: 1024, distance: 80, filter: 'hard' },
+    t1: { cascades: 3, size: 1024, distance: 120, filter: 'soft' },
+    t2: { cascades: 3, size: 2048, distance: 150, filter: 'soft' },
+};
+/** The texture size class per tier (ADR-0060). */
+const TEXTURE_SIZE = { t0: 512, t1: 1024, t2: 2048 };
+/** Render scales the governor may use, best first (DESIGN.md §4: 0.5×–1.0× in a few steps,
+ *  so transient targets are rebuilt rarely). */
+const RESOLUTION_LEVELS = [1, 0.9, 0.8, 0.7, 0.6, 0.5];
+/** The scene's colour target: linear HDR, tone-mapped to the swapchain by `post.tonemap`. */
+export const HDR_FORMAT = 'rgba16float';
+/** Builds everything that lives on a device; used at init and again on recovery. */
+async function buildPipeline(canvas, capacity, bundles, staging, options, store, materials, texturesFor, accept, debug) {
+    const gpu = await acquireGpu(canvas, { compat: options.compat, accept });
+    // Setup errors are not caught by GpuHealth (it attaches afterwards): scope them, and fail
+    // loudly instead of drawing from resources a rejected command left empty.
+    gpu.device.pushErrorScope('validation');
+    const { textures, tier: tierName, disable } = await texturesFor(gpu);
+    const t0 = performance.now();
+    const pipelines = new PipelineCache(gpu.device);
+    // The geometry and textures are re-uploaded from the stores, which outlive devices
+    // (recovery rebuilds this from them).
+    const po = options.post;
+    const hdr = options.hdr ?? (tierName !== 't0' || !!(po && (po.bloom || po.taa || po.fxaa || po.grading)));
+    const scene = new SceneRenderer(gpu.device, hdr ? HDR_FORMAT : gpu.format, store, materials, textures, capacity);
+    const environment = new Environment(gpu.device);
+    scene.environment = environment;
+    const lights = new ClusteredLights(gpu.device);
+    scene.lights = lights;
+    const so = options.shadows === false || (options.shadows === undefined && disable.has('shadows')) ? null : (options.shadows ?? {});
+    const shadows = new SunShadows(gpu.device, {
+        cascades: so ? (so.cascades ?? SHADOW_DEFAULTS[tierName].cascades) : 0,
+        size: so?.size ?? SHADOW_DEFAULTS[tierName].size,
+        distance: so?.distance ?? SHADOW_DEFAULTS[tierName].distance,
+        splitLambda: so?.splitLambda,
+        filter: so?.filter ?? SHADOW_DEFAULTS[tierName].filter,
+    });
+    scene.shadows = shadows;
+    Object.assign(scene.lighting, options.lighting ?? {});
+    // The post chain needs the HDR target (ADR-0092); grading rides in the tone-mapping pass.
+    // Its passes come from `@yali-engine/render/post`, so a page without them carries none of their bytes.
+    const passes = hdr && (po?.bloom || po?.taa || po?.fxaa) ? (po.passes ?? null) : null;
+    if (hdr && (po?.bloom || po?.taa || po?.fxaa) && !passes) {
+        throw Object.assign(new YaliError('POST_PASSES', 'Bloom, TAA and FXAA need the post chain\'s passes.', "import { postPasses } from '@yali-engine/render/post' and pass post: { passes: postPasses, ... }."), { path: 'post.passes' });
+    }
+    const bloom = passes && po?.bloom ? new passes.Bloom(gpu.device, po.bloom === true ? {} : po.bloom) : null;
+    // Compatibility mode cannot load from a depth texture: no TAA there.
+    const taa = passes && po?.taa && gpu.backend !== 'webgpu-compat' ? new passes.Taa(gpu.device, po.taa === true ? undefined : po.taa.blend, po.taa !== true && po.taa.upscale === true) : null;
+    if (taa && po?.taa && po.taa !== true) {
+        // Before init: the pass after TAA exists only when asked for (ADR-0119).
+        taa.sharpen = po.taa.sharpen ?? 0;
+        taa.motionBlur = po.taa.motionBlur ?? 0;
+    }
+    const fxaa = passes && po?.fxaa ? new passes.Fxaa(gpu.device, gpu.format) : null;
+    const tonemap = new ToneMapper(gpu.device, fxaa ? 'rgba8unorm' : gpu.format);
+    tonemap.curve = options.toneMapping ?? 'neutral';
+    tonemap.exposure = options.exposure ?? 1;
+    tonemap.grading = gradingDefaults(po?.grading);
+    if (!hdr)
+        scene.inlineTone = tonemap; // read each frame: the knobs stay live
+    scene.useBundles = options.bundles ?? (bundles && !disable.has('bundles'));
+    scene.shadingLevels = (options.dynamicShading ?? tierName === 't0') ? 3 : 1;
+    scene.shaderVariant = options.shaderVariant ?? null;
+    scene.useStaging = staging ?? (gpu.backend !== 'webgpu-compat' && !disable.has('staging'));
+    const vertexStorage = gpu.device.limits.maxStorageBuffersInVertexStage;
+    const mode = options.instances ?? 'auto';
+    // The storage path finds each draw's range through firstInstance, which needs
+    // `indirect-first-instance`; without it (or without vertex-stage storage) the vertex path.
+    const storageOk = (vertexStorage === undefined || vertexStorage >= 2) && gpu.features.has('indirect-first-instance');
+    scene.path = mode === 'auto' ? (storageOk && !disable.has('storage-instances') ? 'storage' : 'vertex') : mode;
+    const cull = options.cull ?? 'auto';
+    scene.cull = cull === 'auto' ? (gpu.backend === 'webgpu-compat' || disable.has('gpu-cull') ? 'cpu' : 'gpu') : cull;
+    scene.occlusion = options.occlusion ?? null;
+    const debugPass = new DebugLinesPass(gpu.device, scene.format, scene.cameraBuffer);
+    scene.overlays.push((pass) => debugPass.encode(pass, debug));
+    await Promise.all([scene.init(pipelines), tonemap.init(pipelines), environment.init(pipelines), lights.init(pipelines), debugPass.init(pipelines), bloom?.init(pipelines), taa?.init(pipelines), fxaa?.init(pipelines)]);
+    if (options.meshlets && scene.cull === 'gpu' && scene.path === 'storage') {
+        const clusters = await options.meshlets.create(gpu.device, scene, store);
+        await clusters.init(pipelines);
+        scene.clusters = clusters;
+    }
+    if (options.sky)
+        environment.setSky(options.sky);
+    const setupError = await gpu.device.popErrorScope();
+    if (setupError) {
+        throw new YaliError('RENDER_SETUP', `Building the renderer's GPU state failed validation: ${setupError.message}`, 'This is an engine bug; report it with the message.');
+    }
+    const shaderMs = performance.now() - t0;
+    const timer = new GpuTimer(gpu.device, gpu.features.has('timestamp-query'));
+    const graph = new FrameGraph(gpu.device);
+    graph.timer = timer;
+    graph.importTexture('backbuffer', () => gpu.context.getCurrentTexture().createView());
+    // TAA and occlusion's pyramid sample the depth after the draw.
+    graph.transientTexture('depth', { format: 'depth32float', usage: GPUTextureUsage.RENDER_ATTACHMENT | (taa || scene.occlusionActive ? GPUTextureUsage.TEXTURE_BINDING : 0) });
+    lights.addPass(graph);
+    if (hdr) {
+        const target = GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING;
+        // Transmission samples a copy of the opaque scene (ADR-0099): the target is copied from.
+        scene.screenTransmission = true;
+        graph.transientTexture('scene.hdr', { format: HDR_FORMAT, usage: target | GPUTextureUsage.COPY_SRC });
+        scene.addPasses(graph, 'scene.hdr', 'depth', !!taa);
+        // scene.hdr -> [post.taa] -> [bloom chain] -> post.tonemap (+ grading) -> [post.fxaa] -> backbuffer
+        let color = 'scene.hdr';
+        if (taa) {
+            // Per-object motion where the scene can draw it (ADR-0098); elsewhere the camera's only.
+            if (po?.taa === true || (po?.taa && po.taa.motion !== false))
+                taa.motionFrom(scene);
+            color = taa.addPass(graph, color, 'depth');
+        }
+        bloom?.addPasses(graph, color);
+        if (fxaa) {
+            graph.transientTexture('post.ldr', { format: 'rgba8unorm', usage: target, output: true });
+            tonemap.addPass(graph, color, 'post.ldr', bloom?.output);
+            fxaa.addPass(graph, 'post.ldr', 'backbuffer');
+        }
+        else
+            tonemap.addPass(graph, color, 'backbuffer', bloom?.output);
+    }
+    else
+        scene.addPasses(graph, 'backbuffer', 'depth');
+    graph.setOutput('backbuffer');
+    return { gpu, scene, debugPass, tonemap, bloom, taa, fxaa, environment, lights, shadows, graph, timer, pipelines, shaderMs };
+}
+function destroyPipeline(p, destroyDevice) {
+    p.scene.clusters?.destroy?.();
+    p.scene.destroy();
+    p.debugPass.destroy();
+    p.tonemap.destroy();
+    p.bloom?.destroy();
+    p.taa?.destroy();
+    p.environment.destroy();
+    p.lights.destroy();
+    p.shadows.destroy();
+    p.timer.destroy();
+    p.graph.destroy();
+    if (destroyDevice) {
+        p.gpu.context.unconfigure();
+        p.gpu.device.destroy();
+    }
+}
+/**
+ * The render plugin (DESIGN.md §11–§14). It acquires a WebGPU device (core, then
+ * compatibility mode) or, where the browser has no WebGPU, falls back to WebGL2 (ADR-0070),
+ * selects the tier, draws extracted instances each frame (Submit stage), and rebuilds its
+ * whole device state after device loss without restarting the app (DESIGN.md §3).
+ *
+ * @example
+ * const app = App.create({ plugins: [renderPlugin({ canvas }), gamePlugin] });
+ * await app.init();
+ * app.start();
+ */
+export function renderPlugin(options) {
+    let ctx = null;
+    return {
+        name: '@yali-engine/render',
+        version: '0.4.0',
+        async build(b) {
+            const lc = b.app.lifecycle;
+            const bundles = options.bundles ?? true;
+            const viewport = new Viewport(options.canvas, options.viewport);
+            const staging = options.staging;
+            const store = new MeshStore();
+            const materials = new MaterialStore();
+            const camera = new OrbitCamera();
+            const debug = new DebugLines(camera);
+            // `render.Mesh` exists only with a world (an App created with a core).
+            let world = null;
+            try {
+                world = b.app.world;
+            }
+            catch {
+                // no core, no world: meshes are not available
+            }
+            const Mesh = world ? registerMeshComponent(world) : null;
+            const Light = world ? registerLightComponent(world) : null;
+            const extractor = world && Mesh ? new InstanceExtractor(world, Mesh) : null;
+            const rules = options.deviceFilter ?? DEVICE_FILTER;
+            let textures = null;
+            let firstSelection = null;
+            // The profile is collected once (it opens a WebGL context to read the renderer string).
+            let firstProfile = null;
+            // The tier and the device filter, decided on the first adapter before a device or the
+            // canvas context exists: a row that sends this GPU to WebGL2 leaves the canvas free for it.
+            const accept = async (adapter, backend) => {
+                if (firstSelection)
+                    return; // a recovery: decided on the first device
+                firstProfile = await collectDeviceProfile(adapter);
+                firstSelection = selectTier(backend, firstProfile, rules, options.tier);
+                if (firstSelection.useWebGL2 && options.backend !== 'webgpu') {
+                    throw new YaliError('WEBGPU_FILTERED', `The device filter sends this GPU to WebGL2 (${firstSelection.matched.join(', ')}).`, 'Nothing to fix: pass backend: "webgpu" to keep WebGPU anyway.');
+                }
+            };
+            // Created on the first device (its family and tier decide the arrays), re-attached on recovery.
+            const texturesFor = async (g) => {
+                if (!textures) {
+                    const t = firstSelection;
+                    const family = options.textureFamily ?? (t.disable.includes('compressed-textures') ? 'rgba8' : pickFamily(g.features));
+                    textures = new TextureStore({ family, size: options.textureSize ?? TEXTURE_SIZE[t.tier] });
+                }
+                textures.attach(g.device);
+                const s = firstSelection;
+                return { textures, tier: s.tier, disable: new Set(s.disable) };
+            };
+            let pipeline = null;
+            if (options.backend !== 'webgl2') {
+                try {
+                    pipeline = await buildPipeline(options.canvas, options.capacity ?? 65_536, bundles, staging, options, store, materials, texturesFor, accept, debug);
+                }
+                catch (err) {
+                    // No WebGPU here at all, or a device-filter row against it: the WebGL2 fallback
+                    // (unless the app asked for WebGPU only).
+                    const code = err instanceof YaliError ? err.code : '';
+                    if (options.backend === 'webgpu' || (code !== 'WEBGPU_UNAVAILABLE' && code !== 'WEBGPU_NO_ADAPTER' && code !== 'WEBGPU_FILTERED'))
+                        throw err;
+                }
+            }
+            if (pipeline)
+                ctx = startWebGpu(pipeline);
+            else {
+                // Loaded only here: a WebGPU page carries none of the WebGL2 backend's bytes.
+                const { startWebGL2 } = await import("./webgl2/webgl2.js");
+                ctx = await startWebGL2({ b, options, viewport, camera, debug, store, materials, world, Mesh, Light, extractor, rules, tierSizes: { texture: TEXTURE_SIZE, shadows: SHADOW_DEFAULTS } });
+            }
+            // Temporal upscaling (ADR-0135), only where TAA runs: the canvas at full size, renderScale for the scene.
+            viewport.upscale = !!pipeline?.taa?.upscale;
+            b.provide('render', ctx);
+            // What both backends share: the camera, the extract, the counters and the quality knobs.
+            b.counter('render.pixels', () => viewport.width * viewport.height, 'px');
+            b.counter('render.scale', () => viewport.renderScale);
+            b.counter('render.instances', () => extractor?.count ?? 0);
+            b.counter('render.visible', () => ctx?.scene.visible ?? 0);
+            b.counter('render.draws', () => ctx?.scene.stats.draws ?? 0);
+            b.counter('render.lights', () => ctx?.lights.count ?? 0);
+            b.counter('render.debugLines', () => debug.drawn / 2);
+            b.counter('render.gpuSceneBytes', () => ctx?.scene.gpuBytes ?? 0, 'bytes');
+            b.counter('render.gpuTextureBytes', () => ctx?.textures.gpuBytes ?? 0, 'bytes');
+            b.counter('render.transientBytes', () => ctx?.graph?.transientBytes ?? 0, 'bytes');
+            // Coarser LODs and no sub-pixel instances before a lower resolution: registered first,
+            // so the governor tries it first (ADR-0050). A step that saves nothing is undone.
+            if (options.dynamicLod ?? true)
+                b.quality({ name: 'render.lodBias', levels: [0, 1, 2, 3], cost: 'gpu', apply: (v) => (ctx.scene.lodBias = v) });
+            // Cheaper shading before a lower resolution (ADR-0072): only where it was compiled (T0 by default).
+            if (ctx.scene.shadingLevels > 1)
+                b.quality({ name: 'render.shading', levels: [0, 1, 2], cost: 'gpu', apply: (v) => (ctx.scene.shadingLevel = v) });
+            if (options.dynamicResolution ?? true) {
+                const initial = viewport.renderScale;
+                const levels = [initial, ...RESOLUTION_LEVELS.filter((v) => v < initial)];
+                b.quality({ name: 'render.scale', levels, cost: 'gpu', apply: (v) => (viewport.renderScale = v) });
+            }
+            // Camera before Extract, so extract systems read this frame's eye.
+            b.system({
+                name: 'render.camera',
+                stage: 'PostUpdate',
+                run: (f) => {
+                    viewport.update();
+                    camera.time = f.time.virtual;
+                    camera.update(viewport.width / viewport.height);
+                },
+            });
+            // Every `render.Mesh` instance, extracted by the core in one call (camera-relative,
+            // grouped by mesh), uploaded in Submit.
+            b.system({
+                name: 'render.extract',
+                stage: 'Extract',
+                run: () => {
+                    if (!extractor)
+                        return;
+                    const r = ctx;
+                    if (r.scene.cull === 'cpu') {
+                        const heap = extractor.world.core.heap;
+                        heap.refresh();
+                        r.scene.writeCullParams(heap.f32, extractor.cullAt >>> 2, camera, viewport.height, viewport.width);
+                        extractor.runCulled(camera.eye, store);
+                    }
+                    else
+                        extractor.run(camera.eye, store.entries.length);
+                },
+            });
+            b.onDispose(() => extractor?.dispose());
+            /** The WebGPU backend: its context, Submit system, recovery and teardown. */
+            function startWebGpu(first) {
+                let p = first;
+                const { gpu } = p;
+                lc.emit({ type: 'init:adapter', backend: gpu.backend, adapterInfo: gpu.adapterInfo });
+                const l = gpu.device.limits;
+                lc.emit({
+                    type: 'init:capabilities',
+                    features: [...gpu.features],
+                    limits: { maxStorageBufferBindingSize: l.maxStorageBufferBindingSize, maxBufferSize: l.maxBufferSize },
+                });
+                const profile = firstProfile;
+                const tier = firstSelection;
+                lc.emit({ type: 'init:device-filter', matched: tier.matched });
+                lc.emit({ type: 'init:tier', tier: tier.tier, source: tier.source });
+                lc.emit({ type: 'init:shaders', pipelines: p.pipelines.stats.pipelines, ms: first.shaderMs });
+                const health = new GpuHealth();
+                let simulated = false;
+                // Frames in flight on the GPU and frames not drawn for it (ADR-0129); one callback, no per-frame closure.
+                let inFlight = 0;
+                let skipped = 0;
+                const finished = () => {
+                    inFlight = Math.max(0, inFlight - 1); // a lost device's frames settle after the reset
+                };
+                let disposing = false;
+                let detach = () => { };
+                const watch = (q) => {
+                    detach = health.attach(q.gpu.device, {
+                        onLost: (info) => {
+                            if (disposing)
+                                return;
+                            void b.app.deviceLost({
+                                reason: simulated ? 'unknown' : info.reason === 'destroyed' ? 'destroyed' : 'unknown',
+                                message: simulated ? 'simulated device loss (simulateDeviceLoss)' : info.message,
+                            });
+                            simulated = false;
+                        },
+                        onHeal: () => p.graph.invalidate(),
+                    });
+                };
+                watch(p);
+                const captures = [];
+                const submits = [];
+                const c = {
+                    backend: gpu.backend,
+                    gpu: p.gpu,
+                    scene: p.scene,
+                    tonemap: p.tonemap,
+                    post: {
+                        get bloom() {
+                            return !!p.bloom;
+                        },
+                        get fxaa() {
+                            return !!p.fxaa;
+                        },
+                        get taa() {
+                            return !!p.taa;
+                        },
+                        get bloomIntensity() {
+                            return p.bloom?.intensity ?? 0;
+                        },
+                        set bloomIntensity(v) {
+                            if (p.bloom)
+                                p.bloom.intensity = v;
+                        },
+                        get bloomThreshold() {
+                            return p.bloom?.threshold ?? 0;
+                        },
+                        set bloomThreshold(v) {
+                            if (p.bloom)
+                                p.bloom.threshold = v;
+                        },
+                        get bloomKnee() {
+                            return p.bloom?.knee ?? 0;
+                        },
+                        set bloomKnee(v) {
+                            if (p.bloom)
+                                p.bloom.knee = v;
+                        },
+                        get bloomRadius() {
+                            return p.bloom?.radius ?? 0;
+                        },
+                        set bloomRadius(v) {
+                            if (p.bloom)
+                                p.bloom.radius = v;
+                        },
+                        get taaBlend() {
+                            return p.taa?.blend ?? 0;
+                        },
+                        set taaBlend(v) {
+                            if (p.taa)
+                                p.taa.blend = v;
+                        },
+                        get taaSharpen() {
+                            return p.taa?.sharpen ?? 0;
+                        },
+                        set taaSharpen(v) {
+                            if (p.taa)
+                                p.taa.sharpen = v;
+                        },
+                        get motionBlur() {
+                            return p.taa?.motionBlur ?? 0;
+                        },
+                        set motionBlur(v) {
+                            if (p.taa)
+                                p.taa.motionBlur = v;
+                        },
+                        get grading() {
+                            return p.tonemap.grading;
+                        },
+                        resetHistory() {
+                            p.taa?.reset();
+                        },
+                        readMotion() {
+                            return p.taa ? p.taa.readMotion() : Promise.resolve(null);
+                        },
+                    },
+                    environment: p.environment,
+                    lights: p.lights,
+                    shadows: p.shadows,
+                    Light,
+                    meshes: store,
+                    materials,
+                    textures: textures,
+                    Mesh,
+                    graph: p.graph,
+                    timer: p.timer,
+                    pipelines: p.pipelines,
+                    viewport,
+                    camera,
+                    debug,
+                    prepasses: [],
+                    health,
+                    profile,
+                    tier: tier.tier,
+                    recoveries: 0,
+                    submitMs: 0,
+                    uploadMs: 0,
+                    maxFramesInFlight: 0,
+                    get framesInFlight() {
+                        return inFlight;
+                    },
+                    get skippedFrames() {
+                        return skipped;
+                    },
+                    capture() {
+                        return new Promise((resolve, reject) => captures.push({ resolve, reject }));
+                    },
+                    simulateDeviceLoss() {
+                        simulated = true;
+                        p.gpu.device.destroy();
+                    },
+                };
+                // Profiling (ADR-0025): sub-scopes of the submit system, GPU passes by name, counters.
+                const profiler = b.app.profiler;
+                const upload = profiler.scope('render.upload', 'Submit');
+                const encode = profiler.scope('render.encode', 'Submit');
+                const queueSubmit = profiler.scope('render.queue-submit', 'Submit');
+                let passNames = [];
+                let passScopes = [];
+                let seenResults = 0;
+                b.counter('render.pipelines', () => p.pipelines.stats.pipelines);
+                /** The camera's offset from the GPU-cull records' anchor (ADR-0075); zero for camera-relative records. */
+                const origin = new Float32Array(3);
+                b.system({
+                    name: 'render.submit',
+                    stage: 'Submit',
+                    run: () => {
+                        if (health.state.status === 'lost')
+                            return; // recovering: draw nothing
+                        // The GPU is `maxFramesInFlight` frames behind: this frame is not drawn (ADR-0129).
+                        if (c.maxFramesInFlight > 0 && inFlight >= c.maxFramesInFlight) {
+                            skipped++;
+                            return;
+                        }
+                        const t0 = performance.now();
+                        p.graph.resize(viewport.width, viewport.height, viewport.outputWidth, viewport.outputHeight);
+                        p.scene.setTargetSize(viewport.width, viewport.height);
+                        profiler.begin(upload);
+                        textures.pump(1);
+                        for (let i = 0; i < 3; i++)
+                            origin[i] = extractor && !extractor.culled ? camera.eye[i] - extractor.anchor[i] : 0;
+                        if (p.taa) {
+                            p.taa.setOrigin(origin);
+                            p.taa.prepare(camera, viewport.width, viewport.height, viewport.outputWidth, viewport.outputHeight);
+                            p.scene.jitter = p.taa.jitter;
+                        }
+                        // Each level of the chain holds about the scene's energy: the weight is shared out.
+                        if (p.bloom)
+                            p.tonemap.bloom = p.bloom.intensity / p.bloom.levels;
+                        p.scene.setCamera(camera, viewport.height, origin);
+                        p.lights.update(world, Light, camera, viewport.width, viewport.height);
+                        p.shadows.update(camera, viewport.width / viewport.height, origin);
+                        if (extractor) {
+                            const core = extractor.world.core;
+                            p.scene.ensureCapacity(extractor.count);
+                            p.scene.upload(core.heap.u8, core.heap.u32, extractor);
+                        }
+                        profiler.end(upload);
+                        c.uploadMs = performance.now() - t0;
+                        profiler.begin(encode);
+                        const encoder = p.gpu.device.createCommandEncoder();
+                        p.scene.recordUpload(encoder);
+                        const pool = p.scene.vertexPool;
+                        const indices = p.scene.indexPool;
+                        if (pool && indices)
+                            for (const f of c.prepasses)
+                                f(encoder, pool, indices);
+                        p.graph.execute(encoder);
+                        if (p.taa?.motion)
+                            p.scene.recordMotionCopies(encoder);
+                        const timing = p.timer.resolve(encoder);
+                        const readVisible = p.scene.afterPasses(encoder);
+                        const grab = captures.length ? recordCapture(p.gpu, encoder) : null;
+                        // A capture frame runs in a validation scope: a failed submit must reject the
+                        // capture, never hand back an empty frame (a blank golden image is a silent pass).
+                        if (grab)
+                            p.gpu.device.pushErrorScope('validation');
+                        submits[0] = encoder.finish();
+                        profiler.end(encode);
+                        profiler.begin(queueSubmit);
+                        p.gpu.device.queue.submit(submits);
+                        if (c.maxFramesInFlight > 0) {
+                            inFlight++;
+                            void p.gpu.device.queue.onSubmittedWorkDone().then(finished, finished);
+                        }
+                        p.scene.afterSubmit();
+                        profiler.end(queueSubmit);
+                        p.timer.collect(timing);
+                        if (readVisible)
+                            p.scene.collect();
+                        if (grab) {
+                            const waiting = captures.splice(0);
+                            const scope = p.gpu.device.popErrorScope();
+                            scope
+                                .then((err) => {
+                                if (err)
+                                    throw new YaliError('CAPTURE_FAILED', `The captured frame's submit failed validation: ${err.message}`, 'See the message; the frame was not drawn.');
+                                return grab();
+                            })
+                                .then((cap) => waiting.forEach((w) => w.resolve(cap)), (e) => waiting.forEach((w) => w.reject(e)));
+                        }
+                        c.submitMs = performance.now() - t0;
+                        debug.clear();
+                        // GPU pass durations, once per readback that completed since the last frame.
+                        if (p.timer.results !== seenResults) {
+                            seenResults = p.timer.results;
+                            if (p.graph.passNames !== passNames) {
+                                passNames = p.graph.passNames;
+                                passScopes = passNames.map((n) => profiler.gpuScope(n));
+                            }
+                            for (let i = 0; i < passScopes.length; i++)
+                                profiler.gpu(passScopes[i], p.timer.ms[i]);
+                        }
+                    },
+                });
+                b.recover(async () => {
+                    detach();
+                    inFlight = 0; // the lost device's frames never finish
+                    destroyPipeline(p, false); // the device is already gone
+                    const next = await buildPipeline(options.canvas, p.scene.capacity, bundles, staging, options, store, materials, texturesFor, accept, debug);
+                    next.tonemap.exposure = p.tonemap.exposure;
+                    next.tonemap.curve = p.tonemap.curve;
+                    next.tonemap.grading = p.tonemap.grading;
+                    if (next.bloom && p.bloom)
+                        Object.assign(next.bloom, { intensity: p.bloom.intensity, threshold: p.bloom.threshold, knee: p.bloom.knee, radius: p.bloom.radius });
+                    if (next.taa && p.taa)
+                        next.taa.blend = p.taa.blend;
+                    Object.assign(next.scene.lighting, p.scene.lighting);
+                    next.environment.setSky(p.environment.sky);
+                    next.shadows.distance = p.shadows.distance;
+                    next.scene.shadingLevel = p.scene.shadingLevel;
+                    p = next;
+                    Object.assign(c, { gpu: next.gpu, scene: next.scene, tonemap: next.tonemap, environment: next.environment, lights: next.lights, shadows: next.shadows, graph: next.graph, timer: next.timer, pipelines: next.pipelines });
+                    c.recoveries++;
+                    seenResults = 0;
+                    health.reset();
+                    watch(next);
+                    return { devices: 1, pipelines: next.pipelines.stats.pipelines, buffers: next.scene.liveBuffers + next.debugPass.liveBuffers, timers: next.timer.liveResources };
+                });
+                b.leaks(() => ({
+                    gpuResources: p.scene.liveBuffers + p.debugPass.liveBuffers + p.timer.liveResources + p.graph.liveTextures + (p.taa?.liveTextures ?? 0),
+                    listeners: viewport.listeners,
+                }));
+                b.onDispose(() => {
+                    disposing = true;
+                    viewport.dispose();
+                    detach();
+                    textures?.detach();
+                    destroyPipeline(p, true);
+                    ctx = null;
+                });
+                return c;
+            }
+        },
+    };
+}
+/**
+ * Records a copy of this frame's canvas texture into a readback buffer on `encoder` (so it
+ * sees exactly what the passes drew). Call the returned function after `queue.submit`: it
+ * maps the buffer (mapping before the submit would invalidate it) and resolves with
+ * tightly packed RGBA8.
+ */
+function recordCapture(gpu, encoder) {
+    const texture = gpu.context.getCurrentTexture();
+    const w = texture.width;
+    const h = texture.height;
+    const bytesPerRow = Math.ceil((w * 4) / 256) * 256; // copies need 256-byte row alignment
+    const buffer = gpu.device.createBuffer({ label: 'yali:capture', size: bytesPerRow * h, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [w, h]);
+    const bgra = gpu.format === 'bgra8unorm';
+    return () => buffer.mapAsync(GPUMapMode.READ).then(() => {
+        const src = new Uint8Array(buffer.getMappedRange());
+        const rgba = new Uint8Array(w * h * 4);
+        for (let y = 0; y < h; y++) {
+            const s = y * bytesPerRow;
+            const d = y * w * 4;
+            for (let x = 0; x < w * 4; x += 4) {
+                rgba[d + x] = src[s + x + (bgra ? 2 : 0)];
+                rgba[d + x + 1] = src[s + x + 1];
+                rgba[d + x + 2] = src[s + x + (bgra ? 0 : 2)];
+                rgba[d + x + 3] = src[s + x + 3];
+            }
+        }
+        buffer.unmap();
+        buffer.destroy();
+        return { width: w, height: h, rgba };
+    }, (err) => {
+        buffer.destroy();
+        throw err;
+    });
+}
+//# sourceMappingURL=render-plugin.js.map