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

package/dist/index.cjs

@@ -1,9 +1,23 @@
 'use strict';
 
-const three = require('three');
+const THREE = require('three');
 const tsl = require('three/tsl');
 
-class TerrainGeometry extends three.BufferGeometry {
+function _interopNamespaceCompat(e) {
+  if (e && typeof e === 'object' && 'default' in e) return e;
+  const n = Object.create(null);
+  if (e) {
+    for (const k in e) {
+      n[k] = e[k];
+    }
+  }
+  n.default = e;
+  return n;
+}
+
+const THREE__namespace = /*#__PURE__*/_interopNamespaceCompat(THREE);
+
+class TerrainGeometry extends THREE.BufferGeometry {
   constructor(innerSegments = 14, extendUV = false) {
     super();
     if (innerSegments < 1 || !Number.isFinite(innerSegments) || !Number.isInteger(innerSegments)) {
@@ -15,21 +29,21 @@ class TerrainGeometry extends three.BufferGeometry {
       this.setIndex(this.generateIndices(innerSegments));
       this.setAttribute(
         "position",
-        new three.BufferAttribute(
+        new THREE.BufferAttribute(
           new Float32Array(this.generatePositions(innerSegments)),
           3
         )
       );
       this.setAttribute(
         "normal",
-        new three.BufferAttribute(
+        new THREE.BufferAttribute(
           new Float32Array(this.generateNormals(innerSegments)),
           3
         )
       );
       this.setAttribute(
         "uv",
-        new three.BufferAttribute(
+        new THREE.BufferAttribute(
           new Float32Array(
             extendUV ? this.generateUvsExtended(innerSegments) : this.generateUvsOnlyInner(innerSegments)
           ),
@@ -235,6 +249,487 @@ const isSkirtUV = tsl.Fn(([segments]) => {
   return innerX.and(innerY).not();
 });
 
+const CHILDREN_STRIDE = 4;
+const NEIGHBORS_STRIDE = 4;
+const NODE_STRIDE = 4;
+const U_INT_16_MAX_VALUE = 65535;
+const EMPTY_SENTINEL_VALUE = U_INT_16_MAX_VALUE;
+class QuadtreeNodeView {
+  maxNodeCount;
+  childrenIndicesBuffer;
+  neighborsIndicesBuffer;
+  nodeBuffer;
+  leafNodeMask;
+  leafNodeCountBuffer;
+  activeLeafIndices;
+  activeLeafCount = 0;
+  constructor(maxNodeCount, childrenIndicesBuffer, neighborsIndicesBuffer, nodeBuffer, leafNodeMask, leafNodeCountBuffer) {
+    this.maxNodeCount = maxNodeCount;
+    this.childrenIndicesBuffer = childrenIndicesBuffer ?? new Uint16Array(CHILDREN_STRIDE * maxNodeCount);
+    this.neighborsIndicesBuffer = neighborsIndicesBuffer ?? new Uint16Array(NEIGHBORS_STRIDE * maxNodeCount);
+    this.nodeBuffer = nodeBuffer ?? new Int32Array(NODE_STRIDE * maxNodeCount);
+    this.leafNodeMask = leafNodeMask ?? new Uint8Array(maxNodeCount);
+    this.leafNodeCountBuffer = leafNodeCountBuffer ?? new Uint16Array(1);
+    this.activeLeafIndices = new Uint16Array(maxNodeCount);
+    this.clear();
+  }
+  /**
+   * Clear all buffers
+   */
+  clear() {
+    this.nodeBuffer.fill(0);
+    this.childrenIndicesBuffer.fill(EMPTY_SENTINEL_VALUE);
+    this.neighborsIndicesBuffer.fill(EMPTY_SENTINEL_VALUE);
+    this.leafNodeMask.fill(0);
+    this.leafNodeCountBuffer[0] = 0;
+    this.activeLeafCount = 0;
+  }
+  /**
+   * Get buffer references for direct access (useful for GPU operations)
+   */
+  getBuffers() {
+    return {
+      childrenIndicesBuffer: this.childrenIndicesBuffer,
+      neighborsIndicesBuffer: this.neighborsIndicesBuffer,
+      nodeBuffer: this.nodeBuffer,
+      leafNodeMask: this.leafNodeMask
+    };
+  }
+  /**
+   * Get the maximum node count
+   */
+  getMaxNodeCount() {
+    return this.maxNodeCount;
+  }
+  // Getters for individual buffer values
+  getLevel(index) {
+    return this.nodeBuffer[index * NODE_STRIDE];
+  }
+  getX(index) {
+    return this.nodeBuffer[index * NODE_STRIDE + 1];
+  }
+  getY(index) {
+    return this.nodeBuffer[index * NODE_STRIDE + 2];
+  }
+  getLeafNodeCount() {
+    return this.leafNodeCountBuffer[0];
+  }
+  getLeaf(index) {
+    return this.leafNodeMask[index] === 1;
+  }
+  getChildren(index) {
+    const offset = index * CHILDREN_STRIDE;
+    return [
+      this.childrenIndicesBuffer[offset],
+      this.childrenIndicesBuffer[offset + 1],
+      this.childrenIndicesBuffer[offset + 2],
+      this.childrenIndicesBuffer[offset + 3]
+    ];
+  }
+  getNeighbors(index) {
+    const offset = index * NEIGHBORS_STRIDE;
+    return [
+      this.neighborsIndicesBuffer[offset],
+      this.neighborsIndicesBuffer[offset + 1],
+      this.neighborsIndicesBuffer[offset + 2],
+      this.neighborsIndicesBuffer[offset + 3]
+    ];
+  }
+  // Setters for individual buffer values
+  setLevel(index, level) {
+    this.nodeBuffer[index * NODE_STRIDE] = level;
+  }
+  setX(index, x) {
+    this.nodeBuffer[index * NODE_STRIDE + 1] = x;
+  }
+  setY(index, y) {
+    this.nodeBuffer[index * NODE_STRIDE + 2] = y;
+  }
+  setLeaf(index, leaf) {
+    const wasLeaf = this.leafNodeMask[index] === 1;
+    const newValue = leaf ? 1 : 0;
+    if (leaf && !wasLeaf) {
+      this.leafNodeCountBuffer[0]++;
+      this.leafNodeMask[index] = 1;
+      this.activeLeafIndices[this.activeLeafCount] = index;
+      this.activeLeafCount++;
+      this.setChildren(index, [
+        EMPTY_SENTINEL_VALUE,
+        EMPTY_SENTINEL_VALUE,
+        EMPTY_SENTINEL_VALUE,
+        EMPTY_SENTINEL_VALUE
+      ]);
+    } else if (!leaf && wasLeaf) {
+      this.leafNodeCountBuffer[0]--;
+      this.leafNodeMask[index] = 0;
+    }
+    this.nodeBuffer[index * NODE_STRIDE + 3] = newValue;
+  }
+  setChildren(index, children) {
+    const offset = index * CHILDREN_STRIDE;
+    this.childrenIndicesBuffer[offset] = children[0];
+    this.childrenIndicesBuffer[offset + 1] = children[1];
+    this.childrenIndicesBuffer[offset + 2] = children[2];
+    this.childrenIndicesBuffer[offset + 3] = children[3];
+  }
+  setNeighbors(index, neighbors) {
+    const offset = index * NEIGHBORS_STRIDE;
+    this.neighborsIndicesBuffer[offset] = neighbors[0];
+    this.neighborsIndicesBuffer[offset + 1] = neighbors[1];
+    this.neighborsIndicesBuffer[offset + 2] = neighbors[2];
+    this.neighborsIndicesBuffer[offset + 3] = neighbors[3];
+  }
+  /**
+   * Get array of active leaf node indices with count (zero-copy, no allocation)
+   */
+  getActiveLeafNodeIndices() {
+    return {
+      indices: this.activeLeafIndices,
+      count: this.activeLeafCount
+    };
+  }
+  /**
+   * Release internal buffers and mark this view as destroyed
+   */
+  destroy() {
+    this.childrenIndicesBuffer = new Uint16Array(0);
+    this.neighborsIndicesBuffer = new Uint16Array(0);
+    this.nodeBuffer = new Int32Array(0);
+    this.leafNodeMask = new Uint8Array(0);
+    this.leafNodeCountBuffer = new Uint16Array(0);
+    this.maxNodeCount = 0;
+  }
+  clone() {
+    return new QuadtreeNodeView(
+      this.maxNodeCount,
+      this.childrenIndicesBuffer,
+      this.neighborsIndicesBuffer,
+      this.nodeBuffer,
+      this.leafNodeMask,
+      this.leafNodeCountBuffer
+    );
+  }
+}
+
+function distanceBasedSubdivision(factor = 2) {
+  return (ctx) => {
+    if (ctx.nodeSize <= ctx.minNodeSize) {
+      return false;
+    }
+    return ctx.distance < ctx.nodeSize * factor;
+  };
+}
+function screenSpaceSubdivision(options) {
+  const targetTrianglePixels = options.targetTrianglePixels ?? 6;
+  const tileSegments = options.tileSegments ?? 13;
+  return (ctx) => {
+    if (ctx.nodeSize <= ctx.minNodeSize) {
+      return false;
+    }
+    const screenInfo = options.getScreenSpaceInfo();
+    if (!screenInfo) {
+      return ctx.distance < ctx.nodeSize * 2;
+    }
+    const safeDistance = Math.max(ctx.distance, 1e-3);
+    const tileScreenSize = ctx.nodeSize / safeDistance * screenInfo.projectionFactor;
+    const triangleScreenSize = tileScreenSize / tileSegments;
+    return triangleScreenSize > targetTrianglePixels;
+  };
+}
+function computeScreenSpaceInfo(fovY, screenHeight) {
+  const projectionFactor = screenHeight / (2 * Math.tan(fovY / 2));
+  return { projectionFactor, screenHeight };
+}
+
+const tempVector3 = new THREE__namespace.Vector3();
+const tempBox3 = new THREE__namespace.Box3();
+const tempMin = new THREE__namespace.Vector3();
+const tempMax = new THREE__namespace.Vector3();
+class Quadtree {
+  nodeCount = 0;
+  deepestLevel = 0;
+  config;
+  nodeView;
+  subdivisionStrategy;
+  // Pre-allocated buffers to avoid object creation
+  tempChildIndices = [-1, -1, -1, -1];
+  tempNeighborIndices = [-1, -1, -1, -1];
+  /**
+   * 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, subdivisionStrategy, nodeView) {
+    this.config = config;
+    this.subdivisionStrategy = subdivisionStrategy ?? distanceBasedSubdivision(2);
+    this.nodeView = nodeView ?? new QuadtreeNodeView(config.maxNodes);
+    this.initialize();
+  }
+  /**
+   * Set the subdivision strategy.
+   * Use this to change LOD behavior at runtime.
+   *
+   * @param strategy The subdivision strategy function
+   */
+  setSubdivisionStrategy(strategy) {
+    this.subdivisionStrategy = strategy;
+  }
+  /**
+   * Get the current subdivision strategy
+   */
+  getSubdivisionStrategy() {
+    return this.subdivisionStrategy;
+  }
+  initialize() {
+    this.nodeView.clear();
+    this.nodeCount = 0;
+    this.deepestLevel = 0;
+    this.createNode(0, 0, 0);
+  }
+  /**
+   * 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, frustum) {
+    this.reset();
+    const closestLeafIndex = this.updateNode(0, position, frustum);
+    return closestLeafIndex;
+  }
+  /**
+   * Recursively update a node and its children based on distance and size criteria
+   * and return the closest leaf node index to the provided position.
+   */
+  updateNode(nodeIndex, position, frustum) {
+    const level = this.nodeView.getLevel(nodeIndex);
+    const nodeSize = this.config.rootSize / (1 << level);
+    const nodeX = this.nodeView.getX(nodeIndex);
+    const nodeY = this.nodeView.getY(nodeIndex);
+    const minX = this.config.origin.x + (nodeX * nodeSize - 0.5 * this.config.rootSize);
+    const minZ = this.config.origin.z + (nodeY * nodeSize - 0.5 * this.config.rootSize);
+    const worldX = minX + 0.5 * nodeSize;
+    const worldZ = minZ + 0.5 * nodeSize;
+    if (frustum) {
+      const altitude = Math.abs(position.y - this.config.origin.y);
+      const verticalHalfExtent = this.config.rootSize + altitude;
+      const minY = this.config.origin.y - verticalHalfExtent;
+      const maxY = this.config.origin.y + verticalHalfExtent;
+      tempMin.set(minX, minY, minZ);
+      tempMax.set(minX + nodeSize, maxY, minZ + nodeSize);
+      tempBox3.set(tempMin, tempMax);
+      if (!frustum.intersectsBox(tempBox3)) {
+        this.nodeView.setLeaf(nodeIndex, false);
+        return -1;
+      }
+    }
+    tempVector3.set(worldX, this.config.origin.y, worldZ);
+    const distance = position.distanceTo(tempVector3);
+    const shouldSubdivide = this.shouldSubdivide(level, distance, nodeSize);
+    if (shouldSubdivide && level < this.config.maxLevel) {
+      if (this.nodeCount + 4 > this.config.maxNodes) {
+        this.nodeView.setLeaf(nodeIndex, true);
+        return nodeIndex;
+      }
+      this.subdivideNode(nodeIndex);
+      const children = this.nodeView.getChildren(nodeIndex);
+      let bestLeafIndex = -1;
+      let bestDistSq = Number.POSITIVE_INFINITY;
+      for (let i = 0; i < 4; i++) {
+        if (children[i] !== -1) {
+          const leafIdx = this.updateNode(children[i], position, frustum);
+          if (leafIdx !== -1) {
+            const leafLevel = this.nodeView.getLevel(leafIdx);
+            const size = this.config.rootSize / (1 << leafLevel);
+            const x = this.nodeView.getX(leafIdx);
+            const y = this.nodeView.getY(leafIdx);
+            const cx = this.config.origin.x + ((x + 0.5) * size - 0.5 * this.config.rootSize);
+            const cz = this.config.origin.z + ((y + 0.5) * size - 0.5 * this.config.rootSize);
+            const dx = position.x - cx;
+            const dz = position.z - cz;
+            const d2 = dx * dx + dz * dz;
+            if (d2 < bestDistSq) {
+              bestDistSq = d2;
+              bestLeafIndex = leafIdx;
+            }
+          }
+        }
+      }
+      this.nodeView.setLeaf(nodeIndex, false);
+      return bestLeafIndex;
+    }
+    this.nodeView.setLeaf(nodeIndex, true);
+    return nodeIndex;
+  }
+  /**
+   * Determine if a node should be subdivided using the configured strategy
+   */
+  shouldSubdivide(level, distance, nodeSize) {
+    const context = {
+      level,
+      distance,
+      nodeSize,
+      minNodeSize: this.config.minNodeSize,
+      rootSize: this.config.rootSize
+    };
+    return this.subdivisionStrategy(context);
+  }
+  /**
+   * Create a new node and return its index
+   */
+  createNode(level, x, y) {
+    if (this.nodeCount >= this.config.maxNodes) {
+      console.warn("Maximum node count reached, skipping node creation");
+      return -1;
+    }
+    if (level > this.deepestLevel) {
+      this.deepestLevel = level;
+    }
+    this.tempChildIndices[0] = EMPTY_SENTINEL_VALUE;
+    this.tempChildIndices[1] = EMPTY_SENTINEL_VALUE;
+    this.tempChildIndices[2] = EMPTY_SENTINEL_VALUE;
+    this.tempChildIndices[3] = EMPTY_SENTINEL_VALUE;
+    this.tempNeighborIndices[0] = EMPTY_SENTINEL_VALUE;
+    this.tempNeighborIndices[1] = EMPTY_SENTINEL_VALUE;
+    this.tempNeighborIndices[2] = EMPTY_SENTINEL_VALUE;
+    this.tempNeighborIndices[3] = EMPTY_SENTINEL_VALUE;
+    const nodeIndex = this.nodeCount++;
+    this.nodeView.setLevel(nodeIndex, level);
+    this.nodeView.setX(nodeIndex, x);
+    this.nodeView.setY(nodeIndex, y);
+    this.nodeView.setChildren(nodeIndex, this.tempChildIndices);
+    this.nodeView.setNeighbors(nodeIndex, this.tempNeighborIndices);
+    this.nodeView.setLeaf(nodeIndex, false);
+    return nodeIndex;
+  }
+  /**
+   * Subdivide a node by creating its four children
+   */
+  subdivideNode(nodeIndex) {
+    const childLevel = this.nodeView.getLevel(nodeIndex) + 1;
+    const childX = this.nodeView.getX(nodeIndex) * 2;
+    const childY = this.nodeView.getY(nodeIndex) * 2;
+    const childIndices = [
+      this.createNode(childLevel, childX, childY),
+      // top-left
+      this.createNode(childLevel, childX + 1, childY),
+      // top-right
+      this.createNode(childLevel, childX, childY + 1),
+      // bottom-left
+      this.createNode(childLevel, childX + 1, childY + 1)
+      // bottom-right
+    ];
+    if (childIndices.some((index) => index === -1)) {
+      console.warn("Failed to create all children, skipping subdivision");
+      return;
+    }
+    this.nodeView.setChildren(nodeIndex, childIndices);
+    this.updateChildNeighbors(nodeIndex, childIndices);
+  }
+  /**
+   * Update neighbor relationships for child nodes
+   */
+  updateChildNeighbors(_parentIndex, childIndices) {
+    for (let i = 0; i < 4; i++) {
+      const childIndex = childIndices[i];
+      this.tempNeighborIndices[0] = EMPTY_SENTINEL_VALUE;
+      this.tempNeighborIndices[1] = EMPTY_SENTINEL_VALUE;
+      this.tempNeighborIndices[2] = EMPTY_SENTINEL_VALUE;
+      this.tempNeighborIndices[3] = EMPTY_SENTINEL_VALUE;
+      const childX = i % 2;
+      const childY = Math.floor(i / 2);
+      if (childX === 0 && i + 1 < 4) {
+        this.tempNeighborIndices[1] = childIndices[i + 1];
+      } else if (childX === 1 && i - 1 >= 0) {
+        this.tempNeighborIndices[0] = childIndices[i - 1];
+      }
+      if (childY === 0 && i + 2 < 4) {
+        this.tempNeighborIndices[3] = childIndices[i + 2];
+      } else if (childY === 1 && i - 2 >= 0) {
+        this.tempNeighborIndices[2] = childIndices[i - 2];
+      }
+      this.nodeView.setNeighbors(childIndex, this.tempNeighborIndices);
+    }
+  }
+  /**
+   * Get the deepest subdivision level currently in the quadtree
+   */
+  getDeepestLevel() {
+    return this.deepestLevel;
+  }
+  /**
+   * Get the total number of nodes
+   */
+  getNodeCount() {
+    return this.nodeCount;
+  }
+  getLeafNodeCount() {
+    return this.nodeView.getLeafNodeCount();
+  }
+  /**
+   * Get active leaf node indices for efficient GPU processing
+   */
+  getActiveLeafNodeIndices() {
+    return this.nodeView.getActiveLeafNodeIndices();
+  }
+  /**
+   * Get the configuration
+   */
+  getConfig() {
+    return this.config;
+  }
+  /**
+   * Get all leaf nodes as an array of node objects
+   */
+  getLeafNodes() {
+    const leafNodes = [];
+    for (let i = 0; i < this.nodeCount; i++) {
+      if (this.nodeView.getLeaf(i)) {
+        leafNodes.push({
+          level: this.nodeView.getLevel(i),
+          x: this.nodeView.getX(i),
+          y: this.nodeView.getY(i)
+        });
+      }
+    }
+    return leafNodes;
+  }
+  /**
+   * Reset the quadtree
+   */
+  reset() {
+    this.initialize();
+  }
+  /**
+   * Get the NodeView instance for direct access
+   */
+  getNodeView() {
+    return this.nodeView;
+  }
+  /**
+   * Release internal resources associated with this quadtree
+   */
+  destroy() {
+    this.nodeView.destroy();
+    this.nodeCount = 0;
+    this.deepestLevel = 0;
+  }
+  /**
+   * Set the configuration
+   */
+  setConfig(config, reset = false) {
+    this.config = config;
+    if (reset) {
+      this.initialize();
+    }
+  }
+}
+
+exports.Quadtree = Quadtree;
 exports.TerrainGeometry = TerrainGeometry;
+exports.computeScreenSpaceInfo = computeScreenSpaceInfo;
+exports.distanceBasedSubdivision = distanceBasedSubdivision;
 exports.isSkirtUV = isSkirtUV;
 exports.isSkirtVertex = isSkirtVertex;
+exports.screenSpaceSubdivision = screenSpaceSubdivision;