three-virtual-geometry 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,100 @@
+/**
+ * Occlusion culling against a hierarchical depth buffer (HZB), on by default.
+ *
+ * Per frame, before the cut is computed:
+ *  1. occluder pass - the occluder meshes' previous-frame camera cuts (their index buffers still hold them)
+ *     are drawn depth-only with the CURRENT camera into a small depth target. That geometry was visible last
+ *     frame, so it is a subset of the real occluders.
+ *  2. HZB build - mip 0 is that depth (copied into a storage buffer), each further mip is the MAX of its
+ *     2x2 children: a texel only hides what lies behind all of its occluders.
+ *  3. cull - an instance or meshlet sphere is dropped from the camera cut when its projected box, read at
+ *     the mip where it covers at most 2x2 texels, is entirely behind the max depth there.
+ *
+ * Why it is safe: removing occluders can only push the depth buffer back, so anything hidden by the subset
+ * is hidden by the full scene. Stale or missing occluders cost efficiency, never correctness. The occluders
+ * are LOD-simplified (they may bulge up to the error threshold in front of the true surface), so the tested
+ * sphere is grown by that error first.
+ *
+ * Only meshes flagged `occluder` are drawn in step 1 (by default: opaque, single-sided, no alpha test, i.e.
+ * solid geometry such as terrain, rocks, buildings; foliage is mostly holes). Every mesh is tested, unless
+ * its `occlusionCulling` is off. Shadow cuts are never occlusion culled: a caster hidden from the camera can
+ * still shadow something visible.
+ *
+ * Storage: the whole HZB (a header with each mip's offset and size, then all mips) is one storage buffer,
+ * sized for `maxSize`, so nothing is reallocated on resize.
+ */
+import * as THREE from 'three/webgpu';
+import type { VirtualMesh } from './VirtualMesh';
+type Node = any;
+export declare class OcclusionCulling {
+    /** Lever: set false to turn occlusion culling off (no occluder pass, no HZB, nothing culled by it). */
+    enabled: boolean;
+    /**
+     * Lever: decide by measurement. Whether occlusion pays off depends on the scene and the GPU: the occluder
+     * pass has a fixed cost, which wins in cities and interiors and loses in open landscapes. With `auto`,
+     * frame times are compared with occlusion off and on (`autoProbeFrames` each), the faster setting is kept
+     * for `autoHoldFrames`, then measured again. Within 3% (e.g. both capped by vsync) it stays off.
+     * Set false to keep it on whenever `enabled`.
+     */
+    auto: boolean;
+    autoProbeFrames: number;
+    autoHoldFrames: number;
+    /** The auto setting currently in use (true: occlusion on). */
+    autoChoice: boolean;
+    private phase;
+    private phaseFrames;
+    private samples;
+    private offMean;
+    private lastTick;
+    /** Depth resolution relative to the drawing buffer. Lower is cheaper and culls a little less. */
+    resolutionScale: number;
+    /** Largest HZB dimension in texels (memory ~1.33 * maxSize^2 * 4 bytes). */
+    readonly maxSize: number;
+    /** True when this frame's HZB holds at least one occluder (the cull kernels test against it only then). */
+    active: boolean;
+    /** 1 while this frame's HZB is valid; the cull kernels only occlusion-cull then. */
+    readonly activeNode: THREE.UniformNode<"uint", number>;
+    private readonly depthScene;
+    private readonly proxies;
+    private readonly projection;
+    private readonly near;
+    private readonly levelCapacity;
+    private readonly levelOffsets;
+    private readonly hzbAttribute;
+    private readonly hzbWrite;
+    private readonly hzbRead;
+    /** Copy + reduce kernels for the current depth size, dispatched with this frame's cut (one submission). */
+    private buildNodes;
+    private renderTarget;
+    private width;
+    private height;
+    private levels;
+    private readonly bufferSize;
+    constructor(projection: Node, near: Node, maxSize?: number);
+    /**
+     * True only when a sphere (view-space center, radius) is certainly hidden. Any doubt (touching the near
+     * plane, outside the screen) keeps it.
+     */
+    occluded(viewCenter: Node, radius: Node): Node;
+    /** Called once per frame by the context: feeds the auto A/B measurement (see `auto`). */
+    tick(now: number): void;
+    private next;
+    private autoWanted;
+    /** Depth-only proxy of a mesh's camera cut, created on first use and kept in sync with its pool. */
+    private proxyOf;
+    unregisterMesh(mesh: VirtualMesh): void;
+    /**
+     * Whether occlusion culling runs this frame (enabled, a supported camera and depth mode, and the auto tuner
+     * wants it). Meshes get their per-mesh flag from this before the cut is computed.
+     */
+    wantsFrame(renderer: THREE.WebGPURenderer, camera: THREE.Camera, _frame: number): boolean;
+    /**
+     * Renders the occluders' last camera cuts into the depth target and returns the compute kernels that turn
+     * it into the HZB; run them before the cut (the caller prepends them to the same compute submission).
+     * Sets `activeNode`, which the cull kernels check: without occluders this frame, nothing is occlusion culled.
+     */
+    beginFrame(renderer: THREE.WebGPURenderer, camera: THREE.Camera, meshes: readonly VirtualMesh[]): THREE.ComputeNode[];
+    private resize;
+    dispose(): void;
+}
+export {};

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

