three-virtual-geometry 0.0.0-stage → 0.1.1

package/dist/core/constants.d.ts

@@ -0,0 +1,27 @@
+/** Max triangles per meshlet. The renderer always issues `MAX_MESHLET_TRIANGLES * 3` vertices per drawn meshlet. */
+export declare const MAX_MESHLET_TRIANGLES = 128;
+/** Max unique vertices per meshlet (meshoptimizer allows up to 256). */
+export declare const MAX_MESHLET_VERTICES = 128;
+/** Stand-in for `Infinity` on the GPU: the parent error of root meshlets. */
+export declare const ERROR_INFINITY = 1e+30;
+/**
+ * Instances whose LOD range is at most this many meshlets, and where every meshlet is guaranteed to be
+ * selected, emit their meshlets directly from the instance pass (no meshlet pass for them).
+ */
+export declare const FAST_PATH_MAX_MESHLETS = 4;
+/**
+ * Relative margin the fast path keeps from the LOD threshold, so float rounding between the bound and the
+ * per-meshlet test can never make the fast path select a meshlet the full test would reject.
+ */
+export declare const FAST_PATH_MARGIN = 0.001;
+/** Floats per meshlet in `VirtualMeshData.meshletBounds` (4 x vec4). */
+export declare const MESHLET_BOUNDS_STRIDE = 16;
+/** Uints per meshlet in `VirtualMeshData.meshletInfo` (1 x uvec4). */
+export declare const MESHLET_INFO_STRIDE = 4;
+/** Debug views for `VirtualGeometry.debugMode`. */
+export declare const VG_DEBUG_MODES: {
+    readonly shaded: 0;
+    readonly meshlets: 1;
+    readonly lodLevel: 2;
+    readonly instances: 3;
+};

package/dist/core/import/fromObject3D.d.ts

