@drawcall/lod 0.2.0 → 0.3.0

package/dist/levels/cameras.js

@@ -0,0 +1,122 @@
+import { Vector2, Vector4 } from "three/webgpu";
+import { at } from "../at.js";
+import { busy } from "./renderer.js";
+import { renderNow, sameContext } from "./compile/contexts.js";
+// What renders tell a Lod of the cameras that draw it.
+const viewport = new Vector4();
+const canvas = new Vector2();
+/**
+ * The height `renderer` draws at now, which levels are chosen at: CSS pixels on the canvas, so that a high-density
+ * screen picks the levels a standard one does and pays for its extra pixels only in fill; pixels in a render target,
+ * except one the canvas's size, which stands in for it (a post-processing target); in a shadow pass, the map's texels.
+ */
+export function drawingHeight(renderer, shadow) {
+    const active = renderer.getRenderTarget();
+    if (shadow)
+        return active ? active.height : null;
+    if (!active)
+        return renderer.getViewport(viewport).w;
+    const ratio = active.height === renderer.getDrawingBufferSize(canvas).y ? renderer.getPixelRatio() : 1;
+    return active.viewport.w / ratio;
+}
+/** The render contexts kept per camera: those of a camera that draws several scenes or targets each frame. */
+const CONTEXTS = 8;
+/**
+ * What a Lod's renders told of each camera that drew it: the height it draws at, where it rendered, and the shadow
+ * maps it drew. A context or shadow map whose target is disposed is passed over, so that no compile revives the target.
+ */
+export class CameraRenders {
+    /** Per camera: a side table, as three's Camera has no place for a package's state; a camera let go is let go here. */
+    cameras = new WeakMap();
+    /** The targets disposed since they were last drawn into. */
+    disposed = new WeakSet();
+    /** One listener on each target drawn into, until it is disposed or `dispose` is called. */
+    listeners = new Map();
+    /**
+     * The height `camera` draws at, measured from `renderer` while it renders (see `drawingHeight`), else the last it
+     * drew at; before it drew, the canvas's.
+     */
+    heightOf(camera, renderer, shadow) {
+        const height = busy(renderer) ? drawingHeight(renderer, shadow) : null;
+        if (height !== null)
+            this.stateOf(camera).height = height;
+        return this.cameras.get(camera)?.height ?? renderer.getSize(canvas).y;
+    }
+    /** Where `camera` last rendered a scene holding the Lod, into a target not disposed. */
+    contextOf(camera) {
+        return this.cameras.get(camera)?.contexts.find((context) => !this.isDisposed(context.target));
+    }
+    /**
+     * Whether `context` is still one its camera renders in: not one whose target was disposed, nor one evicted by the
+     * cap on contexts per camera.
+     */
+    holds(context) {
+        return !this.isDisposed(context.target) && (this.cameras.get(context.camera)?.contexts.includes(context) ?? false);
+    }
+    /** The shadow maps `cameras` drew, into targets not disposed. */
+    shadowsOf(cameras) {
+        return [...cameras].flatMap((camera) => this.cameras.get(camera)?.shadows ?? []).filter((map) => !this.isDisposed(map.target));
+    }
+    /** Whether `camera`, a light's shadow camera, drew a shadow map whose target is not disposed. */
+    drawsShadowMap(camera) {
+        return this.cameras.get(camera)?.shadows.some((map) => !this.isDisposed(map.target)) ?? false;
+    }
+    /**
+     * Whether `target` was disposed since it was last drawn into: what draws into it compiles nothing. The output never
+     * is.
+     */
+    isDisposed(target) {
+        return target !== null && this.disposed.has(target);
+    }
+    /** Note what `renderer` rendering `scene` with `camera` tells: the camera's render context, or a shadow map. */
+    note(renderer, scene, camera) {
+        const now = renderNow(renderer, scene, camera);
+        if (!now)
+            return;
+        const state = this.stateOf(camera);
+        if ("shadow" in now) {
+            const { shadow } = now;
+            this.drawnInto(shadow.target);
+            const index = state.shadows.findIndex((map) => map.target === shadow.target);
+            if (index >= 0)
+                state.shadows[index] = shadow;
+            else
+                state.shadows.push(shadow);
+            return;
+        }
+        const { contexts } = state;
+        const { target } = now.context;
+        if (target)
+            this.drawnInto(target);
+        const index = contexts.findIndex((context) => sameContext(context, now.context));
+        contexts.unshift(index >= 0 ? at(contexts.splice(index, 1), 0) : now.context);
+        if (contexts.length > CONTEXTS)
+            contexts.pop();
+    }
+    /** Stop listening to the targets drawn into. */
+    dispose() {
+        for (const [target, listener] of this.listeners)
+            target.removeEventListener("dispose", listener);
+        this.listeners.clear();
+    }
+    /** `target` is drawn into now: live again if it was disposed, and listened to for its disposal. */
+    drawnInto(target) {
+        this.disposed.delete(target);
+        if (this.listeners.has(target))
+            return;
+        const listener = () => {
+            this.disposed.add(target);
+            target.removeEventListener("dispose", listener);
+            this.listeners.delete(target);
+        };
+        this.listeners.set(target, listener);
+        target.addEventListener("dispose", listener);
+    }
+    stateOf(camera) {
+        let state = this.cameras.get(camera);
+        if (!state)
+            this.cameras.set(camera, (state = { height: null, contexts: [], shadows: [] }));
+        return state;
+    }
+}
+//# sourceMappingURL=cameras.js.map

