@drawcall/lod 0.3.0 → 0.4.0

package/dist/lod.js

@@ -1,37 +1,60 @@
-import { Object3D, Sphere } from "three/webgpu";
+import { Box3, Color, Float32BufferAttribute, InstancedBufferAttribute, InstancedBufferGeometry, Matrix4, Mesh, MeshBasicNodeMaterial, Object3D, Sphere, } from "three/webgpu";
 import { at } from "./at.js";
-import { measureLevels, prepareBounds } from "./levels/bounds.js";
 import { disposeCopies } from "./dispose.js";
-import { EncodedLevels, emptyLevels, levelsFrom, tintOf } from "./levels/index.js";
-import { FADE, drawnLevel, levelsToDraw } from "./levels/draw.js";
-import { setFadeSource } from "./levels/fade.js";
+import { EncodedLevels, emptyLevels, levelsFrom } from "./levels/index.js";
+import { FADE } from "./levels/draw.js";
+import { fadeSourceOf } from "./levels/fade.js";
 import { levelsToLoad } from "./levels/load.js";
 import { LodLevelLoadManager } from "./levels/manager.js";
-import { levelMaterial } from "./levels/material.js";
-import { screenHeight, screenOf } from "./levels/screen.js";
-import { inShadowMap } from "./levels/renderer.js";
-import { isImpostorMesh, isLOD, isLine, isMesh, isPoints, rejectSkinned, sameClass } from "./three.js";
+import { inShadowMap, maxStorageBinding } from "./levels/renderer.js";
+import { isRenderer, isStorageInstanced, sameClass } from "./three.js";
 import { WIND } from "./wind/hooks.js";