@@ -0,0 +1,116 @@
+/**
+ * One-call scene import: every static mesh of an Object3D (e.g. a loaded glTF scene) becomes VirtualGeometry geometry.
+ *
+ * Meshes are grouped by (geometry, geometry group, material, render flags), so repeated geometry becomes one
+ * VirtualMesh with one instance per occurrence (InstancedMesh instances included). Each unique geometry range
+ * is built once. Skinned and morphing meshes, points, lines and sprites are left alone and keep rendering.
+ */
+import * as THREE from 'three/webgpu';
+import { type VirtualMeshBuildOptions, type VirtualMeshData, type VirtualMeshSource } from '../preprocess/buildVirtualMesh.js';
+import type { VirtualGeometry } from '../runtime/VirtualGeometry.js';
+import type { VirtualMesh, VirtualMeshOptions } from '../runtime/VirtualMesh.js';
+/** Builds one DAG. Same signature as `buildVirtualMesh`, so a caching builder drops in here or via `options.builder`. */
+export type VirtualGeometryBuilder = (source: VirtualMeshSource, options?: VirtualMeshBuildOptions) => Promise<VirtualMeshData>;
+export interface VirtualGeometryImportOptions {
+    /** DAG build options for every geometry (`onProgress` is driven by the import; use `onProgress` below). */
+    build?: Omit<VirtualMeshBuildOptions, 'onProgress'>;
+    /** Options for each created VirtualMesh (e.g. `maxDrawDistance`), or a function returning them per group. */
+    mesh?: VirtualMeshOptions | ((group: VirtualGeometryImportGroup) => VirtualMeshOptions | undefined);
+    /** Return false to leave a mesh as it is (it keeps rendering normally). Called for every compatible mesh. */
+    filter?: (mesh: THREE.Mesh) => boolean;
+    /**
+     * true (default): the VirtualMeshes are added to `object` and the converted meshes stop rendering (their
+     * leaf meshes are taken out of the graph, meshes with children stay with their layers cleared; `dispose()`
+     * restores both). false: nothing in the scene changes; add `result.object` yourself.
+     */
+    replace?: boolean;
+    /** Overall progress in 0..1 while building. May be async (awaited), e.g. to let the page repaint. */
+    onProgress?: (fraction: number) => void | Promise<void>;
+    /** Converts a source material. Default: node materials are cloned, classic mesh materials go through `toNodeMaterial`. */
+    material?: (material: THREE.Material, group: VirtualGeometryImportGroup) => THREE.NodeMaterial | null;
+    /** DAG builder (default `buildVirtualMesh`), e.g. a cached one with the same signature. */
+    builder?: VirtualGeometryBuilder;
+}
+/** Meshes that share geometry, geometry range, material and render flags: one VirtualMesh. */
+export interface VirtualGeometryImportGroup {
+    geometry: THREE.BufferGeometry;
+    /** Index range (vertex range for non-indexed geometry) this group draws: one entry of `geometry.groups`, clipped to the draw range. */
+    range: {
+        start: number;
+        count: number;
+    };
+    material: THREE.Material;
+    /** Column-major world matrix per instance (16 floats each), in the order of `instances`. */
+    matrices: Float32Array;
+    /** rgba per instance, from `InstancedMesh.instanceColor` (null when no source has instance colors). */
+    colors: Float32Array | null;
+    /** Source of each instance: the mesh, and the instance index for an InstancedMesh (else -1). */
+    instances: {
+        object: THREE.Mesh;
+        index: number;
+    }[];
+    /** Per-vertex colors are used (`material.vertexColors` and a `color` attribute), like three would. */
+    vertexColors: boolean;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    /** False when the mesh or one of its ancestors is hidden. */
+    visible: boolean;
+    renderOrder: number;
+    layers: number;
+    /** From the first source mesh. */
+    name: string;
+    userData: Record<string, unknown>;
+}
+/** Why a mesh is left alone, or null when it can be converted. */
+export declare function incompatibility(mesh: THREE.Object3D): string | null;
+/**
+ * Collects the convertible meshes under `root` into instance groups (pure CPU work, no GPU, testable in Node).
+ * World matrices are read after updating them, so the result matches what three would render now.
+ */
+export declare function collectVirtualGeometryGroups(root: THREE.Object3D, filter?: (mesh: THREE.Mesh) => boolean): {
+    groups: VirtualGeometryImportGroup[];
+    meshes: THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap>[] | THREE.Material<THREE.MaterialEventMap>, THREE.Object3DEventMap>[];
+    skipped: {
+        object: THREE.Object3D;
+        reason: string;
+    }[];
+};
+/** Result of `VirtualGeometry.add()`: the created meshes, and how to undo the import. */
+export declare class VirtualGeometryImport {
+    private readonly context;
+    /** Holds every created VirtualMesh. Added to the imported object unless `replace: false`. */
+    readonly object: THREE.Group<THREE.Object3DEventMap>;
+    /** One VirtualMesh per entry of `groups`. */
+    readonly meshes: VirtualMesh[];
+    groups: VirtualGeometryImportGroup[];
+    /** Meshes that were left alone, and why. */
+    readonly skipped: {
+        object: THREE.Object3D;
+        reason: string;
+    }[];
+    readonly stats: {
+        sourceMeshes: number;
+        instances: number;
+        uniqueGeometries: number;
+        buildMs: number;
+    };
+    private readonly hidden;
+    /** Converted leaf meshes taken out of the graph, with their former parent (restored by `dispose`). */
+    private readonly detached;
+    constructor(context: VirtualGeometry, collected: ReturnType<typeof collectVirtualGeometryGroups>);
+    /** @internal Stops the given source meshes from rendering (restored by `dispose`). */
+    hide(meshes: THREE.Mesh[], root: THREE.Object3D): void;
+    /** World matrix of a source object, also when it (or its ancestors) were taken out of the graph. */
+    private worldMatrixOf;
+    /**
+     * Re-reads every source mesh's current world matrix into the instances (call after moving the imported
+     * object or animating its nodes). Instances are baked in world space at import time otherwise.
+     */
+    syncTransforms(): void;
+    /** Removes the VirtualMeshes and lets the source meshes render again. */
+    dispose(): void;
+}
+/**
+ * Converts every compatible mesh under `object` to VirtualGeometry geometry. See `VirtualGeometry.add`.
+ */
+export declare function virtualMeshesFromObject3D(context: VirtualGeometry, object: THREE.Object3D, options?: VirtualGeometryImportOptions): Promise<VirtualGeometryImport>;

