@hello-terrain/three 0.0.0-alpha.1 → 0.0.0-alpha.2

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import * as THREE from 'three';
 import { BufferGeometry } from 'three';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { Node } from 'three/webgpu';
@@ -113,4 +114,261 @@ declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: numb
  */
 declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
 
-export { TerrainGeometry, isSkirtUV, isSkirtVertex };
+type NeighborIndices = [number, number, number, number];
+type ChildIndices = [number, number, number, number];
+/**
+ * Class that manages all node-related buffer arrays and provides access methods
+ */
+declare class QuadtreeNodeView {
+    private maxNodeCount;
+    private childrenIndicesBuffer;
+    private neighborsIndicesBuffer;
+    private nodeBuffer;
+    private leafNodeMask;
+    private leafNodeCountBuffer;
+    private activeLeafIndices;
+    private activeLeafCount;
+    constructor(maxNodeCount: number, childrenIndicesBuffer?: Uint16Array, neighborsIndicesBuffer?: Uint16Array, nodeBuffer?: Int32Array, leafNodeMask?: Uint8Array, leafNodeCountBuffer?: Uint16Array);
+    /**
+     * Clear all buffers
+     */
+    clear(): void;
+    /**
+     * Get buffer references for direct access (useful for GPU operations)
+     */
+    getBuffers(): {
+        childrenIndicesBuffer: Uint16Array<ArrayBufferLike>;
+        neighborsIndicesBuffer: Uint16Array<ArrayBufferLike>;
+        nodeBuffer: Int32Array<ArrayBufferLike>;
+        leafNodeMask: Uint8Array<ArrayBufferLike>;
+    };
+    /**
+     * Get the maximum node count
+     */
+    getMaxNodeCount(): number;
+    getLevel(index: number): number;
+    getX(index: number): number;
+    getY(index: number): number;
+    getLeafNodeCount(): number;
+    getLeaf(index: number): boolean;
+    getChildren(index: number): ChildIndices;
+    getNeighbors(index: number): NeighborIndices;
+    setLevel(index: number, level: number): void;
+    setX(index: number, x: number): void;
+    setY(index: number, y: number): void;
+    setLeaf(index: number, leaf: boolean): void;
+    setChildren(index: number, children: ChildIndices): void;
+    setNeighbors(index: number, neighbors: NeighborIndices): void;
+    /**
+     * Get array of active leaf node indices with count (zero-copy, no allocation)
+     */
+    getActiveLeafNodeIndices(): {
+        indices: Uint16Array;
+        count: number;
+    };
+    /**
+     * Release internal buffers and mark this view as destroyed
+     */
+    destroy(): void;
+    clone(): QuadtreeNodeView;
+}
+
+/**
+ * Context passed to subdivision strategy functions.
+ * Contains all information needed to make subdivision decisions.
+ */
+interface SubdivisionContext {
+    /** Current node's quadtree level (0 = root) */
+    level: number;
+    /** Distance from camera/position to node center in world units */
+    distance: number;
+    /** World-space size of the node (edge length) */
+    nodeSize: number;
+    /** Minimum allowed node size from config */
+    minNodeSize: number;
+    /** Root terrain size from config */
+    rootSize: number;
+}
+/**
+ * Function type for subdivision strategies.
+ * Returns true if the node should be subdivided, false otherwise.
+ */
+type SubdivisionStrategy = (context: SubdivisionContext) => boolean;
+/**
+ * Screen-space projection info for LOD calculations.
+ * Computed from camera properties each frame.
+ */
+interface ScreenSpaceInfo {
+    /**
+     * Projection factor: screenHeight / (2 * tan(fovY / 2))
+     * This converts world-space size to screen-space pixels at distance 1.
+     */
+    projectionFactor: number;
+    /**
+     * Screen height in pixels (for reference/debugging)
+     */
+    screenHeight: number;
+}
+/**
+ * Distance-based subdivision strategy with hysteresis to prevent LOD flickering.
+ * Subdivides when: distance < nodeSize * factor
+ *
+ * @param factor Multiplier for subdivision threshold (default: 2)
+ * @returns SubdivisionStrategy function
+ */
+declare function distanceBasedSubdivision(factor?: number): SubdivisionStrategy;
+/**
+ * Screen-space subdivision strategy.
+ * Subdivides based on projected triangle size in pixels.
+ * Ensures triangles don't exceed a target pixel size on screen.
+ *
+ * @param options Configuration for screen-space subdivision
+ * @returns SubdivisionStrategy function
+ */
+declare function screenSpaceSubdivision(options: {
+    /**
+     * Target triangle size in screen pixels.
+     * Subdivide when triangles would be larger than this.
+     * Recommended: 4-8 pixels
+     * @default 6
+     */
+    targetTrianglePixels?: number;
+    /**
+     * Number of segments per tile edge.
+     * Should match TerrainMesh.innerTileSegments.
+     * @default 13
+     */
+    tileSegments?: number;
+    /**
+     * Function that returns current screen-space projection info.
+     * Called each time subdivision is evaluated.
+     */
+    getScreenSpaceInfo: () => ScreenSpaceInfo | null;
+}): SubdivisionStrategy;
+/**
+ * Compute screen-space info from camera parameters.
+ * Helper function to create ScreenSpaceInfo from typical Three.js camera values.
+ *
+ * @param fovY Vertical field of view in radians
+ * @param screenHeight Screen height in pixels
+ * @returns ScreenSpaceInfo for use with screenSpaceSubdivision
+ *
+ * @example
+ * ```ts
+ * // In your render loop:
+ * const fovRadians = camera.fov * Math.PI / 180;
+ * const screenInfo = computeScreenSpaceInfo(fovRadians, renderer.domElement.height);
+ * ```
+ */
+declare function computeScreenSpaceInfo(fovY: number, screenHeight: number): ScreenSpaceInfo;
+
+interface QuadtreeParams {
+    maxLevel: number;
+    rootSize: number;
+    minNodeSize: number;
+    origin: THREE.Vector3;
+    maxNodes: number;
+}
+declare class Quadtree {
+    private nodeCount;
+    private deepestLevel;
+    private config;
+    private nodeView;
+    private subdivisionStrategy;
+    private tempChildIndices;
+    private tempNeighborIndices;
+    /**
+     * Create a new Quadtree.
+     *
+     * @param config Quadtree configuration parameters
+     * @param subdivisionStrategy Strategy function for subdivision decisions.
+     *        Defaults to distanceBasedSubdivision(2).
+     * @param nodeView Optional pre-allocated NodeView for buffer reuse
+     */
+    constructor(config: QuadtreeParams, subdivisionStrategy?: SubdivisionStrategy, nodeView?: QuadtreeNodeView);
+    /**
+     * Set the subdivision strategy.
+     * Use this to change LOD behavior at runtime.
+     *
+     * @param strategy The subdivision strategy function
+     */
+    setSubdivisionStrategy(strategy: SubdivisionStrategy): void;
+    /**
+     * Get the current subdivision strategy
+     */
+    getSubdivisionStrategy(): SubdivisionStrategy;
+    private initialize;
+    /**
+     * Update the quadtree based on the given position and return the index
+     * of the leaf node that best corresponds to the position (closest leaf).
+     */
+    update(position: THREE.Vector3, frustum?: THREE.Frustum): number;
+    /**
+     * Recursively update a node and its children based on distance and size criteria
+     * and return the closest leaf node index to the provided position.
+     */
+    private updateNode;
+    /**
+     * Determine if a node should be subdivided using the configured strategy
+     */
+    private shouldSubdivide;
+    /**
+     * Create a new node and return its index
+     */
+    private createNode;
+    /**
+     * Subdivide a node by creating its four children
+     */
+    private subdivideNode;
+    /**
+     * Update neighbor relationships for child nodes
+     */
+    private updateChildNeighbors;
+    /**
+     * Get the deepest subdivision level currently in the quadtree
+     */
+    getDeepestLevel(): number;
+    /**
+     * Get the total number of nodes
+     */
+    getNodeCount(): number;
+    getLeafNodeCount(): number;
+    /**
+     * Get active leaf node indices for efficient GPU processing
+     */
+    getActiveLeafNodeIndices(): {
+        indices: Uint16Array;
+        count: number;
+    };
+    /**
+     * Get the configuration
+     */
+    getConfig(): QuadtreeParams;
+    /**
+     * Get all leaf nodes as an array of node objects
+     */
+    getLeafNodes(): Array<{
+        level: number;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Reset the quadtree
+     */
+    reset(): void;
+    /**
+     * Get the NodeView instance for direct access
+     */
+    getNodeView(): QuadtreeNodeView;
+    /**
+     * Release internal resources associated with this quadtree
+     */
+    destroy(): void;
+    /**
+     * Set the configuration
+     */
+    setConfig(config: QuadtreeParams, reset?: boolean): void;
+}
+
+export { Quadtree, TerrainGeometry, computeScreenSpaceInfo, distanceBasedSubdivision, isSkirtUV, isSkirtVertex, screenSpaceSubdivision };
+export type { QuadtreeParams, ScreenSpaceInfo, SubdivisionContext, SubdivisionStrategy };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import * as THREE from 'three';
 import { BufferGeometry } from 'three';
 import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
 import { Node } from 'three/webgpu';
@@ -113,4 +114,261 @@ declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: numb
  */
 declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
 
-export { TerrainGeometry, isSkirtUV, isSkirtVertex };
+type NeighborIndices = [number, number, number, number];
+type ChildIndices = [number, number, number, number];
+/**
+ * Class that manages all node-related buffer arrays and provides access methods
+ */
+declare class QuadtreeNodeView {
+    private maxNodeCount;
+    private childrenIndicesBuffer;
+    private neighborsIndicesBuffer;
+    private nodeBuffer;
+    private leafNodeMask;
+    private leafNodeCountBuffer;
+    private activeLeafIndices;
+    private activeLeafCount;
+    constructor(maxNodeCount: number, childrenIndicesBuffer?: Uint16Array, neighborsIndicesBuffer?: Uint16Array, nodeBuffer?: Int32Array, leafNodeMask?: Uint8Array, leafNodeCountBuffer?: Uint16Array);
+    /**
+     * Clear all buffers
+     */
+    clear(): void;
+    /**
+     * Get buffer references for direct access (useful for GPU operations)
+     */
+    getBuffers(): {
+        childrenIndicesBuffer: Uint16Array<ArrayBufferLike>;
+        neighborsIndicesBuffer: Uint16Array<ArrayBufferLike>;
+        nodeBuffer: Int32Array<ArrayBufferLike>;
+        leafNodeMask: Uint8Array<ArrayBufferLike>;
+    };
+    /**
+     * Get the maximum node count
+     */
+    getMaxNodeCount(): number;
+    getLevel(index: number): number;
+    getX(index: number): number;
+    getY(index: number): number;
+    getLeafNodeCount(): number;
+    getLeaf(index: number): boolean;
+    getChildren(index: number): ChildIndices;
+    getNeighbors(index: number): NeighborIndices;
+    setLevel(index: number, level: number): void;
+    setX(index: number, x: number): void;
+    setY(index: number, y: number): void;
+    setLeaf(index: number, leaf: boolean): void;
+    setChildren(index: number, children: ChildIndices): void;
+    setNeighbors(index: number, neighbors: NeighborIndices): void;
+    /**
+     * Get array of active leaf node indices with count (zero-copy, no allocation)
+     */
+    getActiveLeafNodeIndices(): {
+        indices: Uint16Array;
+        count: number;
+    };
+    /**
+     * Release internal buffers and mark this view as destroyed
+     */
+    destroy(): void;
+    clone(): QuadtreeNodeView;
+}
+
+/**
+ * Context passed to subdivision strategy functions.
+ * Contains all information needed to make subdivision decisions.
+ */
+interface SubdivisionContext {
+    /** Current node's quadtree level (0 = root) */
+    level: number;
+    /** Distance from camera/position to node center in world units */
+    distance: number;
+    /** World-space size of the node (edge length) */
+    nodeSize: number;
+    /** Minimum allowed node size from config */
+    minNodeSize: number;
+    /** Root terrain size from config */
+    rootSize: number;
+}
+/**
+ * Function type for subdivision strategies.
+ * Returns true if the node should be subdivided, false otherwise.
+ */
+type SubdivisionStrategy = (context: SubdivisionContext) => boolean;
+/**
+ * Screen-space projection info for LOD calculations.
+ * Computed from camera properties each frame.
+ */
+interface ScreenSpaceInfo {
+    /**
+     * Projection factor: screenHeight / (2 * tan(fovY / 2))
+     * This converts world-space size to screen-space pixels at distance 1.
+     */
+    projectionFactor: number;
+    /**
+     * Screen height in pixels (for reference/debugging)
+     */
+    screenHeight: number;
+}
+/**
+ * Distance-based subdivision strategy with hysteresis to prevent LOD flickering.
+ * Subdivides when: distance < nodeSize * factor
+ *
+ * @param factor Multiplier for subdivision threshold (default: 2)
+ * @returns SubdivisionStrategy function
+ */
+declare function distanceBasedSubdivision(factor?: number): SubdivisionStrategy;
+/**
+ * Screen-space subdivision strategy.
+ * Subdivides based on projected triangle size in pixels.
+ * Ensures triangles don't exceed a target pixel size on screen.
+ *
+ * @param options Configuration for screen-space subdivision
+ * @returns SubdivisionStrategy function
+ */
+declare function screenSpaceSubdivision(options: {
+    /**
+     * Target triangle size in screen pixels.
+     * Subdivide when triangles would be larger than this.
+     * Recommended: 4-8 pixels
+     * @default 6
+     */
+    targetTrianglePixels?: number;
+    /**
+     * Number of segments per tile edge.
+     * Should match TerrainMesh.innerTileSegments.
+     * @default 13
+     */
+    tileSegments?: number;
+    /**
+     * Function that returns current screen-space projection info.
+     * Called each time subdivision is evaluated.
+     */
+    getScreenSpaceInfo: () => ScreenSpaceInfo | null;
+}): SubdivisionStrategy;
+/**
+ * Compute screen-space info from camera parameters.
+ * Helper function to create ScreenSpaceInfo from typical Three.js camera values.
+ *
+ * @param fovY Vertical field of view in radians
+ * @param screenHeight Screen height in pixels
+ * @returns ScreenSpaceInfo for use with screenSpaceSubdivision
+ *
+ * @example
+ * ```ts
+ * // In your render loop:
+ * const fovRadians = camera.fov * Math.PI / 180;
+ * const screenInfo = computeScreenSpaceInfo(fovRadians, renderer.domElement.height);
+ * ```
+ */
+declare function computeScreenSpaceInfo(fovY: number, screenHeight: number): ScreenSpaceInfo;
+
+interface QuadtreeParams {
+    maxLevel: number;
+    rootSize: number;
+    minNodeSize: number;
+    origin: THREE.Vector3;
+    maxNodes: number;
+}
+declare class Quadtree {
+    private nodeCount;
+    private deepestLevel;
+    private config;
+    private nodeView;
+    private subdivisionStrategy;
+    private tempChildIndices;
+    private tempNeighborIndices;
+    /**
+     * Create a new Quadtree.
+     *
+     * @param config Quadtree configuration parameters
+     * @param subdivisionStrategy Strategy function for subdivision decisions.
+     *        Defaults to distanceBasedSubdivision(2).
+     * @param nodeView Optional pre-allocated NodeView for buffer reuse
+     */
+    constructor(config: QuadtreeParams, subdivisionStrategy?: SubdivisionStrategy, nodeView?: QuadtreeNodeView);
+    /**
+     * Set the subdivision strategy.
+     * Use this to change LOD behavior at runtime.
+     *
+     * @param strategy The subdivision strategy function
+     */
+    setSubdivisionStrategy(strategy: SubdivisionStrategy): void;
+    /**
+     * Get the current subdivision strategy
+     */
+    getSubdivisionStrategy(): SubdivisionStrategy;
+    private initialize;
+    /**
+     * Update the quadtree based on the given position and return the index
+     * of the leaf node that best corresponds to the position (closest leaf).
+     */
+    update(position: THREE.Vector3, frustum?: THREE.Frustum): number;
+    /**
+     * Recursively update a node and its children based on distance and size criteria
+     * and return the closest leaf node index to the provided position.
+     */
+    private updateNode;
+    /**
+     * Determine if a node should be subdivided using the configured strategy
+     */
+    private shouldSubdivide;
+    /**
+     * Create a new node and return its index
+     */
+    private createNode;
+    /**
+     * Subdivide a node by creating its four children
+     */
+    private subdivideNode;
+    /**
+     * Update neighbor relationships for child nodes
+     */
+    private updateChildNeighbors;
+    /**
+     * Get the deepest subdivision level currently in the quadtree
+     */
+    getDeepestLevel(): number;
+    /**
+     * Get the total number of nodes
+     */
+    getNodeCount(): number;
+    getLeafNodeCount(): number;
+    /**
+     * Get active leaf node indices for efficient GPU processing
+     */
+    getActiveLeafNodeIndices(): {
+        indices: Uint16Array;
+        count: number;
+    };
+    /**
+     * Get the configuration
+     */
+    getConfig(): QuadtreeParams;
+    /**
+     * Get all leaf nodes as an array of node objects
+     */
+    getLeafNodes(): Array<{
+        level: number;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Reset the quadtree
+     */
+    reset(): void;
+    /**
+     * Get the NodeView instance for direct access
+     */
+    getNodeView(): QuadtreeNodeView;
+    /**
+     * Release internal resources associated with this quadtree
+     */
+    destroy(): void;
+    /**
+     * Set the configuration
+     */
+    setConfig(config: QuadtreeParams, reset?: boolean): void;
+}
+
+export { Quadtree, TerrainGeometry, computeScreenSpaceInfo, distanceBasedSubdivision, isSkirtUV, isSkirtVertex, screenSpaceSubdivision };
+export type { QuadtreeParams, ScreenSpaceInfo, SubdivisionContext, SubdivisionStrategy };