package/dist/levels/cameras.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameras.js","sourceRoot":"","sources":["../../src/levels/cameras.ts"],"names":[],"mappings":"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"}

package/dist/levels/compile/contexts.d.ts

@@ -0,0 +1,30 @@
+import type { Camera, Material, Renderer, Scene } from "three/webgpu";
+export interface RenderContext {
+    camera: Camera;
+    scene: Scene;
+    /** The target the render was asked for: null for the output, also while three draws it through its output pass. */
+    target: ReturnType<Renderer["getRenderTarget"]>;
+    mrt: Parameters<Renderer["setMRT"]>[0];
+    cubeFace: number;
+    mipLevel: number;
+    /** How deep in renders it drew (see `callDepth`). */
+    depth: number;
+}
+/** A render target a camera or shadow map draws into. */
+export type Target = NonNullable<RenderContext["target"]>;
+/** A shadow map rendered for a scene, with the camera and override material three drew it with. */
+export interface ShadowMap {
+    camera: Camera;
+    scene: Scene;
+    target: Target;
+    overrideMaterial: Material;
+    depth: number;
+}
+/** What `renderer` rendering `scene` with `camera` is now: a camera's render context, or a shadow map. */
+export declare function renderNow(renderer: Renderer, scene: Scene, camera: Camera): {
+    context: RenderContext;
+} | {
+    shadow: ShadowMap;
+} | null;
+/** Whether `a` and `b` describe the same render: what was compiled for one is compiled for the other. */
+export declare const sameContext: (a: RenderContext, b: RenderContext) => boolean;

package/dist/levels/compile/contexts.js

@@ -0,0 +1,18 @@
+import { callDepth, inShadowMap, isOutputPass } from "../renderer.js";
+/** What `renderer` rendering `scene` with `camera` is now: a camera's render context, or a shadow map. */
+export function renderNow(renderer, scene, camera) {
+    const active = renderer.getRenderTarget();
+    // A compile, outside renders, prepares draws at depth 0.
+    const depth = Math.max(callDepth(renderer), 0);
+    if (inShadowMap(scene)) {
+        const material = scene.overrideMaterial;
+        return active && material ? { shadow: { camera, scene, target: active, overrideMaterial: material, depth } } : null;
+    }
+    const target = isOutputPass(active) ? null : active;
+    const cubeFace = renderer.getActiveCubeFace();
+    const mipLevel = renderer.getActiveMipmapLevel();
+    return { context: { camera, scene, target, mrt: renderer.getMRT(), cubeFace, mipLevel, depth } };
+}
+/** Whether `a` and `b` describe the same render: what was compiled for one is compiled for the other. */
+export const sameContext = (a, b) => a.scene === b.scene && a.target === b.target && a.mrt === b.mrt && a.cubeFace === b.cubeFace && a.mipLevel === b.mipLevel && a.depth === b.depth;
+//# sourceMappingURL=contexts.js.map

