@drawcall/lod 0.2.0 → 0.3.0

package/dist/levels/fade.d.ts

@@ -0,0 +1,69 @@
+import { type Camera, Color, type IndirectStorageBufferAttribute, Matrix4, StorageBufferAttribute, StorageInstancedBufferAttribute, type Node, type NodeBuilder, type Object3D } from "three/webgpu";
+/**
+ * For one camera, the instances an InstancedLod's level meshes draw: per slot, the instance and its signed fade, and
+ * where the camera's indirect draws of them lie, `DRAW_BYTES` apart in the order of the InstancedLod's meshes.
+ */
+export interface InstanceSlots {
+    /** the index of the instance each slot draws */
+    readonly indices: StorageBufferAttribute;
+    /** its signed fade */
+    readonly fades: StorageBufferAttribute;
+    /** Where the camera's indirect draws of the InstancedLod's meshes start (see rows.ts). */
+    readonly args: {
+        readonly offset: number;
+        readonly attribute: IndirectStorageBufferAttribute;
+    };
+}
+/** What an InstancedLod's level meshes draw their instances from: every pool index's matrix, and its colour (RGB and a pad). */
+export interface DrawnInstances {
+    matrices: StorageInstancedBufferAttribute;
+    readonly colors: StorageInstancedBufferAttribute;
+}
+/** How a mesh of a level is drawn, which says where its fade and shadow size come from. */
+export type FadeSource = {
+    kind: "object";
+    /** the signed fade */
+    fade: number;
+    /** the whole object's bounding diameter, world units */
+    diameter: number;
+    /** debug tint, white when off */
+    tint: Color;
+} | {
+    kind: "instances";
+    /** per camera, the instance and signed fade of each slot; null for none (an ImpostorMesh of its own, drawing every instance) */
+    slots: ((camera: Camera) => InstanceSlots) | null;
+    /** one instance's bounding radius in its own space */
+    radius: number;
+    tint: Color;
+    /**
+     * For a plain mesh of an InstancedLod's level: the instances it draws, and `space`, where its geometry's space
+     * sits in the source's (InstancedLod draws template geometry moved into the instance's space). An ImpostorMesh
+     * carries its own instances.
+     */
+    level?: {
+        readonly instances: DrawnInstances;
+        readonly space: Matrix4;
+    };
+};
+/** Draw `mesh` as `source` says: its materials read it while it renders. */
+export declare const setFadeSource: (mesh: Object3D, source: FadeSource) => void;
+export declare const fadeSourceOf: (mesh: Object3D) => FadeSource | undefined;
+/** This draw's debug tint (see `Lod.debug`). */
+export declare const tint: import("three/webgpu").UniformNode<"color", Color>;
+/** Interleaved gradient noise over the pixels of the target being drawn. */
+export declare const dither: (pixel: Node<"vec2">) => Node<"float">;
+/** Where `object`'s geometry space sits in its source's: moved for an InstancedLod's plain level mesh (see `FadeSource`). */
+export declare const spaceOf: (object: Object3D | null) => Matrix4 | null;
+/** This draw's instance matrix when its matrices live in storage, else null. */
+export declare function instanceMatrixOf(object: Object3D): Node<"mat4"> | null;
+/** The colour of a draw whose instances have none: given one from the start, a draw's shader stays the same once they do. */
+export declare const white: StorageInstancedBufferAttribute;
+export declare const instanceColor: import("three/webgpu").VaryingNode<"vec3">;
+/** Apply the level's shared instance bindings before its own deformation, as Three does for InstancedMesh. */
+export declare function placeInstances(builder: NodeBuilder): void;
+/** This draw's signed fade. */
+export declare const fade: import("three/src/nodes/TSL.js").FnNode<[], Node<"float">>;
+/** Whether this pixel is this draw's, by its fade: false on the other level's pixels. */
+export declare const keepsPixel: import("three/src/nodes/TSL.js").FnNode<[], Node<"bool">>;
+/** `position` in a shadow map render, or nothing (a point) when the draw is too small to cast. */
+export declare const castPosition: (position: Node<"vec3">) => Node<"vec3">;

