@drawcall/lod 0.2.0 → 0.3.0

package/dist/instanced/chunks.js

@@ -0,0 +1,208 @@
+import { Box3, InstancedBufferAttribute } from "three/webgpu";
+import { isStorageInstanced } from "../three.js";
+import { InstancedLodChunk, measureChunk } from "./chunk.js";
+import { Mirror } from "./mirror.js";
+import { MAX_SURVIVOR_SCALE } from "./measure.js";
+/** `attribute`, a GPU chunk's, as the storage attribute InstancedLodChunk checked it is. */
+function onGpu(attribute) {
+    if (!isStorageInstanced(attribute))
+        throw new TypeError("InstancedLod: a GPU chunk's attribute is not a storage attribute");
+    return attribute;
+}
+const grown = new Box3();
+/**
+ * The chunks of one InstancedLod: their pool slots, the mirrors the pool reads CPU attributes through, and their
+ * bounds, which load levels and cull the level meshes.
+ */
+export class ChunkSet {
+    pool;
+    row;
+    bounds;
+    reach;
+    levelAt;
+    held = new Map();
+    mirrors = new Map();
+    /** Bumped whenever a chunk was added, removed or re-measured: what `heights` reads changed. */
+    version = 0;
+    /**
+     * Chunks over `pool`, for the InstancedLod sorting as row `row`, whose instances `bounds` bounds in the InstancedLod's space; `reach` tells how far from an
+     * instance's origin, in its space, every level and its sway reach, and `levelAt` is what a chunk's getLevelAt asks.
+     */
+    constructor(pool, row, bounds, reach, levelAt) {
+        this.pool = pool;
+        this.row = row;
+        this.bounds = bounds;
+        this.reach = reach;
+        this.levelAt = levelAt;
+    }
+    get size() {
+        return this.held.size;
+    }
+    /** The chunks, in the order they were added. */
+    keys() {
+        return this.held.keys();
+    }
+    /** The pool slots of the chunks. */
+    slots() {
+        return [...this.held.values()].map(({ slot }) => slot);
+    }
+    /** The chunks whose instances the CPU holds. */
+    cpu() {
+        return [...this.held].flatMap(([chunk, { state }]) => (state.gpu ? [] : [chunk]));
+    }
+    /**
+     * What makes chunks of their own with every chunk's instances, their attributes copied (see `InstancedLod.copy`). A
+     * GPU chunk cannot be copied: its instances live on the GPU.
+     */
+    copies() {
+        const cpu = this.cpu();
+        if (cpu.length !== this.size)
+            throw new Error("InstancedLod.copy: a GPU chunk's instances live on the GPU and cannot be copied");
+        return cpu.map(({ instanceMatrix, instanceColor, start, count }) => ({
+            instanceMatrix: copyOf(instanceMatrix),
+            instanceColor: instanceColor ? copyOf(instanceColor) : undefined,
+            start,
+            count,
+        }));
+    }
+    /** Hold `parameters`' instances as a chunk, copied into the pool at its next run; `bound` bounds it. */
+    add(parameters) {
+        const gpu = isStorageInstanced(parameters.instanceMatrix);
+        const state = { gpu, originBox: new Box3(), minScale: 0, maxScale: 0, boundingBox: new Box3(), levelAt: null };
+        const chunk = new InstancedLodChunk(parameters, state);
+        const { instanceMatrix, instanceColor, instanceCount } = chunk;
+        const attributes = gpu
+            ? // A storage attribute's RGB is padded to four floats.
+                { matrices: onGpu(instanceMatrix), colors: instanceColor && { attribute: onGpu(instanceColor), stride: 4 }, counts: instanceCount }
+            : {
+                matrices: this.mirror(instanceMatrix, chunk).attribute,
+                colors: instanceColor && { attribute: this.mirror(instanceColor, chunk).attribute, stride: 3 },
+                counts: null,
+            };
+        const slot = this.pool.add({ attributes, start: chunk.start, count: chunk.count, countIndex: chunk.instanceCountIndex, row: this.row });
+        state.levelAt = (index, camera) => this.levelAt(chunk, index, camera);
+        this.held.set(chunk, { slot, state });
+        this.version++;
+        return chunk;
+    }
+    /** Let go of `chunk`; its pages return to the pool at its next run. */
+    remove(chunk) {
+        const held = this.held.get(chunk);
+        if (!held)
+            throw new Error("InstancedLod: the chunk is not one of its chunks");
+        this.pool.remove(held.slot);
+        held.state.levelAt = null;
+        this.held.delete(chunk);
+        this.version++;
+        for (const attribute of [chunk.instanceMatrix, chunk.instanceColor]) {
+            const shared = attribute && this.mirrors.get(attribute);
+            if (!shared)
+                continue;
+            shared.users.delete(chunk);
+            if (shared.users.size > 0)
+                continue;
+            shared.mirror.dispose();
+            this.mirrors.delete(shared.mirror.source);
+        }
+    }
+    /**
+     * Take in the CPU attributes' edits, those whose versions moved, for every chunk reading them: re-measured, and
+     * copied into the pool again at its next run. Whether any changed; `bound` bounds them.
+     */
+    refresh() {
+        const changed = new Set();
+        for (const { mirror, users } of this.mirrors.values()) {
+            if (!mirror.refresh())
+                continue;
+            for (const chunk of users) {
+                if (chunk.instanceMatrix === mirror.source)
+                    measureChunk(chunk, this.heldOf(chunk).state);
+                changed.add(chunk);
+            }
+        }
+        for (const chunk of changed)
+            this.pool.change(this.heldOf(chunk).slot);
+        if (changed.size > 0)
+            this.version++;
+        return changed.size > 0;
+    }
+    /** Bound every chunk, its box (see `InstancedLodChunk.boundingBox`), and all of them, survivors grown by up to `grow`. */
+    bound(grow) {
+        const { sphere, box } = this.bounds;
+        const reach = this.reach();
+        box.makeEmpty();
+        for (const { state } of this.held.values()) {
+            if (state.originBox.isEmpty()) {
+                state.boundingBox.makeEmpty();
+                continue;
+            }
+            state.boundingBox.copy(state.originBox).expandByScalar(reach * state.maxScale);
+            box.union(grown.copy(state.originBox).expandByScalar(reach * state.maxScale * grow));
+        }
+        if (box.isEmpty())
+            sphere.makeEmpty();
+        else
+            box.getBoundingSphere(sphere);
+    }
+    /**
+     * The heights on a screen of `scale` from `eye`, both in the InstancedLod's space, that each chunk's instances can
+     * have, `source` an instance's source sphere: its shortest instance at its farthest, its tallest at its nearest.
+     */
+    *heights(source, eye, scale, ortho, cull) {
+        const grow = cull?.survivors ? MAX_SURVIVOR_SCALE : 1;
+        const diameter = 2 * source.radius * scale;
+        for (const { state } of this.held.values()) {
+            const { originBox, minScale, maxScale } = state;
+            if (originBox.isEmpty() || maxScale === 0)
+                continue;
+            if (cull && originBox.distanceToPoint(cull.eye) >= cull.far)
+                continue;
+            const shortest = diameter * minScale;
+            const tallest = diameter * maxScale * grow;
+            if (ortho) {
+                yield [shortest, tallest];
+                continue;
+            }
+            // An instance's centre lies this far from its origin.
+            const offset = source.center.length() * maxScale * grow;
+            const near = Math.max(originBox.distanceToPoint(eye) - offset, 1e-6);
+            const far = farthest(originBox, eye) + offset;
+            yield [shortest / far, tallest / near];
+        }
+    }
+    /** Free the chunks' slots and release the mirrors; the chunks no longer find their levels. */
+    dispose() {
+        for (const { slot, state } of this.held.values()) {
+            this.pool.remove(slot);
+            state.levelAt = null;
+        }
+        this.held.clear();
+        this.version++;
+        for (const { mirror } of this.mirrors.values())
+            mirror.dispose();
+        this.mirrors.clear();
+    }
+    /** The mirror of `attribute`, which `chunk` reads too. */
+    mirror(attribute, chunk) {
+        const shared = this.mirrors.get(attribute) ?? { mirror: new Mirror(attribute), users: new Set() };
+        this.mirrors.set(attribute, shared);
+        shared.users.add(chunk);
+        return shared.mirror;
+    }
+    heldOf(chunk) {
+        const held = this.held.get(chunk);
+        if (!held)
+            throw new Error("InstancedLod: a mirror's chunk is not one of its chunks");
+        return held;
+    }
+}
+/** The distance from `point` to the farthest point of `box`. */
+function farthest(box, point) {
+    const { min, max } = box;
+    return Math.hypot(Math.max(Math.abs(point.x - min.x), Math.abs(point.x - max.x)), Math.max(Math.abs(point.y - min.y), Math.abs(point.y - max.y)), Math.max(Math.abs(point.z - min.z), Math.abs(point.z - max.z)));
+}
+/** A CPU attribute of its own with `attribute`'s instances. */
+function copyOf(attribute) {
+    return new InstancedBufferAttribute(attribute.array.slice(), attribute.itemSize);
+}
+//# sourceMappingURL=chunks.js.map