package/dist/levels/compile/contexts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../src/levels/compile/contexts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA4BtE,0GAA0G;AAC1G,MAAM,UAAU,SAAS,CAAC,QAAkB,EAAE,KAAY,EAAE,MAAc;IACxE,MAAM,MAAM,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;IAC1C,yDAAyD;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/C,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC;QACxC,OAAO,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACtH,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACpD,MAAM,QAAQ,GAAG,QAAQ,CAAC,iBAAiB,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,oBAAoB,EAAE,CAAC;IACjD,OAAO,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;AACnG,CAAC;AAED,yGAAyG;AACzG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAgB,EAAE,CAAgB,EAAW,EAAE,CACzE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC"}

package/dist/levels/compile/index.d.ts

@@ -0,0 +1,39 @@
+import type { Object3D, Renderer } from "three/webgpu";
+import type { RenderContext, ShadowMap, Target } from "./contexts.js";
+/** What a compile is for besides its context: shadow maps, and which targets were disposed. */
+export interface CompileFor {
+    /** The shadow maps the scene's level meshes draw into: each mesh that casts compiles for them too. */
+    shadows: readonly ShadowMap[];
+    /** Whether `target` was disposed: no draw compiles for it, as that would make its textures again. */
+    isDisposed(target: Target): boolean;
+}
+/**
+ * What a LodGpu's renderer prepares for the levels arriving: the levels share its queue's budget and its pipeline
+ * cache, which it shares the readiness of (see `sharePipelines`).
+ */
+export declare class Compiler {
+    private readonly renderer;
+    /** Uploaded since the last frame. */
+    private uploaded;
+    /** The last upload: uploads run in turn. */
+    private uploads;
+    /**
+     * The last draw compiled for each shader build: material, attributes, target, shadow map and nesting. three starts a
+     * build for each draw that misses its cache, even one another draw is building, so a draw that builds alike waits
+     * for the last one and finds its build cached.
+     */
+    private readonly builds;
+    constructor(renderer: Renderer);
+    /**
+     * Prepare the same target and MRT as the camera's draw, even if normal rendering has since restored the canvas, and
+     * the shadow maps of `compileFor`, for each mesh that casts. r186 uploads a texture synchronously inside initTexture,
+     * and creates a pipeline it meets while rendering synchronously, so each texture and draw is prepared here first.
+     * Textures upload paced across frames (see `paced`); every draw then compiles at once, as do the draws of every
+     * other level the renderer prepares, so their pipelines are created side by side.
+     */
+    compileAsync(object: Object3D, context: RenderContext, { shadows, isDisposed }: CompileFor): Promise<void>;
+    /** Run `upload`, which answers the bytes it uploaded, after the next frame if those since the last one reached `FRAME_UPLOAD`. */
+    private paced;
+    /** Compile the draw of `mesh`'s groups `part` for `target`. */
+    private compileDraw;
+}

package/dist/levels/compile/index.js