package/dist/levels/fade.js

@@ -0,0 +1,150 @@
+import { Color, Matrix4, StorageBufferAttribute, StorageInstancedBufferAttribute, } from "three/webgpu";
+import { Fn, NodeUpdateType, cameraProjectionMatrix, dot, float, fract, instanceIndex, modelWorldMatrix, normalLocal, positionLocal, transformNormal, varyingProperty, screenCoordinate, screenSize, select, storage, uniform, uniformGroup, varying, vec2, vec3, } from "three/tsl";
+import { isImpostorMesh, isInstancedMesh, isStorageInstanced } from "../three.js";
+import { column, isOrthographic, maxScale } from "../tsl.js";
+/**
+ * Per level mesh, where its fade comes from: a side table, as three's Object3D has no typed place for a package's state
+ * (userData is the app's).
+ */
+const sources = new WeakMap();
+/** Draw `mesh` as `source` says: its materials read it while it renders. */
+export const setFadeSource = (mesh, source) => void sources.set(mesh, source);
+export const fadeSourceOf = (mesh) => sources.get(mesh);
+const WHITE = new Color(1, 1, 1);
+const of = (object) => (object ? sources.get(object) : undefined);
+// Per-object values, shared by every material: each draw reads its own.
+const objectFade = uniform(0).onObjectUpdate(({ object }) => {
+    const draw = of(object);
+    return draw?.kind === "object" ? draw.fade : 0;
+});
+// A mesh no level draws is never too small to cast.
+const objectDiameter = uniform(0).onObjectUpdate(({ object }) => {
+    const draw = of(object);
+    return draw?.kind === "object" ? draw.diameter : 3.4e38;
+});
+const instanceRadius = uniform(0).onObjectUpdate(({ object }) => {
+    const draw = of(object);
+    return draw?.kind === "instances" ? draw.radius : 0;
+});
+/** This draw's debug tint (see `Lod.debug`). */
+export const tint = uniform(new Color(1, 1, 1)).onObjectUpdate(({ object }) => of(object)?.tint ?? WHITE);
+/** Interleaved gradient noise over the pixels of the target being drawn. */
+export const dither = (pixel) => fract(float(52.9829189).mul(fract(dot(pixel, vec2(0.06711056, 0.00583715)))));
+/** The level mesh `object` is, when it is an InstancedLod's plain one. */
+function levelOf(object) {
+    const draw = of(object);
+    return draw?.kind === "instances" ? (draw.level ?? null) : null;
+}
+/** The instances where `object` reads its matrices and colours from storage: its own, or its InstancedLod's; else null. */
+function instancesOf(object) {
+    if (isImpostorMesh(object))
+        return { matrices: object.instanceMatrix, colors: object.instanceColor };
+    const level = levelOf(object);
+    if (level)
+        return level.instances;
+    return isInstancedMesh(object) && isStorageInstanced(object.instanceMatrix) ? { matrices: object.instanceMatrix, colors: null } : null;
+}
+/** Where `object`'s geometry space sits in its source's: moved for an InstancedLod's plain level mesh (see `FadeSource`). */
+export const spaceOf = (object) => levelOf(object)?.space ?? null;
+// The draw buffers below are replaced per object, so they stay out of three's texture-keyed
+// binding caches: each render object has its own bindings of this group, while its shader
+// reads the shared nodes.
+const instanceGroup = uniformGroup("lodInstances", 2, NodeUpdateType.OBJECT);
+const identity = new StorageInstancedBufferAttribute(new Float32Array(new Matrix4().elements), 16);
+const matrices = storage(identity, "mat4", 0)
+    .setName("lodInstanceMatrices")
+    .setGroup(instanceGroup)
+    .toReadOnly()
+    .onObjectUpdate(({ object }) => {
+    const instances = object && instancesOf(object);
+    if (!instances)
+        throw new Error("Lod: instance draw has no matrices");
+    return instances.matrices;
+});
+/** `object`'s slots as `camera` draws it, when it draws slots. */
+function slotsOf(object, camera) {
+    const draw = of(object);
+    return draw?.kind === "instances" && draw.slots && camera ? draw.slots(camera) : null;
+}
+const zero = new StorageBufferAttribute(new Float32Array(1), 1);
+const fades = storage(zero, "float", 0)
+    .setName("lodInstanceFades")
+    .setGroup(instanceGroup)
+    .toReadOnly()
+    .onObjectUpdate(({ object, camera }) => slotsOf(object, camera)?.fades ?? zero);
+const none = new StorageBufferAttribute(new Uint32Array(1), 1);
+const indices = storage(none, "uint", 0)
+    .setName("lodInstanceSlots")
+    .setGroup(instanceGroup)
+    .toReadOnly()
+    .onObjectUpdate(({ object, camera }) => slotsOf(object, camera)?.indices ?? none);
+/** 1 when the draw's instances are slots the instance pass for each camera fills, else 0. */
+const slotted = uniform(0, "uint").onObjectUpdate(({ object }) => {
+    const draw = of(object);
+    return Number(draw?.kind === "instances" && draw.slots !== null);
+});
+const instanceCaster = uniform(false).onObjectUpdate(({ object }) => of(object)?.kind === "instances");
+/** The instance this draw's instance index stands for: the one in its slot, or itself. */
+const instance = Fn(() => slotted.equal(1).select(indices.element(instanceIndex), instanceIndex));
+/** This draw's instance matrix when its matrices live in storage, else null. */
+export function instanceMatrixOf(object) {
+    return instancesOf(object) ? matrices.element(instance()) : null;
+}
+/** The colour of a draw whose instances have none: given one from the start, a draw's shader stays the same once they do. */
+export const white = new StorageInstancedBufferAttribute(new Float32Array([1, 1, 1, 1]), 4);
+const colors = storage(white, "vec4", 0)
+    .setName("lodInstanceColors")
+    .setGroup(instanceGroup)
+    .toReadOnly()
+    .onObjectUpdate(({ object }) => (object && instancesOf(object)?.colors) || white);
+const colorIndex = uniform(0, "uint").onObjectUpdate(({ object }) => {
+    const colors = object && instancesOf(object)?.colors;
+    return Number(!!colors && colors !== white);
+});
+export const instanceColor = varying(colors.element(instance().mul(colorIndex)).xyz).setInterpolation("flat");
+/** Apply the level's shared instance bindings before its own deformation, as Three does for InstancedMesh. */
+export function placeInstances(builder) {
+    if (!levelOf(builder.object))
+        return;
+    const matrix = matrices.element(instance());
+    positionLocal.assign(matrix.mul(positionLocal).xyz);
+    if (builder.geometry.hasAttribute("normal"))
+        normalLocal.assign(transformNormal(normalLocal, matrix));
+    varyingProperty("vec3", "vInstanceColor").assign(instanceColor);
+}
+/** This draw's signed fade. */
+export const fade = Fn((builder) => {
+    if (isImpostorMesh(builder.object))
+        return varying(fades.element(instanceIndex.mul(slotted)))
+            .setInterpolation("flat")
+            .add(objectFade);
+    const draw = sources.get(builder.object);
+    if (draw?.kind !== "instances" || !draw.slots)
+        return objectFade;
+    // Constant across the primitive: keep compute-written slots out of fragment bindings.
+    return varying(fades.element(instanceIndex)).setInterpolation("flat");
+});
+/** Whether this pixel is this draw's, by its fade: false on the other level's pixels. */
+export const keepsPixel = Fn(() => {
+    const f = fade();
+    const d = dither(screenCoordinate.xy);
+    return select(f.greaterThanEqual(0), d.greaterThanEqual(f), d.lessThan(f.negate()));
+});
+/**
+ * Whether this draw is too small for the shadow map being drawn: narrower than a texel
+ * of an orthographic (directional light's) map, it would cover a texel centre only by
+ * chance, flickering as it or the map moves. Only valid in a shadow map render.
+ */
+const tooSmallToCast = Fn((builder) => {
+    const object = builder.object;
+    const card = isImpostorMesh(object);
+    const instance = card || sources.get(object)?.kind === "instances" ? instanceMatrixOf(object) : null;
+    const instanced = instance ? maxScale(modelWorldMatrix.mul(instance)).mul(instanceRadius).mul(2) : objectDiameter;
+    const diameter = card ? select(instanceCaster, instanced, objectDiameter) : instanced;
+    // projection[1][1] is 2 × zoom / (top - bottom)
+    const texel = float(2).div(column(cameraProjectionMatrix, 1).y.mul(screenSize.y));
+    return isOrthographic(cameraProjectionMatrix).and(diameter.lessThan(texel));
+});
+/** `position` in a shadow map render, or nothing (a point) when the draw is too small to cast. */
+export const castPosition = (position) => select(tooSmallToCast(), vec3(0), position);
+//# sourceMappingURL=fade.js.map

