@drawcall/lod 0.1.2 → 0.3.0

package/dist/loader/index.d.ts

@@ -0,0 +1,62 @@
+import { Loader, LoadingManager } from "three/webgpu";
+import { type LodLevel } from "../levels/index.js";
+import type { LodCacheOptions } from "./cache.js";
+import { type LodRequest } from "./request.js";
+/**
+ * Loads asset URLs through manager handlers, else with a GLTFLoader of its own, which decodes meshopt only: register
+ * a GLTFLoader configured with Draco or KTX2 decoders for models compressed with them, and a GLTSLoader for .glts
+ * sources.
+ *
+ * Impostor and interior bakes draw with a renderer of the loader's own, made at its first bake: `dispose` frees it.
+ */
+export declare class LodLoader extends Loader<LodLevel[], LodRequest> {
+    private readonly cacheOptions?;
+    private gltf;
+    /**
+     * The renderer this loader bakes with, made at its first bake. Its own, not the app's: a canvas the size of a bake
+     * frame would draw that frame over the whole target (see `bakeImpostor`).
+     */
+    private renderer;
+    /** URLs whose builds this loader serves without saving, once it has warned why. */
+    private readonly uncached;
+    constructor(manager?: LoadingManager, cacheOptions?: LodCacheOptions | undefined);
+    load(request: LodRequest, onLoad: (levels: LodLevel[]) => void, _onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+    /**
+     * Describes the ladder from the cache, else from its source, which the first level loaded then takes. Empty levels
+     * load with it, as does the source when it is the only drawable; other levels load when a camera needs them,
+     * including a coarse stand-in while its first detail arrives, and each derived level is cached on its own and built
+     * when first loaded. A level whose default threshold is measured from it is built with the ladder, as is every level
+     * in a `vite build` warmup.
+     *
+     * What the levels load is freed when the last Lod holding them is disposed (see `LodLevel.hold`), which spends them:
+     * a Lod made from them later throws, so call loadAsync again. Levels no Lod ever holds are never freed: they are
+     * yours until a Lod holds them.
+     */
+    loadAsync(request: LodRequest): Promise<LodLevel[]>;
+    /** The source's shape from its entry, else measured from the source and saved. */
+    private shape;
+    /**
+     * A deferred level's bytes from its entry, else built from `spare`, the ladder's source, or from a source of its own:
+     * the source level's carries onLevel effects. Disposes `spare` either way.
+     */
+    private levelBytes;
+    /**
+     * Build level `index` from `loaded`, and save it to `entry`, read before, when what it was built from can be validated
+     * later: what loading the source read, and what this build loads besides.
+     */
+    private persist;
+    /** The renderer this loader bakes with, made at its first bake. */
+    private bakeRenderer;
+    /**
+     * Free the renderer this loader made for its bakes; a bake under way fails. Levels it loaded stay as they are, and a
+     * later bake makes a new renderer.
+     */
+    dispose(): void;
+    /** Save `bytes` to `entry`, read before, when what they were built from can be validated later; warn once otherwise. */
+    private save;
+    /** Builds of `url` are served without saving from now on, after one warning naming why; a build warmup fails instead. */
+    private warnUncached;
+    /** The ladder's source, with what loading it read. */
+    private loadSource;
+    private loadAsset;
+}

package/dist/loader/index.js

@@ -0,0 +1,284 @@
+import { Box3, Group, Loader, LoadingManager, Vector3 } from "three/webgpu";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { MissingDependencyError } from "vitecache";
+import { at } from "../at.js";
+import { createBakeRenderer } from "../bake.js";
+import { disposeRejected, disposeTree } from "../dispose.js";
+import { framePixels } from "../impostor/impostor.js";
+import { resolveThresholds } from "../levels/index.js";
+import { meshoptDecoder } from "../meshopt.js";
+import { isMesh, isObject3D, rejectSkinned } from "../three.js";
+import { buildLevel } from "./build.js";
+import { LodLoadContext } from "./context.js";
+import { AssetDependencies, bundledModules } from "./dependencies.js";
+import { decodeLevel, encodeLevel, encodeShape, placedBox, readLevel, readShape, shapeOf } from "./level.js";
+import { auxiliary, cached, derived, levelEntry, normalize, shapeEntry, warmup } from "./request.js";
+import { assetPath, isLocal } from "./url.js";
+// The loader: it describes a ladder of levels from a source, builds each level when first loaded and caches it.
+/**
+ * Loads asset URLs through manager handlers, else with a GLTFLoader of its own, which decodes meshopt only: register
+ * a GLTFLoader configured with Draco or KTX2 decoders for models compressed with them, and a GLTSLoader for .glts
+ * sources.
+ *
+ * Impostor and interior bakes draw with a renderer of the loader's own, made at its first bake: `dispose` frees it.
+ */
+export class LodLoader extends Loader {
+    cacheOptions;
+    gltf;
+    /**
+     * The renderer this loader bakes with, made at its first bake. Its own, not the app's: a canvas the size of a bake
+     * frame would draw that frame over the whole target (see `bakeImpostor`).
+     */
+    renderer;
+    /** URLs whose builds this loader serves without saving, once it has warned why. */
+    uncached = new Set();
+    constructor(manager, cacheOptions) {
+        super(manager);
+        this.cacheOptions = cacheOptions;
+    }
+    load(request, onLoad, _onProgress, onError) {
+        this.loadAsync(request).then(onLoad, onError ?? ((error) => console.error(error)));
+    }
+    /**
+     * Describes the ladder from the cache, else from its source, which the first level loaded then takes. Empty levels
+     * load with it, as does the source when it is the only drawable; other levels load when a camera needs them,
+     * including a coarse stand-in while its first detail arrives, and each derived level is cached on its own and built
+     * when first loaded. A level whose default threshold is measured from it is built with the ladder, as is every level
+     * in a `vite build` warmup.
+     *
+     * What the levels load is freed when the last Lod holding them is disposed (see `LodLevel.hold`), which spends them:
+     * a Lod made from them later throws, so call loadAsync again. Levels no Lod ever holds are never freed: they are
+     * yours until a Lod holds them.
+     */
+    async loadAsync(request) {
+        const input = normalize(request, this.path);
+        const { url, levels: requests } = input;
+        // Only the inputs: what each build or the shape is saved with is captured by its own loads.
+        const dependencies = new AssetDependencies(input.urls, this.manager);
+        const context = new LodLoadContext(() => this.loadSource(url), input.onLevel);
+        this.manager.itemStart(url);
+        try {
+            // vitecache resolves only same-origin paths to project files, so other sources build uncached.
+            const modules = dependencies.requested.every(isLocal) ? await bundledModules(input.urls, this.manager) : undefined;
+            const ladder = { ...input, modules };
+            // A simplified or baked level's default threshold is measured from its deviation, so it is built with the ladder.
+            const eager = requests.flatMap((level, index) => level.type !== "empty" && (warmup || (level.type !== "impostor" && level.maxPixels === undefined)) ? [index + 1] : []);
+            const reads = await Promise.all(eager.map(async (index) => ({ index, ...(await cached(levelEntry(ladder, index, dependencies, this.cacheOptions))) })));
+            // Only what measures a default threshold: bytes no camera asked for are not held.
+            const measured = new Map();
+            for (const { index, entry, bytes } of reads) {
+                const level = bytes ?? (await this.persist(ladder, index, await context.source(), entry));
+                if (!bytes)
+                    context.setBuilt(index, level);
+                measured.set(index, readLevel(level).level);
+            }
+            const shape = await this.shape(ladder, dependencies, () => context.source());
+            const box = placedBox(shape);
+            if (box.isEmpty())
+                throw new Error("LodLoader: the source has no visible geometry to measure");
+            const thresholds = resolveThresholds([
+                {},
+                ...requests.map((level, position) => ({
+                    // An impostor's default is its frame's even when a warmup bakes it, as it is without one.
+                    maxPixels: level.maxPixels ?? (level.type === "impostor" ? framePixels(level.resolution) : undefined),
+                    measured: level.type === "impostor" ? undefined : measured.get(position + 1),
+                })),
+            ], shape.box.getSize(new Vector3()).length(), "LodLoader");
+            const { hold } = context;
+            // Every load runs once however often it is asked for: every Lod made from the levels and the levels reading the
+            // source's materials share one object. The source's starts synchronously, so it takes the spare before a coarser
+            // level demanded in the same tick.
+            const loadSource = once(async () => context.arrive((context.take() ?? (await this.loadSource(url))).source, 0, { materials: true }));
+            const materials = async () => {
+                const { object } = at(levels, 0);
+                return materialsOf(object ?? (await loadSource()));
+            };
+            const deferred = [
+                { load: loadSource, maxPixels: Infinity, box, hold },
+                ...requests.map((level, position) => {
+                    const index = position + 1;
+                    const maxPixels = at(thresholds, index);
+                    if (level.type === "empty")
+                        return { load: once(async () => context.arrive(new Group(), index, { materials: true })), maxPixels, box: new Box3(), hold };
+                    const load = once(async () => {
+                        const bytes = context.takeBuilt(index) ?? (await this.levelBytes(ladder, index, context.take()));
+                        const object = await decodeLevel(level.type, readLevel(bytes), materials, level.type === "impostor" ? level.draw : undefined);
+                        // A simplified level draws with the source level's materials, which that level frees.
+                        return context.arrive(object, index, { materials: level.type !== "simplify" });
+                    });
+                    return { load, maxPixels, box: box.clone(), hold };
+                }),
+            ];
+            const levels = await preload(deferred);
+            return levels;
+        }
+        catch (error) {
+            context.fail();
+            this.manager.itemError(url);
+            throw error;
+        }
+        finally {
+            this.manager.itemEnd(url);
+        }
+    }
+    /** The source's shape from its entry, else measured from the source and saved. */
+    async shape(ladder, dependencies, loadSource) {
+        const { entry, bytes } = await cached(shapeEntry(ladder, dependencies, this.cacheOptions));
+        if (bytes)
+            return readShape(bytes);
+        const { source, dependencies: read } = await loadSource();
+        const shape = shapeOf(source);
+        await this.save(ladder.url, entry, encodeShape(shape), read);
+        return shape;
+    }
+    /**
+     * A deferred level's bytes from its entry, else built from `spare`, the ladder's source, or from a source of its own:
+     * the source level's carries onLevel effects. Disposes `spare` either way.
+     */
+    async levelBytes(ladder, index, spare) {
+        const { entry, bytes } = await cached(levelEntry(ladder, index, new AssetDependencies(ladder.urls, this.manager), this.cacheOptions));
+        if (bytes) {
+            if (spare)
+                disposeTree(spare.source);
+            return bytes;
+        }
+        const loaded = spare ?? (await this.loadSource(ladder.url));
+        try {
+            return await this.persist(ladder, index, loaded, entry);
+        }
+        finally {
+            disposeTree(loaded.source);
+        }
+    }
+    /**
+     * Build level `index` from `loaded`, and save it to `entry`, read before, when what it was built from can be validated
+     * later: what loading the source read, and what this build loads besides.
+     */
+    async persist(ladder, index, { source, dependencies: read }, entry) {
+        const { urls } = ladder;
+        const request = derived(ladder.levels, index);
+        const dependencies = new AssetDependencies(urls, this.manager).include(read);
+        const load = (name) => {
+            const asset = urls[auxiliary(index, name)];
+            return asset === undefined ? undefined : this.loadAsset(asset, dependencies);
+        };
+        let low, interior, built;
+        try {
+            rejectSkinned(source, "LodLoader");
+            low = await load("low");
+            interior = await load("interior");
+            built = await buildLevel(source, request, { low, interior }, () => this.bakeRenderer());
+            const bytes = await encodeLevel(built, request.type, shapeOf(source), materialsOf(source));
+            await this.save(ladder.url, entry, bytes, dependencies);
+            return bytes;
+        }
+        finally {
+            for (const object of [interior, low])
+                if (object)
+                    disposeTree(object);
+            // A simplified level draws with the source's materials, which are freed with the source.
+            if (built)
+                disposeTree(built, { materials: request.type !== "simplify" });
+        }
+    }
+    /** The renderer this loader bakes with, made at its first bake. */
+    bakeRenderer() {
+        this.renderer ??= createBakeRenderer();
+        return this.renderer;
+    }
+    /**
+     * Free the renderer this loader made for its bakes; a bake under way fails. Levels it loaded stay as they are, and a
+     * later bake makes a new renderer.
+     */
+    dispose() {
+        const renderer = this.renderer;
+        this.renderer = undefined;
+        // A renderer that failed to initialise failed the bake that made it.
+        void renderer?.then((made) => made.dispose(), () => { });
+    }
+    /** Save `bytes` to `entry`, read before, when what they were built from can be validated later; warn once otherwise. */
+    async save(url, entry, bytes, dependencies) {
+        if (!entry)
+            return this.warnUncached(url, "it is not a same-origin path");
+        // Read now: GLTS sources go on reporting what they observe while levels are built.
+        const saved = dependencies.saved();
+        if ("reason" in saved)
+            return this.warnUncached(url, saved.reason);
+        if (this.uncached.has(url))
+            return;
+        try {
+            await entry.save(bytes, { dependencies: saved.dependencies });
+        }
+        catch (error) {
+            // A dependency without a backing file, such as a middleware URL or a package the app does not install, cannot be validated.
+            if (!(error instanceof MissingDependencyError))
+                throw error;
+            this.warnUncached(url, error.message);
+        }
+    }
+    /** Builds of `url` are served without saving from now on, after one warning naming why; a build warmup fails instead. */
+    warnUncached(url, reason) {
+        if (warmup)
+            throw new Error(`LodLoader: cannot precompute "${url}": ${reason}`);
+        if (this.uncached.has(url))
+            return;
+        this.uncached.add(url);
+        console.warn(`LodLoader: "${url}" is not cached by this loader: ${reason}`);
+    }
+    /** The ladder's source, with what loading it read. */
+    async loadSource(url) {
+        const dependencies = new AssetDependencies({ source: url }, this.manager);
+        return { source: await this.loadAsset(url, dependencies), dependencies };
+    }
+    async loadAsset(url, dependencies) {
+        const { path, extension } = assetPath(url);
+        const handler = this.manager.getHandler(path);
+        if (!handler && extension === "glts")
+            throw new Error(`LodLoader: cannot load "${url}": register a GLTSLoader for .glts on the loading manager`);
+        let result;
+        if (handler)
+            result = await handler.loadAsync(url);
+        else {
+            this.gltf ??= new GLTFLoader(this.manager).setMeshoptDecoder(meshoptDecoder());
+            const decoder = this.gltf.setCrossOrigin(this.crossOrigin).setWithCredentials(this.withCredentials).setRequestHeader(this.requestHeader);
+            result = await decoder.loadAsync(url);
+        }
+        const object = objectOf(result, url);
+        try {
+            dependencies.capture(url, object, result);
+            return object;
+        }
+        catch (error) {
+            disposeRejected(object);
+            throw error;
+        }
+    }
+}
+/** `load`, run once however often it is called: every call shares its promise. */
+function once(load) {
+    let started;
+    return () => (started ??= load());
+}
+function materialsOf(object) {
+    const materials = [];
+    object.traverse((node) => {
+        if (isMesh(node))
+            for (const material of [node.material].flat())
+                materials.push(material);
+    });
+    return materials;
+}
+/** Loads what every camera draws before it picks a level: the empty levels, and the source if it is the only drawable. */
+async function preload(levels) {
+    const drawable = levels.filter((level) => !level.box.isEmpty());
+    return Promise.all(levels.map(async (level) => level.box.isEmpty() || drawable.length === 1 ? { object: await level.load(), maxPixels: level.maxPixels, hold: level.hold } : level));
+}
+function objectOf(result, url) {
+    if (isObject3D(result))
+        return result;
+    const scene = typeof result === "object" && result !== null ? Reflect.get(result, "scene") : undefined;
+    if (isObject3D(scene))
+        return scene;
+    throw new Error(`LodLoader: the handler for "${url}" did not load an Object3D or a glTF`);
+}
+//# sourceMappingURL=index.js.map

package/dist/loader/index.js.map

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

package/dist/loader/level.d.ts

@@ -0,0 +1,41 @@
+import { Box3, Matrix4, type Material, type Object3D } from "three/webgpu";
+import { type ImpostorMeshOptions } from "../impostor/mesh/index.js";
+import type { LodLevelRequest } from "./request.js";
+/** A level the loader builds from the source and caches. */
+export type Derived = Exclude<LodLevelRequest, {
+    type: "empty";
+}>;
+type Kind = Derived["type"];
+/**
+ * The source's full-detail bounds in its own space and its placement. Every drawable level declares these bounds,
+ * so a ladder is described before its finer levels are built; each derived level must fit inside them.
+ */
+export interface Shape {
+    box: Box3;
+    matrix: Matrix4;
+}
+export declare function shapeOf(source: Object3D): Shape;
+/** `shape` on its own, as its cache entry holds it. */
+export declare const encodeShape: (shape: Shape) => Uint8Array;
+export declare const readShape: (bytes: Uint8Array) => Shape;
+/** The bounds every drawable level declares, in the space of the Lod that holds it. */
+export declare const placedBox: ({ box, matrix }: Shape) => Box3;
+interface Metadata {
+    name: string;
+    deviation?: number;
+    texels?: number;
+    matrix: Matrix4;
+    matrixAutoUpdate: boolean;
+    castShadow: boolean;
+    receiveShadow: boolean;
+}
+export interface Entry {
+    shape: Shape;
+    level: Metadata;
+    payload: Uint8Array;
+}
+export declare function encodeLevel(object: Object3D, kind: Kind, shape: Shape, materials: readonly Material[]): Promise<Uint8Array>;
+/** Decode a level placed as it was built; `materials` are the source's, which a simplified level draws with. */
+export declare function decodeLevel(kind: Kind, { level, payload }: Entry, materials: () => Promise<Material[]>, draw: ImpostorMeshOptions | undefined): Promise<Object3D>;
+export declare function readLevel(bytes: Uint8Array): Entry;
+export {};

package/dist/loader/level.js

@@ -0,0 +1,140 @@
+import { Box3, Matrix4 } from "three/webgpu";
+import { decodeBakedMeshAsync, encodeBakedMeshAsync } from "../baked/codec.js";
+import { boundingBox } from "../source/detail.js";
+import { decodeImpostorAsync, encodeImpostorAsync } from "../impostor/codec.js";
+import { ImpostorMesh } from "../impostor/mesh/index.js";
+import { measure, recordDeviation } from "../levels/index.js";
+import { isImpostorMesh, isMesh } from "../three.js";
+import { decodeMeshAsync, encodeMeshAsync } from "../codec/mesh.js";
+export function shapeOf(source) {
+    if (source.matrixAutoUpdate)
+        source.updateMatrix();
+    return { box: boundingBox(source), matrix: source.matrix.clone() };
+}
+/** `shape` on its own, as its cache entry holds it. */
+export const encodeShape = (shape) => new TextEncoder().encode(JSON.stringify(shapeFields(shape)));
+export const readShape = (bytes) => parseShape(object(JSON.parse(new TextDecoder().decode(bytes))));
+const shapeFields = ({ box, matrix }) => ({ box: [...box.min.toArray(), ...box.max.toArray()], placement: matrix.toArray() });
+function parseShape(meta) {
+    const box = new Box3().setFromArray(numbers(meta.box, 6));
+    if (box.isEmpty())
+        fail("empty source box");
+    return { box, matrix: new Matrix4().fromArray(numbers(meta.placement, 16)) };
+}
+/** The bounds every drawable level declares, in the space of the Lod that holds it. */
+export const placedBox = ({ box, matrix }) => box.clone().applyMatrix4(matrix);
+const MAGIC = 0x33444f4c;
+export async function encodeLevel(object, kind, shape, materials) {
+    if (object.matrixAutoUpdate)
+        object.updateMatrix();
+    const box = boundingBox(object).applyMatrix4(object.matrix);
+    if (box.isEmpty())
+        throw new Error(`LodLoader: the ${kind} level draws nothing`);
+    const bounds = placedBox(shape);
+    // Rounding in welds and bakes may move a vertex by a hair.
+    if (!bounds
+        .clone()
+        .expandByScalar(bounds.getSize(box.min.clone()).length() * 1e-4)
+        .containsBox(box))
+        throw new Error(`LodLoader: the ${kind} level extends beyond the source's bounds; derived shapes, such as a low shell, must stay inside the source`);
+    const payload = await encodePayload(object, kind, materials);
+    const header = new TextEncoder().encode(JSON.stringify({
+        ...shapeFields(shape),
+        name: object.name,
+        ...measure(object),
+        matrix: object.matrix.toArray(),
+        matrixAutoUpdate: object.matrixAutoUpdate,
+        castShadow: object.castShadow,
+        receiveShadow: object.receiveShadow,
+    }));
+    const bytes = new Uint8Array(8 + header.length + payload.length);
+    const data = new DataView(bytes.buffer);
+    data.setUint32(0, MAGIC, true);
+    data.setUint32(4, header.length, true);
+    bytes.set(header, 8);
+    bytes.set(payload, 8 + header.length);
+    return bytes;
+}
+async function encodePayload(object, kind, materials) {
+    switch (kind) {
+        case "simplify":
+            return encodeMeshAsync(object, materials);
+        case "baked":
+            if (!isMesh(object))
+                throw new Error("LodLoader: baked level is not a mesh");
+            return encodeBakedMeshAsync(object);
+        case "impostor":
+            if (!isImpostorMesh(object))
+                throw new Error("LodLoader: impostor level is not an ImpostorMesh");
+            return encodeImpostorAsync(object.impostor);
+    }
+}
+/** Decode a level placed as it was built; `materials` are the source's, which a simplified level draws with. */
+export async function decodeLevel(kind, { level, payload }, materials, draw) {
+    const object = kind === "simplify"
+        ? await decodeMeshAsync(payload, await materials())
+        : kind === "baked"
+            ? await decodeBakedMeshAsync(payload)
+            : new ImpostorMesh(await decodeImpostorAsync(payload), 1, draw);
+    object.name = level.name;
+    level.matrix.decompose(object.position, object.quaternion, object.scale);
+    object.matrix.copy(level.matrix);
+    object.matrixAutoUpdate = level.matrixAutoUpdate;
+    object.castShadow = level.castShadow;
+    object.receiveShadow = level.receiveShadow;
+    if (level.deviation !== undefined)
+        recordDeviation(object, level.deviation);
+    return object;
+}
+export function readLevel(bytes) {
+    if (bytes.length < 8)
+        fail("missing header");
+    const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const length = data.getUint32(4, true);
+    if (data.getUint32(0, true) !== MAGIC || length > bytes.length - 8)
+        fail("invalid header");
+    const meta = object(JSON.parse(new TextDecoder().decode(bytes.subarray(8, 8 + length))));
+    if (typeof meta.name !== "string" ||
+        typeof meta.castShadow !== "boolean" ||
+        typeof meta.receiveShadow !== "boolean" ||
+        typeof meta.matrixAutoUpdate !== "boolean")
+        fail("invalid level settings");
+    const deviation = meta.deviation === undefined ? undefined : finite(meta.deviation);
+    if (deviation !== undefined && deviation < 0)
+        fail("negative deviation");
+    const texels = meta.texels === undefined ? undefined : finite(meta.texels);
+    if (texels !== undefined && texels <= 0)
+        fail("invalid texels");
+    return {
+        shape: parseShape(meta),
+        level: {
+            name: meta.name,
+            deviation,
+            texels,
+            matrix: new Matrix4().fromArray(numbers(meta.matrix, 16)),
+            matrixAutoUpdate: meta.matrixAutoUpdate,
+            castShadow: meta.castShadow,
+            receiveShadow: meta.receiveShadow,
+        },
+        payload: bytes.subarray(8 + length),
+    };
+}
+function object(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("expected metadata object");
+    return Object.fromEntries(Object.entries(value));
+}
+function finite(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail("expected finite number");
+    return value;
+}
+function numbers(value, count) {
+    if (!Array.isArray(value) || value.length !== count)
+        fail(`expected ${count} numbers`);
+    return value.map(finite);
+}
+function fail(reason) {
+    throw new Error(`LodLoader: invalid cache (${reason})`);
+}
+//# sourceMappingURL=level.js.map

package/dist/loader/level.js.map

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

package/dist/loader/request.d.ts

@@ -0,0 +1,87 @@
+import type { Object3D } from "three/webgpu";
+import type { CacheEntry } from "vitecache";
+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 LodCacheOptions } from "./cache.js";
+import type { Derived } from "./level.js";
+import type { AssetDependencies } from "./dependencies.js";
+/**
+ * Whether this runs in a production server-side build (`import.meta.env.PROD` and `SSR`), which precomputes assets
+ * into the deployed cache: every level is built and saved, and a level that cannot be saved fails the build.
+ */
+export declare const warmup: boolean;
+/**
+ * Levels derived from the source, finest first. Each derived level is built and persisted when it first loads; a
+ * simplified or baked level without `maxPixels` is built with the ladder, since its default threshold is measured from
+ * its deviation, and so is every level in a `vite build` warmup. 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[];
+    /**
+     * Apply runtime effects when a level arrives, before draws compile. Does not change baked content or bounds.
+     * `index` is the returned ladder's: 0 is the source, and `levels[i]` arrives as `i + 1`. Set `castShadow` and
+     * `shadowSide` here: a level compiles its draws, shadow maps' included, before it arrives, so a shadow setting
+     * changed later compiles mid-frame.
+     */
+    onLevel?: (object: Object3D, index: number) => void | Promise<void>;
+};
+/** A normalized request, with the digests of its bundled modules when its levels are cacheable. */
+export type Ladder = ReturnType<typeof normalize> & {
+    modules: Record<string, string> | undefined;
+};
+/** `request` with its URLs resolved against `path`, and every asset URL it builds from named as a dependency. */
+export declare function normalize(request: LodRequest, path: string): {
+    url: string;
+    levels: readonly LodLevelRequest[];
+    urls: Record<string, string>;
+    /**
+     * Apply runtime effects when a level arrives, before draws compile. Does not change baked content or bounds.
+     * `index` is the returned ladder's: 0 is the source, and `levels[i]` arrives as `i + 1`. Set `castShadow` and
+     * `shadowSide` here: a level compiles its draws, shadow maps' included, before it arrives, so a shadow setting
+     * changed later compiles mid-frame.
+     */
+    onLevel?: (object: Object3D, index: number) => void | Promise<void>;
+};
+/** The request of ladder level `index`, which must be a derived level. */
+export declare function derived(levels: readonly LodLevelRequest[], index: number): Derived;
+/** The dependency name of the low or interior asset of the baked level at ladder index `level`. */
+export declare const auxiliary: (level: number, name: "low" | "interior") => string;
+/** Derived level `index`'s cache entry, keyed by the inputs it is built from; undefined when the ladder is not cacheable. */
+export declare function levelEntry(ladder: Ladder, index: number, dependencies: AssetDependencies, options?: LodCacheOptions): CacheEntry | undefined;
+/** The cache entry of the source's shape, which describes the ladder before any level is built. */
+export declare function shapeEntry(ladder: Ladder, dependencies: AssetDependencies, options?: LodCacheOptions): CacheEntry | undefined;
+/** `entry` and the bytes it holds, read: undefined when it holds none. */
+export declare function cached(entry: CacheEntry | undefined): Promise<{
+    entry: CacheEntry | undefined;
+    bytes: Uint8Array | undefined;
+}>;