@drawcall/lod 0.2.0 → 0.4.0

package/dist/loader/node.js

@@ -0,0 +1,199 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { createCanvas } from "@drawcall/webgpu";
+import { resolve as resolveImport } from "import-meta-resolve";
+import { Loader, LoadingManager, WebGPURenderer } from "three/webgpu";
+import { publicURL } from "vitecache";
+import { setUpBakeRenderer } from "../bake.js";
+import { CachedLodLoader as BrowserCachedLodLoader } from "./index.js";
+import { loaderPathURL, placeholderOrigin } from "./url.js";
+/** The session of each load, by its async context: the served fetch is global. */
+const sessions = new AsyncLocalStorage();
+/**
+ * CachedLodLoader in Node, as the vitecache plugin and the glts CLI run it: `loadAsync` builds and saves every level of
+ * the ladder, each with the public files the ladder's loads read and the installed versions of three and of the
+ * packages its .glts sources import. A load that reads anything else, such as a URL off the public directory or a module
+ * a .glts source imports from a CDN, fails, since no stored level could be checked against it. Served paths such as
+ * `/trees/oak.glts`, and `file:` URLs in the public directory, as a headless .glts script's manager resolves them to,
+ * load from vitecache's public directory (see `publicURL`), and `.glts` sources through a GLTSLoader of the load's own;
+ * bakes draw on a WebGPU device of @drawcall/webgpu. The manager only resolves the request's URL.
+ *
+ * Each `loadAsync` loads and bakes with what it makes for itself, which it frees before resolving, so loads may run
+ * concurrently. The levels it returns load their stored bytes as in browsers, and none holds the source: the source
+ * level, and a simplified level, which draws with the source's materials, load the source again when a camera needs
+ * them, as the glts CLI's renders of a .glts script that draws a Lod do.
+ */
+export class CachedLodLoader extends BrowserCachedLodLoader {
+    constructor(manager, options = {}) {
+        super(manager, options);
+    }
+    loadAsync(request) {
+        const input = typeof request === "string" ? { url: request } : request;
+        const url = this.publicPath(this.manager.resolveURL(loaderPathURL(input.url, this.path)));
+        return session({ read: new Set(), packages: new Set() }, async () => {
+            const loader = new SessionLoader(this.options);
+            try {
+                return await loader.loadAsync({ ...input, url });
+            }
+            finally {
+                await loader.dispose();
+            }
+        });
+    }
+    /** Nothing to free: each load frees what it made. */
+    async dispose() { }
+    /** A `file:` URL in the public directory as its served path; others as in browsers. */
+    publicPath(url) {
+        if (!url.startsWith("file:"))
+            return super.publicPath(url);
+        const base = publicURL("/");
+        if (!url.startsWith(base))
+            throw new Error(`CachedLodLoader: cannot precompute "${url}", which lies outside the public directory ${base}`);
+        return `/${url.slice(base.length)}`;
+    }
+}
+/** One `loadAsync` of the Node loader: builds every level, with a GLTSLoader and bake renderer of its own. */
+class SessionLoader extends BrowserCachedLodLoader {
+    buildsAll = true;
+    scripts;
+    constructor(options) {
+        super(servingManager(), options);
+        // Packages resolve as the app's do.
+        this.scripts = new ScriptLoader(this.manager, publicURL("/"));
+        this.manager.addHandler(/\.glts$/i, this.scripts);
+    }
+    async dispose() {
+        await super.dispose();
+        await this.scripts.dispose();
+    }
+    /** Load `url` in the load's session, or, once `loadAsync` has resolved, in a session of its own. */
+    loadAsset(url) {
+        if (sessions.getStore())
+            return super.loadAsset(url);
+        return session({ read: new Set(), packages: new Set() }, () => super.loadAsset(url));
+    }
+    newBakeRenderer() {
+        // Three's DOM canvas types exclude native canvases; its constructor checks the actual API.
+        const renderer = Reflect.construct(WebGPURenderer, [{ canvas: canvas(), antialias: false }]);
+        if (!(renderer instanceof WebGPURenderer))
+            throw new Error("CachedLodLoader: three did not make a WebGPURenderer");
+        return setUpBakeRenderer(renderer);
+    }
+    inputs() {
+        const state = sessions.getStore();
+        if (!state)
+            throw new Error("CachedLodLoader: a level was built outside loadAsync");
+        // three builds every level, whatever its source imports.
+        const packages = [...new Set(["three", ...state.packages])].sort();
+        return [...[...state.read].sort().map((path) => ({ path })), ...packages.map((name) => ({ package: name }))];
+    }
+}
+/** A manager that serves root-relative paths from the public directory while a load runs. */
+function servingManager() {
+    const manager = new LoadingManager();
+    manager.setURLModifier((url) => {
+        if (!url.startsWith("/") || url.startsWith("//"))
+            return url;
+        if (!sessions.getStore())
+            throw new Error(`CachedLodLoader: cannot load "${url}" once the load that asked for it has ended`);
+        return placeholderOrigin + url;
+    });
+    return manager;
+}
+/**
+ * Loads `.glts` sources with a GLTSLoader made at the first load, resolving their packages as the app at `root` does,
+ * and records the packages each imports.
+ */
+class ScriptLoader extends Loader {
+    root;
+    loader;
+    constructor(manager, root) {
+        super(manager);
+        this.root = root;
+    }
+    async loadAsync(url) {
+        this.loader ??= import("@drawcall/glts").then(({ GLTSLoader }) => new GLTSLoader(this.manager, { resolve: (specifier) => resolveImport(specifier, this.root) }));
+        const scene = await (await this.loader).loadAsync(url);
+        const { packages, runtimeModules } = scene.source;
+        if (runtimeModules.length > 0)
+            throw new Error(`CachedLodLoader: cannot precompute "${url}": it imports ${runtimeModules.join(", ")} from a CDN at runtime, which a stored level cannot be checked against`);
+        const state = sessions.getStore();
+        if (!state)
+            throw new Error(`CachedLodLoader: "${url}" loaded outside loadAsync`);
+        for (const name of packages)
+            state.packages.add(name);
+        return scene;
+    }
+    /** Free the GLTSLoader and the scenes it loaded, resolving once freed; the next load makes another. */
+    async dispose() {
+        const loader = this.loader;
+        this.loader = undefined;
+        // A GLTSLoader that failed to load failed the load that made it.
+        const made = await loader?.catch(() => undefined);
+        made?.dispose();
+    }
+}
+let users = 0;
+/** What sessions install while any runs: the canvas, and what restores the globals. */
+let installed;
+/**
+ * The restore of the last sessions to finish, which the next install waits for: @drawcall/webgpu saves and restores
+ * the globals it installs per canvas, so two canvases' lives must not overlap.
+ */
+let restored = Promise.resolve();
+let current;
+/** The canvas of the sessions running. */
+function canvas() {
+    if (!current)
+        throw new Error("CachedLodLoader: baking outside loadAsync");
+    return current;
+}
+async function session(state, run) {
+    users++;
+    // A failed restore failed the session that ran it. Sessions running together share one install.
+    const shared = (installed ??= restored.catch(() => { }).then(install));
+    try {
+        current = (await shared).canvas;
+        return await sessions.run(state, run);
+    }
+    finally {
+        if (--users === 0) {
+            installed = current = undefined;
+            // A failed install failed the run above.
+            restored = shared.then(({ restore }) => restore(), () => { });
+            await restored;
+        }
+    }
+}
+/** A canvas of @drawcall/webgpu, which installs WebGPU, image decoding and workers while it lives, and the served fetch. */
+async function install() {
+    const canvas = await createCanvas(1, 1);
+    const { fetch } = globalThis;
+    globalThis.fetch = (input, init) => serve(fetch, input, init);
+    const restore = async () => {
+        globalThis.fetch = fetch;
+        await canvas.dispose();
+    };
+    return { canvas, restore };
+}
+async function serve(fetch, input, init) {
+    const url = new URL(input instanceof Request ? input.url : input);
+    const state = sessions.getStore();
+    if (!state || url.protocol === "data:" || url.protocol === "blob:")
+        return fetch(input, init);
+    if (url.origin !== placeholderOrigin)
+        throw new Error(`CachedLodLoader: cannot precompute a load that fetches ${url.href}, which a stored level cannot be checked against`);
+    const file = publicURL(url.pathname);
+    try {
+        const bytes = await readFile(fileURLToPath(file));
+        state.read.add(file);
+        return new Response(bytes);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return new Response(null, { status: 404 });
+        throw error;
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/loader/node.js.map

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

package/dist/loader/request.d.ts

@@ -0,0 +1,54 @@
+import type { ImpostorMeshOptions } from "../impostor/mesh/index.js";
+import type { BakeImpostorOptions } from "../impostor/bake/index.js";
+import type { SimplifyOptions } from "../simplify/index.js";
+import type { Derived } from "./level.js";
+/**
+ * Levels derived from the source, finest first. In browsers each derived level is built when it first loads, except a
+ * simplified or baked level without `maxPixels`, which is built with the ladder since its default threshold is measured
+ * from its deviation; in Node every level is built with the ladder. An impostor's default is `framePixels` of its
+ * resolution: the threshold of a frame fitted to the source's bounding sphere, so the level before it draws smaller
+ * than it needs to. The frame the bake fits to the source is up to about 1.5 times tighter; give `maxPixels` to
+ * switch to the impostor sooner. Changing `maxPixels` or an impostor's `draw` reuses them, except an impostor's
+ * `maxPixels`, which also sizes its bake.
+ */
+export type LodLevelRequest = ({
+    type: "simplify";
+    maxPixels?: number;
+} & SimplifyOptions) | ({
+    type: "baked";
+    maxPixels?: number;
+    textureSize?: number;
+    /** Room geometry for window baking, as an asset URL relative to the source. */
+    interior?: string;
+} & ({
+    /** Authored low shell to bake onto, as an asset URL relative to the source. */
+    low: string;
+    ratio?: never;
+} | {
+    low?: never;
+    ratio?: number;
+})) | ({
+    type: "impostor";
+    draw?: ImpostorMeshOptions;
+} & BakeImpostorOptions) | {
+    type: "empty";
+    maxPixels: number;
+};
+/** A .glb, .gltf or .glts asset URL. Source and simplified levels load the original asset on demand. */
+export type LodRequest = string | {
+    url: string;
+    levels?: readonly LodLevelRequest[];
+};
+/** A normalized request. */
+export type Ladder = ReturnType<typeof normalize>;
+/**
+ * `request` with its source URL resolved against `path`, which loads it, and `key` of that, which its levels are stored
+ * under. A baked level's low and interior URLs stay relative to the source.
+ */
+export declare function normalize(request: LodRequest, path: string, key: (url: string) => string): {
+    url: string;
+    key: string;
+    levels: readonly LodLevelRequest[];
+};
+/** The request of ladder level `index`, which must be a derived level. */
+export declare function derived(levels: readonly LodLevelRequest[], index: number): Derived;

package/dist/loader/request.js

@@ -0,0 +1,19 @@
+import { loaderPathURL } from "./url.js";
+const DEFAULT_LEVELS = [{ type: "impostor" }];
+/**
+ * `request` with its source URL resolved against `path`, which loads it, and `key` of that, which its levels are stored
+ * under. A baked level's low and interior URLs stay relative to the source.
+ */
+export function normalize(request, path, key) {
+    const input = typeof request === "string" ? { url: request } : request;
+    const url = loaderPathURL(input.url, path);
+    return { url, key: key(url), levels: structuredClone(input.levels ?? DEFAULT_LEVELS) };
+}
+/** The request of ladder level `index`, which must be a derived level. */
+export function derived(levels, index) {
+    const level = levels[index - 1];
+    if (!level || level.type === "empty")
+        throw new Error(`CachedLodLoader: level ${index} is not derived`);
+    return level;
+}
+//# sourceMappingURL=request.js.map

package/dist/loader/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/loader/request.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAkCzC,MAAM,cAAc,GAA+B,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;AAK1E;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAmB,EAAE,IAAY,EAAE,GAA4B;IACvF,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IACvE,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3C,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC;AACzF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,OAAO,CAAC,MAAkC,EAAE,KAAa;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,iBAAiB,CAAC,CAAC;IACxG,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/loader/url.d.ts

@@ -1,13 +1,17 @@
+/**
+ * An origin no URL has: paths parse against it where there is no document to resolve them against, and Node loads
+ * fetch the app's public files at it, as a page of the app fetches them from its own.
+ */
+export declare const placeholderOrigin = "https://lod.invalid";
 /** Resolve a relative asset path without changing absolute URLs or root-relative paths. */
 export declare function loaderPathURL(url: string, base: string): string;
-export declare const urlPath: (url: string) => string;
-export declare const urlQuery: (url: string) => string;
+/**
+ * `url` as a path below the app's base, such as `/tree/model.glts`, when the app serves it, so that what is stored for
+ * it does not depend on where the app is deployed; any other URL, absolute.
+ */
+export declare function publicPath(url: string, basePath: string): string;
 export declare function assetPath(url: string): {
     path: string;
     extension: string;
 };
 export declare function sourceRelativeURL(value: string, source: string): string;
-/** A same-origin path, as localURL leaves it: vitecache can resolve only these to project files. */
-export declare const isLocal: (url: string) => boolean;
-/** Keep same-origin dependencies portable between development and deployment. */
-export declare function localURL(url: string): string;

package/dist/loader/url.js

@@ -1,31 +1,39 @@
 import { LoaderUtils } from "three/webgpu";
 const absolute = /^[a-z][a-z\d+.-]*:/i;
-const fallbackBase = "https://lod.invalid";
+/**
+ * An origin no URL has: paths parse against it where there is no document to resolve them against, and Node loads
+ * fetch the app's public files at it, as a page of the app fetches them from its own.
+ */
+export const placeholderOrigin = "https://lod.invalid";
 /** Resolve a relative asset path without changing absolute URLs or root-relative paths. */
 export function loaderPathURL(url, base) {
     return absolute.test(url) || url.startsWith("/") ? url : LoaderUtils.resolveURL(url, base);
 }
-export const urlPath = (url) => url.replace(/[?#].*$/s, "");
-export const urlQuery = (url) => new URL(url, fallbackBase).search;
+/** What relative URLs resolve against: the page, else an origin no URL has. */
+const page = () => (typeof document === "undefined" ? placeholderOrigin : document.baseURI);
+/**
+ * `url` as a path below the app's base, such as `/tree/model.glts`, when the app serves it, so that what is stored for
+ * it does not depend on where the app is deployed; any other URL, absolute.
+ */
+export function publicPath(url, basePath) {
+    const resolved = new URL(url, page());
+    // The cache's URL includes the app's base.
+    const base = new URL("..", new URL(basePath, page()));
+    if (resolved.origin !== base.origin || !resolved.pathname.startsWith(base.pathname))
+        return resolved.href;
+    return `/${resolved.pathname.slice(base.pathname.length)}${resolved.search}`;
+}
+const urlPath = (url) => url.replace(/[?#].*$/s, "");
 export function assetPath(url) {
     const path = urlPath(url);
     const extension = /\.(glb|gltf|glts)$/i.exec(path)?.[1]?.toLowerCase();
     if (!extension)
-        throw new Error(`LodLoader: cannot load "${url}": expected a .glb, .gltf or .glts file`);
+        throw new Error(`CachedLodLoader: cannot load "${url}": expected a .glb, .gltf or .glts file`);
     return { path, extension };
 }
 export function sourceRelativeURL(value, source) {
-    const base = new URL(source, typeof document === "undefined" ? fallbackBase : document.baseURI);
+    const base = new URL(source, typeof document === "undefined" ? placeholderOrigin : document.baseURI);
     const url = new URL(value, base);
     return url.origin === base.origin && !absolute.test(source) ? url.pathname + url.search + url.hash : url.href;
 }
-/** A same-origin path, as localURL leaves it: vitecache can resolve only these to project files. */
-export const isLocal = (url) => url.startsWith("/") && !url.startsWith("//");
-/** Keep same-origin dependencies portable between development and deployment. */
-export function localURL(url) {
-    if (typeof location === "undefined" || !/^https?:/i.test(url))
-        return url;
-    const parsed = new URL(url);
-    return parsed.origin === location.origin ? parsed.pathname + parsed.search + parsed.hash : url;
-}
 //# sourceMappingURL=url.js.map

package/dist/loader/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/loader/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAE3C,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY;IACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;AAEnF,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IACvE,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,yCAAyC,CAAC,CAAC;IACzG,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAc;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChG,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AAChH,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAE9F,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1E,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACjG,CAAC"}
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/loader/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEvD,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY;IACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED,+EAA+E;AAC/E,MAAM,IAAI,GAAG,GAAW,EAAE,CAAC,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAEpG;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,QAAgB;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,2CAA2C;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtD,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC;IAC1G,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC/E,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAErE,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IACvE,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,yCAAyC,CAAC,CAAC;IAC/G,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,MAAc;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrG,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AAChH,CAAC"}

package/dist/lod.d.ts

@@ -1,67 +1,168 @@
-import { Object3D, type Camera, type Intersection, type Raycaster } from "three/webgpu";
-import { type LevelsEventMap } from "./residency.js";
-import { type LevelView, type LodLevel } from "./levels.js";
-import { WIND_BOUNDS } from "./wind/hooks.js";
+import { Box3, Color, InstancedBufferAttribute, Matrix4, Object3D, type Camera, type Intersection, type LoadingManager, type Raycaster } from "three/webgpu";
+import { type LodLevel, type ThresholdedLevel } from "./levels/index.js";
+import { type LodEventMap } from "./levels/manager.js";
+import { WIND } from "./wind/hooks.js";
+import { type LodCluster } from "./instanced/clusters.js";
+import { type CullDistance } from "./instanced/cull.js";
+/** How a Lod is made. */
+export interface LodOptions {
+    /**
+     * Gets an item while levels a camera needs load, compile or fade in, ended once they are complete; three's
+     * `DefaultLoadingManager` without one. Wait for a quiet frame, one in which no item started or ended, rendering (or
+     * compiling) the Scene that holds the Lod a frame apart meanwhile, to capture what a camera sees complete. A Lod its
+     * renderer rendered around for a frame without updating it ends its item, and its next update starts it again.
+     * Renders of other scenes in a separate task can end the item early, and the next update reopens it; a renderer that
+     * only compiles leaves a hidden Lod's item held.
+     */
+    manager?: LoadingManager;
+}
 /**
- * One object's levels, switched by on-screen height with dithered transitions.
- * The renderer updates selection before shadows; each camera uses its last drawn
- * viewport height (1080 until known). Orthographic views switch without fading.
- * Shadows follow selection and omit casters smaller than a shadow texel.
+ * Copies of one object at levels of detail, driven like a three InstancedMesh: `instanceMatrix`, `instanceColor`,
+ * `count` and `boundingBox`, and `clusters` to cull and choose levels by. Each copy draws the level levelsToDraw gives
+ * for its height on screen, switching with dithered fades; each camera's instances are sorted into indirect draws on
+ * the GPU. `new Lod(levels)` is one object at the Lod's own transform.
+ *
+ * The attributes are assignable. A CPU attribute's edits draw once its `needsUpdate` is set (within its update ranges,
+ * which the Lod takes and clears), as an InstancedMesh's do. A StorageInstancedBufferAttribute, such as one the app's
+ * compute pass writes, is read in place, every frame; a storage colour holds four floats per instance. A matrix of
+ * scale 0 draws nothing. Instance matrices may scale arbitrarily; the Lod's own transform and its parents should scale
+ * uniformly.
+ *
+ * Which levels load and which level meshes draw for a camera follow from the instances' bounds: per cluster, its box
+ * and scales; without clusters, `boundingBox` around the first `count` instances, else what the CPU measures of a CPU
+ * instanceMatrix. With clusters, only their instances draw. A storage instanceMatrix with neither loads every level
+ * (it warns once). Each camera draws only the instances in its frustum, and each shadow map is a camera of its own: it
+ * draws the casters in its frustum, each at the level its texels resolve, as an orthographic camera would (an instance
+ * smaller than a texel casts nothing). Thresholds, fades and loading follow `LodLevel`; `cullDistance` thins the
+ * instances out with distance. Nothing draws until the coarsest level that draws something has loaded, which loads
+ * first; a deferred level loads when a camera first needs it, and meanwhile the nearest loaded coarser level draws in
+ * its place. Arriving levels' texture uploads are paced to about one uncompressed 2048² RGBA texture's bytes per frame.
  *
- * Eager and deferred objects are cloned into this owner's space. A nested Lod selects
- * and fades its own levels. Lines, points and sprites draw without fading or reporting
- * viewport height. Raycasts hit the source only.
+ * It draws with WebGPU only (three's WebGPURenderer on its WebGPU backend, with `indirect-first-instance`), with the
+ * first renderer that draws it: it learns of it in that renderer's first frame, which draws nothing of it, and another
+ * renderer drawing it is its error. Sequential cameras are supported; a nested render with a camera that the outer
+ * render also draws with replaces that camera's instance lists, so exclude the Lod from it with camera layers.
  *
- * Build a new Lod after adding or moving meshes within a level: geometry is measured
- * and hooked at construction or arrival. Skinned meshes and ShaderMaterials are
- * refused; use static meshes with node materials or supported built-in materials.
+ * Level templates are cloned, then their meshes are instanced, as children of the Lod on its layers; it sets each
+ * one's `visible` per camera, so hide the Lod itself, never its level meshes. Skinned meshes, InstancedMeshes (except ImpostorMesh),
+ * lines, points, sprites and LODs in levels are refused, as are ShaderMaterials; use static meshes with node materials
+ * or supported built-in materials. Build a new Lod after adding or moving meshes within a level: geometry is measured
+ * at construction or arrival. For external detail, leave level 0 empty and draw the instances that `getLevelAt`
+ * reports there.
  */
-export declare class Lod extends Object3D<LevelsEventMap> {
+export declare class Lod extends Object3D<LodEventMap> {
     /** Multiplies every measured height: below 1, cheaper levels take over sooner. */
     static quality: number;
     /** Tint every level by its index, to see which level draws where. */
     static debug: boolean;
-    /**
-     * Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its
-     * `maxPixels`, the finer level draws too.
-     */
+    /** Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its `maxPixels`, the finer level draws too. */
     static readonly fade = 0.1;
     readonly isLOD = true;
+    readonly isLod = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate: boolean;
-    /** Draw only this level, without fades. */
+    /** Draw only this level, without fades, once the coarsest level that draws something has loaded. */
     forceLevel: number | null;
-    readonly levels: readonly LevelView[];
-    private readonly entries;
-    /** Per level, how its meshes draw. */
-    private readonly draws;
-    /** Bounding sphere of the source (see the constructor) in the Lod's own space. */
-    private sphere;
-    private casterRadius;
+    /** The levels, each `object` the template its level meshes are made from, once there is one (never in the scene). */
+    readonly levels: ThresholdedLevel[];
+    /** Thins the instances out with distance from a camera, in every camera; null draws them at any distance. */
+    cullDistance: CullDistance | null;
+    /** 16 floats per instance: a CPU InstancedBufferAttribute (identities to start with) or a storage one. */
+    instanceMatrix: InstancedBufferAttribute;
+    /** RGB per instance, white without: three floats on the CPU, four in a storage attribute. */
+    instanceColor: InstancedBufferAttribute | null;
+    /** How many of `instanceMatrix`'s instances draw. */
+    count: number;
+    /** Bounds every instance at every level, in the Lod's space (see `computeBoundingBox`); measured when null. */
+    boundingBox: Box3 | null;
+    /** Disjoint ranges of instances, each inside its box, which cull and choose levels apart; clipped to `count`. */
+    clusters: LodCluster[] | undefined;
+    /** The levels as they were given, which a copy is made from. */
+    private inputs;
+    /** What it is made of for its levels, which a copy makes anew. */
+    private built;
     private disposed;
-    private readonly residency;
+    private readonly instances;
+    /** What the level meshes draw. */
+    private readonly drawn;
+    /** Around every instance, survivors grown: what every level mesh is culled and boxed by. */
+    private readonly bounds;
+    private readonly view;
+    /** The cluster ranges last checked to be disjoint. */
+    private readonly checked;
+    /** What `cullIn` writes cullDistance into, in this Lod's space. */
+    private readonly cull;
+    /**
+     * Drawn until a renderer has drawn the Lod, to learn which: three tells a mesh its renderer, but not a LOD. It bounds
+     * the instances for Box3.setFromObject, as the level meshes do once there are some.
+     */
+    private readonly sentinel;
+    private warned;
+    /** `levels[0]` is the source; empty only as the target of `copy`. `count` instances, at the Lod's origin to start with. */
+    constructor(levels: readonly LodLevel[], count?: number, options?: LodOptions);
     get pending(): boolean;
     get error(): Error | undefined;
+    /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
+    get manager(): LoadingManager;
+    set manager(manager: LoadingManager | undefined);
+    setMatrixAt(index: number, matrix: Matrix4): this;
+    getMatrixAt(index: number, matrix: Matrix4): Matrix4;
+    /** Write instance `index`'s colour, making a white `instanceColor` for every instance first if there is none. */
+    setColorAt(index: number, color: Color): this;
+    /** Instance `index`'s colour: white without `instanceColor`. */
+    getColorAt(index: number, color: Color): Color;
     /**
-     * `levels[0]` is the source. Empty only as the target of `copy`. A source that draws
-     * nothing (an empty Object3D, for detail another system draws) is measured by the
-     * first level that draws something.
+     * Set `boundingBox` around the first `count` instances at every level and its sway, from a CPU instanceMatrix as it
+     * is now; the CPU cannot read a storage one.
      */
-    constructor(levels?: readonly LodLevel[]);
-    private build;
-    /** Fade the meshes under `node` by `draw` and learn the viewport height from them; an inner Lod fades its own. */
-    private hook;
-    [WIND_BOUNDS](padding: number): void;
-    /** Pick and fade levels for `camera`; detail starts after a draw supplies its render context. */
+    computeBoundingBox(): void;
+    /** What this Lod is made of for `inputs`: its levels, their meshes and their loading. */
+    private init;
+    /**
+     * The sentinel, drawn until a renderer has drawn the Lod (see `see`): no instances, on the Lod's layers, casting, and
+     * never hit by a raycast. Its box is the instances' bounds, and its vertices that box's corners (see `placeSentinel`),
+     * which precise Box3.setFromObject reads.
+     */
+    private makeSentinel;
+    /** `renderer`, which three hands a mesh's draw, draws the Lod (see `LodLevelLoadManager.see`): it, once checked. */
+    private see;
+    [WIND](padding: number, slope: number, baseY: number): void;
+    /** Take in the instances as they are now, so that its level meshes bound them (see Box3.setFromObject), then update the world matrices. */
+    updateMatrixWorld(force?: boolean): void;
+    /** Sort the instances into level lists for `camera`, a camera's or a shadow map's, and load the levels they need. What fails is reported (see `error`). */
     update(camera: Camera): void;
-    private install;
-    raycast(raycaster: Raycaster, intersects: Intersection[]): boolean;
+    /** Take in the attributes, clusters and cullDistance as they are now, and bound the instances. */
+    private refresh;
+    /** Put the sentinel's vertices at the corners of the instances' bounds; at the origin while nothing bounds them. */
+    private placeSentinel;
+    /** Sort for `camera`, a shadow map's when `shadow`, drawn by `renderer`. */
+    private sort;
+    /** `camera` in this Lod's space, drawn by `renderer` (see `localCamera`). */
+    private localCamera;
+    /**
+     * The level that draws most of instance `index`'s pixels for `camera` from where it is now, with the levels loaded
+     * now and no arrival under way (see `drawnLevel`); null at scale 0, thinned out by `cullDistance`, or while no level
+     * it could draw is loaded. From the CPU instanceMatrix as it is, edits not yet drawn included; the CPU cannot read a
+     * storage one. It measures with the renderer drawing the Lod, so it throws before one has drawn it.
+     */
+    getLevelAt(index: number, camera: Camera): number | null;
     /**
-     * Copies `source`'s levels into this empty Lod (it throws otherwise). The copies share
-     * geometry, materials and textures with `source`, as three's clone does; the Lod
-     * settings and each level's `maxPixels` come along.
+     * Hits the first `count` instances on the source level, with `instanceId` set as on an InstancedMesh's hits; `object`
+     * is this Lod. Instances of a storage instanceMatrix, which the CPU cannot read, are not hit. Its level meshes, on its
+     * layers, are never hit themselves.
+     */
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+    /**
+     * Copies `source`'s levels, instances and settings into this Lod without levels (it throws otherwise); the copy
+     * shares geometry and textures with `source`, and holds copies of its attributes and clusters. Storage attributes
+     * cannot be copied: their instances live on the GPU.
      */
     copy(source: Lod): this;
-    /** Release drawables and templates only after every owner sharing their geometry, materials and textures has stopped drawing. */
+    clone(): this;
+    /**
+     * Release its buffers and what it made of its levels, once nothing it prepares or compiles still uses them. Objects
+     * you give or load, its attributes among them, are yours to dispose; CachedLodLoader's are freed when the last Lod
+     * holding them is disposed (see `LodLevel.hold`).
+     */
     dispose(): void;
 }