@drawcall/lod 0.1.2 → 0.3.0

package/dist/instanced/index.js

@@ -1,573 +1,290 @@
-import { Box3, InstancedMesh, Matrix4, Object3D, Ray, Sphere, Vector3, } from "three/webgpu";
-import { measureLevels } from "../bounds.js";
-import { disposeTree } from "../dispose.js";
-import { drawOf, setDraw } from "../fade.js";
-import { placeInterior } from "../baked/interior/material.js";
-import { impostorInstances } from "../impostor/mesh/index.js";
-import { Level, cloneLevels, copyThresholds, estimate, fadeProgress, levelAt, tintLevels, validate } from "../levels.js";
+import { Box3, Object3D, Sphere } from "three/webgpu";
+import { at } from "../at.js";
+import { disposeCopies } from "../dispose.js";
+import { EncodedLevels, emptyLevels, levelsFrom } from "../levels/index.js";
+import { fadeSourceOf } from "../levels/fade.js";
+import { levelsToLoad } from "../levels/load.js";
+import { LodLevelLoadManager } from "../levels/manager.js";
 import { Lod } from "../lod.js";
-import { available, fallbacks, inView } from "../lazy.js";
-import { gpuRenderer, inShadowPass, isLazyImpostor, isImpostorMesh, isInstancedMesh, isLOD, isMesh, rejectSkinned, sameClass } from "../three.js";
-import { TYPICAL_HEIGHT, View, viewportHeight, watchViewport } from "../view.js";
-import { WIND_BOUNDS } from "../wind/hooks.js";
-import { copyWind, refreshWind } from "../wind/index.js";
-import { groupMaterial, indirect, placed, ranges } from "./meshes.js";
-import { Bounds, stretch } from "./bounds.js";
-import { Dirty } from "./dirty.js";
-import { ARGS_BYTES, Selection } from "./select.js";
-const IDENTITY = new Matrix4();
-const view = new View();
-const inverse = new Matrix4();
-const ray = new Ray();
-const sphere = new Sphere();
-const instance = new Matrix4();
-const world = new Matrix4();
-const box = new Box3();
-const hits = [];
+import { inShadowMap } from "../levels/renderer.js";
+import { sameClass } from "../three.js";
+import { WIND } from "../wind/hooks.js";
+import { copyWind } from "../wind/index.js";
+import { ChunkSet } from "./chunks.js";
+import { cullIn, emptyCull } from "./cull.js";
+import { MeshesByLevel } from "./levels.js";
+import { InstanceLists, frustumIn, listedOf } from "./lists.js";
+import { localCamera, shownBy, walk } from "./camera.js";
+import { drawMatrices } from "./meshes.js";
+import { raycastInstances } from "./raycast.js";
+import { InstanceShape } from "./shape.js";
+import { MAX_SURVIVOR_SCALE, instanceLevel } from "./measure.js";
+const DEFAULT_INSTANCES = 16384;
 /**
- * Selections due before the next draw of any InstancedLod: the first level mesh to draw
- * runs them all in one compute call (each call has a cost of its own: an encoder, a
- * pass, a submit). Each renderer runs those its own buffers are not current with.
- */
-const pending = new Set();
-/**
- * `count` copies of one object with levels of detail, each switched by its own height on
- * screen: `Lod` for instances. The GPU sorts the instances into levels once per view
- * (see select.ts) and every mesh of a level draws the instances it holds in one indirect
- * draw; an instance near a switch is in both neighbours and they split its pixels with
- * the dither. Thresholds, `forceLevel`, `Lod.quality`, `Lod.debug` and shadows work as
- * for `Lod`; nothing of an instance is drawn into a directional light's shadow map whose
- * texels are wider than it. Each level is culled by the crowd's bounds, tightened for
- * finer levels to the region near the camera where their instances can draw.
+ * Independently drawn copies of one object, sorted into indirect draws per camera on the GPU. Instances arrive and
+ * leave in chunks (see `addChunk`), from the CPU or written by the app's GPU passes; `cullDistance` thins them out with
+ * distance. Thresholds, fades, loading and global settings follow Lod: each instance draws what levelsToDraw gives for
+ * its height. 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). Instance matrices may scale arbitrarily; the InstancedLod's own transform and its
+ * parents should scale uniformly. Scale 0 draws nothing.
+ *
+ * Level templates are cloned, then their meshes are instanced; it sets each level mesh's `visible` per camera, so hide
+ * the InstancedLod itself, never its level meshes. Skinned meshes, InstancedMeshes (except ImpostorMesh)
+ * and nested Lods are unsupported. For external detail, leave level 0 empty and draw the instances that
+ * `chunk.getLevelAt` reports there.
  *
- * Instance matrices are model transforms of the object, as for an InstancedMesh; set
- * them with `setMatrixAt`, and instance colours with `setColorAt`. An instance at scale 0
- * draws nothing. Its own transform (and its parents') should scale uniformly; instances
- * may scale any way.
+ * Every level mesh's `geometry.boundingBox` and `boundingSphere` bound all its instances, not one, so
+ * `new Box3().setFromObject(lod)` bounds them once a level has loaded; with `precise` it walks a level's vertices once,
+ * at no instance, as it cannot see them. Measure one instance by a level's `object`, scaled by its matrix.
  *
- * Levels are templates, read when it is built: their meshes are drawn instanced, not
- * added to the scene. They cannot contain skinned meshes, InstancedMeshes (other than an
- * ImpostorMesh) or nested Lods. To build a hierarchy on top, leave level 0 empty (see
- * `Lod`) and draw the detail of the instances `levelOf` reports at level 0 yourself.
+ * Instances live in its LodGpu's pool, and every InstancedLod of a LodGpu sorts for a camera in one compute call.
+ * Requires WebGPU `indirect-first-instance`. 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 this InstancedLod from it with camera
+ * layers.
  */
 export class InstancedLod extends Object3D {
+    gpu;
     isLOD = true;
     isInstancedLod = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate = true;
-    /** Draw only this level for every instance, without fades. */
+    /** Draw only this level, without fades, once the coarsest level that draws something has loaded. */
     forceLevel = null;
-    levels;
-    count;
-    entries = [];
-    /** Per level, the meshes drawing it. */
-    meshes = [];
-    probes = [];
-    selection = null;
-    fallback = [];
-    installed = new Set();
+    /** The levels, each `object` the template its level meshes are made from, once there is one (never in the scene). */
+    levels = [];
+    /** Thins the instances out with distance from a camera, in every camera; null draws them at any distance. */
+    cullDistance = null;
+    /** The levels as they were given, which a copy is made from. */
+    inputs = [];
+    /** What it is made of for its levels and sizes, which a copy makes anew. */
+    built;
     disposed = false;
-    /** Instance matrices, 16 floats each: the selection uploads them from here. */
-    matrices;
-    /** Instance colours, 4 floats each, once `setColorAt` was called. */
-    colors = null;
-    /** Each instance's bounding sphere, centre and radius, in the InstancedLod's space. */
-    spheres;
-    /** Bounding sphere of the source in an instance's space. */
-    sphere = new Sphere();
-    /** Every placed level, kept separate from the source sphere used for LOD selection. */
-    envelope = new Box3();
-    rest = new Sphere();
-    /** Around every instance; each level may use tighter bounds. */
-    bounds = new Sphere();
-    /** Per level, what its meshes are culled by: `bounds`, or less where its instances must be near the camera. */
-    reaches = [];
-    /** Logical demand at the initial default viewport, separate from first-draw visibility. */
-    demand = [];
-    /** Source-radius padding for the shadow caster cutoff; culling pads every level separately. */
-    padding = 0;
-    matrixChanges;
-    colorChanges;
-    blocks;
-    last = { selected: false, eye: new Vector3(), scale: 0, ortho: false, fades: false, forced: null };
-    /** `levels[0]` is the source. Empty only as the target of `copy`. */
-    constructor(levels = [], count = 0) {
+    /** Around every instance, survivors grown: what every level mesh is culled and boxed by. */
+    bounds = { sphere: new Sphere(), box: new Box3() };
+    /** What `cullIn` writes cullDistance into, in this InstancedLod's space. */
+    cull = emptyCull();
+    /**
+     * `levels[0]` is the source. Empty only as the target of `copy`. It holds no instances until chunks are added. `gpu`
+     * is what it shares with every Lod drawing with its renderer.
+     */
+    constructor(levels, gpu, options = {}) {
         super();
-        if (!Number.isInteger(count) || count < 0)
-            throw new Error(`InstancedLod: count must be an integer >= 0, got ${count}`);
-        this.levels = this.entries;
-        this.count = count;
-        this.matrices = new Float32Array(count * 16);
-        this.spheres = new Float32Array(count * 4);
-        for (let i = 0; i < count; i++)
-            IDENTITY.toArray(this.matrices, i * 16);
-        this.matrixChanges = new Dirty(count);
-        this.colorChanges = new Dirty(count);
-        this.matrixChanges.all();
-        const draws = levels.length > 0 ? this.build(levels) : 0;
-        this.blocks = new Bounds(this.matrices, this.spheres, this.sphere, this.bounds, draws, this.rest);
-    }
-    build(objects, rebuilding = false) {
-        const [source] = objects;
-        if (!source)
-            throw new Error("InstancedLod: needs at least the source level");
-        if (isLazyImpostor(source))
-            throw new Error("InstancedLod: the source level must be eager");
-        for (const object of objects) {
-            if (isLazyImpostor(object)) {
-                object.materialize();
-            }
-            if (available(object))
-                this.installed.add(object);
-        }
-        this.fallback = fallbacks(objects);
-        for (const object of objects) {
-            rejectSkinned(object, "InstancedLod");
-            object.traverse((node) => {
-                if (isLOD(node))
-                    throw new Error("InstancedLod: levels cannot contain a Lod or InstancedLod; nest them with Lod");
-                if (isInstancedMesh(node) && !isImpostorMesh(node))
-                    throw new Error(`InstancedLod: levels cannot contain an InstancedMesh ("${node.name}")`);
-            });
-        }
-        const { own, placed } = measureLevels(objects, "InstancedLod");
-        this.sphere.copy(placed);
-        if (!rebuilding) {
-            objects.forEach((object, i) => this.entries.push(new Level(object, i, false, this.entries)));
-            estimate(this.entries, 2 * own.radius);
-        }
-        validate(this.entries);
-        // Every template mesh, split per material group: an indirect draw has one range.
-        const parts = objects.map((object, level) => {
-            // A template's own transform places it in the instance's space, as a Lod's child.
-            object.updateWorldMatrix(true, true);
-            const outside = object.parent ? object.parent.matrixWorld.clone().invert() : new Matrix4();
-            const found = [];
-            object.traverse((node) => {
-                if (!isMesh(node))
-                    return;
-                const placement = outside.clone().multiply(node.matrixWorld);
-                if (level === 0)
-                    this.probes.push({ mesh: node, placement });
-                ranges(node).forEach((range, group) => found.push({ template: node, placement, group, draw: { level, ...range } }));
-            });
-            return found;
-        });
-        const draws = parts.flat().map((part) => part.draw);
-        const selection = this.selection ??
-            new Selection(this.matrices, this.sphere, parts.map((found, i) => found.length > 0 || isLazyImpostor(at(objects, i))), draws, this.fallback);
-        if (this.selection)
-            selection.replace(draws, this.fallback);
-        this.selection = selection;
-        if (this.colors)
-            this.useColors(selection, this.colors);
-        let k = 0;
-        parts.forEach((found, i) => {
-            const level = at(this.entries, i);
-            this.reaches[i] ??= new Sphere();
-            this.demand[i] ??= new Sphere();
-            const previous = this.meshes[i];
-            if (previous?.length && previous.length !== found.length)
-                throw new Error("InstancedLod: an existing level's meshes changed");
-            this.meshes[i] = found.map((part, index) => {
-                const offset = k++ * ARGS_BYTES, mesh = previous?.[index];
-                if (!mesh)
-                    return this.instance(level, part.template, part.placement, part.group, offset, selection);
-                this.bind(mesh, level, selection, offset);
-                return mesh;
-            });
-        });
-        this.boundLevels();
-        if (!rebuilding)
-            for (const object of objects)
-                if (isLazyImpostor(object))
-                    object.retain();
-        return draws.length;
+        this.gpu = gpu;
+        // Each level's draws start at its list (see update.ts).
+        if (!gpu.renderer.hasFeature("indirect-first-instance"))
+            throw new Error("InstancedLod: needs the GPU feature indirect-first-instance, which this device lacks");
+        const maxInstanceCount = options.maxInstanceCount ?? DEFAULT_INSTANCES;
+        if (!Number.isInteger(maxInstanceCount) || maxInstanceCount < 1)
+            throw new RangeError(`InstancedLod: maxInstanceCount must be a positive integer, got ${maxInstanceCount}`);
+        this.built = this.init(levels, maxInstanceCount);
+        this.built.loads.item.given = options.manager;
     }
-    /** Install ready atlas templates atomically before selecting this view. */
-    refresh() {
-        if (this.installed.size === this.entries.length)
-            return;
-        let changed = false;
-        for (const { object } of this.entries) {
-            if (!isLazyImpostor(object) || this.installed.has(object))
-                continue;
-            object.materialize();
-            changed ||= available(object);
-        }
-        if (!changed)
-            return;
-        if (this.selection)
-            pending.delete(this.selection);
-        this.probes.length = 0;
-        this.envelope.makeEmpty();
-        const draws = this.build(this.entries.map((entry) => entry.object), true);
-        this.blocks = new Bounds(this.matrices, this.spheres, this.sphere, this.bounds, draws, this.rest);
-        this.matrixChanges.all();
-        this.measure();
-        refreshWind(this);
-        this.updateWorldMatrix(true, true);
-        this.dispatchEvent({ type: "levelschange" });
-    }
-    /** Bound what the level meshes draw, including template placement and impostor boxes. */
-    boundLevels() {
-        for (const meshes of this.meshes) {
-            for (const mesh of meshes) {
-                if (!isImpostorMesh(mesh))
-                    mesh.geometry.computeBoundingBox();
-                const bounds = mesh.geometry.boundingBox;
-                if (!bounds)
-                    throw new Error("InstancedLod: a level mesh has no geometry bounds");
-                box.copy(bounds);
-                if (isImpostorMesh(mesh))
-                    box.applyMatrix4(mesh.placement);
-                this.envelope.union(box);
-            }
-        }
-        this.rest.copy(this.sphere);
-        if (this.envelope.isEmpty())
-            return;
-        const { center } = this.rest;
-        const { min, max } = this.envelope;
-        this.rest.radius = Math.max(this.rest.radius, Math.hypot(Math.max(Math.abs(min.x - center.x), Math.abs(max.x - center.x)), Math.max(Math.abs(min.y - center.y), Math.abs(max.y - center.y)), Math.max(Math.abs(min.z - center.z), Math.abs(max.z - center.z))));
+    get pending() {
+        return this.built.loads.pending;
     }
-    /** Material group `group` of `template` drawn for every instance in `level`'s slots, from indirect draw arguments at byte `offset`. */
-    instance(level, template, placement, group, offset, selection) {
-        // An impostor card is placed in the shader; any other mesh draws its geometry moved
-        // into the instance's space, so the instance matrix is all it needs.
-        const mesh = isImpostorMesh(template)
-            ? impostorInstances(template, this.count, placement)
-            : new InstancedMesh(placed(template.geometry, placement), groupMaterial(template, group), this.count);
-        mesh.geometry = indirect(mesh.geometry, selection, offset);
-        this.bind(mesh, level, selection, offset);
-        if (!isImpostorMesh(template))
-            placeInterior(mesh, placement);
-        mesh.name = template.name;
-        mesh.castShadow = template.castShadow;
-        mesh.receiveShadow = template.receiveShadow;
-        this.reaches[level.index] ??= this.bounds.clone();
-        mesh.boundingSphere = this.reaches[level.index] ?? null;
-        const previous = mesh.onBeforeRender;
-        // Selected once per view, before the first level mesh draws: in the view, or in a
-        // shadow pass that comes first. The GPU runs it before anything drawn after it.
-        mesh.onBeforeRender = (renderer, scene, camera, geometry, material, group) => {
-            previous.call(mesh, renderer, scene, camera, geometry, material, group);
-            if (pending.size === 0)
-                return;
-            const gpu = gpuRenderer(renderer);
-            // Each level's draws start at its slots (see select.ts).
-            if (!gpu.hasFeature("indirect-first-instance"))
-                throw new Error("InstancedLod: needs the GPU feature indirect-first-instance, which this device lacks");
-            const passes = [...pending].flatMap((due) => due.take(gpu));
-            pending.clear();
-            if (passes.length > 0)
-                gpu.compute(passes);
-        };
-        watchViewport(mesh);
-        this.add(mesh);
-        return mesh;
+    get error() {
+        return this.built.loads.error;
     }
-    bind(mesh, level, selection, offset) {
-        mesh.geometry.setIndirect(selection.args, selection.argsOffset + offset);
-        mesh.instanceMatrix = selection.slots.matrices;
-        mesh.instanceColor = selection.slots.colors;
-        setDraw(mesh, { kind: "instances", fades: selection.slots.fades, radius: this.drawRadius, tint: level.tint });
+    /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
+    get manager() {
+        return this.built.loads.item.manager;
     }
-    setMatrixAt(index, matrix) {
-        this.check(index);
-        matrix.toArray(this.matrices, index * 16);
-        this.matrixChanges.add(index);
+    set manager(manager) {
+        this.built.loads.item.given = manager;
     }
-    getMatrixAt(index, matrix) {
-        this.check(index);
-        return matrix.fromArray(this.matrices, index * 16);
+    /** Its chunks, in the order they were added. */
+    get chunks() {
+        return this.built.chunks.keys();
     }
-    /** Tint instance `index` by `color`, as InstancedMesh.setColorAt does, in every level. */
-    setColorAt(index, color) {
-        this.check(index);
-        if (!this.colors) {
-            this.colors = new Float32Array(this.count * 4).fill(1);
-            if (this.selection)
-                this.useColors(this.selection, this.colors);
-        }
-        color.toArray(this.colors, index * 4);
-        this.colorChanges.add(index);
-    }
-    /** Instance `index`'s colour: white unless set. */
-    getColorAt(index, color) {
-        this.check(index);
-        return this.colors ? color.fromArray(this.colors, index * 4) : color.setRGB(1, 1, 1);
-    }
-    /** Carry `colors` with the instances from now on: every level's meshes draw them. */
-    useColors(selection, colors) {
-        selection.useColors(colors);
-        for (const mesh of this.meshes.flat()) {
-            mesh.instanceColor = selection.slots.colors;
-            // Instance colours change the shader.
-            for (const material of [mesh.material].flat())
-                material.needsUpdate = true;
-        }
-        this.colorChanges.all();
+    /** What this InstancedLod is made of for `inputs` and `maxInstanceCount`: its levels, their meshes and their loading. */
+    init(inputs, maxInstanceCount) {
+        const shape = new InstanceShape(inputs);
+        const { pool, renderer } = this.gpu;
+        const lists = new InstanceLists(this.gpu.sorter, listedOf(inputs), maxInstanceCount);
+        const chunks = new ChunkSet(pool, lists.row, this.bounds, () => shape.originReach, (chunk, index, camera) => this.levelAt(chunk, index, camera));
+        const drawn = { matrices: pool.matrices, colors: pool.colors };
+        const drawing = { shape, lists, drawn };
+        this.inputs = inputs;
+        if (inputs.length > 0)
+            this.levels.push(...levelsFrom(inputs, 2 * shape.ownRadius, "InstancedLod"));
+        const encoded = new EncodedLevels(this.levels, emptyLevels(inputs), "InstancedLod");
+        const drawFor = (renderer, camera) => this.built.loads.guard(() => {
+            if (renderer !== this.gpu.renderer)
+                throw new Error("InstancedLod: another renderer than its LodGpu's drew it");
+            lists.drawFor(camera);
+        });
+        const meshes = new MeshesByLevel(this, this.levels, drawing, this.bounds, drawFor);
+        const loads = new LodLevelLoadManager(this, this.gpu, `InstancedLod ${this.uuid}`, inputs, encoded.get(null, true), (level, loaded) => meshes.prepare(level, loaded), (level) => meshes.of(level), async () => {
+            const instances = await pool.status(renderer, chunks.slots());
+            if (instances !== null && instances > maxInstanceCount)
+                throw new Error(`InstancedLod: its chunks hold ${instances} instances, more than its lists hold: raise its maxInstanceCount (${maxInstanceCount})`);
+            return instances !== null;
+        });
+        return { maxInstanceCount, chunks, ...drawing, meshes, loads, encoded };
     }
     /**
-     * The finest level instance `index` drew in the last update, or null before the first
-     * (or at scale 0). Inside a fade the next coarser level draws too.
+     * Add `parameters`' instances as one chunk, from the CPU or the GPU (see `InstancedLodChunkParameters`). The next
+     * render that updates this InstancedLod copies them into its pages. Its item (see `LodOptions.manager`) stays held
+     * until the GPU shows every chunk copied; a chunk the pool lacks pages for draws the instances it got until it is
+     * removed, and is this InstancedLod's error (see `error`).
      */
-    levelOf(index) {
-        this.check(index);
-        const { last } = this;
-        if (!last.selected)
-            return null;
-        this.measure();
-        const offset = index * 4;
-        const r = at(this.spheres, offset + 3);
-        if (r === 0)
-            return null;
-        let height = 2 * r * last.scale;
-        if (!last.ortho) {
-            const x = this.spheres[offset];
-            const y = this.spheres[offset + 1];
-            const z = this.spheres[offset + 2];
-            if (x === undefined || y === undefined || z === undefined)
-                throw new Error(`InstancedLod: missing sphere ${index}`);
-            const dx = x - last.eye.x;
-            const dy = y - last.eye.y;
-            const dz = z - last.eye.z;
-            height /= Math.max(Math.sqrt(dx * dx + dy * dy + dz * dz), 1e-6);
-        }
-        const level = levelAt(this.entries, height, last.forced);
-        const selected = last.fades && fadeProgress(this.entries, level, height) > 0 ? level.index - 1 : level.index;
-        return this.fallback[selected] ?? selected;
+    addChunk(parameters) {
+        if (this.disposed)
+            throw new Error("InstancedLod: it was disposed");
+        if (this.levels.length === 0)
+            throw new Error("InstancedLod: give it levels before chunks");
+        const chunk = this.built.chunks.add(parameters);
+        this.measureBounds();
+        this.built.loads.chunksChanged();
+        return chunk;
     }
-    check(index) {
-        if (!Number.isInteger(index) || index < 0 || index >= this.count)
-            throw new Error(`InstancedLod: index ${index} is not in 0..${this.count - 1}`);
+    /** Remove `chunk`'s instances; its pages return to the pool in the next render. */
+    removeChunk(chunk) {
+        this.built.chunks.remove(chunk);
+        this.measureBounds();
+        this.built.loads.chunksChanged();
     }
-    /** Source radius padded for the level shaders' shadow caster cutoff. */
-    get drawRadius() {
-        return this.sphere.radius * (1 + this.padding);
+    /** Bound every chunk's instances, survivors grown. */
+    measureBounds() {
+        this.built.chunks.bound(this.cullDistance?.scaleSurvivors ? MAX_SURVIVOR_SCALE : 1);
     }
-    [WIND_BOUNDS](padding, slope, baseY) {
-        this.padding = padding / this.sphere.radius;
-        for (const mesh of this.meshes.flat()) {
-            const draw = drawOf(mesh);
-            if (draw?.kind === "instances")
-                draw.radius = this.drawRadius;
+    [WIND](padding, slope, baseY) {
+        if (this.built.loads.started)
+            throw new Error("InstancedLod: apply wind before the first render");
+        this.built.shape.wind(padding, slope, baseY);
+        for (const mesh of this.built.meshes.all()) {
+            const source = fadeSourceOf(mesh);
+            if (source?.kind === "instances")
+                source.radius = this.built.shape.fadeRadius;
         }
-        // The wind shape comes from the source, but taller/offset levels can sway farther.
-        const reach = slope * Math.max(Math.abs(this.envelope.min.y - baseY), Math.abs(this.envelope.max.y - baseY));
-        this.blocks.pad(this.rest.radius > 0 ? reach / this.rest.radius : 0);
-        this.blocks.refit();
+        this.measureBounds();
     }
-    /** Measure only changed matrices; matrix and colour uploads have separate ranges. */
-    measure() {
-        if (this.matrixChanges.empty && this.colorChanges.empty)
-            return;
-        this.measureChanges();
-    }
-    // Keep the closure-bearing work out of the unchanged path: V8 can allocate a
-    // lexical context on entry even when a function returns before its callbacks.
-    measureChanges() {
-        const { selection } = this;
-        const matricesChanged = !this.matrixChanges.empty;
-        this.matrixChanges.drain((start, end) => {
-            this.blocks.measure(start, end);
-            if (selection)
-                upload(selection.matrices, start, end);
-        });
-        this.colorChanges.drain((start, end) => {
-            if (selection?.colors)
-                upload(selection.colors, start, end);
-        });
-        selection?.changed();
-        if (matricesChanged)
-            this.blocks.refit();
-    }
-    /** Sort the instances into levels for `camera`; three's renderer calls this itself while `autoUpdate`. */
+    /** 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) {
-        if (this.disposed || inShadowPass(this))
+        if (this.disposed || this.levels.length === 0)
             return;
-        this.refresh();
-        const { entries, selection } = this;
-        if (!selection)
+        // A shadow map draws nothing of an InstancedLod whose levels cast nothing; one not loaded yet may.
+        const shadow = inShadowMap(this);
+        if (shadow && !this.levels.some(({ object }, i) => !object || this.built.meshes.of(i).some((mesh) => mesh.castShadow)))
             return;
-        validate(entries);
-        if (this.forceLevel !== null && !entries[this.forceLevel])
-            throw new Error(`Lod: forceLevel ${this.forceLevel} is not a level`);
-        this.measure();
-        const height = viewportHeight(camera);
-        view.begin(camera, height ?? TYPICAL_HEIGHT, this.forceLevel);
-        tintLevels(entries, Lod.debug);
-        const worldScale = this.matrixWorld.getMaxScaleOnAxis();
-        const scale = view.scale * Lod.quality * (view.ortho ? worldScale : 1);
-        const { last } = this;
-        last.eye.copy(view.eye).applyMatrix4(inverse.copy(this.matrixWorld).invert());
-        Object.assign(last, { selected: true, scale, ortho: view.ortho, fades: view.fades, forced: this.forceLevel });
-        const stable = this.blocks.select(entries, last, this.reaches, height !== null, this.matrixWorld);
-        if (this.installed.size < entries.length) {
-            let demand = this.reaches;
-            if (height === null) {
-                // Every mesh must get a first chance to report its viewport. That conservative
-                // visibility is not a reason to load every lazy tier: use the actual default
-                // selection, including forced and empty levels, for initial atlas demand.
-                demand = this.demand;
-                this.blocks.select(entries, last, demand, true, this.matrixWorld);
-            }
-            for (let i = this.reaches.length - 1; i >= 0; i--) {
-                const reach = at(this.reaches, i), object = at(entries, i).object;
-                if (isLazyImpostor(object) && object.status === "idle" && inView(camera, this.matrixWorld, at(demand, i)))
-                    object.request();
-                const target = this.fallback[i] ?? i;
-                if (target !== i) {
-                    at(this.reaches, target).union(reach);
-                    reach.makeEmpty();
-                }
-            }
-        }
-        selection.aim(last.eye, scale, view.ortho, view.fades, this.forceLevel, entries, stable);
-        // Selected only when something may draw: an InstancedLod with every level hidden
-        // keeps its last selection.
-        if (this.showLevels())
-            pending.add(selection);
+        this.built.loads.guard(() => this.sort(camera, shadow));
     }
-    /** Only levels whose conservative bounds contain a possible selected instance. */
-    showLevels() {
-        let shown = false;
-        this.meshes.forEach((meshes, level) => {
-            const visible = !this.reaches[level]?.isEmpty();
-            for (const mesh of meshes)
-                mesh.visible = visible;
-            shown ||= visible && meshes.length > 0;
+    /** Sort for `camera`, a shadow map's when `shadow`. */
+    sort(camera, shadow) {
+        const { loads, shape, lists, chunks, drawn, encoded, meshes } = this.built;
+        const { levels, eye, scale, ortho } = this.localCamera(camera, shadow);
+        if (chunks.refresh())
+            this.measureBounds();
+        // The pages change before any sorts with them.
+        const { pool } = this.gpu;
+        pool.prepare(this.gpu.renderer);
+        const survivors = this.cullDistance?.scaleSurvivors ?? false;
+        if (survivors !== (drawn.matrices !== pool.matrices))
+            this.scaleSurvivors(survivors);
+        const cull = cullIn(this.cullDistance, this.matrixWorld, this.cull);
+        const local = { levels, eye, scale, ortho, cull };
+        const found = lists.of(camera);
+        // Outside the camera's frustum, nothing draws: a shadow map, which loads nothing by heights, walks no chunk then.
+        const seen = frustumIn(found, camera, this.matrixWorld).intersectsSphere(this.bounds.sphere);
+        if (!shadow || seen)
+            walk(found, local, this.built);
+        // A shadow map draws from the levels its scene's cameras loaded.
+        loads.request(camera, shadow ? levelsToLoad([], encoded.heights(levels)) : found.wanted, shadow);
+        meshes.tint(Lod.debug);
+        lists.prune(camera, (other) => loads.requests.rendering(other));
+        const { loaded, before, progress } = loads;
+        // Three projects this InstancedLod's children for the camera after this update.
+        const shown = seen ? shownBy(found, levels, encoded, { loaded, before, progress }) : 0;
+        lists.sort(camera, {
+            ...local,
+            loaded,
+            before,
+            progress,
+            bounds: this.bounds.sphere,
+            box: this.bounds.box,
+            source: shape.source,
+            reach: shape.reach,
+            onlyLevel: cull === null ? found.onlyLevel : 0,
+            chunks: chunks.version,
         });
-        return shown;
+        // Nothing draws from the camera's indirect draws before a sort writes them, which a level mesh's draw runs first.
+        meshes.show(found.written ? shown : 0);
+    }
+    /** `camera` in this InstancedLod's space (see `localCamera`). */
+    localCamera(camera, shadow) {
+        const { loads, encoded } = this.built;
+        return localCamera(camera, loads.heightOf(camera, shadow), this.matrixWorld, encoded, this.forceLevel);
+    }
+    /** Draw survivors' scaled matrices, or the pool's again. */
+    scaleSurvivors(survivors) {
+        const { pool, sorter } = this.gpu;
+        this.built.drawn.matrices = survivors ? sorter.scaledMatrices : pool.matrices;
+        drawMatrices(this.built.meshes.all(), this.built.drawn);
+        this.measureBounds();
+    }
+    /** The level instance `index` of `chunk` draws most of its pixels with for `camera` (see `InstancedLodChunk.getLevelAt`). */
+    levelAt(chunk, index, camera) {
+        const cull = cullIn(this.cullDistance, this.matrixWorld, this.cull);
+        const local = this.localCamera(camera, inShadowMap(this));
+        return instanceLevel(chunk.instanceMatrix.array, (chunk.start + index) * 16, cull, local, this.built.shape.source, this.built.loads.loaded);
     }
     /**
-     * Hits every instance's source level, with `instanceId` set; `object` is this
-     * InstancedLod. Meshes of the source on layers the raycaster does not test are skipped.
+     * Hits every instance of its CPU chunks on the source level, with `instanceId` and `chunk` set (see
+     * `InstancedLodIntersection`); `object` is this InstancedLod. A GPU chunk's instances the CPU cannot see, and meshes
+     * of the source on layers the raycaster does not test, are not hit.
      */
     raycast(raycaster, intersects) {
-        ray.copy(raycaster.ray).applyMatrix4(inverse.copy(this.matrixWorld).invert());
-        for (let i = 0; i < this.count; i++) {
-            instance.fromArray(this.matrices, i * 16);
-            sphere.center.copy(this.rest.center).applyMatrix4(instance);
-            sphere.radius = this.rest.radius * stretch(instance);
-            if (!ray.intersectsSphere(sphere))
-                continue;
-            for (const { mesh, placement } of this.probes) {
-                if (!mesh.layers.test(raycaster.layers))
-                    continue;
-                // The template's own raycast, as if it stood where this instance does.
-                const own = mesh.matrixWorld;
-                mesh.matrixWorld = world.multiplyMatrices(this.matrixWorld, instance).multiply(placement);
-                hits.length = 0;
-                mesh.raycast(raycaster, hits);
-                mesh.matrixWorld = own;
-                for (const hit of hits)
-                    intersects.push(Object.assign(hit, { object: this, instanceId: i }));
-            }
-        }
+        raycastInstances(this, { parts: this.built.meshes.source, rest: this.built.shape.rest }, this.built.chunks.cpu(), raycaster, intersects);
         return false;
     }
     /**
-     * Copies `source`'s levels, instances and settings into this empty InstancedLod of the
-     * same count (it throws otherwise); the copy shares geometry and textures with `source`.
+     * Copies `source`'s levels, CPU chunks and settings into this empty InstancedLod, one without levels or chunks (it
+     * throws otherwise); the copy shares geometry and textures with `source`, and its chunks hold copies of the source's
+     * attributes. A GPU chunk cannot be copied: its instances live on the GPU.
      */
     copy(source) {
-        if (this.entries.length > 0 || this.count !== source.count)
-            throw new Error("InstancedLod.copy: copy into an empty InstancedLod of the same count");
+        if (this.levels.length > 0 || this.built.chunks.size > 0)
+            throw new Error("InstancedLod.copy: copy into an InstancedLod without levels or chunks");
+        const chunks = source.built.chunks.copies();
+        const inputs = source.inputs.map((input, i) => ({ ...input, maxPixels: at(source.levels, i).maxPixels }));
         super.copy(source, false);
-        this.matrices.set(source.matrices);
-        this.colors = source.colors?.slice() ?? null;
-        this.matrixChanges.all();
-        if (this.colors)
-            this.colorChanges.all();
-        const draws = source.entries.length > 0 ? this.build(cloneLevels(source.entries)) : 0;
-        this.blocks = new Bounds(this.matrices, this.spheres, this.sphere, this.bounds, draws, this.rest);
-        copyThresholds(source.entries, this.entries);
+        this.built.chunks.dispose();
+        this.built.lists.dispose();
+        this.built = this.init(inputs, source.built.maxInstanceCount);
+        this.built.loads.item.given = source.built.loads.item.given;
         this.forceLevel = source.forceLevel;
         this.autoUpdate = source.autoUpdate;
+        this.cullDistance = source.cullDistance && { ...source.cullDistance };
         copyWind(source, this);
+        for (const chunk of chunks)
+            this.addChunk(chunk);
         return this;
     }
     clone() {
-        // three's clone builds `new this.constructor()`, which has no count.
-        const clone = new InstancedLod([], this.count).copy(this);
+        const clone = new InstancedLod([], this.gpu).copy(this);
         if (!sameClass(this, clone))
             throw new Error("InstancedLod.clone: a subclass must override clone");
         return clone;
     }
     /**
-     * Frees every level, the source included, and the instanced meshes. Clones share
-     * geometry and textures, so dispose only once no clone draws any more.
+     * Release its buffers and what it made of its levels, once nothing it prepares or compiles still uses them. Objects
+     * you give or load, chunk attributes among them, are yours to dispose; LodLoader's are freed when the last Lod
+     * holding them is disposed (see `LodLevel.hold`).
      */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.clearDraws();
-        for (const { object } of this.entries)
-            isLazyImpostor(object) ? object.release() : disposeTree(object);
-    }
-    clearDraws() {
-        // An ImpostorMesh frees its own material and geometry; the other meshes' faded
-        // materials go with the levels' originals.
-        for (const mesh of this.meshes.flat()) {
-            this.remove(mesh);
-            mesh.dispose();
-            if (!isImpostorMesh(mesh))
-                mesh.geometry.dispose();
-        }
-        if (this.selection)
-            pending.delete(this.selection);
-        this.selection?.dispose();
-        this.selection = null;
-        this.meshes.length = 0;
-    }
-}
-function at(values, i) {
-    const value = values[i];
-    if (value === undefined)
-        throw new Error(`InstancedLod: index ${i} out of range`);
-    return value;
-}
-/** Union pending uploads, including repeated edits while a crowd is not drawn. */
-function upload(attribute, start, end) {
-    start *= attribute.itemSize;
-    end *= attribute.itemSize;
-    const ranges = attribute.updateRanges;
-    let low = 0;
-    let high = ranges.length;
-    while (low < high) {
-        const middle = (low + high) >>> 1;
-        const range = at(ranges, middle);
-        if (range.start + range.count < start)
-            low = middle + 1;
-        else
-            high = middle;
-    }
-    const first = ranges[low];
-    if (!first || first.start > end) {
-        const range = { start, count: end - start };
-        if (low === ranges.length)
-            ranges.push(range);
-        else
-            ranges.splice(low, 0, range);
-    }
-    else {
-        end = Math.max(end, first.start + first.count);
-        first.start = Math.min(start, first.start);
-        let next = low + 1;
-        while (next < ranges.length) {
-            const range = at(ranges, next);
-            if (range.start > end)
-                break;
-            end = Math.max(end, range.start + range.count);
-            next++;
-        }
-        first.count = end - first.start;
-        if (next > low + 1)
-            ranges.splice(low + 1, next - low - 1);
+        super.dispose();
+        this.built.chunks.dispose();
+        this.built.loads.dispose(() => {
+            this.built.meshes.dispose();
+            this.built.lists.dispose();
+            for (const { object } of this.levels)
+                if (object)
+                    disposeCopies(object);
+        });
     }
-    attribute.needsUpdate = true;
 }
 //# sourceMappingURL=index.js.map