package/dist/core/import/toNodeMaterial.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three/webgpu';
+/** True when `toNodeMaterial` can convert the material (node materials, and the classic mesh materials). */
+export declare function canConvertToNodeMaterial(material: THREE.Material): boolean;
+/**
+ * The node-material equivalent of a classic mesh material: MeshStandardMaterial -> MeshStandardNodeMaterial,
+ * and likewise for Physical, Phong, Lambert, Basic, Toon, Matcap and Normal. Every property is copied (colors,
+ * maps and their texture objects, transparency, alphaTest, side, blending, userData, ...). Node materials are
+ * returned as they are; materials without a node equivalent (ShaderMaterial, ...) return null.
+ */
+export declare function toNodeMaterial(material: THREE.Material): THREE.NodeMaterial | null;

package/dist/core/io/cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `buildVirtualMeshCached`: `buildVirtualMesh` behind a persistent IndexedDB cache, keyed by a SHA-256 of the
+ * source arrays and build options. The first load builds and stores the encoded result; later loads decode
+ * it. Any cache problem (no IndexedDB, private mode, quota, corrupt entry) falls back to building.
+ */
+import { type VirtualMeshBuildOptions, type VirtualMeshData, type VirtualMeshSource } from '../preprocess/buildVirtualMesh.js';
+/**
+ * Part of every cache key. Bump it whenever `buildVirtualMesh` produces different output for the same input
+ * (algorithm or default changes), so stale cached builds are never returned.
+ */
+export declare const VG_BUILD_VERSION = 3;
+export interface VirtualGeometryCacheOptions {
+    /**
+     * Fixed cache key instead of a content hash (skips hashing the source). You must change it whenever the
+     * source mesh or build options change.
+     */
+    key?: string;
+    /** 'indexeddb' (default) or false to always build. */
+    store?: 'indexeddb' | false;
+}
+export interface VirtualGeometryCachedBuildOptions extends VirtualMeshBuildOptions {
+    cache?: VirtualGeometryCacheOptions;
+}
+/**
+ * Same as `buildVirtualMesh`, plus a persistent cache. On a hit the build is skipped, `onProgress(1)` is still
+ * called, and `stats.buildMs` reports the time this call took (hashing, lookup and decoding).
+ */
+export declare function buildVirtualMeshCached(source: VirtualMeshSource, options?: VirtualGeometryCachedBuildOptions): Promise<VirtualMeshData>;
+/** Deletes every cached build. Resolves even if IndexedDB is unavailable. */
+export declare function clearVirtualMeshCache(): Promise<void>;
+/** SHA-256 over every source field (typed arrays by content), the build options and the format versions. */
+export declare function virtualMeshCacheKey(source: VirtualMeshSource, options?: VirtualMeshBuildOptions, customKey?: string): Promise<string>;

package/dist/core/io/serialize.d.ts

@@ -0,0 +1,21 @@
+import type { VirtualMeshData } from '../preprocess/buildVirtualMesh.js';
+/** Bumped whenever the container layout or an encoding changes; older readers reject newer files. */
+export declare const VG_FORMAT_VERSION = 1;
+export interface VirtualMeshEncodeOptions {
+    /** Store `indices` instead of rebuilding it from the meshlet arrays on decode. Default false. */
+    keepIndices?: boolean;
+    /** Lossless compression with meshoptimizer's codecs. Default true; false stores every array uncompressed. */
+    compress?: boolean;
+    /**
+     * Also deflate fields where that makes them smaller (about 30% smaller files, about 2x slower decoding).
+     * Default true; ignored where `CompressionStream` is unavailable. The IndexedDB cache turns it off.
+     */
+    deflate?: boolean;
+}
+export declare class VirtualMeshFormatError extends Error {
+    constructor(message: string);
+}
+export declare function encodeVirtualMesh(data: VirtualMeshData, options?: VirtualMeshEncodeOptions): Promise<Uint8Array>;
+export declare function decodeVirtualMesh(input: ArrayBuffer | ArrayBufferView): Promise<VirtualMeshData>;
+/** Fetches and decodes a baked `.vgeo` file, or decodes bytes that are already in memory. */
+export declare function loadVirtualMesh(source: string | URL | ArrayBuffer | ArrayBufferView, init?: RequestInit): Promise<VirtualMeshData>;

