@drawcall/lod 0.3.0 → 0.4.0

package/dist/lod.d.ts

@@ -1,38 +1,56 @@
-import { Object3D, type Camera, type Intersection, type LoadingManager, type Raycaster } from "three/webgpu";
-import type { LodGpu } from "./gpu.js";
+import { Box3, Color, InstancedBufferAttribute, Matrix4, 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 { WIND } from "./wind/hooks.js";
+import { type LodCluster } from "./instanced/clusters.js";
+import { type CullDistance } from "./instanced/cull.js";
+/** How a Lod is made. */
 export interface LodOptions {
     /**
-     * Gets an item while levels a camera needs load, compile or fade in, ended once they are complete. Without one, a
-     * Lod nested in another's level reports to that one's, any other to three's `DefaultLoadingManager`. Wait for a
-     * quiet frame, one in which no item started or ended, rendering (or compiling) the Scene that holds the Lod a frame
-     * apart meanwhile, to capture what a camera sees complete. A Lod its renderer rendered around for a frame without
-     * updating it ends its item, and its next update starts it again. Renders of other scenes in a separate task can end
-     * the item early, and the next update reopens it; a renderer that only compiles leaves a hidden Lod's item held.
+     * Gets an item while levels a camera needs load, compile or fade in, ended once they are complete; three's
+     * `DefaultLoadingManager` without one. Wait for a quiet frame, one in which no item started or ended, rendering (or
+     * compiling) the Scene that holds the Lod a frame apart meanwhile, to capture what a camera sees complete. A Lod its
+     * renderer rendered around for a frame without updating it ends its item, and its next update starts it again.
+     * Renders of other scenes in a separate task can end the item early, and the next update reopens it; a renderer that
+     * only compiles leaves a hidden Lod's item held.
      */
     manager?: LoadingManager;
 }
 /**
- * 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 declare class Lod extends Object3D<LodEventMap> {
-    private readonly gpu;
     /** Multiplies every measured height: below 1, cheaper levels take over sooner. */
     static quality: number;
     /** Tint every level by its index, to see which level draws where. */
@@ -40,69 +58,111 @@ export declare class Lod extends Object3D<LodEventMap> {
     /** Share of a level's range its fade spans: from `maxPixels × (1 - fade)` up to its `maxPixels`, the finer level draws too. */
     static readonly fade = 0.1;
     readonly isLOD = true;
+    readonly isLod = true;
     /** Let the renderer call `update` with its camera every frame. */
     autoUpdate: boolean;
     /** Draw only this level, without fades, once the coarsest level that draws something has loaded. */
     forceLevel: number | 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). */
     readonly levels: ThresholdedLevel[];
+    /** Thins the instances out with distance from a camera, in every camera; null draws them at any distance. */
+    cullDistance: CullDistance | null;
+    /** 16 floats per instance: a CPU InstancedBufferAttribute (identities to start with) or a storage one. */
+    instanceMatrix: InstancedBufferAttribute;
+    /** RGB per instance, white without: three floats on the CPU, four in a storage attribute. */
+    instanceColor: InstancedBufferAttribute | null;
+    /** How many of `instanceMatrix`'s instances draw. */
+    count: number;
+    /** Bounds every instance at every level, in the Lod's space (see `computeBoundingBox`); measured when null. */
+    boundingBox: Box3 | null;
+    /** Disjoint ranges of instances, each inside its box, which cull and choose levels apart; clipped to `count`. */
+    clusters: LodCluster[] | undefined;
     /** The levels as they were given, which a copy is made from. */
     private inputs;
-    /** Per level, where its meshes' fade comes from. */
-    private readonly fades;
-    /** Per level, whether its object is a Lod, which fades its own levels. */
-    private readonly nested;
-    /**
-     * Per loaded level, what in it may cast (see `shadowCasters`): found when it is built or joins, read every shadow
-     * map.
-     */
-    private readonly casters;
-    /** The levels as levelsToDraw reads them. */
-    private encoded;
-    /** Bounding sphere of the source (see `measureLevels`) in the Lod's own space. */
-    private sphere;
-    private casterRadius;
-    private loads;
+    /** What it is made of for its levels, which a copy makes anew. */
+    private built;
     private disposed;
+    private readonly instances;
+    /** What the level meshes draw. */
+    private readonly drawn;
+    /** Around every instance, survivors grown: what every level mesh is culled and boxed by. */
+    private readonly bounds;
+    private readonly view;
+    /** The cluster ranges last checked to be disjoint. */
+    private readonly checked;
+    /** What `cullIn` writes cullDistance into, in this Lod's space. */
+    private readonly cull;
     /**
-     * `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: readonly LodLevel[], gpu: LodGpu, options?: LodOptions);
-    private build;
-    /** Fade the meshes under `node` by `fade`; an inner Lod fades its own. */
-    private hook;
-    /** A copy of `loaded`, level `index`'s object, parented hidden for world matrices and wind until it joins. */
-    private prepare;
+    private readonly sentinel;
+    private warned;
+    /** `levels[0]` is the source; empty only as the target of `copy`. `count` instances, at the Lod's origin to start with. */
+    constructor(levels: readonly LodLevel[], count?: number, options?: LodOptions);
     get pending(): boolean;
     get error(): Error | undefined;
     /** Where the item of levels a camera misses goes (see `LodOptions.manager`). */
     get manager(): LoadingManager;
     set manager(manager: LoadingManager | undefined);
-    /** Switch and fade the levels for `camera`, and load those it needs. What fails is reported (see `error`): three is rendering. */
+    setMatrixAt(index: number, matrix: Matrix4): this;
+    getMatrixAt(index: number, matrix: Matrix4): Matrix4;
+    /** Write instance `index`'s colour, making a white `instanceColor` for every instance first if there is none. */
+    setColorAt(index: number, color: Color): this;
+    /** Instance `index`'s colour: white without `instanceColor`. */
+    getColorAt(index: number, color: Color): Color;
+    /**
+     * 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(): void;
+    /** What this Lod is made of for `inputs`: its levels, their meshes and their loading. */
+    private init;
+    /**
+     * 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.
+     */
+    private makeSentinel;
+    /** `renderer`, which three hands a mesh's draw, draws the Lod (see `LodLevelLoadManager.see`): it, once checked. */
+    private see;
+    [WIND](padding: number, slope: number, baseY: number): void;
+    /** 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?: boolean): 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;
-    /** Show the levels for `camera`, a shadow map's when `shadow`. */
-    private show;
-    /** The source's height on `camera`'s screen, and the levels as levelsToDraw reads them there. */
-    private measure;
+    /** Take in the attributes, clusters and cullDistance as they are now, and bound the instances. */
+    private refresh;
+    /** Put the sentinel's vertices at the corners of the instances' bounds; at the origin while nothing bounds them. */
+    private placeSentinel;
+    /** Sort for `camera`, a shadow map's when `shadow`, drawn by `renderer`. */
+    private sort;
+    /** `camera` in this Lod's space, drawn by `renderer` (see `localCamera`). */
+    private localCamera;
+    /**
+     * 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.
+     */
+    getLevelAt(index: number, camera: Camera): number | null;
     /**
-     * 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.
+     * 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.
      */
-    getLevel(camera: Camera): number | null;
-    [WIND](padding: number): void;
-    raycast(raycaster: Raycaster, intersects: Intersection[]): boolean;
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
     /**
-     * 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: Lod): this;
     clone(): this;
     /**
-     * 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(): void;
 }