package/dist/levels/fade.js.map

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

package/dist/levels/index.d.ts

@@ -0,0 +1,99 @@
+import { Color, type Box3, type Object3D } from "three/webgpu";
+import type { d } from "typegpu";
+import { type DrawLevels } from "./draw.js";
+import { LevelHeights } from "./load.js";
+/**
+ * One level of a Lod or InstancedLod: an object given, or one `load` makes when a camera first needs it, which `box`
+ * bounds meanwhile. `lod.levels` holds the same shape, with `object` the Lod's own copy, once there is one. For an
+ * InstancedLod, `object` is the template its level meshes are made from, never in the scene.
+ *
+ * Objects you give or load are yours to dispose, as a three Mesh never disposes its geometry or material; a Lod frees
+ * only what it made of them. LodLoader's are freed when the last Lod holding them is disposed (see `hold`).
+ */
+export interface LodLevel {
+    /** The level's object: yours to dispose. */
+    object?: Object3D;
+    /**
+     * Makes the level's object, yours to dispose. A load shared across several Lods runs once per Lod; memoize it to
+     * share one object.
+     */
+    load?: () => Promise<Object3D>;
+    /** A deferred level's bounds in the Lod's space; empty for a level that draws nothing. */
+    box?: Box3;
+    /**
+     * Largest on-screen height, in CSS pixels × Lod.quality, at which this level draws: Infinity for level 0, the finest;
+     * every later one at most (1 - Lod.fade) of its finer neighbour's, which leaves room for the fades. A deferred level
+     * needs one. A given level without one gets one measured from its surface deviation (see `simplify`, `bakeMesh`) or
+     * its impostor's texels, else half its finer neighbour's (512 for level 1), raised to leave room for the fades;
+     * `lod.levels` holds what it got.
+     */
+    maxPixels?: number;
+    /**
+     * Holds what the level's object comes from while a Lod draws it: every Lod made from the level, a copy or clone
+     * included, calls each distinct `hold` once as it is made, and the release it answers once it is disposed. LodLoader's
+     * levels free what they loaded when the last release is called, which spends them: a Lod made from them later throws.
+     * LodLoader's levels no Lod ever holds are never freed: they are yours until a Lod holds them.
+     */
+    hold?: () => () => void;
+}
+/** A level with its threshold, as `lod.levels` holds it. */
+export type ThresholdedLevel = LodLevel & {
+    maxPixels: number;
+};
+/** Throws unless `levels` can be drawn: each given or deferred with a finite box, and thresholds as `LodLevel` says. */
+export declare function checkLevels(levels: readonly ThresholdedLevel[], who: string): void;
+/**
+ * `inputs` as `lod.levels` holds them: each object cloned, each threshold given or measured (see `LodLevel.maxPixels`)
+ * for a source `diameter` across. Throws unless they can be drawn.
+ */
+export declare function levelsFrom(inputs: readonly LodLevel[], diameter: number, who: string): ThresholdedLevel[];
+/** The bits of the levels that draw nothing: an empty object or box. */
+export declare function emptyLevels(levels: readonly LodLevel[]): number;
+/** Level `index`'s debug tint, or white. */
+export declare const tintOf: (index: number, debug: boolean) => Color;
+/** Surface deviation from the source, in the source's units. */
+export declare const recordDeviation: (level: Object3D, deviation: number) => void;
+export declare const deviationOf: (level: Object3D) => number | undefined;
+/** What a level's default threshold is measured from: surface deviation, else impostor texels. */
+interface Measured {
+    deviation?: number;
+    texels?: number;
+}
+export declare function measure(object: Object3D): Measured;
+/** A level to find a threshold for: its own maxPixels, else what it measured. */
+interface Measurable {
+    maxPixels?: number;
+    measured?: Measured;
+}
+/**
+ * Thresholds for `levels` of an object `diameter` across: each level's own maxPixels, else its measured surface
+ * deviation's or impostor texels' height, else half the previous one (512 for level 1), raised where needed to leave
+ * room for the fades. Throws if the result does not (see `checkLevels`).
+ */
+export declare function resolveThresholds(levels: readonly Measurable[], diameter: number, who: string): number[];
+/**
+ * A Lod's or InstancedLod's levels as levelsToDraw reads them (see `drawLevels`), checked and encoded again only when a
+ * threshold or the forced level has changed. What it returns is shared: read it, do not hold on to it.
+ */
+export declare class EncodedLevels {
+    private readonly levels;
+    /** The bits of the levels that draw nothing. */
+    private readonly empty;
+    private readonly who;
+    private thresholds;
+    private forced;
+    /** For cameras that fade levels and for those that do not. */
+    private encoded;
+    constructor(levels: readonly ThresholdedLevel[], 
+    /** The bits of the levels that draw nothing. */
+    empty: number, who: string);
+    /** The levels with `forced` the forced level, for a camera that `fades` levels or not. Throws unless they can be drawn. */
+    get(forced: number | null, fades: boolean): d.Infer<typeof DrawLevels>;
+    /**
+     * What `levels`, as `get` gave them, draw at each height with the levels of `loaded` loaded, all by default (see
+     * LevelHeights): worked out the first time it is asked, and anew with the levels.
+     */
+    heights(levels: d.Infer<typeof DrawLevels>, loaded?: number): LevelHeights;
+    private encode;
+}
+export {};