package/dist/core/preprocess/buildVirtualMesh.d.ts

@@ -0,0 +1,105 @@
+export interface VirtualMeshSource {
+    /** xyz per vertex */
+    positions: Float32Array;
+    /** xyz per vertex */
+    normals: Float32Array;
+    /** Optional rgb per vertex, multiplied with the material color. */
+    colors?: Float32Array;
+    /** Optional uv per vertex (texture coordinates). Vertices on a UV seam must be separate vertices. */
+    uvs?: Float32Array;
+    indices: Uint32Array;
+}
+export interface VirtualMeshBuildOptions {
+    /** Meshlets per group before simplification. */
+    groupSize?: number;
+    maxLodLevels?: number;
+    /** A group that keeps more than this fraction of its triangles stops refining (its meshlets become roots). */
+    maxGroupKeepRatio?: number;
+    /** Fraction of a group's triangles kept by its simplification (the per-level reduction factor). */
+    simplifyRatio?: number;
+    /** Stop when a whole level removed less than this fraction of triangles. */
+    minLevelReduction?: number;
+    /** Remove small disconnected components while simplifying (good for foliage). */
+    prune?: boolean;
+    /**
+     * Keep simplifying below a single meshlet once the remaining roots form the whole mesh, so distant
+     * instances can draw a handful of triangles (or nothing, with `prune`) instead of a full meshlet.
+     */
+    tailSimplify?: boolean;
+    /** Stop the tail at this many triangles. */
+    minRootTriangles?: number;
+    /**
+     * Let coarse LODs switch to voxel proxies when those are more accurate than simplified triangles
+     * (foliage and other aggregate geometry; solid meshes keep their triangles). Default true.
+     */
+    voxelLods?: boolean;
+    onProgress?: (fraction: number) => void | Promise<void>;
+}
+export interface VirtualMeshData {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array | null;
+    /** uv per vertex, or null when the source had none. */
+    uvs: Float32Array | null;
+    /** Concatenated meshlet triangle lists, indexing `positions`. */
+    indices: Uint32Array;
+    meshletCount: number;
+    /**
+     * 4 x vec4 per meshlet:
+     * [0] LOD sphere (center, radius)  - shared by all meshlets created from the same group
+     * [1] parent LOD sphere (center, radius)
+     * [2] (error, parentError, 0, 0) - object-space; parentError = ERROR_INFINITY for roots
+     * [3] culling sphere (center, radius) - the meshlet's own geometry
+     */
+    meshletBounds: Float32Array;
+    /**
+     * uvec4 per meshlet: (triangleCount, firstIndex, lodLevel, vertexOffset).
+     * `firstIndex / 3` is also the meshlet's first entry in `meshletTriangles`.
+     */
+    meshletInfo: Uint32Array;
+    /** Global vertex ids, per meshlet, in meshlet-local order (`vertexOffset` indexes this). */
+    meshletVertices: Uint32Array;
+    /** One packed triangle per entry: three meshlet-local vertex ids in bits 0-7, 8-15, 16-23. */
+    meshletTriangles: Uint32Array;
+    /** Meshlets are sorted by LOD level. Per level: [firstMeshlet, meshletCount]. */
+    levelRanges: Uint32Array;
+    /** Per level: [smallest own error, largest parent error] in object space (parent may be ERROR_INFINITY). */
+    levelErrors: Float32Array;
+    /**
+     * Per level: [largest own error, smallest parent error] in object space. Used by the fast path: if every
+     * meshlet of a level passes the LOD test at the nearest distance (largest own error) and at the farthest
+     * (smallest parent error), the level needs no per-meshlet test.
+     */
+    levelGuardErrors: Float32Array;
+    /** Sphere enclosing every LOD and parent sphere: bounds the distances the LOD test can see. */
+    lodBoundsSphere: [number, number, number, number];
+    /** Sphere enclosing every meshlet's culling sphere (all LODs): if an instance sphere is inside the frustum, so are they. */
+    cullBoundsSphere: [number, number, number, number];
+    /**
+     * DAG links, CSR form: meshlet i is replaced by coarser meshlets
+     * `replacementIndices[replacementStart[i] .. replacementStart[i + 1]]`. Empty for coarsest meshlets.
+     */
+    replacementStart: Uint32Array;
+    replacementIndices: Uint32Array;
+    /** Whole-object bounding sphere (center xyz, radius). */
+    boundingSphere: [number, number, number, number];
+    stats: {
+        leafTriangles: number;
+        leafMeshlets: number;
+        rootTriangles: number;
+        rootMeshlets: number;
+        lodLevels: number;
+        /** Coarse levels built from voxel proxies (see voxelProxy.ts). */
+        voxelLevels: number;
+        buildMs: number;
+    };
+}
+export declare function buildVirtualMesh(src: VirtualMeshSource, options?: VirtualMeshBuildOptions): Promise<VirtualMeshData>;
+/**
+ * How far the simplified mesh's bounding box retreats from the original's, per side (max over the 6
+ * sides). An empty result counts as losing the whole extent. Used as a floor for the LOD error so a
+ * version that lost its silhouette is only drawn once that loss is below the pixel threshold.
+ */
+export declare function extentShrink(before: Uint32Array, after: Uint32Array, positions: Float32Array): number;
+/** Order-independent edge id. Safe while vertex ids stay below 2^26. */
+export declare const edgeKey: (a: number, b: number) => number;