package/dist/instanced/chunks.js.map

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

package/dist/instanced/cull.d.ts

@@ -0,0 +1,28 @@
+import { Matrix4, Vector3, type Camera } from "three/webgpu";
+/**
+ * How an InstancedLod thins its instances out with distance from `camera`, in every camera, as Fog does: every instance
+ * draws up to `near` from it, none from `far` on, and in between a share falling linearly, chosen by a hash of each
+ * instance's origin (its matrix's translation), the same on the CPU and the GPU. An instance whose translation changes
+ * rolls a new value: it may appear or vanish as it moves. With `scaleSurvivors`, the instances drawn grow by 1/√share,
+ * up to `MAX_SURVIVOR_SCALE` (8), so a thinned field stays about as covered.
+ */
+export interface CullDistance {
+    camera: Camera;
+    near: number;
+    far: number;
+    scaleSurvivors?: boolean;
+}
+/** cullDistance in the InstancedLod's space. */
+export interface Cull {
+    eye: Vector3;
+    near: number;
+    far: number;
+    survivors: boolean;
+}
+/**
+ * `cullDistance`, checked, in the space of `space`, an InstancedLod's world matrix, written into `target`; null for
+ * none. Nothing holds on to what it answers past a sort: the sort and its keys copy its values.
+ */
+export declare function cullIn(cullDistance: CullDistance | null, space: Matrix4, target: Cull): Cull | null;
+/** A Cull to write into (see `cullIn`). */
+export declare const emptyCull: () => Cull;