@@ -0,0 +1,201 @@
+import * as THREE from 'three/webgpu';
+import type { VirtualMesh, VirtualMeshInstances, VirtualMeshOptions } from './VirtualMesh';
+import { OcclusionCulling } from './OcclusionCulling';
+import type { VirtualMeshData } from '../preprocess/buildVirtualMesh';
+import { GeometryPool } from './GeometryPool';
+import { type VirtualGeometryImport, type VirtualGeometryImportOptions } from '../import/fromObject3D';
+export { VG_DEBUG_MODES } from '../constants';
+export interface VirtualGeometryStats {
+    drawnMeshlets: number;
+    drawnTriangles: number;
+    /** Triangles if every instance were drawn at full detail (no LOD, no culling). */
+    fullDetailTriangles: number;
+    instances: number;
+    /** Instances that survived instance culling (frustum, sub-pixel). */
+    visibleInstances: number;
+    /** Triangles the LOD cut asked for. Above drawnTriangles means some mesh ran out of index buffer. */
+    requestedTriangles: number;
+    /** True when a mesh dropped meshlets for lack of capacity (visible as flicker). */
+    overflow: boolean;
+    /** Fullest draw buffer of any mesh, as a fraction of its capacity (above 1: overflow). */
+    capacityUse: number;
+    /** Instances hidden from the camera by occlusion culling. */
+    occludedInstances: number;
+    /** Triangles drawn into shadow maps (the coarser shadow cut). */
+    shadowTriangles: number;
+}
+export interface VirtualGeometryOptions {
+    /** Max triangles drawn per frame per pool (camera). Default 10M (120 MB of indices, under the 128 MB binding limit). */
+    maxTriangles?: number;
+    /** Max triangles drawn into shadow maps per frame per pool. Default 4M. */
+    maxShadowTriangles?: number;
+    /** Max meshlets drawn per frame per pool. Default 1M. */
+    maxMeshlets?: number;
+    /**
+     * Largest storage-buffer binding a pool may use, in bytes. A pool that would exceed it is closed and a new one
+     * opened. Default 120 MB (WebGPU guarantees 128 MB; raise it if you request a higher device limit).
+     */
+    maxPoolBytes?: number;
+}
+export declare class VirtualGeometry {
+    readonly viewMatrix: THREE.UniformNode<"mat4", THREE.Matrix4>;
+    readonly projectionMatrix: THREE.UniformNode<"mat4", THREE.Matrix4>;
+    /** `projection[1][1] * viewportHeight / 2`: converts view-space error to pixels. */
+    readonly projScale: THREE.UniformNode<"float", number>;
+    readonly near: THREE.UniformNode<"float", number>;
+    /** Max projected error, in pixels, a meshlet may have to be drawn. */
+    readonly errorThreshold: THREE.UniformNode<"float", number>;
+    /**
+     * Lever: target number of drawn triangles per frame. When > 0, the error threshold is adjusted (slowly, see
+     * adaptThreshold) to keep the drawn triangle count near this budget. Off by default: a fixed threshold gives
+     * the steadiest image, because LODs then only switch with distance, never all at once.
+     */
+    triangleBudget: number;
+    /** Bounds for the automatically adjusted error threshold, in pixels. */
+    thresholdRange: [number, number];
+    /** Latest GPU readback, updated every `statsInterval` frames while a budget or HUD is active. */
+    lastStats: VirtualGeometryStats | null;
+    statsInterval: number;
+    /** Frames updated so far. */
+    frameCount: number;
+    /** The user's threshold while the capacity guard holds a coarser one (no budget), else null. */
+    private guardBase;
+    /** Consecutive stats readbacks with the drawn triangles outside the budget's deadband. */
+    private outOfBand;
+    private guardWritten;
+    private statsPending;
+    readonly frustumCulling: THREE.UniformNode<"uint", number>;
+    readonly debugMode: THREE.UniformNode<"uint", number>;
+    /**
+     * Instances whose bounding sphere projects to a smaller radius than this (pixels) are skipped. 0 disables.
+     * The sphere is never smaller than the object, so at 0.7 nothing wider than ~1.4 px on screen is dropped.
+     */
+    readonly minPixelRadius: THREE.UniformNode<"float", number>;
+    readonly frustumPlanes: THREE.UniformNode<"vec4", THREE.Vector4>[];
+    /**
+     * Direction * length that light travels (e.g. sun direction * 300). When non-zero, frustum culling
+     * keeps meshlets whose shadow, swept along this vector, can reach the view frustum, so shadow
+     * casters just outside the view still cast shadows. Zero disables it.
+     */
+    readonly shadowSweep: THREE.UniformNode<"vec3", THREE.Vector3>;
+    /**
+     * Set `shadowSweep` automatically from the shadow cameras of the lights that render the meshes (direction
+     * of an orthographic shadow camera, length = its larger extent). Turn off to set `shadowSweep` yourself.
+     */
+    autoShadowSweep: boolean;
+    /**
+     * Shadow maps use a coarser cut: the error threshold times this. Shadows are soft and seen from the camera
+     * at a distance, so this saves most of the shadow-pass triangles with no visible change. 1 = camera detail.
+     */
+    readonly shadowErrorScale: THREE.UniformNode<"float", number>;
+    private readonly detectedSweep;
+    private detectedSweepFrame;
+    /**
+     * Occlusion culling (on by default): geometry hidden behind solid meshes is not drawn. Levers:
+     * `occlusion.enabled`, `occlusion.resolutionScale`, and per mesh `occluder` / `occlusionCulling`.
+     */
+    readonly occlusion: OcclusionCulling;
+    /** Skip LOD selection/culling and keep drawing the last selection (for inspecting the cut). */
+    freeze: boolean;
+    /**
+     * Run `update()` automatically before every render of a scene that contains this context's meshes, with the
+     * camera that render uses (default true). Shadow-map renders reuse the cut of the camera being rendered.
+     * Calling `update()` yourself still works: a render right after it with the same camera does not repeat it.
+     */
+    autoUpdate: boolean;
+    /**
+     * Measure the error threshold in CSS pixels (default) instead of device pixels. On a 2x display,
+     * device pixels would request ~4x the triangles for detail nobody can see.
+     */
+    errorInCssPixels: boolean;
+    readonly meshes: VirtualMesh[];
+    /** Shared buffers and compute passes; meshes go into the first pool with room (see GeometryPool). */
+    readonly pools: GeometryPool[];
+    private readonly capacity;
+    private readonly maxPoolBytes;
+    constructor(options?: VirtualGeometryOptions);
+    private readonly frustum;
+    private readonly projScreen;
+    private readonly size;
+    /** Compute nodes dispatched this frame (reused to avoid per-frame allocation). */
+    private readonly computeList;
+    private readonly dispatchedPools;
+    /** Frames where `update` ran no compute pass because nothing the cut depends on changed. */
+    skippedFrames: number;
+    /** Inputs of the cut as of the last frame that changed them (NaN until the first frame). */
+    private readonly cutInputs;
+    private readonly cutInputsScratch;
+    /** Scenes whose onBeforeRender runs the auto update (installed the first time one of our meshes renders in them). */
+    private readonly sceneHooks;
+    /** `renderer.info.render.calls` and camera of the last automatic and the last manual update. */
+    private autoCall;
+    private autoCamera;
+    private manualCall;
+    private manualCamera;
+    private updatingAuto;
+    /**
+     * Converts every static mesh under `object` (e.g. `gltf.scene`) to VirtualGeometry geometry, in place: meshes sharing
+     * geometry and material become one VirtualMesh with many instances, materials are converted to node materials
+     * with their textures, and the originals stop rendering. Skinned/morphing meshes, points and lines are left
+     * alone. Returns the created meshes and a `dispose()` that restores the originals. See `VirtualGeometryImportOptions`.
+     */
+    add(object: THREE.Object3D, options?: VirtualGeometryImportOptions): Promise<VirtualGeometryImport>;
+    /** Create a renderable mesh from a built DAG. Add the result to any three.js scene. */
+    createMesh(data: VirtualMeshData, material: THREE.NodeMaterial, instances: VirtualMeshInstances, options?: VirtualMeshOptions): VirtualMesh;
+    /**
+     * Lever: compile a pool's compute pipelines in the background before its first dispatch (default), so adding
+     * meshes never freezes the page; they appear once ready. False: compile on first use (a hitch).
+     */
+    asyncCompile: boolean;
+    private compilePool;
+    /** Builds pools whose buffers grew and points their meshes at the new buffers. */
+    private preparePools;
+    /**
+     * Optional, for loading screens: compiles every pipeline the scene needs (compute and render), so the first
+     * frames neither freeze nor show meshes popping in. Call after adding the meshes, before the first render.
+     */
+    compileAsync(renderer: THREE.WebGPURenderer, scene: THREE.Object3D, camera: THREE.Camera): Promise<void>;
+    /** Called by meshes from onBeforeShadow: remembers the light direction for `autoShadowSweep`. */
+    noteShadowCamera(shadowCamera: THREE.Camera): void;
+    /** Puts the mesh's geometry and instances into the first pool with room (a new pool when none has). */
+    register(mesh: VirtualMesh, instances: VirtualMeshInstances): void;
+    /**
+     * Auto update, from a VirtualMesh's onBeforeRender. The first time, this also hooks the scene's onBeforeRender,
+     * which runs before the render pass starts (so shadow maps rendered inside the pass already see the new cut);
+     * later frames update from there. A compute submitted from inside a pass still runs before that pass on the
+     * GPU, because the pass is submitted when it ends.
+     */
+    private autoUpdateFor;
+    unregister(mesh: VirtualMesh): void;
+    /** Dispose every mesh created by this context. */
+    dispose(): void;
+    /**
+     * Runs LOD selection + culling on the GPU for `camera`. With `autoUpdate` (default) the renderer calls this
+     * for you before each render; call it yourself before `renderer.render` when `autoUpdate` is false.
+     * When the camera, the settings and every mesh's instances are unchanged, the compute passes are
+     * skipped and the previous cut (index buffer + draw args) is drawn again.
+     */
+    update(renderer: THREE.WebGPURenderer, camera: THREE.PerspectiveCamera): void;
+    /**
+     * True when anything the GPU cut reads from the context differs from the last frame that was computed
+     * (and records the new values). Exact comparison on purpose: an unmoved camera recomputes the same
+     * matrices bit for bit, while any real change, including a budget-controller step, differs.
+     */
+    private cutInputsChanged;
+    /**
+     * Slow multiplicative controller. Drawn triangles grow roughly with 1/threshold^2. Every change of the
+     * threshold re-picks LODs across the whole screen, so it moves rarely (deadband) and in small steps.
+     *
+     * Draw capacity is a hard constraint: an overflowing mesh drops meshlets in a different order every frame,
+     * which flickers. So the controller coarsens *before* a buffer is full, never refines into one, and may go
+     * above `thresholdRange[1]` only for capacity, coming back down as soon as there is room.
+     */
+    private adaptThreshold;
+    /**
+     * Without a budget the threshold is the user's, except that draw capacity stays a hard limit: coarsen
+     * temporarily before a buffer fills up, and return to the user's value once there is room again.
+     */
+    private guardCapacity;
+    /** GPU -> CPU readback of the last culling result. Async; never call every frame. One small readback per pool. */
+    readStats(renderer: THREE.WebGPURenderer): Promise<VirtualGeometryStats>;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * A renderable set of instances of one preprocessed mesh (a three.js Mesh, so it goes into any scene).
+ *
+ * The geometry and instances live in a GeometryPool shared with other meshes; the pool's compute passes select
+ * the cut for all of its meshes at once (see GeometryPool). This object holds the material and two geometries,
+ * the camera cut and the shadow cut, which draw this mesh's region of the pool's index buffers.
+ */
+import * as THREE from 'three/webgpu';
+import type { VirtualMeshData } from '../preprocess/buildVirtualMesh';
+import type { VirtualGeometry } from './VirtualGeometry';
+import { type GeometryPool, type PoolEntry } from './GeometryPool';
+export { vgWorldNormal, encodeOctNormal, packVertices, packUvs } from './GeometryPool';
+export interface VirtualMeshInstances {
+    /** 16 floats (column-major Matrix4) per instance. */
+    matrices: Float32Array;
+    /** Optional rgba tint per instance (multiplied with the material color). */
+    colors?: Float32Array;
+}
+export interface VirtualMeshOptions {
+    /**
+     * Cull distance in world units: instances farther than this are not drawn (and cost almost nothing, since
+     * whole cells are rejected at once). They shrink to nothing over the last 15% of the distance, so there is
+     * no visible pop. Default: Infinity. Can be changed later via `mesh.maxDrawDistance`.
+     */
+    maxDrawDistance?: number;
+    /**
+     * Hide instances whose bounding sphere is smaller than this many pixels (radius) on screen. Combined with
+     * `VirtualGeometry.minPixelRadius` (the larger one wins). Default: 0. Also settable via `mesh.minPixelRadius`.
+     */
+    minPixelRadius?: number;
+    /** @deprecated Draw capacity is shared per pool now: see `VirtualGeometryOptions`. Ignored. */
+    maxDrawnMeshlets?: number;
+    /** @deprecated Draw capacity is shared per pool now: see `VirtualGeometryOptions`. Ignored. */
+    maxDrawnTriangles?: number;
+}
+export declare class VirtualMesh extends THREE.Mesh<THREE.BufferGeometry, THREE.NodeMaterial> {
+    readonly isVirtualMesh = true;
+    readonly data: VirtualMeshData;
+    readonly instanceCount: number;
+    readonly fullDetailTriangles: number;
+    /** The pool holding this mesh's geometry and instances, and its record there. Set by `VirtualGeometry`. */
+    pool: GeometryPool;
+    entry: PoolEntry;
+    /** Geometries drawing this mesh's region of the pool's camera and shadow index buffers. */
+    readonly cameraGeometry: THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>;
+    readonly shadowGeometry: THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>;
+    /** `context.frameCount` of the last shadow-map render of this mesh. */
+    lastShadowFrame: number;
+    /**
+     * Lever: draw this mesh into the occlusion depth pass, so it can hide other geometry. Default: solid
+     * materials (opaque, single-sided, no alpha test). Foliage is mostly holes, so it only gets tested.
+     */
+    occluder: boolean;
+    /** Lever: let occlusion culling remove hidden instances and meshlets of this mesh. */
+    occlusionCulling: boolean;
+    /** GPU instance slot of each caller instance (inverse of the Morton order). */
+    readonly gpuIndexOf: Uint32Array;
+    /** Morton order: caller instance of each GPU slot. */
+    readonly gpuToInput: Uint32Array;
+    private readonly dirtyCells;
+    private drawingShadow;
+    private poolVersion;
+    private readonly context;
+    /** Cull distance in world units (Infinity: never). See `VirtualMeshOptions.maxDrawDistance`. */
+    get maxDrawDistance(): number;
+    set maxDrawDistance(distance: number);
+    /** Per-mesh minimum on-screen radius in pixels. See `VirtualMeshOptions.minPixelRadius`. */
+    get minPixelRadius(): number;
+    set minPixelRadius(pixels: number);
+    /** The pool's per-frame draw capacity (shared by every mesh of the pool). */
+    get capacity(): {
+        meshlets: number;
+        triangles: number;
+    };
+    constructor(context: VirtualGeometry, data: VirtualMeshData, material: THREE.NodeMaterial, instances: VirtualMeshInstances, options?: VirtualMeshOptions);
+    /** Points the geometries and the material at the pool's current buffers and nodes (after a pool rebuild). */
+    syncPool(): void;
+    /** Force the next `VirtualGeometry.update` to recompute the cut. */
+    markCutDirty(): void;
+    /** Update one instance transform. Call `commitInstances()` after a batch of changes. */
+    setMatrixAt(index: number, matrix: THREE.Matrix4): void;
+    commitInstances(): void;
+    /**
+     * Stop rendering this mesh and drop it from its context. The GPU buffers are released when the
+     * renderer frees them; call this before removing the object from the scene for good.
+     */
+    dispose(context?: VirtualGeometry): void;
+    /** Triangles drawn for this mesh by the last computed cut (camera and shadow), from one readback. */
+    readStats(renderer: THREE.WebGPURenderer): Promise<{
+        drawnTriangles: number;
+        shadowTriangles: number;
+    }>;
+}

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

@@ -0,0 +1,50 @@
+import type { VirtualMeshData } from '../preprocess/buildVirtualMesh';
+/** Camera parameters the LOD test needs. Same values the GPU pass uses. */
+export interface CutView {
+    /** Column-major world-to-view matrix (camera.matrixWorldInverse.elements). */
+    viewMatrix: ArrayLike<number>;
+    /** projection[1][1] * viewportHeight / 2: converts view-space error to pixels. */
+    projScale: number;
+    near: number;
+    /**
+     * Uniform scale of the instance, applied to the sphere radii and errors as the GPU does. `viewMatrix`
+     * must then include the instance's scale in its centers too (view * model). Default 1.
+     */
+    scale?: number;
+}
+/**
+ * CPU reference for the GPU LOD selection (no frustum culling, identity model matrix).
+ * A meshlet is in the cut when its own projected error is within `threshold` pixels and its
+ * parent's projected error is not. Returns one flag per meshlet.
+ *
+ * Use it to test the DAG (see `verifyCutCoverage`) or to pick LODs on the CPU, e.g. for physics or AI.
+ */
+export declare function selectCut(data: VirtualMeshData, view: CutView, threshold: number): Uint8Array;
+/**
+ * Checks that a cut has no holes: every leaf meshlet (LOD 0) is covered by a selected meshlet on its
+ * path to the coarsest level (itself or one of its replacements, recursively).
+ * Returns the indices of uncovered leaves (empty array = valid cut).
+ */
+export declare function verifyCutCoverage(data: VirtualMeshData, selected: Uint8Array): number[];
+/**
+ * CPU reference for the GPU instance pass: the contiguous range of meshlets (sorted by LOD level)
+ * that can possibly pass the LOD test for an instance, from distance bounds alone.
+ *
+ * Every LOD and parent sphere lies inside `lodBoundsSphere`, so the distance to any of them is within
+ * [D - R, D + R]. A level can contribute only if its smallest own error could be within the threshold
+ * at the farthest distance and its largest parent error could exceed it at the nearest.
+ * Returns [start, end) or [0, 0] when nothing can be selected.
+ */
+export declare function instanceMeshletRange(data: VirtualMeshData, view: CutView, threshold: number): [number, number];
+/**
+ * CPU reference for the GPU fast path of the instance pass. Returns the range [start, end) when every
+ * meshlet in it is guaranteed to be selected by the LOD test, for any distance the instance can have, and
+ * the range is at most FAST_PATH_MAX_MESHLETS long. Otherwise returns null (use the per-meshlet pass).
+ *
+ * Guarantee per level, over the distance band [dMin, dMax] of `instanceMeshletRange`:
+ *  - largest own error projects to <= threshold at dMin (its closest possible distance), and
+ *  - smallest parent error projects to > threshold at dMax (its farthest possible distance).
+ * A small relative margin keeps float rounding on the GPU from flipping a borderline meshlet.
+ * The caller must also check that the instance is fully inside the frustum (see `cullBoundsSphere`).
+ */
+export declare function instanceGuaranteedRange(data: VirtualMeshData, view: CutView, threshold: number): [number, number] | null;

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

@@ -0,0 +1,33 @@
+/**
+ * Texture coordinates for materials on a VirtualMesh.
+ *
+ * A VirtualMesh pulls its vertices from storage buffers, so its placeholder geometry has no `uv` attribute and
+ * three's default texture lookups (`uv()`) would read nothing. The vertex stage writes the pulled UV into the
+ * `vgUv` varying, and `bindVirtualGeometryTextures` points the material's textures at it.
+ */
+import * as THREE from 'three/webgpu';
+type Node = any;
+/** Interpolated texture coordinates of the current fragment (vec2), for custom material nodes. */
+export declare const vgUv: THREE.PropertyNode<"vec2">;
+/** Texture lookup at `vgUv`, with the texture's offset/repeat/rotation applied like three's own maps. */
+export declare function vgTexture(map: THREE.Texture): Node;
+/**
+ * Normal map without precomputed tangents: the tangent frame comes from screen-space derivatives of the view
+ * position and `vgUv` (same construction as three's derivative tangents, http://www.thetenthplanet.de/archives/1180).
+ */
+export declare function vgNormalMap(map: THREE.Texture, scale: Node, type?: THREE.NormalMapTypes): Node;
+/**
+ * Makes a material's textures sample `vgUv`. Called by VirtualMesh on the material it takes over.
+ *
+ * - `map` and `alphaMap` move into `colorNode` (and are cleared on the material): the shadow pass reads
+ *   `colorNode.a` for alpha-tested shadows, but would sample the material's `map` with the missing `uv()`.
+ * - Normal, bump and clearcoat normal maps become explicit normal nodes, because three builds normals in a
+ *   context that ignores custom UVs.
+ * - Every other texture lookup without explicit coordinates (roughness, metalness, emissive, AO, light,
+ *   clearcoat, sheen, transmission maps, textures in your own nodes, ...) gets `vgUv` through
+ *   `material.contextNode`. A `getUV` in your own `contextNode` takes precedence.
+ *
+ * Nodes the material already has are kept: only properties three would otherwise read implicitly are rewired.
+ */
+export declare function bindVirtualGeometryTextures(material: THREE.NodeMaterial): void;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * three-virtual-geometry: Virtual geometry for three.js WebGPU.
+ *
+ * Quick start:
+ *
+ *   import { VirtualGeometry } from 'three-virtual-geometry';
+ *
+ *   const vg = new VirtualGeometry();   // once
+ *   await vg.add(gltf.scene);         // converts its static meshes in place (materials, textures, instancing)
+ *   scene.add(gltf.scene);
+ *   renderer.render(scene, camera);       // LOD selection and culling run automatically before each render
+ *
+ * Lower level: `buildVirtualMeshCached(fromBufferGeometry(geometry))` once per mesh, then
+ * `vg.createMesh(data, material, { matrices })` (16 floats per instance) and add it to a scene.
+ */
+export { buildVirtualMesh } from './core/preprocess/buildVirtualMesh';
+export type { VirtualMeshBuildOptions, VirtualMeshData, VirtualMeshSource } from './core/preprocess/buildVirtualMesh';
+export { partitionMeshlets } from './core/preprocess/partition';
+export { buildVirtualMeshCached, clearVirtualMeshCache, virtualMeshCacheKey, VG_BUILD_VERSION } from './core/io/cache';
+export type { VirtualGeometryCacheOptions, VirtualGeometryCachedBuildOptions } from './core/io/cache';
+export { decodeVirtualMesh, encodeVirtualMesh, loadVirtualMesh, VirtualMeshFormatError, VG_FORMAT_VERSION } from './core/io/serialize';
+export type { VirtualMeshEncodeOptions } from './core/io/serialize';
+export { instanceGuaranteedRange, instanceMeshletRange, selectCut, verifyCutCoverage } from './core/runtime/cut';
+export type { CutView } from './core/runtime/cut';
+export { VirtualMesh, vgWorldNormal } from './core/runtime/VirtualMesh';
+export { vgUv, vgTexture, vgNormalMap, bindVirtualGeometryTextures } from './core/runtime/vgMaterial';
+export { toNodeMaterial, canConvertToNodeMaterial } from './core/import/toNodeMaterial';
+export { virtualMeshesFromObject3D, collectVirtualGeometryGroups, VirtualGeometryImport } from './core/import/fromObject3D';
+export type { VirtualGeometryImportOptions, VirtualGeometryImportGroup, VirtualGeometryBuilder } from './core/import/fromObject3D';
+export type { VirtualMeshInstances, VirtualMeshOptions } from './core/runtime/VirtualMesh';
+export { VirtualGeometry } from './core/runtime/VirtualGeometry';
+export type { VirtualGeometryStats, VirtualGeometryOptions } from './core/runtime/VirtualGeometry';
+export { VG_DEBUG_MODES, MAX_MESHLET_TRIANGLES, MAX_MESHLET_VERTICES } from './core/constants';
+export { fromBufferGeometry, mergeSources } from './source';
+export type { FromGeometryOptions } from './source';