@@ -0,0 +1,185 @@
+import { isMesh, isNode, isTexture } from "../../three.js";
+import { compileMesh, frame, sharePipelines } from "./pipelines.js";
+/**
+ * What a LodGpu's renderer prepares for the levels arriving: the levels share its queue's budget and its pipeline
+ * cache, which it shares the readiness of (see `sharePipelines`).
+ */
+export class Compiler {
+    renderer;
+    /** Uploaded since the last frame. */
+    uploaded = 0;
+    /** The last upload: uploads run in turn. */
+    uploads = Promise.resolve();
+    /**
+     * The last draw compiled for each shader build: material, attributes, target, shadow map and nesting. three starts a
+     * build for each draw that misses its cache, even one another draw is building, so a draw that builds alike waits
+     * for the last one and finds its build cached.
+     */
+    builds = new Map();
+    constructor(renderer) {
+        this.renderer = renderer;
+        sharePipelines(renderer);
+    }
+    /**
+     * Prepare the same target and MRT as the camera's draw, even if normal rendering has since restored the canvas, and
+     * the shadow maps of `compileFor`, for each mesh that casts. r186 uploads a texture synchronously inside initTexture,
+     * and creates a pipeline it meets while rendering synchronously, so each texture and draw is prepared here first.
+     * Textures upload paced across frames (see `paced`); every draw then compiles at once, as do the draws of every
+     * other level the renderer prepares, so their pipelines are created side by side.
+     */
+    async compileAsync(object, context, { shadows, isDisposed }) {
+        const { renderer } = this;
+        const { memory } = renderer.info;
+        for (const texture of textures(object))
+            await this.paced(() => {
+                const known = memory.textures;
+                renderer.initTexture(texture);
+                return memory.textures === known ? 0 : bytesOf(texture);
+            });
+        const meshes = [];
+        object.traverse((node) => {
+            if (isMesh(node))
+                meshes.push(node);
+        });
+        const draws = [];
+        for (const mesh of meshes) {
+            const targets = [{ context, overrideMaterial: null }];
+            if (mesh.castShadow)
+                for (const { camera, target, overrideMaterial, depth } of shadows.filter((map) => map.scene === context.scene))
+                    targets.push({ context: { ...context, camera, target, mrt: null, cubeFace: 0, mipLevel: 0, depth }, overrideMaterial });
+            // r186 starts only the first material before yielding; isolate one draw so setup sees its captured target/MRT.
+            const parts = Array.isArray(mesh.material) ? mesh.geometry.groups.map((group) => [group]) : [mesh.geometry.groups];
+            for (const target of targets)
+                for (const part of parts)
+                    draws.push(this.compileDraw(mesh, target, part, isDisposed));
+        }
+        await Promise.all(draws);
+    }
+    /** Run `upload`, which answers the bytes it uploaded, after the next frame if those since the last one reached `FRAME_UPLOAD`. */
+    paced(upload) {
+        const run = this.uploads.then(async () => {
+            if (this.uploaded >= FRAME_UPLOAD)
+                await frame();
+            const bytes = upload();
+            // The next frame empties the budget, whether or not an upload waits for it.
+            if (bytes > 0 && this.uploaded === 0)
+                void frame().then(() => void (this.uploaded = 0));
+            this.uploaded += bytes;
+        });
+        this.uploads = run.catch(() => { });
+        return run;
+    }
+    /** Compile the draw of `mesh`'s groups `part` for `target`. */
+    compileDraw(mesh, target, part, isDisposed) {
+        const { builds } = this;
+        const material = Array.isArray(mesh.material) ? mesh.material[part[0]?.materialIndex ?? 0] : mesh.material;
+        const key = [
+            material ? material.uuid : "none",
+            Object.keys(mesh.geometry.attributes).sort().join(),
+            target.context.target ? target.context.target.texture.id : "canvas",
+            target.overrideMaterial ? target.overrideMaterial.uuid : "camera",
+            target.context.depth,
+        ].join(" ");
+        const start = () => {
+            // Uploads and alike builds may have taken frames: a target disposed meanwhile stays disposed.
+            const drawn = target.context.target;
+            if (drawn && isDisposed(drawn))
+                return Promise.resolve();
+            const groups = mesh.geometry.groups;
+            try {
+                mesh.geometry.groups = part;
+                return compileMesh(this.renderer, mesh, target);
+            }
+            finally {
+                mesh.geometry.groups = groups;
+            }
+        };
+        const alike = builds.get(key);
+        const own = alike ? alike.then(start) : start();
+        const settled = own.then(() => { }, () => { });
+        builds.set(key, settled);
+        void settled.then(() => {
+            if (builds.get(key) === settled)
+                builds.delete(key);
+        });
+        return own;
+    }
+}
+/**
+ * What texture uploads may add in one frame, in bytes: a 2048² RGBA texture. Uploads run on the GPU's queue before the
+ * frame that follows them, which waits for them all. A draw's geometry is not paced: its buffers copy in far less
+ * time than a texture of the same size and its mipmaps.
+ */
+const FRAME_UPLOAD = 16 * 2 ** 20;
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+/**
+ * The bytes `texture` uploads, as three 0.186.1 uploads it: its mip levels', or its image's and the mipmaps three
+ * generates from it. An uncompressed cube's image is its six faces, and its mip levels are those after the first, with
+ * six images each; a compressed cube's faces carry their own mip levels, unless it has some.
+ */
+function bytesOf(texture) {
+    const levels = texture.mipmaps ?? [];
+    const cube = Array.isArray(texture.image);
+    if (levels.length > 0 && (!cube || Reflect.get(texture, "isCompressedTexture") === true))
+        return bytesIn(levels);
+    const bytes = bytesIn(texture.image) + bytesIn(levels);
+    return texture.generateMipmaps && levels.length === 0 ? Math.ceil((bytes * 4) / 3) : bytes;
+}
+/** The bytes of an image, a mip level, a cube's face or a list of them: its data's, or four per texel. */
+function bytesIn(image) {
+    if (Array.isArray(image))
+        return sum(image.map(bytesIn));
+    if (typeof image !== "object" || image === null)
+        return 0;
+    if (isTexture(image))
+        return bytesIn(image.mipmaps?.length ? image.mipmaps : image.image);
+    const images = Reflect.get(image, "images");
+    if (Array.isArray(images))
+        return bytesIn(images);
+    const data = Reflect.get(image, "data");
+    if (ArrayBuffer.isView(data))
+        return data.byteLength;
+    const dimension = (name) => {
+        const value = Reflect.get(image, name);
+        return typeof value === "number" ? value : 1;
+    };
+    return dimension("width") * dimension("height") * dimension("depth") * 4;
+}
+/**
+ * The textures `object`'s meshes draw: their materials', those their nodes sample, and those a material keeps in plain
+ * objects and arrays for nodes it makes while it builds (an impostor's atlases, a baked mesh's rooms).
+ */
+function textures(object) {
+    const found = new Set();
+    const visited = new Set();
+    const visit = (value) => {
+        if (typeof value !== "object" || value === null || visited.has(value))
+            return;
+        visited.add(value);
+        if (isTexture(value))
+            found.add(value);
+        else if (isNode(value)) {
+            visit(Reflect.get(value, "value"));
+            for (const child of value.getChildren())
+                visit(child);
+        }
+        else if (Array.isArray(value))
+            for (const entry of value)
+                visit(entry);
+        else if ([Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            for (const [key, entry] of Object.entries(value))
+                if (key !== "userData")
+                    visit(entry);
+    };
+    object.traverse((node) => {
+        if (!isMesh(node))
+            return;
+        // userData is the application's, not what a material binds.
+        for (const material of [node.material].flat())
+            for (const [key, value] of Object.entries(material))
+                if (key !== "userData")
+                    visit(value);
+    });
+    return found;
+}
+//# sourceMappingURL=index.js.map

package/dist/levels/compile/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/levels/compile/index.ts"],"names":[],"mappings":"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"}

package/dist/levels/compile/pipelines.d.ts

@@ -0,0 +1,26 @@
+import type { Material, Mesh, Renderer } from "three/webgpu";
+import type { RenderContext } from "./contexts.js";
+/** The next frame. */
+export declare const frame: () => Promise<void>;
+/**
+ * r186 caches a pipeline before it finishes, but a compile reusing it receives none of its promises. Share that
+ * pipeline's readiness, not the readiness of every earlier level: wrap r186's `_pipelines.getForRender`, as no public
+ * API tells when a cached pipeline is ready. Installed once per renderer, by its LodGpu. The adapter
+ * follows the renderer's pipeline cache lifetime; pending entries disappear on success or failure and otherwise hold no
+ * completed pipelines.
+ */
+export declare function sharePipelines(renderer: Renderer): void;
+/** What a level's draws are compiled for: the camera's draw, or a shadow map's with the material three overrides with. */
+export interface CompileTarget {
+    context: RenderContext;
+    overrideMaterial: Material | null;
+}
+export declare function compileMesh(renderer: Renderer, mesh: Mesh, { context, overrideMaterial }: CompileTarget): Promise<void>;
+/**
+ * Run `compile`, which starts a compileAsync, so that it prepares draws for renders `depth` deep. Mirrors three r186
+ * (0.186.1): compileAsync takes its render context, as a render of its own, with the first `_renderContexts.get` of
+ * its synchronous start. Only that call is given `depth`; renders the compile starts meanwhile take their own. A three
+ * that no longer makes that call fails here rather than compiling for the wrong depth. No public API compiles for a
+ * depth other than 0.
+ */
+export declare function atDepth(renderer: Renderer, depth: number, compile: () => Promise<void>): Promise<void>;

package/dist/levels/compile/pipelines.js

@@ -0,0 +1,177 @@
+/** The next frame. */
+export const frame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+const isPipelines = (value) => typeof value === "object" && value !== null && typeof Reflect.get(value, "getForRender") === "function";
+/**
+ * r186 caches a pipeline before it finishes, but a compile reusing it receives none of its promises. Share that
+ * pipeline's readiness, not the readiness of every earlier level: wrap r186's `_pipelines.getForRender`, as no public
+ * API tells when a cached pipeline is ready. Installed once per renderer, by its LodGpu. The adapter
+ * follows the renderer's pipeline cache lifetime; pending entries disappear on success or failure and otherwise hold no
+ * completed pipelines.
+ */
+export function sharePipelines(renderer) {
+    const pipelines = Reflect.get(renderer, "_pipelines");
+    if (!isPipelines(pipelines))
+        throw new Error("Lod: three's renderer keeps no render pipelines (lod mirrors r186)");
+    if (Reflect.get(pipelines.getForRender, SHARED) === true)
+        return;
+    const get = pipelines.getForRender;
+    const pending = new WeakMap();
+    pipelines.getForRender = (object, promises) => {
+        const before = promises?.length ?? 0;
+        const pipeline = get.call(pipelines, object, promises);
+        if (!promises)
+            return pipeline;
+        if (typeof pipeline !== "object" || pipeline === null)
+            throw new Error("Lod: three returned no render pipeline");
+        let ready = pending.get(pipeline);
+        if (!ready) {
+            ready = pipelineReady(renderer, pipeline, promises.slice(before));
+            pending.set(pipeline, ready);
+            const clear = () => pending.delete(pipeline);
+            void ready.then(clear, clear);
+        }
+        promises.push(ready);
+        return pipeline;
+    };
+    Reflect.set(pipelines.getForRender, SHARED, true);
+}
+/** Marks the wrapped getForRender: a second LodGpu of the renderer shares its pipelines already. */
+const SHARED = Symbol("lodSharedPipelines");
+/**
+ * A cached pipeline may have been started by the host before the adapter was installed: wait until the backend's data
+ * for it holds a pipeline or an error. r186's `_isDeviceLost` is read as no public API tells a lost device.
+ */
+async function pipelineReady(renderer, pipeline, started) {
+    await Promise.all(started);
+    const get = Reflect.get(renderer.backend, "get");
+    if (typeof get !== "function")
+        throw new Error("Lod: three's backend keeps no pipeline data");
+    for (;;) {
+        const data = Reflect.apply(get, renderer.backend, [pipeline]);
+        if (typeof data !== "object" || data === null)
+            throw new Error("Lod: three's backend has no render pipeline data");
+        if (Reflect.get(data, "error") === true)
+            throw new Error("Lod: render pipeline compilation failed");
+        if (Reflect.get(renderer, "_isDeviceLost") === true)
+            throw new Error("Lod: device lost while compiling a render pipeline");
+        if (Reflect.get(data, "pipeline"))
+            return;
+        await frame();
+    }
+}
+/**
+ * What r186's renderObject gives an override material for one draw, and puts back once it has handed the draw on.
+ * This and `DRAWN` mirror three 0.186.1's Renderer.renderObject; a three that sets other keys builds shadow shaders
+ * in the frame again.
+ */
+const DRAW_STATE = ["colorNode", "depthNode", "positionNode", "side", "displacementMap", "displacementScale", "displacementBias"];
+/** The keys a draw adds to an override material that lacks them, in the order it adds them. */
+const DRAWN = ["alphaMap", "displacementMap", "displacementScale", "displacementBias"];
+/**
+ * A copy of the shadow map's override material for compiling one draw. r186's compileAsync builds the draw only after
+ * renderObject has put back the per-draw state it gave the override (the caster's shadow nodes and side), so with the
+ * shared material it would prepare a pipeline the shadow map never draws with. The copy holds the state of the draw.
+ * It is not disposed: that would release the pipeline before the shadow map draws with it.
+ */
+function keepingDrawState(material) {
+    const copy = material.clone();
+    // The build's cache key lists a material's keys in order. clone() leaves out those three adds to its shadow material,
+    // its flag and those its draws set, which the copy gets in the order the shared material has them once it drew.
+    for (const key of [...Object.keys(material), ...DRAWN])
+        if (!key.startsWith("_") && !Object.hasOwn(copy, key))
+            Reflect.set(copy, key, Reflect.get(material, key) ?? null);
+    for (const key of DRAW_STATE) {
+        let value = Reflect.get(copy, key);
+        let given = false;
+        Object.defineProperty(copy, key, {
+            get: () => value,
+            set: (next) => {
+                if (given)
+                    return;
+                given = true;
+                value = next;
+            },
+        });
+    }
+    return copy;
+}
+export function compileMesh(renderer, mesh, { context, overrideMaterial }) {
+    const { camera, scene } = context;
+    const target = renderer.getRenderTarget();
+    const mrt = renderer.getMRT();
+    const cubeFace = renderer.getActiveCubeFace();
+    const mipLevel = renderer.getActiveMipmapLevel();
+    const culled = mesh.frustumCulled;
+    const visible = mesh.visible;
+    const children = mesh.children;
+    const background = scene.background;
+    const backgroundNode = scene.backgroundNode;
+    const override = scene.overrideMaterial;
+    try {
+        renderer.setRenderTarget(context.target, context.cubeFace, context.mipLevel);
+        renderer.setMRT(context.mrt);
+        scene.overrideMaterial = overrideMaterial && keepingDrawState(overrideMaterial);
+        // Demanded levels can still be hidden or outside the last camera's frustum.
+        mesh.frustumCulled = false;
+        mesh.visible = true;
+        mesh.children = [];
+        // r186 compiles backgrounds first, which would postpone this mesh until after renderer state is restored.
+        scene.background = null;
+        scene.backgroundNode = null;
+        return atDepth(renderer, context.depth, () => renderer.compileAsync(mesh, camera, scene));
+    }
+    finally {
+        scene.background = background;
+        scene.backgroundNode = backgroundNode;
+        scene.overrideMaterial = override;
+        mesh.children = children;
+        mesh.frustumCulled = culled;
+        mesh.visible = visible;
+        renderer.setRenderTarget(target, cubeFace, mipLevel);
+        renderer.setMRT(mrt);
+    }
+}
+const isRenderContexts = (value) => typeof value === "object" && value !== null && typeof Reflect.get(value, "get") === "function";
+/**
+ * Run `compile`, which starts a compileAsync, so that it prepares draws for renders `depth` deep. Mirrors three r186
+ * (0.186.1): compileAsync takes its render context, as a render of its own, with the first `_renderContexts.get` of
+ * its synchronous start. Only that call is given `depth`; renders the compile starts meanwhile take their own. A three
+ * that no longer makes that call fails here rather than compiling for the wrong depth. No public API compiles for a
+ * depth other than 0.
+ */
+export function atDepth(renderer, depth, compile) {
+    if (depth === 0)
+        return compile();
+    const contexts = Reflect.get(renderer, "_renderContexts");
+    if (!isRenderContexts(contexts))
+        throw new Error("Lod: three's renderer keeps no render contexts");
+    const own = Object.hasOwn(contexts, "get");
+    const get = contexts.get;
+    let taken = false;
+    const restore = () => {
+        if (own)
+            contexts.get = get;
+        else
+            Reflect.deleteProperty(contexts, "get");
+    };
+    contexts.get = (target, mrt) => {
+        taken = true;
+        restore();
+        return get.call(contexts, target, mrt, depth);
+    };
+    let result;
+    try {
+        result = compile();
+    }
+    finally {
+        if (!taken)
+            restore();
+    }
+    // compileAsync returns at once on a lost device, which is no fault of three's version; r186's `_isDeviceLost` alone
+    // tells it.
+    if (taken || Reflect.get(renderer, "_isDeviceLost") === true)
+        return result;
+    void result.catch(() => { });
+    throw new Error("Lod: three's compileAsync took no render context as it started (lod mirrors three r186)");
+}
+//# sourceMappingURL=pipelines.js.map

package/dist/levels/compile/pipelines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipelines.js","sourceRoot":"","sources":["../../../src/levels/compile/pipelines.ts"],"names":[],"mappings":"AAOA,sBAAsB;AACtB,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAElG,MAAM,WAAW,GAAG,CAAC,KAAc,EAAsB,EAAE,CACzD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,UAAU,CAAC;AAE1G;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,MAAM,SAAS,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAC/D,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACnH,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,KAAK,IAAI;QAAE,OAAO;IACjE,MAAM,GAAG,GAAG,SAAS,CAAC,YAAY,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAyB,CAAC;IACrD,SAAS,CAAC,YAAY,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC/B,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACjH,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YAClE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC7B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7C,KAAK,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC;AAED,oGAAoG;AACpG,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE5C;;;GAGG;AACH,KAAK,UAAU,aAAa,CAAC,QAAkB,EAAE,QAAgB,EAAE,OAAoC;IACrG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1D,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAC9F,SAAS,CAAC;QACR,MAAM,IAAI,GAAY,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACnH,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACpG,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,eAAe,CAAC,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC3H,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC;YAAE,OAAO;QAC1C,MAAM,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,kBAAkB,CAAC,CAAC;AAClI,+FAA+F;AAC/F,MAAM,KAAK,GAAG,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,kBAAkB,CAAC,CAAC;AAEvF;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC9B,sHAAsH;IACtH,gHAAgH;IAChH,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC;QACpD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC;IACpH,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5C,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE;YAC/B,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;YAChB,GAAG,EAAE,CAAC,IAAa,EAAE,EAAE;gBACrB,IAAI,KAAK;oBAAE,OAAO;gBAClB,KAAK,GAAG,IAAI,CAAC;gBACb,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAkB,EAAE,IAAU,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAiB;IACtG,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,iBAAiB,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAG,QAAQ,CAAC,oBAAoB,EAAE,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACpC,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACxC,IAAI,CAAC;QACH,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7E,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,KAAK,CAAC,gBAAgB,GAAG,gBAAgB,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;QAChF,4EAA4E;QAC5E,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,0GAA0G;QAC1G,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;QACxB,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;QAC5B,OAAO,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IAC5F,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;QAC9B,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC;QACtC,KAAK,CAAC,gBAAgB,GAAG,QAAQ,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACrD,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAOD,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAA2B,EAAE,CACnE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,UAAU,CAAC;AAEjG;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,QAAkB,EAAE,KAAa,EAAE,OAA4B;IACrF,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,OAAO,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACnE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACnG,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACzB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,IAAI,GAAG;YAAE,QAAQ,CAAC,GAAG,GAAG,GAAG,CAAC;;YACvB,OAAO,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC;IACF,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;QAC7B,KAAK,GAAG,IAAI,CAAC;QACb,OAAO,EAAE,CAAC;QACV,OAAO,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC,CAAC;IACF,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,OAAO,EAAE,CAAC;IACrB,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;IACxB,CAAC;IACD,oHAAoH;IACpH,YAAY;IACZ,IAAI,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,eAAe,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC5E,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAC;AAC7G,CAAC"}