package/dist/instanced/cull.js

@@ -0,0 +1,22 @@
+import { Matrix4, Vector3 } from "three/webgpu";
+const inverse = new Matrix4();
+/**
+ * `cullDistance`, checked, in the space of `space`, an InstancedLod's world matrix, written into `target`; null for
+ * none. Nothing holds on to what it answers past a sort: the sort and its keys copy its values.
+ */
+export function cullIn(cullDistance, space, target) {
+    if (!cullDistance)
+        return null;
+    const { camera, near, far, scaleSurvivors = false } = cullDistance;
+    if (!(Number.isFinite(near) && Number.isFinite(far) && near >= 0 && far > near))
+        throw new RangeError(`InstancedLod: cullDistance needs 0 <= near < far, both finite, got ${near} and ${far}`);
+    const scale = space.getMaxScaleOnAxis();
+    target.eye.setFromMatrixPosition(camera.matrixWorld).applyMatrix4(inverse.copy(space).invert());
+    target.near = near / scale;
+    target.far = far / scale;
+    target.survivors = scaleSurvivors;
+    return target;
+}
+/** A Cull to write into (see `cullIn`). */
+export const emptyCull = () => ({ eye: new Vector3(), near: 0, far: 0, survivors: false });
+//# sourceMappingURL=cull.js.map