package/dist/core/preprocess/partition.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Groups meshlets into clusters of ~`groupSize` that share as many boundary
+ * edges as possible. This stands in for METIS (the graph partitioner nanite-webgpu uses):
+ * a greedy region-growing pass over the meshlet adjacency graph, seeded in
+ * Morton order so groups stay spatially compact. Meshlets without enough
+ * neighbours (e.g. disconnected leaves or grass blades) are then merged with
+ * spatially close leftovers so they can still be simplified together.
+ */
+export interface PartitionInput {
+    /** Boundary edge keys (position-welded vertex ids, see `edgeKey`). */
+    boundaryEdges: number[];
+    center: [number, number, number];
+}
+export declare function partitionMeshlets(meshlets: PartitionInput[], groupSize: number): number[][];
+/** Indices sorted along a 30-bit Morton curve of the given points. */
+export declare function mortonOrder(points: [number, number, number][]): number[];

package/dist/core/preprocess/voxelProxy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Voxel proxies for coarse LODs, for foliage and other aggregate geometry.
+ *
+ * Triangle simplification breaks down on aggregate geometry such as a tree crown made of hundreds of
+ * separate leaf clumps: below a few hundred triangles it can only delete or collapse whole clumps, so
+ * the silhouette shrinks and the LOD error jumps. A voxel proxy keeps the volume instead: the mesh is
+ * voxelized, gaps between clumps are closed, and a smooth closed surface is extracted (surface nets).
+ * That surface is one connected shape, which simplifies gracefully to a handful of triangles.
+ *
+ * Every proxy vertex lies within about one cell of the original surface, and closing fills gaps of at most
+ * two cells, so `VOXEL_ERROR_CELLS * cellSize` bounds how far the proxy deviates from the original.
+ */
+/** Deviation of a proxy from the source mesh, in cells (surface offset plus closed gaps). */
+export declare const VOXEL_ERROR_CELLS = 2;
+export interface VoxelProxy {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array | null;
+    /** UV of a representative source sample near each vertex (null when the source has no UVs). */
+    uvs: Float32Array | null;
+    indices: Uint32Array;
+    cellSize: number;
+}
+/**
+ * Voxelizes the triangles `indices` of a mesh with `resolution` cells along its longest side and returns
+ * a closed, smooth surface around the occupied volume (null if the mesh is empty).
+ * With `uvs`, each proxy vertex takes the UV of the first source sample in its cell's voxels, so textured
+ * geometry keeps plausible colors at a distance (UVs cannot be averaged across islands).
+ */
+export declare function buildVoxelProxy(positions: Float32Array, colors: Float32Array | null | undefined, indices: Uint32Array, resolution: number, uvs?: Float32Array | null): VoxelProxy | null;

