@hello-terrain/three 0.0.0-alpha.7 → 0.0.0-alpha.9

package/dist/index.d.cts

@@ -404,6 +404,8 @@ interface TerrainFieldStorage {
     readonly texture: StorageArrayTexture | StorageTexture;
     uv(ix: Node, iy: Node, tileIndex: Node): Node;
     texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
     resize(width: number, height: number, tileCount: number): void;
 }
 declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
@@ -418,6 +420,13 @@ declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: N
 declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
 declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
 
 interface TerrainUniformsParams {
@@ -449,6 +458,41 @@ declare function createTileCompute(leafStorage: LeafStorageState, uniforms: Terr
     tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
 };
 
+interface ElevationParams {
+    worldPosition: Node$1;
+    rootSize: Node$1;
+    rootUV: Node$1;
+    tileUV: Node$1;
+    tileLevel: Node$1;
+    tileSize: Node$1;
+    tileOriginVec2: Node$1;
+    nodeIndex: Node$1;
+}
+type ElevationCallback = (params: ElevationParams) => Node$1;
+
+interface GpuSpatialIndexContext {
+    data: Uint32Array<ArrayBuffer>;
+    size: number;
+    mask: number;
+    stampGen: UniformNode<number>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainSampler {
+    sampleElevation: (worldX: Node, worldZ: Node) => Node;
+    sampleNormal: (worldX: Node, worldZ: Node) => Node;
+    sampleTerrain: (worldX: Node, worldZ: Node) => Node;
+    sampleValidity: (worldX: Node, worldZ: Node) => Node;
+    evaluateElevation: (worldX: Node, worldZ: Node) => Node;
+    evaluateNormal: (worldX: Node, worldZ: Node, epsilon?: Node) => Node;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+}
+
 interface QuadtreeConfigState {
     state: QuadtreeState;
     surface: Surface;
@@ -469,12 +513,15 @@ interface TerrainTasks {
     surface: TaskRef<Surface>;
     leafStorage: TaskRef<LeafStorageState>;
     leafGpuBuffer: TaskRef<LeafGpuBufferState>;
+    gpuSpatialIndexStorage: TaskRef<GpuSpatialIndexContext>;
+    gpuSpatialIndexUpload: TaskRef<GpuSpatialIndexContext>;
     createUniforms: TaskRef<TerrainUniformsContext>;
     updateUniforms: TaskRef<TerrainUniformsContext>;
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
     createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
+    createTerrainSampler: TaskRef<TerrainSampler>;
     elevationFieldStage: TaskRef<ComputePipeline>;
     terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
@@ -504,6 +551,9 @@ declare const tileNodesTask: _hello_terrain_work.Task<{
  */
 declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
+declare const gpuSpatialIndexStorageTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+declare const gpuSpatialIndexUploadTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
@@ -520,17 +570,7 @@ declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, strin
  */
 declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
-interface ElevationParams {
-    worldPosition: Node$1;
-    rootSize: Node$1;
-    rootUV: Node$1;
-    tileUV: Node$1;
-    tileLevel: Node$1;
-    tileSize: Node$1;
-    tileOriginVec2: Node$1;
-    nodeIndex: Node$1;
-}
-type ElevationCallback = (params: ElevationParams) => Node$1;
+declare const createTerrainSamplerTask: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
 
 /** Root tile size in world units. */
 declare const rootSize: _hello_terrain_work.ParamRef<number>;
@@ -557,6 +597,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -633,6 +675,8 @@ declare const terrainTasks: {
         attribute: three_webgpu.StorageBufferAttribute;
         node: three_webgpu.StorageBufferNode;
     }, string, unknown>;
+    readonly gpuSpatialIndexStorage: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+    readonly gpuSpatialIndexUpload: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
     readonly createUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly updateUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly positionNode: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
@@ -651,6 +695,7 @@ declare const terrainTasks: {
     readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
     }>;
+    readonly createTerrainSampler: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
@@ -668,6 +713,8 @@ type ComputeDeviceLimits = {
 };
 declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
 
+declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -740,5 +787,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainSampler, createTerrainSamplerTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CreateTerrainSamplerParams, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, GpuSpatialIndexContext, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainSampler, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };

package/dist/index.d.mts

@@ -404,6 +404,8 @@ interface TerrainFieldStorage {
     readonly texture: StorageArrayTexture | StorageTexture;
     uv(ix: Node, iy: Node, tileIndex: Node): Node;
     texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
     resize(width: number, height: number, tileCount: number): void;
 }
 declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
@@ -418,6 +420,13 @@ declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: N
 declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
 declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
 
 interface TerrainUniformsParams {
@@ -449,6 +458,41 @@ declare function createTileCompute(leafStorage: LeafStorageState, uniforms: Terr
     tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
 };
 
+interface ElevationParams {
+    worldPosition: Node$1;
+    rootSize: Node$1;
+    rootUV: Node$1;
+    tileUV: Node$1;
+    tileLevel: Node$1;
+    tileSize: Node$1;
+    tileOriginVec2: Node$1;
+    nodeIndex: Node$1;
+}
+type ElevationCallback = (params: ElevationParams) => Node$1;
+
+interface GpuSpatialIndexContext {
+    data: Uint32Array<ArrayBuffer>;
+    size: number;
+    mask: number;
+    stampGen: UniformNode<number>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainSampler {
+    sampleElevation: (worldX: Node, worldZ: Node) => Node;
+    sampleNormal: (worldX: Node, worldZ: Node) => Node;
+    sampleTerrain: (worldX: Node, worldZ: Node) => Node;
+    sampleValidity: (worldX: Node, worldZ: Node) => Node;
+    evaluateElevation: (worldX: Node, worldZ: Node) => Node;
+    evaluateNormal: (worldX: Node, worldZ: Node, epsilon?: Node) => Node;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+}
+
 interface QuadtreeConfigState {
     state: QuadtreeState;
     surface: Surface;
@@ -469,12 +513,15 @@ interface TerrainTasks {
     surface: TaskRef<Surface>;
     leafStorage: TaskRef<LeafStorageState>;
     leafGpuBuffer: TaskRef<LeafGpuBufferState>;
+    gpuSpatialIndexStorage: TaskRef<GpuSpatialIndexContext>;
+    gpuSpatialIndexUpload: TaskRef<GpuSpatialIndexContext>;
     createUniforms: TaskRef<TerrainUniformsContext>;
     updateUniforms: TaskRef<TerrainUniformsContext>;
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
     createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
+    createTerrainSampler: TaskRef<TerrainSampler>;
     elevationFieldStage: TaskRef<ComputePipeline>;
     terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
@@ -504,6 +551,9 @@ declare const tileNodesTask: _hello_terrain_work.Task<{
  */
 declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
+declare const gpuSpatialIndexStorageTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+declare const gpuSpatialIndexUploadTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
@@ -520,17 +570,7 @@ declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, strin
  */
 declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
-interface ElevationParams {
-    worldPosition: Node$1;
-    rootSize: Node$1;
-    rootUV: Node$1;
-    tileUV: Node$1;
-    tileLevel: Node$1;
-    tileSize: Node$1;
-    tileOriginVec2: Node$1;
-    nodeIndex: Node$1;
-}
-type ElevationCallback = (params: ElevationParams) => Node$1;
+declare const createTerrainSamplerTask: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
 
 /** Root tile size in world units. */
 declare const rootSize: _hello_terrain_work.ParamRef<number>;
@@ -557,6 +597,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -633,6 +675,8 @@ declare const terrainTasks: {
         attribute: three_webgpu.StorageBufferAttribute;
         node: three_webgpu.StorageBufferNode;
     }, string, unknown>;
+    readonly gpuSpatialIndexStorage: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+    readonly gpuSpatialIndexUpload: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
     readonly createUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly updateUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly positionNode: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
@@ -651,6 +695,7 @@ declare const terrainTasks: {
     readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
     }>;
+    readonly createTerrainSampler: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
@@ -668,6 +713,8 @@ type ComputeDeviceLimits = {
 };
 declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
 
+declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -740,5 +787,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainSampler, createTerrainSamplerTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CreateTerrainSamplerParams, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, GpuSpatialIndexContext, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainSampler, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };

package/dist/index.d.ts

@@ -404,6 +404,8 @@ interface TerrainFieldStorage {
     readonly texture: StorageArrayTexture | StorageTexture;
     uv(ix: Node, iy: Node, tileIndex: Node): Node;
     texel(ix: Node, iy: Node, tileIndex: Node): Node;
+    /** UV-based filtered sample. `u, v` in [0, 1] tile-local space. */
+    sample(u: Node, v: Node, tileIndex: Node): Node;
     resize(width: number, height: number, tileCount: number): void;
 }
 declare function ArrayTextureBackend(edgeVertexCount: number, tileCount: number, options: Required<Pick<TerrainFieldStorageOptions, "format" | "filter">>): TerrainFieldStorage;
@@ -418,6 +420,13 @@ declare function storeTerrainField(storage: TerrainFieldStorage, ix: Node, iy: N
 declare function loadTerrainField(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldElevation(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
 declare function loadTerrainFieldNormal(storage: TerrainFieldStorage, ix: Node, iy: Node, tileIndex: Node): Node;
+/**
+ * UV-based filtered sample. `u, v` are in [0, 1] tile-local space.
+ * Respects the filter mode (nearest / linear) set on the storage.
+ */
+declare function sampleTerrainField(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldElevation(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
+declare function sampleTerrainFieldNormal(storage: TerrainFieldStorage, u: Node, v: Node, tileIndex: Node): Node;
 declare function packTerrainFieldSample(height: Node, normalXZ: Node, extra?: Node): Node;
 
 interface TerrainUniformsParams {
@@ -449,6 +458,41 @@ declare function createTileCompute(leafStorage: LeafStorageState, uniforms: Terr
     tileVertexWorldPositionCompute: three_src_nodes_TSL_js.ShaderNodeFn<[number | Node, number | Node, number | Node]>;
 };
 
+interface ElevationParams {
+    worldPosition: Node$1;
+    rootSize: Node$1;
+    rootUV: Node$1;
+    tileUV: Node$1;
+    tileLevel: Node$1;
+    tileSize: Node$1;
+    tileOriginVec2: Node$1;
+    nodeIndex: Node$1;
+}
+type ElevationCallback = (params: ElevationParams) => Node$1;
+
+interface GpuSpatialIndexContext {
+    data: Uint32Array<ArrayBuffer>;
+    size: number;
+    mask: number;
+    stampGen: UniformNode<number>;
+    attribute: StorageBufferAttribute;
+    node: StorageBufferNode;
+}
+interface TerrainSampler {
+    sampleElevation: (worldX: Node, worldZ: Node) => Node;
+    sampleNormal: (worldX: Node, worldZ: Node) => Node;
+    sampleTerrain: (worldX: Node, worldZ: Node) => Node;
+    sampleValidity: (worldX: Node, worldZ: Node) => Node;
+    evaluateElevation: (worldX: Node, worldZ: Node) => Node;
+    evaluateNormal: (worldX: Node, worldZ: Node, epsilon?: Node) => Node;
+}
+interface CreateTerrainSamplerParams {
+    terrainFieldStorage: TerrainFieldStorage;
+    spatialIndex: GpuSpatialIndexContext;
+    uniforms: TerrainUniformsContext;
+    elevationCallback: ElevationCallback;
+}
+
 interface QuadtreeConfigState {
     state: QuadtreeState;
     surface: Surface;
@@ -469,12 +513,15 @@ interface TerrainTasks {
     surface: TaskRef<Surface>;
     leafStorage: TaskRef<LeafStorageState>;
     leafGpuBuffer: TaskRef<LeafGpuBufferState>;
+    gpuSpatialIndexStorage: TaskRef<GpuSpatialIndexContext>;
+    gpuSpatialIndexUpload: TaskRef<GpuSpatialIndexContext>;
     createUniforms: TaskRef<TerrainUniformsContext>;
     updateUniforms: TaskRef<TerrainUniformsContext>;
     positionNode: TaskRef<ShaderCallNodeInternal>;
     createElevationFieldContext: TaskRef<ElevationFieldContext>;
     createTileNodes: TaskRef<ReturnType<typeof createTileCompute>>;
     createTerrainFieldTexture: TaskRef<TerrainFieldStorage>;
+    createTerrainSampler: TaskRef<TerrainSampler>;
     elevationFieldStage: TaskRef<ComputePipeline>;
     terrainFieldStage: TaskRef<ComputePipeline>;
     compileCompute: TaskRef<{
@@ -504,6 +551,9 @@ declare const tileNodesTask: _hello_terrain_work.Task<{
  */
 declare const elevationFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
+declare const gpuSpatialIndexStorageTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+declare const gpuSpatialIndexUploadTask: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+
 /** Generates a unique instance ID per graph (cached once). */
 declare const instanceIdTask: _hello_terrain_work.Task<`${string}-${string}-${string}-${string}-${string}`, string, unknown>;
 
@@ -520,17 +570,7 @@ declare const createTerrainFieldTextureTask: _hello_terrain_work.Task<any, strin
  */
 declare const terrainFieldStageTask: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
 
-interface ElevationParams {
-    worldPosition: Node$1;
-    rootSize: Node$1;
-    rootUV: Node$1;
-    tileUV: Node$1;
-    tileLevel: Node$1;
-    tileSize: Node$1;
-    tileOriginVec2: Node$1;
-    nodeIndex: Node$1;
-}
-type ElevationCallback = (params: ElevationParams) => Node$1;
+declare const createTerrainSamplerTask: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
 
 /** Root tile size in world units. */
 declare const rootSize: _hello_terrain_work.ParamRef<number>;
@@ -557,6 +597,8 @@ declare const maxLevel: _hello_terrain_work.ParamRef<number>;
 declare const quadtreeUpdate: _hello_terrain_work.ParamRef<UpdateParams>;
 /** Optional custom terrain surface; defaults to bounded flat surface when null. */
 declare const surface: _hello_terrain_work.ParamRef<Surface | null>;
+/** Terrain field texture filter mode. */
+declare const terrainFieldFilter: _hello_terrain_work.ParamRef<"nearest" | "linear">;
 /** Terrain elevation control function (per vertex, in gpu compute) */
 declare const elevationFn: _hello_terrain_work.ParamRef<ElevationCallback>;
 
@@ -633,6 +675,8 @@ declare const terrainTasks: {
         attribute: three_webgpu.StorageBufferAttribute;
         node: three_webgpu.StorageBufferNode;
     }, string, unknown>;
+    readonly gpuSpatialIndexStorage: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
+    readonly gpuSpatialIndexUpload: _hello_terrain_work.Task<GpuSpatialIndexContext, string, unknown>;
     readonly createUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly updateUniforms: _hello_terrain_work.Task<TerrainUniformsContext, string, unknown>;
     readonly positionNode: _hello_terrain_work.Task<three_src_nodes_TSL_js.ShaderCallNodeInternal, string, unknown>;
@@ -651,6 +695,7 @@ declare const terrainTasks: {
     readonly createTerrainFieldTexture: _hello_terrain_work.Task<any, string, {
         renderer: WebGPURenderer;
     }>;
+    readonly createTerrainSampler: _hello_terrain_work.Task<TerrainSampler, string, unknown>;
     readonly elevationFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly terrainFieldStage: _hello_terrain_work.Task<ComputePipeline, string, unknown>;
     readonly compileCompute: _hello_terrain_work.Task<{
@@ -668,6 +713,8 @@ type ComputeDeviceLimits = {
 };
 declare function getDeviceComputeLimits(renderer: WebGPURenderer): ComputeDeviceLimits;
 
+declare function createTerrainSampler(params: CreateTerrainSamplerParams): TerrainSampler;
+
 /**
  * Maps a value or node from texture space [0, 1] to vector space [-1, 1].
  *
@@ -740,5 +787,5 @@ declare const voronoiCells: three_src_nodes_TSL_js.ShaderNodeFn<[three_tsl.Proxi
     uv: Node;
 }>]>;
 
-export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
-export type { ComputePipeline, ComputeStageCallback, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };
+export { ArrayTextureBackend, AtlasBackend, Dir, TerrainGeometry, TerrainMesh, Texture3DBackend, U32_EMPTY, allocLeafSet, allocSeamTable, beginUpdate, blendAngleCorrectedNormals, buildLeafIndex, buildSeams2to1, compileComputeTask, createComputePipelineTasks, createCubeSphereSurface, createElevationFieldContextTask, createFlatSurface, createInfiniteFlatSurface, createSpatialIndex, createState, createTerrainFieldStorage, createTerrainFieldTextureTask, createTerrainSampler, createTerrainSamplerTask, createTerrainUniforms, createUniformsTask, deriveNormalZ, elevationFieldStageTask, elevationFn, elevationScale, executeComputeTask, getDeviceComputeLimits, gpuSpatialIndexStorageTask, gpuSpatialIndexUploadTask, innerTileSegments, instanceIdTask, isSkirtUV, isSkirtVertex, leafGpuBufferTask, leafStorageTask, loadTerrainField, loadTerrainFieldElevation, loadTerrainFieldNormal, maxLevel, maxNodes, origin, packTerrainFieldSample, positionNodeTask, quadtreeConfigTask, quadtreeUpdate, quadtreeUpdateTask, resetLeafSet, resetSeamTable, rootSize, sampleTerrainField, sampleTerrainFieldElevation, sampleTerrainFieldNormal, skirtScale, storeTerrainField, surface, surfaceTask, terrainFieldFilter, terrainFieldStageTask, terrainGraph, terrainTasks, textureSpaceToVectorSpace, tileNodesTask, update, updateUniformsTask, vElevation, vGlobalVertexIndex, vectorSpaceToTextureSpace, voronoiCells };
+export type { ComputePipeline, ComputeStageCallback, CreateTerrainSamplerParams, CubeSphereSurfaceConfig, ElevationCallback, ElevationFieldContext, ElevationParams, FlatSurfaceConfig, GpuSpatialIndexContext, InfiniteFlatSurfaceConfig, IntNodeInput, LeafGpuBufferState, LeafSet, LeafStorageState, LodMode, QuadtreeConfig, QuadtreeConfigState, QuadtreeState, SeamTable, SpatialIndex, Surface, TerrainFieldStorage, TerrainFieldStorageBackendType, TerrainFieldStorageFormat, TerrainFieldStorageOptions, TerrainGraph, TerrainSampler, TerrainTasks, TerrainUniformsContext, TerrainUniformsParams, TileBounds, TileId, UpdateParams };