package/dist/instanced/cull.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cull.js","sourceRoot":"","sources":["../../src/instanced/cull.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAe,MAAM,cAAc,CAAC;AAwB7D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,YAAiC,EAAE,KAAc,EAAE,MAAY;IACpF,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,GAAG,KAAK,EAAE,GAAG,YAAY,CAAC;IACnE,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,GAAG,GAAG,IAAI,CAAC;QAC7E,MAAM,IAAI,UAAU,CAAC,sEAAsE,IAAI,QAAQ,GAAG,EAAE,CAAC,CAAC;IAChH,MAAM,KAAK,GAAG,KAAK,CAAC,iBAAiB,EAAE,CAAC;IACxC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAChG,MAAM,CAAC,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IAC3B,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC;IACzB,MAAM,CAAC,SAAS,GAAG,cAAc,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2CAA2C;AAC3C,MAAM,CAAC,MAAM,SAAS,GAAG,GAAS,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC"}

package/dist/instanced/index.d.ts

@@ -1,90 +1,120 @@
-import { type Color, Matrix4, Object3D, Sphere, type Camera, type Intersection, type Raycaster } from "three/webgpu";
-import { type LevelView, type LodLevel } from "../levels.js";
-import { type LevelsEventMap } from "../residency.js";
-import { WIND_BOUNDS } from "../wind/hooks.js";
+import { Object3D, type Camera, type Intersection, type LoadingManager, type Raycaster } from "three/webgpu";
+import { type LodLevel, type ThresholdedLevel } from "../levels/index.js";
+import { type LodEventMap } from "../levels/manager.js";
+import type { LodGpu } from "../gpu.js";
+import { type LodOptions } from "../lod.js";
+import { WIND } from "../wind/hooks.js";
+import type { InstancedLodChunk, InstancedLodChunkParameters } from "./chunk.js";
+import { type CullDistance } from "./cull.js";
+/** How an InstancedLod is made. */
+export interface InstancedLodOptions extends LodOptions {
+    /**
+     * The most instances it draws for a camera, over all its chunks, CPU and GPU chunks alike: 16384 by default. Its
+     * lists take 8 bytes per level that draws something per instance (about 400 KB with the defaults and three levels),
+     * and every camera that draws any InstancedLod of its LodGpu, each shadow map's included, holds the lists of every
+     * InstancedLod of that LodGpu. A camera that draws only a few InstancedLods, such as a minimap's or a reflection's,
+     * is bounded by giving those a LodGpu of their own. Chunks that together outgrow it are reported (see `error`),
+     * naming it as the limit to raise. Its LodGpu's pool holds the instances themselves (see `LodGpuOptions`).
+     */
+    maxInstanceCount?: number;
+}
 /**
- * Independently selected copies of one object, batched into indirect draws per view.
- * Thresholds, fades, global settings and shadows follow Lod. Each level's bounds tighten
- * to the region where its instances can draw. Instance matrices may scale arbitrarily;
- * the crowd's own transform and its parents should scale uniformly. Scale 0 draws nothing.
+ * 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.
  *
- * Level templates are cloned, then their meshes are instanced. Skinned meshes,
- * InstancedMeshes (except ImpostorMesh) and nested Lods are unsupported. For external
- * detail, leave level 0 empty and draw the instances that `levelOf` reports there.
+ * 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.
  *
- * Requires WebGPU `indirect-first-instance`. Sequential cameras are supported; nested
- * renders replace the outer selection, so exclude this crowd with camera layers.
+ * 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 declare class InstancedLod extends Object3D<LevelsEventMap> {
+export declare class InstancedLod extends Object3D<LodEventMap> {
+    private readonly gpu;
     readonly isLOD = true;
     readonly isInstancedLod = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate: boolean;
-    /** 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: number | null;
-    readonly levels: readonly LevelView[];
-    readonly count: number;
-    private readonly entries;
-    private readonly probes;
-    private selection;
-    private meshes;
-    private readonly residency;
+    /** The levels, each `object` the template its level meshes are made from, once there is one (never in the scene). */
+    readonly levels: ThresholdedLevel[];
+    /** Thins the instances out with distance from a camera, in every camera; null draws them at any distance. */
+    cullDistance: CullDistance | null;
+    /** The levels as they were given, which a copy is made from. */
+    private inputs;
+    /** What it is made of for its levels and sizes, which a copy makes anew. */
+    private built;
     private disposed;