package/dist/core/runtime/GeometryPool.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Shared GPU buffers and compute passes for many VirtualMeshes.
+ *
+ * Every mesh's vertices, meshlets, level table and instances are appended to one set of storage buffers, and one
+ * fixed set of compute passes selects the cut for all of them. CPU cost, shader count and pipeline compilation
+ * therefore do not grow with the number of unique meshes: a level with hundreds of different props costs the
+ * same 12 dispatches per frame as a scene with one. Each mesh still gets its own indexed indirect draw (its own
+ * material), into a region of the pool's shared index buffer laid out each frame by a prefix sum.
+ *
+ * Per frame (all on the GPU):
+ *  0. reset    - clears the counters.
+ *  1. cells    - one thread per cell (CELL_SIZE instances of one mesh, Morton-ordered): frustum, sub-pixel and
+ *                draw-distance tests on the cell's bounding sphere. Visible cells are appended to a list.
+ *  2. instance - one workgroup per visible cell: per-instance tests, occlusion, then the LOD level range per
+ *                cut (camera and shadow). Instances whose few meshlets are all certain to pass emit them
+ *                directly (fast path); the others go to a work list.
+ *  3. meshlet  - one workgroup per work item: per-meshlet frustum/occlusion culling and the LOD test
+ *                `parentError > t && error <= t`. Selected meshlets get a draw slot and a range inside their
+ *                mesh's region of the index buffer.
+ *  4. prefix   - one thread: lays the meshes' regions out one after another and writes each mesh's draw args.
+ *  5. expand   - one workgroup per drawn meshlet: writes 3 indices per triangle. An index encodes
+ *                `drawSlot * 128 + meshletLocalVertex`; the material's positionNode decodes it and pulls the
+ *                vertex from storage buffers, so any three.js NodeMaterial works unchanged.
+ *
+ * A pool is bounded by WebGPU's storage-buffer binding size; VirtualGeometry opens another pool when one is full.
+ * Buffers grow by reallocation (the nodes are rebuilt, and the pipelines recompiled in the background).
+ *
+ * Based on nanite-webgpu (MIT, Marcin Matuszczyk): cullMeshletsPass + rasterizeHwPass.
+ */
+import * as THREE from 'three/webgpu';
+import type { VirtualMeshData } from '../preprocess/buildVirtualMesh.js';
+import type { VirtualGeometry } from './VirtualGeometry.js';
+type Node = any;
+/** World-space normal of the current vertex, usable in material color/roughness nodes. */
+export declare const vgWorldNormal: THREE.PropertyNode<"vec3">;
+export declare const vgMeshletVarying: THREE.PropertyNode<"float">;
+export declare const vgLodVarying: THREE.PropertyNode<"float">;
+export declare const vgInstanceVarying: THREE.PropertyNode<"float">;
+export declare const vgTintVarying: THREE.PropertyNode<"vec3">;
+/** Bits of an index used for the meshlet-local vertex; the rest is the draw slot. */
+export declare const LOCAL_VERTEX_BITS: number;
+/** Instances per cell. A cell is a contiguous range of one mesh's Morton-sorted instances. */
+export declare const CELL_SIZE = 128;
+/** Fraction of `maxDrawDistance` over which instances shrink to nothing before they are culled. */
+export declare const DRAW_DISTANCE_FADE = 0.15;
+/** Stand-in for an infinite draw distance on the GPU. */
+export declare const NO_DRAW_DISTANCE = 1e+30;
+export interface PoolCapacity {
+    /** Max meshlets drawn per frame, per cut. */
+    meshlets: number;
+    /** Max triangles drawn per frame by the camera cut (its index buffer). */
+    triangles: number;
+    /** Max triangles drawn per frame into shadow maps. */
+    shadowTriangles: number;
+}
+/** CPU-side record of one mesh's place in the pool. */
+export interface PoolEntry {
+    slot: number;
+    data: VirtualMeshData;
+    vertexBase: number;
+    meshletBase: number;
+    meshletVertexBase: number;
+    triangleBase: number;
+    levelBase: number;
+    levelCount: number;
+    instanceBase: number;
+    instanceCount: number;
+    cellBase: number;
+    cellCount: number;
+    uvScale: [number, number];
+    uvOffset: [number, number];
+}
+/** Growable typed array with a GPU attribute; growth replaces the attribute (the pool then rebuilds its nodes). */
+declare class GrowBuffer<T extends Float32Array | Uint32Array> {
+    private readonly make;
+    readonly itemSize: number;
+    /** Largest capacity (items) whose binding stays under the pool's byte limit. */
+    private readonly maxItems;
+    array: T;
+    attribute: THREE.StorageBufferAttribute;
+    used: number;
+    constructor(make: (n: number) => T, itemSize: number, capacity: number, 
+    /** Largest capacity (items) whose binding stays under the pool's byte limit. */
+    maxItems?: number);
+    get capacity(): number;
+    /** Reserves `count` items; returns the first, or -1 when the buffer must grow first. */
+    reserve(count: number): number;
+    /** Reallocates to hold at least `needed` items (keeps the contents). */
+    grow(needed: number): void;
+    /** Marks items [first, first + count) for upload. */
+    touch(first: number, count: number): void;
+}
+export declare class GeometryPool {
+    private readonly context;
+    readonly entries: (PoolEntry | null)[];
+    /** Highest used mesh slot + 1 (the prefix pass loops over this many). */
+    readonly meshSlots: THREE.UniformNode<"uint", number>;
+    readonly cellCount: THREE.UniformNode<"uint", number>;
+    readonly maxBytes: number;
+    readonly capacity: PoolCapacity;
+    readonly vertexData: GrowBuffer<Uint32Array>;
+    readonly vertexAttrs: GrowBuffer<Uint32Array>;
+    readonly meshletBounds: GrowBuffer<Float32Array>;
+    readonly meshletInfo: GrowBuffer<Uint32Array>;
+    readonly meshletVertices: GrowBuffer<Uint32Array>;
+    readonly meshletTriangles: GrowBuffer<Uint32Array>;
+    readonly meshTable: GrowBuffer<Float32Array>;
+    readonly instances: GrowBuffer<Float32Array>;
+    readonly cells: GrowBuffer<Float32Array>;
+    private meshSlotCapacity;
+    private levelUsed;
+    private countersAttribute;
+    drawArgsAttribute: THREE.IndirectStorageBufferAttribute;
+    cameraIndex: THREE.StorageBufferAttribute;
+    shadowIndex: THREE.StorageBufferAttribute;
+    computeNodes: THREE.ComputeNode[];
+    positionNode: Node;
+    /** Bumped on every rebuild: meshes re-point their geometry and material when it changes. */
+    version: number;
+    private needsRebuild;
+    private indexBuffersReady;
+    pipelineState: 'none' | 'compiling' | 'ready';
+    /** The cut needs recomputing (camera moved, instances or settings changed). */
+    dirty: boolean;
+    /** True once a cut was computed (its camera index buffer can then serve as occluders). */
+    hasCut: boolean;
+    constructor(context: VirtualGeometry, capacity: PoolCapacity, maxBytes: number);
+    /** Bytes the geometry of `data` takes in this pool (the largest single binding is what must fit). */
+    static bytesOf(data: VirtualMeshData): number;
+    /** True when `data` (and `instanceCount` instances) still fit under the binding-size limit. */
+    fits(data: VirtualMeshData, instanceCount: number): boolean;
+    /** Appends a mesh's geometry and instances. Returns its entry (`slot` is its index in the mesh table). */
+    add(data: VirtualMeshData, matrices: Float32Array, colors: Float32Array | undefined, gpuToInput: Uint32Array): PoolEntry;
+    /** Frees a mesh's slot (its buffer ranges are reclaimed when the pool is next repacked). */
+    remove(entry: PoolEntry): void;
+    private growMeshSlots;
+    private writeGeometry;
+    /** Writes a mesh record: bounding spheres, levers, level table location, uv packing, flags. */
+    writeMeshRecord(e: PoolEntry, o: {
+        maxDrawDistance: number;
+        minPixelRadius: number;
+        enabled: number;
+        shadow: number;
+        occlusion: number;
+    }): void;
+    /** Updates some of a mesh's per-frame levers (only what changed is uploaded). */
+    writeFlags(e: PoolEntry, o: {
+        maxDrawDistance?: number;
+        minPixelRadius?: number;
+        enabled?: number;
+        shadow?: number;
+        occlusion?: number;
+    }): void;
+    readFlag(e: PoolEntry, index: 'maxDrawDistance' | 'minPixelRadius' | 'enabled' | 'shadow' | 'occlusion'): number;
+    private writeInstances;
+    /** Writes one instance matrix (GPU order index within the mesh). Call `commitInstances` afterwards. */
+    setMatrix(e: PoolEntry, gpuIndex: number, matrix: THREE.Matrix4): void;
+    /** Uploads changed instances and refreshes the bounds of the given cells. */
+    commitInstances(e: PoolEntry, cells: Iterable<number>): void;
+    /**
+     * Bounding sphere of one cell's instances: the AABB of their world-space object spheres gives the center, and
+     * the radius reaches every instance sphere. Both radii are inflated a little so float32 rounding on the GPU can
+     * never make the cell test stricter than the per-instance test.
+     */
+    private computeCell;
+    /**
+     * Index buffers are written by compute and read by draws. three.js picks GPU buffer usage from the first use,
+     * so create them as index buffers (INDEX | STORAGE) before any compute. Also rebuilds the nodes after growth.
+     */
+    prepare(renderer: THREE.WebGPURenderer): void;
+    /** Builds the nodes if the pool's buffers grew since the last build (or it was never built). */
+    ensureBuilt(): void;
+    /** Recreates the per-frame buffers and every node (after the pool's buffers grew). */
+    build(): void;
+    /** Stats of the last computed cut, from a readback of the counters buffer. */
+    readCounters(renderer: THREE.WebGPURenderer): Promise<{
+        camera: {
+            selected: number;
+            drawn: number;
+            survived: number;
+            requestedTriangles: number;
+        };
+        shadow: {
+            selected: number;
+            drawn: number;
+            survived: number;
+            requestedTriangles: number;
+        };
+        occluded: number;
+        perMesh: (c: number, slot: number) => number;
+    }>;
+    /** Byte offset of a mesh's draw args for a cut (0: camera, 1: shadow) in `drawArgsAttribute`. */
+    drawArgsOffset(cut: number, slot: number): number;
+    dispose(): void;
+}
+/**
+ * World-space bounding sphere of the instance whose column-major matrix starts at `base`, computed the same way
+ * the instance pass does: center = model * sphere center, radius = sphere radius * max column length.
+ */
+export declare function instanceSphere(m: ArrayLike<number>, base: number, sphere: number[], out: Float64Array): void;
+export declare function encodeOctNormal(nx: number, ny: number, nz: number): number;
+/** xyz as float bits + octahedral-encoded normal, 4 x u32 per vertex. */
+export declare function packVertices(positions: Float32Array, normals: Float32Array): Uint32Array;
+/**
+ * uv per vertex as two unorm16 in one u32, quantized over the bounds of all UVs (also tiling UVs outside 0..1).
+ * Decode: unpackUnorm2x16(packed) * scale + offset. One step is 1/65535 of the range: well below a texel of a 4K
+ * texture for 0..1 UVs.
+ */
+export declare function packUvs(uvs: Float32Array): {
+    packed: Uint32Array;
+    scale: [number, number];
+    offset: [number, number];
+};
+/**
+ * Instance indices sorted along a 30-bit Morton curve over the instance centers, so that consecutive slots are
+ * spatially close and a fixed-size run of slots forms a compact cell.
+ */
+export declare function mortonOrder(matrices: Float32Array, sphere: number[]): Uint32Array;
+export {};