-import { copyWind, refreshWind } from "./wind/index.js";
+import { copyWind } from "./wind/index.js";
+import { localCamera, shownBy } from "./instanced/camera.js";
+import { ClusterView, boundClusters, checkClusters, measuredBox } from "./instanced/clusters.js";
+import { cullIn, emptyCull } from "./instanced/cull.js";
+import { Instances, measure } from "./instanced/instances.js";
+import { MeshesByLevel } from "./instanced/levels.js";
+import { InstanceLists, frustumIn, listedOf } from "./instanced/lists.js";
+import { MAX_SURVIVOR_SCALE, instanceLevel } from "./instanced/measure.js";
+import { drawInstances } from "./instanced/meshes.js";
+import { raycastInstances } from "./instanced/raycast.js";
+import { InstanceShape } from "./instanced/shape.js";
 /**
- * One object's levels, switched by on-screen height with dithered fades. three's renderer calls `update` with each
- * camera before it draws, shadow maps' included; each camera measures at the height it draws at, measured in each
- * render (outside one, the canvas's). Orthographic cameras switch without fading. Shadows follow what the camera draws
- * and omit casters smaller than a shadow texel; levels cast into three's shadow maps, not into a light whose shadow
- * map a custom shadow node replaces. Nothing draws until the coarsest level that draws something has loaded, which
- * loads first; a deferred level loads when a camera first needs it, once that one has loaded, and meanwhile the
- * nearest loaded coarser level draws in its place.
+ * Copies of one object at levels of detail, driven like a three InstancedMesh: `instanceMatrix`, `instanceColor`,
+ * `count` and `boundingBox`, and `clusters` to cull and choose levels by. Each copy draws the level levelsToDraw gives
+ * for its height on screen, switching with dithered fades; each camera's instances are sorted into indirect draws on
+ * the GPU. `new Lod(levels)` is one object at the Lod's own transform.
  *
- * Arriving levels' texture uploads are paced to about one uncompressed 2048² RGBA texture's bytes per frame. Levels
- * are cloned into the Lod. A nested Lod switches and fades its own levels. Lines, points and sprites draw without
- * fading. Raycasts hit the source only. A Lod draws with its LodGpu's renderer only.
+ * The attributes are assignable. A CPU attribute's edits draw once its `needsUpdate` is set (within its update ranges,
+ * which the Lod takes and clears), as an InstancedMesh's do. A StorageInstancedBufferAttribute, such as one the app's
+ * compute pass writes, is read in place, every frame; a storage colour holds four floats per instance. A matrix of
+ * scale 0 draws nothing. Instance matrices may scale arbitrarily; the Lod's own transform and its parents should scale
+ * uniformly.
  *
- * Build a new Lod after adding or moving meshes within a level: geometry is measured and hooked at construction or
- * arrival. Skinned meshes and ShaderMaterials are refused; use static meshes with node materials or supported built-in
- * materials.
+ * Which levels load and which level meshes draw for a camera follow from the instances' bounds: per cluster, its box
+ * and scales; without clusters, `boundingBox` around the first `count` instances, else what the CPU measures of a CPU
+ * instanceMatrix. With clusters, only their instances draw. A storage instanceMatrix with neither loads every level
+ * (it warns once). Each camera draws only the instances in its frustum, and each shadow map is a camera of its own: it
+ * draws the casters in its frustum, each at the level its texels resolve, as an orthographic camera would (an instance
+ * smaller than a texel casts nothing). Thresholds, fades and loading follow `LodLevel`; `cullDistance` thins the
+ * instances out with distance. Nothing draws until the coarsest level that draws something has loaded, which loads
+ * first; a deferred level loads when a camera first needs it, and meanwhile the nearest loaded coarser level draws in
+ * its place. Arriving levels' texture uploads are paced to about one uncompressed 2048² RGBA texture's bytes per frame.
+ *
+ * It draws with WebGPU only (three's WebGPURenderer on its WebGPU backend, with `indirect-first-instance`), with the
+ * first renderer that draws it: it learns of it in that renderer's first frame, which draws nothing of it, and another
+ * renderer drawing it is its error. Sequential cameras are supported; a nested render with a camera that the outer
+ * render also draws with replaces that camera's instance lists, so exclude the Lod from it with camera layers.
+ *
+ * Level templates are cloned, then their meshes are instanced, as children of the Lod on its layers; it sets each
+ * one's `visible` per camera, so hide the Lod itself, never its level meshes. Skinned meshes, InstancedMeshes (except ImpostorMesh),
+ * lines, points, sprites and LODs in levels are refused, as are ShaderMaterials; use static meshes with node materials
+ * or supported built-in materials. Build a new Lod after adding or moving meshes within a level: geometry is measured
+ * at construction or arrival. For external detail, leave level 0 empty and draw the instances that `getLevelAt`
+ * reports there.
  */
 export class Lod extends Object3D {
-    gpu;
     /** Multiplies every measured height: below 1, cheaper levels take over sooner. */
     static quality = 1;
     /** Tint every level by its index, to see which level draws where. */
@@ -39,229 +62,350 @@ export class Lod extends Object3D {
     /** Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its `maxPixels`, the finer level draws too. */
     static fade = FADE;
     isLOD = true;
+    isLod = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate = true;
     /** Draw only this level, without fades, once the coarsest level that draws something has loaded. */
     forceLevel = null;
-    /** The levels, each `object` this Lod's own copy once there is one. Set `maxPixels` to move a switch. */
+    /** 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;
+    /** 16 floats per instance: a CPU InstancedBufferAttribute (identities to start with) or a storage one. */
+    instanceMatrix;
+    /** RGB per instance, white without: three floats on the CPU, four in a storage attribute. */
+    instanceColor = null;
+    /** How many of `instanceMatrix`'s instances draw. */
+    count;
+    /** Bounds every instance at every level, in the Lod's space (see `computeBoundingBox`); measured when null. */
+    boundingBox = null;
+    /** Disjoint ranges of instances, each inside its box, which cull and choose levels apart; clipped to `count`. */
+    clusters = undefined;
     /** The levels as they were given, which a copy is made from. */
     inputs = [];
-    /** Per level, where its meshes' fade comes from. */
-    fades = [];
-    /** Per level, whether its object is a Lod, which fades its own levels. */
-    nested = [];
-    /**
-     * Per loaded level, what in it may cast (see `shadowCasters`): found when it is built or joins, read every shadow
-     * map.
-     */
-    casters = [];
-    /** The levels as levelsToDraw reads them. */
-    encoded;
-    /** Bounding sphere of the source (see `measureLevels`) in the Lod's own space. */
-    sphere = new Sphere();
-    casterRadius = 0;
-    loads;
+    /** What it is made of for its levels, which a copy makes anew. */
+    built;
     disposed = false;
+    instances = new Instances();
+    /** What the level meshes draw. */
+    drawn;
+    /** Around every instance, survivors grown: what every level mesh is culled and boxed by. */
+    bounds = { sphere: new Sphere(), box: new Box3() };
+    view = new ClusterView();
+    /** The cluster ranges last checked to be disjoint. */
+    checked = [];
+    /** What `cullIn` writes cullDistance into, in this Lod's space. */
+    cull = emptyCull();
     /**
-     * `levels[0]` is the source. Empty only as the target of `copy`. A source that draws nothing (an empty Object3D, for
-     * detail another system draws) is measured by the first level that draws something. `gpu` is what it shares with
-     * every Lod drawing with its renderer.
+     * Drawn until a renderer has drawn the Lod, to learn which: three tells a mesh its renderer, but not a LOD. It bounds
+     * the instances for Box3.setFromObject, as the level meshes do once there are some.
      */
-    constructor(levels, gpu, options = {}) {
+    sentinel;
+    warned = false;
+    /** `levels[0]` is the source; empty only as the target of `copy`. `count` instances, at the Lod's origin to start with. */
+    constructor(levels, count = 1, options = {}) {
         super();
-        this.gpu = gpu;
-        const { loads, encoded } = this.build(levels);
-        this.loads = loads;
-        this.encoded = encoded;
-        this.loads.item.given = options.manager;
-    }
-    build(inputs) {
-        this.inputs = inputs;
-        if (inputs.length > 0) {
-            const { own, placed } = measureLevels(inputs, "Lod");
-            this.sphere = placed;
-            this.casterRadius = placed.radius;
-            this.levels.push(...levelsFrom(inputs, 2 * own.radius, "Lod"));
-        }
-        const encoded = new EncodedLevels(this.levels, emptyLevels(inputs), "Lod");
-        this.levels.forEach(({ object }, i) => {
-            const fade = { kind: "object", fade: 0, diameter: 0, tint: tintOf(i, false) };
-            this.fades.push(fade);
-            this.nested.push(object ? isLOD(object) : false);
-            this.casters.push(object ? shadowCasters(object) : null);
-            if (!object)
-                return;
-            rejectSkinned(object, "Lod");
-            this.add(object);
-            this.hook(object, fade, isLOD(object), object);
-        });
-        const loads = new LodLevelLoadManager(this, this.gpu, `Lod ${this.uuid}`, inputs, encoded.get(null, true), (level, loaded) => this.prepare(level, loaded), (level) => {
-            const object = this.levels[level]?.object;
-            return object ? [object] : [];
-        }, null);
-        return { loads, encoded };
-    }
-    /** Fade the meshes under `node` by `fade`; an inner Lod fades its own. */
-    hook(node, fade, nested, level) {
-        const inner = nested || (node !== level && isLOD(node));
-        if (isMesh(node) && !inner) {
-            setFadeSource(node, fade);
-            // An ImpostorMesh reads its draw itself.
-            if (!isImpostorMesh(node))
-                node.material = Array.isArray(node.material) ? node.material.map((m) => levelMaterial(m)) : levelMaterial(node.material);
-        }
-        for (const child of node.children)
-            this.hook(child, fade, inner, level);
-    }
-    /** A copy of `loaded`, level `index`'s object, parented hidden for world matrices and wind until it joins. */
-    prepare(index, loaded) {
-        const object = loaded.clone();
-        const nested = isLOD(object);
-        const level = at(this.levels, index);
-        object.visible = false;
-        rejectSkinned(object, "Lod");
-        if (level.box)
-            prepareBounds(object, level.box);
-        this.hook(object, at(this.fades, index), nested, object);
-        this.add(object);
-        object.updateWorldMatrix(true, true);
-        refreshWind(this, object);
-        return {
-            object,
-            join: () => {
-                level.object = object;
-                this.nested[index] = nested;
-                this.casters[index] = shadowCasters(object);
-            },
-            discard: () => {
-                this.remove(object);
-                disposeCopies(object);
-            },
-        };
+        if (!Number.isInteger(count) || count < 0)
+            throw new RangeError(`Lod: count must be a nonnegative integer, not ${count}`);
+        this.count = count;
+        this.instanceMatrix = identities(count);
+        this.instances.refresh(this);
+        this.drawn = { matrices: this.instances.matrixStorage, colors: this.instances.colorStorage };
+        this.sentinel = this.makeSentinel();
+        this.built = this.init(levels);
+        this.built.loads.item.given = options.manager;
+        this.refresh();
     }
     get pending() {
-        return this.loads.pending;
+        return this.built.loads.pending;
     }
     get error() {
-        return this.loads.error;
+        return this.built.loads.error;
     }
     /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
     get manager() {
-        return this.loads.item.manager;
+        return this.built.loads.item.manager;
     }
     set manager(manager) {
-        this.loads.item.given = manager;
+        this.built.loads.item.given = manager;
+    }
+    setMatrixAt(index, matrix) {
+        matrix.toArray(this.instanceMatrix.array, index * 16);
+        return this;
+    }
+    getMatrixAt(index, matrix) {
+        return matrix.fromArray(this.instanceMatrix.array, index * 16);
+    }
+    /** Write instance `index`'s colour, making a white `instanceColor` for every instance first if there is none. */
+    setColorAt(index, color) {
+        this.instanceColor ??= new InstancedBufferAttribute(new Float32Array(this.instanceMatrix.count * 3).fill(1), 3);
+        color.toArray(this.instanceColor.array, index * this.instanceColor.itemSize);
+        return this;
+    }
+    /** Instance `index`'s colour: white without `instanceColor`. */
+    getColorAt(index, color) {
+        const colors = this.instanceColor;
+        return colors ? color.fromArray(colors.array, index * colors.itemSize) : color.setRGB(1, 1, 1);
+    }
+    /**
+     * Set `boundingBox` around the first `count` instances at every level and its sway, from a CPU instanceMatrix as it
+     * is now; the CPU cannot read a storage one.
+     */
+    computeBoundingBox() {
+        if (isStorageInstanced(this.instanceMatrix))
+            throw new Error("Lod.computeBoundingBox: the CPU cannot read a storage instanceMatrix: set boundingBox or clusters");
+        this.boundingBox = measuredBox(measure(this.instanceMatrix, this.count, null), this.built.shape, this.boundingBox ?? new Box3());
+    }
+    /** What this Lod is made of for `inputs`: its levels, their meshes and their loading. */
+    init(inputs) {
+        const shape = new InstanceShape(inputs);
+        const lists = new InstanceLists(listedOf(inputs));
+        const drawing = { shape, lists, drawn: this.drawn };
+        this.inputs = inputs;
+        if (inputs.length > 0)
+            this.levels.push(...levelsFrom(inputs, 2 * shape.ownRadius, "Lod"));
+        const encoded = new EncodedLevels(this.levels, emptyLevels(inputs), "Lod");
+        const drawFor = (renderer, camera) => this.built.loads.guard(() => {
+            this.built.lists.drawFor(this.see(renderer), camera, this.instances.matrixStorage);
+        });
+        const meshes = new MeshesByLevel(this, this.levels, drawing, this.bounds, drawFor);
+        // Its sorts show them.
+        meshes.show(0);
+        const loads = new LodLevelLoadManager(this, `Lod ${this.uuid}`, inputs, encoded.get(null, true), (level, loaded) => meshes.prepare(level, loaded), (level) => meshes.of(level));
+        return { ...drawing, meshes, loads, encoded };
     }
-    /** Switch and fade the levels for `camera`, and load those it needs. What fails is reported (see `error`): three is rendering. */
+    /**
+     * The sentinel, drawn until a renderer has drawn the Lod (see `see`): no instances, on the Lod's layers, casting, and
+     * never hit by a raycast. Its box is the instances' bounds, and its vertices that box's corners (see `placeSentinel`),
+     * which precise Box3.setFromObject reads.
+     */
+    makeSentinel() {
+        const geometry = new InstancedBufferGeometry().setAttribute("position", new Float32BufferAttribute(new Float32Array(24), 3));
+        geometry.instanceCount = 0;
+        geometry.boundingBox = this.bounds.box;
+        geometry.boundingSphere = this.bounds.sphere;
+        const sentinel = new Mesh(geometry, SENTINEL_MATERIAL);
+        sentinel.frustumCulled = false;
+        sentinel.layers = this.layers;
+        sentinel.raycast = () => { };
+        // Shadow passes draw it too: a Lod that only casts learns its renderer there.
+        sentinel.castShadow = true;
+        sentinel.onBeforeRender = (renderer) => this.built.loads.guard(() => void this.see(renderer));
+        this.add(sentinel);
+        return sentinel;
+    }
+    /** `renderer`, which three hands a mesh's draw, draws the Lod (see `LodLevelLoadManager.see`): it, once checked. */
+    see(renderer) {
+        if (!isRenderer(renderer))
+            throw new Error("Lod: three drew a mesh of it with no renderer");
+        this.built.loads.see(renderer);
+        return renderer;
+    }
+    [WIND](padding, slope, baseY) {
+        if (this.built.loads.started)
+            throw new Error("Lod: 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)
+                source.radius = this.built.shape.fadeRadius;
+        }
+        this.refresh();
+    }
+    /** Take in the instances as they are now, so that its level meshes bound them (see Box3.setFromObject), then update the world matrices. */
+    updateMatrixWorld(force) {
+        if (!this.disposed && this.levels.length > 0)
+            this.built.loads.guard(() => this.refresh());
+        super.updateMatrixWorld(force);
+    }
+    /** 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 || this.levels.length === 0)
+            return;
         // A shadow map draws nothing of a Lod whose levels cast nothing; one not loaded yet may.
         const shadow = inShadowMap(this);
-        if (shadow && !this.casters.some((casters) => !casters || casters.some((node) => node.castShadow)))
-            return;
-        this.loads.guard(() => this.show(camera, shadow));
-    }
-    /** Show the levels for `camera`, a shadow map's when `shadow`. */
-    show(camera, shadow) {
-        if (this.disposed || this.levels.length === 0)
+        if (shadow && !this.levels.some(({ object }, i) => !object || this.built.meshes.of(i).some((mesh) => mesh.castShadow)))
             return;
-        // A shadow map draws the levels its scene's camera chose.
-        if (shadow)
-            return void this.loads.request(camera, 0, true);
-        const { height, levels } = this.measure(camera, false);
-        const loaded = this.loads.request(camera, levelsToLoad([[height, height]], this.encoded.heights(levels)), false);
-        let { level, finer, fade } = levelsToDraw(height, levels, loaded, this.loads.before, this.loads.progress);
-        // A nested Lod fades its own levels: the switch to or from one is immediate.
-        if (this.nested[level] || this.nested[finer])
-            fade = 0;
-        const diameter = 2 * this.casterRadius * this.matrixWorld.getMaxScaleOnAxis();
-        this.levels.forEach(({ object }, i) => {
-            const source = at(this.fades, i);
-            source.fade = i === level ? fade : i === finer ? -fade : 0;
-            source.diameter = diameter;
-            source.tint = tintOf(i, Lod.debug);
-            if (object)
-                object.visible = i === level || (fade > 0 && i === finer);
+        this.built.loads.guard(() => {
+            const { renderer } = this.built.loads;
+            this.sentinel.visible = renderer === null;
+            if (renderer)
+                this.sort(renderer, camera, shadow);
         });
     }
-    /** The source's height on `camera`'s screen, and the levels as levelsToDraw reads them there. */
-    measure(camera, shadow) {
-        const screen = screenOf(camera, this.loads.heightOf(camera, shadow));
-        const height = screenHeight(this.sphere, this.matrixWorld, screen) * Lod.quality;
-        return { height, levels: this.encoded.get(this.forceLevel, !screen.ortho) };
+    /** Take in the attributes, clusters and cullDistance as they are now, and bound the instances. */
+    refresh() {
+        const { lists, meshes, shape } = this.built;
+        if (this.clusters)
+            checkClusters(this.clusters, this.instanceMatrix.count, this.checked);
+        this.instances.refresh(this);
+        const survivors = this.cullDistance?.scaleSurvivors ?? false;
+        const matrices = survivors ? lists.scaledMatrices(this.instanceMatrix.count) : this.instances.matrixStorage;
+        const colors = this.instances.colorStorage;
+        if (matrices !== this.drawn.matrices || colors !== this.drawn.colors) {
+            this.drawn.matrices = matrices;
+            this.drawn.colors = colors;
+            drawInstances(meshes.all(), this.drawn);
+        }
+        boundClusters(this, this.instances.measured, shape, survivors ? MAX_SURVIVOR_SCALE : 1, this.bounds);
+        this.placeSentinel();
+    }
+    /** Put the sentinel's vertices at the corners of the instances' bounds; at the origin while nothing bounds them. */
+    placeSentinel() {
+        const { box } = this.bounds;
+        const position = this.sentinel.geometry.getAttribute("position");
+        const empty = box.isEmpty();
+        let moved = false;
+        for (let i = 0; i < 8; i++) {
+            const x = empty ? 0 : i & 1 ? box.max.x : box.min.x;
+            const y = empty ? 0 : i & 2 ? box.max.y : box.min.y;
+            const z = empty ? 0 : i & 4 ? box.max.z : box.min.z;
+            if (position.getX(i) === x && position.getY(i) === y && position.getZ(i) === z)
+                continue;
+            position.setXYZ(i, x, y, z);
+            moved = true;
+        }
+        if (moved)
+            position.needsUpdate = true;
+    }
+    /** Sort for `camera`, a shadow map's when `shadow`, drawn by `renderer`. */
+    sort(renderer, camera, shadow) {
+        const { loads, shape, lists, encoded, meshes } = this.built;
+        this.refresh();
+        const limit = maxStorageBinding(renderer);
+        const bytes = this.instanceMatrix.count * 64;
+        if (bytes > limit)
+            throw new RangeError(`Lod: its instanceMatrix of ${this.instanceMatrix.count} instances takes ${bytes} bytes, more than the device's storage binding of ${limit} bytes: split the instances across Lods, or raise maxStorageBufferBindingSize in the renderer's requiredLimits`);
+        const local = this.localCamera(camera, renderer, shadow);
+        const cull = cullIn(this.cullDistance, this.matrixWorld, this.cull);
+        const found = lists.of(camera);
+        const { view } = this;
+        view.see(this, this.instances.measured, shape, frustumIn(found, camera, this.matrixWorld), local, cull);
+        if (view.unbounded && !this.warned) {
+            this.warned = true;
+            console.warn(`Lod ${this.uuid}: nothing bounds its storage instanceMatrix, so every level loads and the CPU culls nothing; set boundingBox or clusters`);
+        }
+        const { levels } = local;
+        // A shadow map draws from the levels its scene's cameras loaded.
+        loads.request(camera, levelsToLoad(shadow ? [] : view.heights, encoded.heights(levels)), shadow);
+        meshes.tint(Lod.debug);
+        lists.prune(camera, (other) => loads.rendering(other));
+        const { loaded, before, progress } = loads;
+        // Three projects this Lod's children for the camera after this update.
+        const { shown, only } = shownBy(view.seen, levels, encoded, { loaded, before, progress });
+        lists.sort(camera, {
+            ...local,
+            cull,
+            loaded,
+            before,
+            progress,
+            source: shape.source,
+            reach: shape.reach,
+            ranges: view.ranges,
+            instances: view.instances,
+            inside: view.inside,
+            onlyLevel: cull === null ? only : 0,
+            version: this.instances.version,
+        }, limit);
+        // 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 Lod's space, drawn by `renderer` (see `localCamera`). */
+    localCamera(camera, renderer, shadow) {
+        const { loads, encoded } = this.built;
+        return localCamera(camera, loads.heightOf(camera, renderer, shadow), this.matrixWorld, encoded, this.forceLevel, Lod.quality);
     }
     /**
-     * The index of the level that draws most of the Lod's pixels for `camera` from where it is, with the levels loaded
-     * now and no arrival under way (see `drawnLevel`); null while no level it could draw is loaded.
+     * The level that draws most of instance `index`'s pixels for `camera` from where it is now, with the levels loaded
+     * now and no arrival under way (see `drawnLevel`); null at scale 0, thinned out by `cullDistance`, or while no level
+     * it could draw is loaded. From the CPU instanceMatrix as it is, edits not yet drawn included; the CPU cannot read a
+     * storage one. It measures with the renderer drawing the Lod, so it throws before one has drawn it.
      */
-    getLevel(camera) {
-        if (this.levels.length === 0)
-            return null;
-        const { height, levels } = this.measure(camera, inShadowMap(this));
-        return drawnLevel(levelsToDraw(height, levels, this.loads.loaded, this.loads.loaded, 1));
-    }
-    [WIND](padding) {
-        if (this.loads.started)
-            throw new Error("Lod: apply wind before the first render");
-        this.casterRadius += padding;
+    getLevelAt(index, camera) {
+        const { renderer } = this.built.loads;
+        if (!renderer)
+            throw new Error("Lod.getLevelAt: render the Lod first: it measures with the renderer drawing it");
+        if (isStorageInstanced(this.instanceMatrix))
+            throw new Error("Lod.getLevelAt: the CPU cannot read a storage instanceMatrix");
+        if (!Number.isInteger(index) || index < 0 || index >= this.count)
+            throw new RangeError(`Lod.getLevelAt: ${index} is not one of its ${this.count} instances`);
+        const cull = cullIn(this.cullDistance, this.matrixWorld, this.cull);
+        const local = this.localCamera(camera, renderer, inShadowMap(this));
+        return instanceLevel(this.instanceMatrix.array, index * 16, cull, local, this.built.shape.source, this.built.loads.loaded);
     }
+    /**
+     * Hits the first `count` instances on the source level, with `instanceId` set as on an InstancedMesh's hits; `object`
+     * is this Lod. Instances of a storage instanceMatrix, which the CPU cannot read, are not hit. Its level meshes, on its
+     * layers, are never hit themselves.
+     */
     raycast(raycaster, intersects) {
-        const source = this.levels[0]?.object;
-        if (source)
-            raycaster.intersectObject(source, true, intersects);
-        // Stop the raycaster from descending into the other levels.
-        return false;
+        if (!isStorageInstanced(this.instanceMatrix))
+            raycastInstances(this, { parts: this.built.meshes.source, rest: this.built.shape.rest }, this.instanceMatrix.array, this.count, raycaster, intersects);
     }
     /**
-     * Copies `source`'s levels into this empty Lod (it throws otherwise). The copies share geometry, materials and
-     * textures with `source`, as three's clone does; the settings, LoadingManager, wind and each level's `maxPixels`
-     * come along.
+     * Copies `source`'s levels, instances and settings into this Lod without levels (it throws otherwise); the copy
+     * shares geometry and textures with `source`, and holds copies of its attributes and clusters. Storage attributes
+     * cannot be copied: their instances live on the GPU.
      */
     copy(source) {
         if (this.levels.length > 0)
-            throw new Error("Lod.copy: copy into an empty Lod");
+            throw new Error("Lod.copy: copy into a Lod without levels");
+        const { instanceMatrix, instanceColor } = source;
+        if (isStorageInstanced(instanceMatrix) || (instanceColor && isStorageInstanced(instanceColor)))
+            throw new Error("Lod.copy: a storage attribute's instances live on the GPU and cannot be copied");
+        const inputs = source.inputs.map((input, i) => ({ ...input, maxPixels: at(source.levels, i).maxPixels }));
         super.copy(source, false);
-        const { loads, encoded } = this.build(source.inputs.map((input, i) => ({ ...input, maxPixels: at(source.levels, i).maxPixels })));
-        this.loads = loads;
-        this.encoded = encoded;
-        this.loads.item.given = source.loads.item.given;
+        this.instanceMatrix = new InstancedBufferAttribute(instanceMatrix.array.slice(), 16);
+        this.instanceColor = instanceColor && new InstancedBufferAttribute(instanceColor.array.slice(), 3);
+        this.count = source.count;
+        this.boundingBox = source.boundingBox?.clone() ?? null;
+        this.clusters = source.clusters?.map((cluster) => ({ ...cluster, boundingBox: cluster.boundingBox.clone() }));
+        this.cullDistance = source.cullDistance && { ...source.cullDistance };
         this.forceLevel = source.forceLevel;
         this.autoUpdate = source.autoUpdate;
+        this.built.lists.dispose();
+        this.built.loads.dispose(() => { });
+        this.built = this.init(inputs);
+        this.built.loads.item.given = source.built.loads.item.given;
         copyWind(source, this);
+        this.refresh();
         return this;
     }
     clone() {
-        const clone = new Lod([], this.gpu).copy(this);
+        const clone = new Lod([], 0).copy(this);
         if (!sameClass(this, clone))
             throw new Error("Lod.clone: a subclass must override clone");
         return clone;
     }
     /**
-     * Release what the Lod made of its levels, once nothing it prepares or compiles still uses them. Objects you give or
-     * load are yours to dispose; LodLoader's are freed when the last Lod holding them is disposed (see `LodLevel.hold`).
+     * Release its buffers and what it made of its levels, once nothing it prepares or compiles still uses them. Objects
+     * you give or load, its attributes among them, are yours to dispose; CachedLodLoader's are freed when the last Lod
+     * holding them is disposed (see `LodLevel.hold`).
      */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         super.dispose();
-        this.loads.dispose(() => {
+        this.sentinel.removeFromParent();
+        this.sentinel.geometry.dispose();
+        this.built.loads.dispose(() => {
+            this.built.meshes.dispose();
+            this.built.lists.dispose();
+            this.instances.dispose();
             for (const { object } of this.levels)
                 if (object)
                     disposeCopies(object);
         });
     }
 }
-/**
- * What three's shadow pass may draw under `root`, itself included: its meshes, lines and points, cast if `castShadow`
- * is set.
- */
-function shadowCasters(root) {
-    const found = [];
-    root.traverse((node) => {
-        if (isMesh(node) || isLine(node) || isPoints(node))
-            found.push(node);
-    });
-    return found;
+const SENTINEL_MATERIAL = new MeshBasicNodeMaterial();
+/** A CPU instanceMatrix of `count` identities. */
+function identities(count) {
+    const array = new Float32Array(count * 16);
+    for (let i = 0; i < count; i++)
+        array.set(IDENTITY, i * 16);
+    return new InstancedBufferAttribute(array, 16);
 }
+const IDENTITY = new Matrix4().elements;
 //# sourceMappingURL=lod.js.map