package/dist/levels/index.js

@@ -0,0 +1,155 @@
+import { Color } from "three/webgpu";
+import { at } from "../at.js";
+import { levelBox } from "./bounds.js";
+import { texelPixels } from "../impostor/impostor.js";
+import { isImpostorMesh } from "../three.js";
+import { FADE, MAX_LEVELS, drawLevels } from "./draw.js";
+import { LevelHeights } from "./load.js";
+/** Throws unless `levels` can be drawn: each given or deferred with a finite box, and thresholds as `LodLevel` says. */
+export function checkLevels(levels, who) {
+    if (levels.length > MAX_LEVELS)
+        throw new Error(`${who}: ${levels.length} levels, but at most ${MAX_LEVELS}`);
+    levels.forEach(({ object, load, box }, i) => {
+        if (!object && !load)
+            throw new Error(`${who}: level ${i} has neither an object nor a load`);
+        if (!object && !box)
+            throw new Error(`${who}: deferred level ${i} needs a box`);
+        if (box && !box.isEmpty() && ![...box.min.toArray(), ...box.max.toArray()].every(Number.isFinite))
+            throw new Error(`${who}: level ${i}'s box must be finite`);
+    });
+    checkThresholds(levels.map(({ maxPixels }) => maxPixels), who);
+}
+/** Throws unless `thresholds` are maxPixels as `LodLevel` says. */
+function checkThresholds(thresholds, who) {
+    thresholds.forEach((maxPixels, i) => {
+        if (i === 0 && maxPixels !== Infinity)
+            throw new Error(`${who}: level 0, the source, is used at any height: its maxPixels is Infinity, not ${maxPixels}`);
+        if (!(maxPixels > 0))
+            throw new Error(`${who}: maxPixels must be > 0, got ${maxPixels}`);
+        const finer = thresholds[i - 1];
+        if (finer !== undefined && maxPixels > finer * (1 - FADE))
+            throw new Error(`${who}: level ${i} has maxPixels ${maxPixels}, but at most ${finer * (1 - FADE)} (${1 - FADE} × level ${i - 1}'s ${finer}) leaves room for the fades`);
+    });
+}
+/**
+ * `inputs` as `lod.levels` holds them: each object cloned, each threshold given or measured (see `LodLevel.maxPixels`)
+ * for a source `diameter` across. Throws unless they can be drawn.
+ */
+export function levelsFrom(inputs, diameter, who) {
+    const thresholds = resolveThresholds(inputs.map(({ object, maxPixels }) => ({ maxPixels, measured: object && maxPixels === undefined ? measure(object) : undefined })), diameter, who);
+    const levels = inputs.map((input, i) => ({ ...input, object: input.object?.clone(), maxPixels: at(thresholds, i) }));
+    checkLevels(levels, who);
+    return levels;
+}
+/** The bits of the levels that draw nothing: an empty object or box. */
+export function emptyLevels(levels) {
+    return levels.reduce((bits, level, i) => (levelBox(level).isEmpty() ? bits | (1 << i) : bits), 0);
+}
+/** Debug tints by level index, see `Lod.debug`. */
+const TINTS = [0xff6060, 0x60ff60, 0x6080ff, 0xffd040, 0xff60ff, 0x60ffff].map((hex) => new Color(hex));
+const WHITE = new Color(1, 1, 1);
+/** Level `index`'s debug tint, or white. */
+export const tintOf = (index, debug) => (debug ? at(TINTS, index % TINTS.length) : WHITE);
+/**
+ * Per simplified or baked object, its deviation: a side table, as three's objects have no typed place for it (userData
+ * is the app's).
+ */
+const deviations = new WeakMap();
+/** Surface deviation from the source, in the source's units. */
+export const recordDeviation = (level, deviation) => void deviations.set(level, deviation);
+export const deviationOf = (level) => deviations.get(level);
+export function measure(object) {
+    return { deviation: deviationOf(object), texels: isImpostorMesh(object) ? texelPixels(object.impostor) : undefined };
+}
+/**
+ * Thresholds for `levels` of an object `diameter` across: each level's own maxPixels, else its measured surface
+ * deviation's or impostor texels' height, else half the previous one (512 for level 1), raised where needed to leave
+ * room for the fades. Throws if the result does not (see `checkLevels`).
+ */
+export function resolveThresholds(levels, diameter, who) {
+    let finer = 1024;
+    const defaults = levels.map(({ maxPixels, measured }, index) => {
+        if (index === 0)
+            return Infinity;
+        const base = !measured
+            ? maxPixels
+            : measured.deviation !== undefined
+                ? diameter / Math.max(measured.deviation, diameter * 1e-4)
+                : (measured.texels ?? finer / 2);
+        if (base === undefined)
+            throw new Error(`${who}: deferred level ${index} needs maxPixels`);
+        finer = base;
+        return base;
+    });
+    const thresholds = levels.map(() => Infinity);
+    let next = 0;
+    for (let i = levels.length - 1; i > 0; i--) {
+        const value = levels[i]?.maxPixels ?? Math.max(at(defaults, i), 2 * next);
+        thresholds[i] = value;
+        next = value;
+    }
+    thresholds[0] = levels[0]?.maxPixels ?? Infinity;
+    checkThresholds(thresholds, who);
+    return thresholds;
+}
+/**
+ * A Lod's or InstancedLod's levels as levelsToDraw reads them (see `drawLevels`), checked and encoded again only when a
+ * threshold or the forced level has changed. What it returns is shared: read it, do not hold on to it.
+ */
+export class EncodedLevels {
+    levels;
+    empty;
+    who;
+    thresholds = [];
+    forced = null;
+    /** For cameras that fade levels and for those that do not. */
+    encoded;
+    constructor(levels, 
+    /** The bits of the levels that draw nothing. */
+    empty, who) {
+        this.levels = levels;
+        this.empty = empty;
+        this.who = who;
+        this.encoded = this.encode(null);
+    }
+    /** The levels with `forced` the forced level, for a camera that `fades` levels or not. Throws unless they can be drawn. */
+    get(forced, fades) {
+        let changed = forced !== this.forced;
+        for (let i = 0; i < this.levels.length && !changed; i++)
+            changed = this.levels[i]?.maxPixels !== this.thresholds[i];
+        if (changed)
+            this.encoded = this.encode(forced);
+        return (fades ? this.encoded.fading : this.encoded.still).levels;
+    }
+    /**
+     * What `levels`, as `get` gave them, draw at each height with the levels of `loaded` loaded, all by default (see
+     * LevelHeights): worked out the first time it is asked, and anew with the levels.
+     */
+    heights(levels, loaded = (1 << levels.count) - 1) {
+        const { fading, still } = this.encoded;
+        const encoding = levels === fading.levels ? fading : levels === still.levels ? still : null;
+        if (!encoding)
+            throw new Error(`${this.who}: heights of levels it did not encode, or no longer does`);
+        if (loaded === (1 << levels.count) - 1)
+            return (encoding.heights ??= new LevelHeights(levels));
+        const { loading } = encoding;
+        const found = loading.find((heights) => heights.loaded === loaded);
+        if (found)
+            return found;
+        const made = new LevelHeights(levels, loaded);
+        loading.unshift(made);
+        loading.length = Math.min(loading.length, 2);
+        return made;
+    }
+    encode(forced) {
+        const { levels, empty, who } = this;
+        checkLevels(levels, who);
+        if (forced !== null && !levels[forced])
+            throw new Error(`${who}: forceLevel ${forced} is not a level`);
+        this.thresholds = levels.map(({ maxPixels }) => maxPixels);
+        this.forced = forced;
+        const encoding = (fades) => ({ levels: drawLevels(levels, empty, forced, fades), heights: null, loading: [] });
+        return { fading: encoding(true), still: encoding(false) };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/levels/index.js.map

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

package/dist/levels/item.d.ts

@@ -0,0 +1,38 @@
+import { type LoadingManager, type Object3D, type Renderer } from "three/webgpu";
+/**
+ * A Lod's item on a LoadingManager, held while it loads: the manager hears of it in a microtask, once the render that
+ * changed it has returned, so what an app's callback does, such as throw or render, happens outside three's render.
+ */
+export declare class LoadingItem {
+    private readonly lod;
+    /** The item's name: the kind of Lod and its uuid. */
+    private readonly name;
+    private readonly renderer;
+    /** The LoadingManager given; else the nearest Lod above's, else three's default (see `manager`). */
+    given: LoadingManager | undefined;
+    /** The LoadingManager the held item started on, which it ends on. */
+    private holding;
+    /** Whether the Lod was updated since the item's last look at its renderer, the renders then, and whether a look is due. */
+    private updated;
+    private renders;
+    private looking;
+    constructor(lod: Object3D, 
+    /** The item's name: the kind of Lod and its uuid. */
+    name: string, renderer: Renderer);
+    /** Where the item goes. */
+    get manager(): LoadingManager;
+    /** A render updated the Lod: the next look at the renderer's renders does not end the item. */
+    touch(): void;
+    /** Hold the item if `held`, else end it; while it is held, look at the renderer's renders (see `look`). */
+    sync(held: boolean): void;
+    /** Report a failure on the LoadingManager the item is held on, and end the item. */
+    fail(): void;
+    private hold;
+    /**
+     * While the item is held, look a frame's time apart at the renderer's renders: a Lod its renderer rendered around for
+     * a frame without updating it (hidden, on a layer no camera tests, out of the scene) ends its item; its next update
+     * starts it again. Renders of other scenes in a separate task can end it early, and the next update reopens it; a
+     * renderer that only compiles holds a hidden Lod's item.
+     */
+    private look;
+}

package/dist/levels/item.js

@@ -0,0 +1,97 @@
+import { DefaultLoadingManager } from "three/webgpu";
+import { hasLoadingManager } from "./renderer.js";
+/** How long a held item waits between looks at its renderer's renders (see `look`): a frame's time. */
+const LOOK_MS = 16;
+/**
+ * A Lod's item on a LoadingManager, held while it loads: the manager hears of it in a microtask, once the render that
+ * changed it has returned, so what an app's callback does, such as throw or render, happens outside three's render.
+ */
+export class LoadingItem {
+    lod;
+    name;
+    renderer;
+    /** The LoadingManager given; else the nearest Lod above's, else three's default (see `manager`). */
+    given;
+    /** The LoadingManager the held item started on, which it ends on. */
+    holding;
+    /** Whether the Lod was updated since the item's last look at its renderer, the renders then, and whether a look is due. */
+    updated = false;
+    renders = 0;
+    looking = false;
+    constructor(lod, 
+    /** The item's name: the kind of Lod and its uuid. */
+    name, renderer) {
+        this.lod = lod;
+        this.name = name;
+        this.renderer = renderer;
+    }
+    /** Where the item goes. */
+    get manager() {
+        if (this.given)
+            return this.given;
+        for (let node = this.lod.parent; node; node = node.parent)
+            if (hasLoadingManager(node))
+                return node.manager;
+        return DefaultLoadingManager;
+    }
+    /** A render updated the Lod: the next look at the renderer's renders does not end the item. */
+    touch() {
+        this.updated = true;
+    }
+    /** Hold the item if `held`, else end it; while it is held, look at the renderer's renders (see `look`). */
+    sync(held) {
+        this.hold(held);
+        if (!this.holding || this.looking)
+            return;
+        // The first look only counts the renders: those still to come in this render are not without an update.
+        this.updated = true;
+        this.look();
+    }
+    /** Report a failure on the LoadingManager the item is held on, and end the item. */
+    fail() {
+        const manager = this.holding;
+        const { name } = this;
+        if (manager)
+            queueMicrotask(() => manager.itemError(name));
+        this.hold(false);
+    }
+    hold(held) {
+        if (held === (this.holding !== undefined))
+            return;
+        const { name } = this;
+        if (held) {
+            const manager = (this.holding = this.manager);
+            queueMicrotask(() => manager.itemStart(name));
+            return;
+        }
+        const manager = this.holding;
+        this.holding = undefined;
+        if (manager)
+            queueMicrotask(() => manager.itemEnd(name));
+    }
+    /**
+     * While the item is held, look a frame's time apart at the renderer's renders: a Lod its renderer rendered around for
+     * a frame without updating it (hidden, on a layer no camera tests, out of the scene) ends its item; its next update
+     * starts it again. Renders of other scenes in a separate task can end it early, and the next update reopens it; a
+     * renderer that only compiles holds a hidden Lod's item.
+     */
+    look() {
+        const { renderer } = this;
+        this.looking = true;
+        const timer = setTimeout(() => {
+            this.looking = false;
+            if (!this.holding)
+                return;
+            const renders = renderer.info.render.calls;
+            if (renders !== this.renders && !this.updated)
+                return this.hold(false);
+            this.renders = renders;
+            this.updated = false;
+            this.look();
+        }, LOOK_MS);
+        // A held item must not hold Node.js open.
+        if (typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function")
+            timer.unref();
+    }
+}
+//# sourceMappingURL=item.js.map

package/dist/levels/item.js.map

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