-    private readonly store;
-    /** Bounding sphere of the source in an instance's space. */
-    private readonly sphere;
-    /** Every placed level, kept separate from the source sphere used for LOD selection. */
-    private readonly envelope;
-    private readonly rest;
-    /** Around every instance; each level may use tighter bounds. */
-    readonly bounds: Sphere;
-    /** Per level, what its meshes are culled by: `bounds`, or less where its instances must be near the camera. */
-    private readonly reaches;
-    /** Logical demand at the initial default viewport, separate from first-draw visibility. */
-    private readonly demand;
-    /** Source-radius padding for the shadow caster cutoff; culling pads every level separately. */
-    private padding;
-    private blocks;
-    private readonly last;
+    /** Around every instance, survivors grown: what every level mesh is culled and boxed by. */
+    private readonly bounds;
+    /** What `cullIn` writes cullDistance into, in this InstancedLod's space. */
+    private readonly cull;
+    /**
+     * `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: readonly LodLevel[], gpu: LodGpu, options?: InstancedLodOptions);
     get pending(): boolean;
     get error(): Error | undefined;
-    /** `levels[0]` is the source. Empty only as the target of `copy`. */
-    constructor(levels?: readonly LodLevel[], count?: number);
-    private build;
-    /** Compile only the arriving level; bounds and instance buffers stay fixed. */
-    private install;
-    /** Metadata includes unloaded levels, so later arrivals cannot enlarge this envelope. */
-    private boundLevels;
-    setMatrixAt(index: number, matrix: Matrix4): void;
-    getMatrixAt(index: number, matrix: Matrix4): Matrix4;
-    /** Tint instance `index` by `color`, as InstancedMesh.setColorAt does, in every level. */
-    setColorAt(index: number, color: Color): void;
-    /** Instance `index`'s colour: white unless set. */
-    getColorAt(index: number, color: Color): Color;
+    /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
+    get manager(): LoadingManager;
+    set manager(manager: LoadingManager | undefined);
+    /** Its chunks, in the order they were added. */
+    get chunks(): Iterable<InstancedLodChunk>;
+    /** What this InstancedLod is made of for `inputs` and `maxInstanceCount`: its levels, their meshes and their loading. */
+    private init;
     /**
-     * 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: number): number | null;
-    /** Source radius padded for the level shaders' shadow caster cutoff. */
-    private get drawRadius();
-    [WIND_BOUNDS](padding: number, slope: number, baseY: number): void;
-    /** Sort instances for `camera`; demand begins after its first drawing context exists. */
+    addChunk(parameters: InstancedLodChunkParameters): InstancedLodChunk;
+    /** Remove `chunk`'s instances; its pages return to the pool in the next render. */
+    removeChunk(chunk: InstancedLodChunk): void;
+    /** Bound every chunk's instances, survivors grown. */
+    private measureBounds;
+    [WIND](padding: number, slope: number, baseY: number): void;
+    /** Sort the instances into level lists for `camera`, a camera's or a shadow map's, and load the levels they need. What fails is reported (see `error`). */
     update(camera: Camera): void;
-    /** Move each level's reach to the level that draws in its place: its fallback, and during a handover also its previous one. */
-    private reroute;
+    /** Sort for `camera`, a shadow map's when `shadow`. */
+    private sort;
+    /** `camera` in this InstancedLod's space (see `localCamera`). */
+    private localCamera;
+    /** Draw survivors' scaled matrices, or the pool's again. */
+    private scaleSurvivors;
+    /** The level instance `index` of `chunk` draws most of its pixels with for `camera` (see `InstancedLodChunk.getLevelAt`). */
+    private levelAt;
     /**
-     * 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: Raycaster, intersects: Intersection[]): boolean;
     /**
-     * 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: InstancedLod): this;
     clone(): this;
-    /** Release drawables and templates only after every owner sharing their geometry, materials and textures has stopped drawing. */
+    /**
+     * 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(): void;
-    private clearDraws;
 }