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

package/dist/index.cjs

@@ -411,25 +411,25 @@ function resolveType(format) {
 function resolveFilter(mode) {
   return mode === "linear" ? three.LinearFilter : three.NearestFilter;
 }
-function configureStorageTexture(texture, format, filter) {
-  texture.format = three.RGBAFormat;
-  texture.type = resolveType(format);
-  texture.magFilter = resolveFilter(filter);
-  texture.minFilter = resolveFilter(filter);
-  texture.wrapS = three.ClampToEdgeWrapping;
-  texture.wrapT = three.ClampToEdgeWrapping;
-  texture.generateMipmaps = false;
-  texture.needsUpdate = true;
+function configureStorageTexture(texture2, format, filter) {
+  texture2.format = three.RGBAFormat;
+  texture2.type = resolveType(format);
+  texture2.magFilter = resolveFilter(filter);
+  texture2.minFilter = resolveFilter(filter);
+  texture2.wrapS = three.ClampToEdgeWrapping;
+  texture2.wrapT = three.ClampToEdgeWrapping;
+  texture2.generateMipmaps = false;
+  texture2.needsUpdate = true;
 }
 function ArrayTextureBackend(edgeVertexCount, tileCount, options) {
   let currentEdgeVertexCount = edgeVertexCount;
   let currentTileCount = tileCount;
-  const texture = new webgpu.StorageArrayTexture(
+  const tex = new webgpu.StorageArrayTexture(
     edgeVertexCount,
     edgeVertexCount,
     tileCount
   );
-  configureStorageTexture(texture, options.format, options.filter);
+  configureStorageTexture(tex, options.format, options.filter);
   return {
     backendType: "array-texture",
     get edgeVertexCount() {
@@ -438,18 +438,21 @@ function ArrayTextureBackend(edgeVertexCount, tileCount, options) {
     get tileCount() {
       return currentTileCount;
     },
-    texture,
+    texture: tex,
     uv(ix, iy, _tileIndex) {
       return tsl.vec2(ix.toFloat(), iy.toFloat());
     },
     texel(ix, iy, tileIndex) {
       return tsl.ivec3(ix, iy, tileIndex);
     },
+    sample(u, v, tileIndex) {
+      return tsl.texture(tex, tsl.vec2(u, v)).depth(tsl.int(tileIndex));
+    },
     resize(width, height, nextTileCount) {
       currentEdgeVertexCount = width;
       currentTileCount = nextTileCount;
-      texture.setSize(width, height, nextTileCount);
-      texture.needsUpdate = true;
+      tex.setSize(width, height, nextTileCount);
+      tex.needsUpdate = true;
     }
   };
 }
@@ -468,8 +471,8 @@ function AtlasBackend(edgeVertexCount, tileCount, options) {
   let currentTileCount = tileCount;
   let tilesPerRow = Math.max(1, Math.ceil(Math.sqrt(tileCount)));
   const atlasSize = tilesPerRow * edgeVertexCount;
-  const texture = new webgpu.StorageTexture(atlasSize, atlasSize);
-  configureStorageTexture(texture, options.format, options.filter);
+  const tex = new webgpu.StorageTexture(atlasSize, atlasSize);
+  configureStorageTexture(tex, options.format, options.filter);
   return {
     backendType: "atlas",
     get edgeVertexCount() {
@@ -478,7 +481,7 @@ function AtlasBackend(edgeVertexCount, tileCount, options) {
     get tileCount() {
       return currentTileCount;
     },
-    texture,
+    texture: tex,
     uv(ix, iy, tileIndex) {
       const { atlasX, atlasY } = atlasCoord(
         tilesPerRow,
@@ -503,27 +506,37 @@ function AtlasBackend(edgeVertexCount, tileCount, options) {
       );
       return tsl.ivec2(atlasX, atlasY);
     },
+    sample(u, v, tileIndex) {
+      const tile = tsl.int(tileIndex);
+      const tilesPerRowNode = tsl.int(tilesPerRow);
+      const col = tile.mod(tilesPerRowNode);
+      const row = tile.div(tilesPerRowNode);
+      const invTilesPerRow = tsl.float(1 / tilesPerRow);
+      const atlasU = col.toFloat().add(u).mul(invTilesPerRow);
+      const atlasV = row.toFloat().add(v).mul(invTilesPerRow);
+      return tsl.texture(tex, tsl.vec2(atlasU, atlasV));
+    },
     resize(width, height, nextTileCount) {
       currentEdgeVertexCount = width;
       currentTileCount = nextTileCount;
       tilesPerRow = Math.max(1, Math.ceil(Math.sqrt(nextTileCount)));
       const nextAtlasSize = tilesPerRow * width;
-      const image = texture.image;
+      const image = tex.image;
       image.width = nextAtlasSize;
       image.height = nextAtlasSize;
-      texture.needsUpdate = true;
+      tex.needsUpdate = true;
     }
   };
 }
 function Texture3DBackend(edgeVertexCount, tileCount, options) {
   let currentEdgeVertexCount = edgeVertexCount;
   let currentTileCount = tileCount;
-  const texture = new webgpu.StorageArrayTexture(
+  const tex = new webgpu.StorageArrayTexture(
     edgeVertexCount,
     edgeVertexCount,
     tileCount
   );
-  configureStorageTexture(texture, options.format, options.filter);
+  configureStorageTexture(tex, options.format, options.filter);
   return {
     backendType: "texture-3d",
     get edgeVertexCount() {
@@ -532,18 +545,21 @@ function Texture3DBackend(edgeVertexCount, tileCount, options) {
     get tileCount() {
       return currentTileCount;
     },
-    texture,
+    texture: tex,
     uv(ix, iy, _tileIndex) {
       return tsl.vec2(ix.toFloat(), iy.toFloat());
     },
     texel(ix, iy, tileIndex) {
       return tsl.ivec3(ix, iy, tileIndex);
     },
+    sample(u, v, tileIndex) {
+      return tsl.texture(tex, tsl.vec2(u, v)).depth(tsl.int(tileIndex));
+    },
     resize(width, height, nextTileCount) {
       currentEdgeVertexCount = width;
       currentTileCount = nextTileCount;
-      texture.setSize(width, height, nextTileCount);
-      texture.needsUpdate = true;
+      tex.setSize(width, height, nextTileCount);
+      tex.needsUpdate = true;
     }
   };
 }
@@ -552,7 +568,7 @@ function tryGetDeviceLimits(renderer) {
   return backend.backend?.device?.limits ?? {};
 }
 function createTerrainFieldStorage(edgeVertexCount, tileCount, renderer, options = {}) {
-  const filter = options.filter ?? "nearest";
+  const filter = options.filter ?? "linear";
   const format = options.format ?? "rgba16float";
   const forcedBackend = options.backend;
   if (forcedBackend === "atlas") {
@@ -593,8 +609,18 @@ function loadTerrainFieldElevation(storage, ix, iy, tileIndex) {
   return loadTerrainField(storage, ix, iy, tileIndex).r;
 }
 function loadTerrainFieldNormal(storage, ix, iy, tileIndex) {
-  const sample = loadTerrainField(storage, ix, iy, tileIndex);
-  return tsl.vec2(sample.g, sample.b);
+  const raw = loadTerrainField(storage, ix, iy, tileIndex);
+  return tsl.vec2(raw.g, raw.b);
+}
+function sampleTerrainField(storage, u, v, tileIndex) {
+  return storage.sample(u, v, tileIndex);
+}
+function sampleTerrainFieldElevation(storage, u, v, tileIndex) {
+  return sampleTerrainField(storage, u, v, tileIndex).r;
+}
+function sampleTerrainFieldNormal(storage, u, v, tileIndex) {
+  const raw = sampleTerrainField(storage, u, v, tileIndex);
+  return tsl.vec2(raw.g, raw.b);
 }
 function packTerrainFieldSample(height, normalXZ, extra = tsl.float(0)) {
   return tsl.vec4(height, normalXZ.x, normalXZ.y, extra);
@@ -621,25 +647,6 @@ const createElevation = (tile, uniforms, elevationFn) => {
     });
   };
 };
-const readElevationFieldAtPositionLocal = (terrainFieldStorage, edgeVertexCount, positionLocal) => tsl.Fn(() => {
-  const nodeIndex = tsl.int(tsl.instanceIndex);
-  const intEdge = tsl.int(edgeVertexCount);
-  const innerSegments = tsl.int(edgeVertexCount).sub(3);
-  const fInnerSegments = tsl.float(innerSegments);
-  const last = intEdge.sub(tsl.int(1));
-  const u = positionLocal.x.add(tsl.float(0.5));
-  const v = positionLocal.z.add(tsl.float(0.5));
-  const x = u.mul(fInnerSegments).round().toInt().add(tsl.int(1));
-  const y = v.mul(fInnerSegments).round().toInt().add(tsl.int(1));
-  const xClamped = tsl.min(tsl.max(x, tsl.int(0)), last);
-  const yClamped = tsl.min(tsl.max(y, tsl.int(0)), last);
-  return loadTerrainFieldElevation(
-    terrainFieldStorage,
-    xClamped,
-    yClamped,
-    nodeIndex
-  );
-});
 
 function createTileCompute(leafStorage, uniforms) {
   const tileLevel = tsl.Fn(([nodeIndex]) => {
@@ -706,6 +713,10 @@ function createTileCompute(leafStorage, uniforms) {
     tileVertexWorldPositionCompute
   };
 }
+function tileLocalToFieldUV(localCoord, innerSegments) {
+  const edge = tsl.float(innerSegments).add(tsl.float(3));
+  return tsl.float(localCoord).mul(tsl.float(innerSegments)).add(tsl.float(1.5)).div(edge);
+}
 
 const rootSize = work.param(256).displayName("rootSize");
 const origin = work.param({
@@ -724,6 +735,7 @@ const quadtreeUpdate = work.param({
   distanceFactor: 1.5
 }).displayName("quadtreeUpdate");
 const surface = work.param(null).displayName("surface");
+const terrainFieldFilter = work.param("linear").displayName("terrainFieldFilter");
 const elevationFn = work.param(() => tsl.float(0));
 
 function createLeafStorage(maxNodes) {
@@ -821,12 +833,12 @@ function ensureChildren(store, parentId) {
   return childBase;
 }
 
-function nextPow2(n) {
+function nextPow2$1(n) {
   let x = 1;
   while (x < n) x <<= 1;
   return x;
 }
-function mix32(x) {
+function mix32$1(x) {
   x >>>= 0;
   x ^= x >>> 16;
   x = Math.imul(x, 2146121005) >>> 0;
@@ -835,12 +847,12 @@ function mix32(x) {
   x ^= x >>> 16;
   return x >>> 0;
 }
-function hashKey(space, level, x, y) {
-  const h = space & 255 ^ (level & 255) << 8 ^ mix32(x) >>> 0 ^ mix32(y) >>> 0;
-  return mix32(h);
+function hashKey$1(space, level, x, y) {
+  const h = space & 255 ^ (level & 255) << 8 ^ mix32$1(x) >>> 0 ^ mix32$1(y) >>> 0;
+  return mix32$1(h);
 }
 function createSpatialIndex(maxEntries) {
-  const size = nextPow2(Math.max(2, maxEntries * 2));
+  const size = nextPow2$1(Math.max(2, maxEntries * 2));
   return {
     size,
     mask: size - 1,
@@ -865,7 +877,7 @@ function insertSpatialIndexRaw(index, space, level, x, y, value) {
   const l = level & 255;
   const xx = x >>> 0;
   const yy = y >>> 0;
-  let slot = hashKey(s, l, xx, yy) & index.mask;
+  let slot = hashKey$1(s, l, xx, yy) & index.mask;
   for (let probes = 0; probes < index.size; probes++) {
     if (index.stamp[slot] !== index.stampGen) {
       index.stamp[slot] = index.stampGen;
@@ -889,7 +901,7 @@ function lookupSpatialIndexRaw(index, space, level, x, y) {
   const l = level & 255;
   const xx = x >>> 0;
   const yy = y >>> 0;
-  let slot = hashKey(s, l, xx, yy) & index.mask;
+  let slot = hashKey$1(s, l, xx, yy) & index.mask;
   for (let probes = 0; probes < index.size; probes++) {
     if (index.stamp[slot] !== index.stampGen) return U32_EMPTY;
     if (index.keysSpace[slot] === s && index.keysLevel[slot] === l && index.keysX[slot] === xx && index.keysY[slot] === yy) {
@@ -1535,11 +1547,13 @@ const createTerrainFieldTextureTask = work.task(
   (get, work, { resources }) => {
     const edgeVertexCount = get(innerTileSegments) + 3;
     const maxNodesValue = get(maxNodes);
+    const filter = get(terrainFieldFilter);
     return work(
       () => createTerrainFieldStorage(
         edgeVertexCount,
         maxNodesValue,
-        resources?.renderer
+        resources?.renderer,
+        { filter }
       )
     );
   }
@@ -1648,6 +1662,275 @@ function createComputePipelineTasks(leafStageTask) {
   return { compile, execute };
 }
 
+const SLOT_STRIDE = 6;
+function nextPow2(n) {
+  let x = 1;
+  while (x < n) x <<= 1;
+  return x;
+}
+function createGpuSpatialIndex(maxEntries) {
+  const size = nextPow2(Math.max(2, maxEntries * 2));
+  const data = new Uint32Array(size * SLOT_STRIDE);
+  const attribute = new webgpu.StorageBufferAttribute(data, SLOT_STRIDE);
+  const node = tsl.storage(attribute, "u32", 1).toReadOnly().setName("gpuSpatialIndex");
+  const stampGen = tsl.uniform(tsl.uint(1)).setName("uGpuSpatialIndexStampGen");
+  return {
+    data,
+    size,
+    mask: size - 1,
+    stampGen,
+    attribute,
+    node
+  };
+}
+function uploadGpuSpatialIndex(gpuIndex, cpuIndex) {
+  if (gpuIndex.size !== cpuIndex.size) {
+    throw new Error(
+      `Spatial index size mismatch (gpu=${gpuIndex.size}, cpu=${cpuIndex.size}).`
+    );
+  }
+  for (let i = 0; i < cpuIndex.size; i += 1) {
+    const base = i * SLOT_STRIDE;
+    gpuIndex.data[base] = cpuIndex.stamp[i] ?? 0;
+    gpuIndex.data[base + 1] = cpuIndex.keysSpace[i] ?? 0;
+    gpuIndex.data[base + 2] = cpuIndex.keysLevel[i] ?? 0;
+    gpuIndex.data[base + 3] = cpuIndex.keysX[i] ?? 0;
+    gpuIndex.data[base + 4] = cpuIndex.keysY[i] ?? 0;
+    gpuIndex.data[base + 5] = cpuIndex.values[i] ?? 0;
+  }
+  gpuIndex.stampGen.value = cpuIndex.stampGen >>> 0;
+  gpuIndex.attribute.needsUpdate = true;
+  gpuIndex.node.needsUpdate = true;
+}
+function readGpuSpatialIndexValue(spatialIndex, slot, fieldOffset) {
+  const offset = tsl.int(slot).mul(tsl.int(SLOT_STRIDE)).add(tsl.int(fieldOffset));
+  return spatialIndex.node.element(offset).toUint();
+}
+const mix32 = tsl.Fn(([x]) => {
+  const v = tsl.uint(x).toVar();
+  v.assign(v.bitXor(v.shiftRight(tsl.uint(16))));
+  v.assign(v.mul(tsl.uint(2146121005)));
+  v.assign(v.bitXor(v.shiftRight(tsl.uint(15))));
+  v.assign(v.mul(tsl.uint(2221713035)));
+  v.assign(v.bitXor(v.shiftRight(tsl.uint(16))));
+  return v;
+});
+const hashKey = tsl.Fn(([space, level, x, y]) => {
+  const s = tsl.uint(space).bitAnd(tsl.uint(255));
+  const l = tsl.uint(level).bitAnd(tsl.uint(255));
+  const h = s.bitXor(l.shiftLeft(tsl.uint(8))).bitXor(mix32(tsl.uint(x))).bitXor(mix32(tsl.uint(y)));
+  return mix32(h);
+});
+const createGpuSpatialLookup = (spatialIndex) => {
+  const slotCount = spatialIndex.size;
+  const mask = tsl.uint(spatialIndex.mask);
+  const stampGen = spatialIndex.stampGen.toUint();
+  const emptyValue = tsl.int(-1);
+  return tsl.Fn(([space, level, x, y]) => {
+    const s = tsl.uint(space).bitAnd(tsl.uint(255));
+    const l = tsl.uint(level).bitAnd(tsl.uint(255));
+    const xx = tsl.uint(x);
+    const yy = tsl.uint(y);
+    const result = emptyValue.toVar();
+    const slot = hashKey(s, l, xx, yy).bitAnd(mask).toVar();
+    const probes = tsl.int(0).toVar();
+    tsl.Loop(slotCount, () => {
+      const stamp = readGpuSpatialIndexValue(spatialIndex, slot, 0);
+      tsl.If(stamp.notEqual(stampGen), () => {
+        tsl.Break();
+      });
+      const ks = readGpuSpatialIndexValue(spatialIndex, slot, 1);
+      const kl = readGpuSpatialIndexValue(spatialIndex, slot, 2);
+      const kx = readGpuSpatialIndexValue(spatialIndex, slot, 3);
+      const ky = readGpuSpatialIndexValue(spatialIndex, slot, 4);
+      tsl.If(
+        ks.equal(s).and(kl.equal(l)).and(kx.equal(xx)).and(ky.equal(yy)),
+        () => {
+          result.assign(tsl.int(readGpuSpatialIndexValue(spatialIndex, slot, 5)));
+          tsl.Break();
+        }
+      );
+      slot.assign(slot.add(tsl.uint(1)).bitAnd(mask));
+      probes.addAssign(1);
+    });
+    return result;
+  });
+};
+const createTileIndexFromWorldPosition = (spatialIndex, uniforms, maxLevel) => {
+  const lookup = createGpuSpatialLookup(spatialIndex);
+  const levelCount = Math.max(1, maxLevel + 1);
+  return tsl.Fn(([worldX, worldZ]) => {
+    const rootOrigin = uniforms.uRootOrigin.toVar();
+    const rootSize = uniforms.uRootSize.toVar();
+    const halfRoot = rootSize.mul(tsl.float(0.5));
+    const tileIndex = tsl.int(-1).toVar();
+    const tileU = tsl.float(0).toVar();
+    const tileV = tsl.float(0).toVar();
+    const i = tsl.int(0).toVar();
+    tsl.Loop(levelCount, () => {
+      const level = tsl.int(maxLevel).sub(i).toVar();
+      const scale = tsl.pow(tsl.float(2), level.toFloat());
+      const tileSize = rootSize.div(scale);
+      const tileX = worldX.sub(rootOrigin.x).add(halfRoot).div(tileSize).floor().toInt();
+      const tileY = worldZ.sub(rootOrigin.z).add(halfRoot).div(tileSize).floor().toInt();
+      const maybeIndex = lookup(tsl.int(0), level, tileX, tileY).toVar();
+      tsl.If(maybeIndex.greaterThanEqual(tsl.int(0)), () => {
+        const minX = rootOrigin.x.add(tileX.toFloat().mul(tileSize)).sub(halfRoot);
+        const minZ = rootOrigin.z.add(tileY.toFloat().mul(tileSize)).sub(halfRoot);
+        tileIndex.assign(maybeIndex);
+        tileU.assign(worldX.sub(minX).div(tileSize));
+        tileV.assign(worldZ.sub(minZ).div(tileSize));
+        tsl.Break();
+      });
+      i.addAssign(1);
+    });
+    return tsl.vec3(tileIndex.toFloat(), tileU, tileV);
+  });
+};
+
+const gpuSpatialIndexStorageTask = work.task((get, work) => {
+  const maxNodesValue = get(maxNodes);
+  return work(() => createGpuSpatialIndex(maxNodesValue));
+}).displayName("gpuSpatialIndexStorageTask");
+const gpuSpatialIndexUploadTask = work.task((get, work) => {
+  const quadtreeConfig = get(quadtreeConfigTask);
+  get(quadtreeUpdateTask);
+  const gpuSpatialIndex = get(gpuSpatialIndexStorageTask);
+  return work(() => {
+    uploadGpuSpatialIndex(gpuSpatialIndex, quadtreeConfig.state.leafIndex);
+    return gpuSpatialIndex;
+  });
+}).displayName("gpuSpatialIndexUploadTask");
+
+function createTerrainSampleNode(params) {
+  const tileLookup = createTileIndexFromWorldPosition(
+    params.spatialIndex,
+    params.uniforms,
+    maxLevel.get()
+  );
+  return tsl.Fn(([worldX, worldZ]) => {
+    const tileResult = tileLookup(worldX, worldZ).toVar();
+    const tileIndex = tsl.int(tileResult.x).toVar();
+    const safeTileIndex = tileIndex.max(tsl.int(0)).toVar();
+    const u = tileResult.y.toVar();
+    const v = tileResult.z.toVar();
+    const fieldU = tileLocalToFieldUV(
+      u,
+      params.uniforms.uInnerTileSegments
+    ).toVar();
+    const fieldV = tileLocalToFieldUV(
+      v,
+      params.uniforms.uInnerTileSegments
+    ).toVar();
+    const found = tileIndex.greaterThanEqual(tsl.int(0)).toVar();
+    const sampled = sampleTerrainField(
+      params.terrainFieldStorage,
+      fieldU,
+      fieldV,
+      safeTileIndex
+    ).toVar();
+    const nx = sampled.g.toVar();
+    const nz = sampled.b.toVar();
+    const ny = tsl.float(1).sub(nx.mul(nx)).sub(nz.mul(nz)).max(0).sqrt();
+    const valid = found.select(tsl.float(1), tsl.float(0)).toVar();
+    return tsl.vec4(
+      sampled.r.mul(valid),
+      nx.mul(valid),
+      ny.mul(valid),
+      nz.mul(valid)
+    );
+  });
+}
+function createTerrainSampler(params) {
+  const elevationNode = createElevationFunction(params.elevationCallback);
+  const terrainSampleAt = createTerrainSampleNode(params);
+  const evaluateElevationAt = tsl.Fn(([worldX, worldZ]) => {
+    const rootOrigin = params.uniforms.uRootOrigin.toVar();
+    const rootSize = params.uniforms.uRootSize.toVar();
+    const centeredX = worldX.sub(rootOrigin.x);
+    const centeredZ = worldZ.sub(rootOrigin.z);
+    const rootUV = tsl.vec2(
+      centeredX.div(rootSize).add(0.5),
+      centeredZ.div(rootSize).mul(tsl.float(-1)).add(0.5)
+    ).toVar();
+    return elevationNode({
+      worldPosition: tsl.vec3(worldX, rootOrigin.y, worldZ),
+      rootSize,
+      rootUV,
+      tileUV: rootUV,
+      tileLevel: tsl.int(0),
+      tileSize: rootSize,
+      tileOriginVec2: tsl.vec2(0, 0),
+      nodeIndex: tsl.int(0)
+    });
+  });
+  const sampleTerrain = tsl.Fn(
+    ([worldX, worldZ]) => terrainSampleAt(worldX, worldZ)
+  );
+  const sampleElevation = tsl.Fn(
+    ([worldX, worldZ]) => terrainSampleAt(worldX, worldZ).x
+  );
+  const sampleNormal = tsl.Fn(
+    ([worldX, worldZ]) => tsl.vec3(
+      terrainSampleAt(worldX, worldZ).y,
+      terrainSampleAt(worldX, worldZ).z,
+      terrainSampleAt(worldX, worldZ).w
+    )
+  );
+  const sampleValidity = tsl.Fn(
+    ([worldX, worldZ]) => terrainSampleAt(worldX, worldZ).y.abs().add(terrainSampleAt(worldX, worldZ).z.abs()).add(terrainSampleAt(worldX, worldZ).w.abs()).greaterThan(tsl.float(0)).select(tsl.float(1), tsl.float(0))
+  );
+  const evaluateElevation = tsl.Fn(
+    ([worldX, worldZ]) => evaluateElevationAt(worldX, worldZ)
+  );
+  const evaluateNormalNode = tsl.Fn(
+    ([worldX, worldZ, epsilon]) => {
+      const eps = epsilon ?? tsl.float(0.1);
+      const elevationScale = params.uniforms.uElevationScale.toVar();
+      const hL = evaluateElevationAt(worldX.sub(eps), worldZ).mul(
+        elevationScale
+      );
+      const hR = evaluateElevationAt(worldX.add(eps), worldZ).mul(
+        elevationScale
+      );
+      const hD = evaluateElevationAt(worldX, worldZ.sub(eps)).mul(
+        elevationScale
+      );
+      const hU = evaluateElevationAt(worldX, worldZ.add(eps)).mul(
+        elevationScale
+      );
+      const inv2eps = tsl.float(0.5).div(eps);
+      const dhdx = hR.sub(hL).mul(inv2eps);
+      const dhdz = hU.sub(hD).mul(inv2eps);
+      return tsl.vec3(dhdx.negate(), tsl.float(1), dhdz.negate()).normalize();
+    }
+  );
+  const evaluateNormal = (worldX, worldZ, epsilon) => evaluateNormalNode(worldX, worldZ, epsilon ?? tsl.float(0.1));
+  return {
+    sampleElevation,
+    sampleNormal,
+    sampleTerrain,
+    sampleValidity,
+    evaluateElevation,
+    evaluateNormal
+  };
+}
+
+const createTerrainSamplerTask = work.task((get, work) => {
+  const terrainFieldStorage = get(createTerrainFieldTextureTask);
+  const spatialIndex = get(gpuSpatialIndexStorageTask);
+  const uniforms = get(createUniformsTask);
+  const elevationCallback = get(elevationFn);
+  return work(
+    () => createTerrainSampler({
+      terrainFieldStorage,
+      spatialIndex,
+      uniforms,
+      elevationCallback
+    })
+  );
+}).displayName("createTerrainSamplerTask");
+
 const isSkirtVertex = tsl.Fn(([segments]) => {
   const segmentsNode = typeof segments === "number" ? tsl.int(segments) : segments;
   const vIndex = tsl.int(tsl.vertexIndex);
@@ -1691,14 +1974,15 @@ function createTileBaseWorldPosition(leafStorage, terrainUniforms) {
 }
 function createTileElevation(terrainUniforms, terrainFieldStorage) {
   if (!terrainFieldStorage) return tsl.float(0);
-  const edgeVertexCount = terrainUniforms.uInnerTileSegments.add(3);
-  return readElevationFieldAtPositionLocal(
+  const innerSegs = terrainUniforms.uInnerTileSegments;
+  const u = tileLocalToFieldUV(tsl.positionLocal.x.add(tsl.float(0.5)), innerSegs);
+  const v = tileLocalToFieldUV(tsl.positionLocal.z.add(tsl.float(0.5)), innerSegs);
+  return sampleTerrainFieldElevation(
     terrainFieldStorage,
-    edgeVertexCount,
-    tsl.positionLocal
-  )().mul(
-    terrainUniforms.uElevationScale
-  );
+    u,
+    v,
+    tsl.int(tsl.instanceIndex)
+  ).mul(terrainUniforms.uElevationScale);
 }
 function createNormalAssignment(terrainUniforms, terrainFieldStorage) {
   if (!terrainFieldStorage) return;
@@ -1707,7 +1991,12 @@ function createNormalAssignment(terrainUniforms, terrainFieldStorage) {
   const localVertexIndex = tsl.int(tsl.vertexIndex);
   const ix = localVertexIndex.mod(edgeVertexCount);
   const iy = localVertexIndex.div(edgeVertexCount);
-  const normalXZ = loadTerrainFieldNormal(terrainFieldStorage, ix, iy, nodeIndex);
+  const normalXZ = loadTerrainFieldNormal(
+    terrainFieldStorage,
+    ix,
+    iy,
+    nodeIndex
+  );
   const nx = normalXZ.x;
   const nz = normalXZ.y;
   const nySq = tsl.float(1).sub(nx.mul(nx)).sub(nz.mul(nz)).max(tsl.float(0));
@@ -1715,10 +2004,16 @@ function createNormalAssignment(terrainUniforms, terrainFieldStorage) {
   tsl.normalLocal.assign(tsl.vec3(nx, ny, nz));
 }
 function createTileWorldPosition(leafStorage, terrainUniforms, terrainFieldStorage) {
-  const baseWorldPosition = createTileBaseWorldPosition(leafStorage, terrainUniforms);
+  const baseWorldPosition = createTileBaseWorldPosition(
+    leafStorage,
+    terrainUniforms
+  );
   return tsl.Fn(() => {
     const base = baseWorldPosition();
-    const yElevation = createTileElevation(terrainUniforms, terrainFieldStorage);
+    const yElevation = createTileElevation(
+      terrainUniforms,
+      terrainFieldStorage
+    );
     const skirtVertex = isSkirtVertex(terrainUniforms.uInnerTileSegments);
     const skirtY = base.y.add(yElevation).sub(terrainUniforms.uSkirtScale.toVar());
     const worldY = tsl.select(skirtVertex, skirtY, base.y.add(yElevation));
@@ -1741,7 +2036,7 @@ const positionNodeTask = work.task((get, work) => {
 }).displayName("positionNodeTask");
 
 function terrainGraph() {
-  return work.graph().add(instanceIdTask).add(quadtreeConfigTask).add(quadtreeUpdateTask).add(leafStorageTask).add(surfaceTask).add(leafGpuBufferTask).add(createUniformsTask).add(updateUniformsTask).add(positionNodeTask).add(createElevationFieldContextTask).add(tileNodesTask).add(createTerrainFieldTextureTask).add(elevationFieldStageTask).add(terrainFieldStageTask).add(compileComputeTask).add(executeComputeTask);
+  return work.graph().add(instanceIdTask).add(quadtreeConfigTask).add(quadtreeUpdateTask).add(leafStorageTask).add(surfaceTask).add(leafGpuBufferTask).add(gpuSpatialIndexStorageTask).add(gpuSpatialIndexUploadTask).add(createUniformsTask).add(updateUniformsTask).add(positionNodeTask).add(createElevationFieldContextTask).add(tileNodesTask).add(createTerrainFieldTextureTask).add(createTerrainSamplerTask).add(elevationFieldStageTask).add(terrainFieldStageTask).add(compileComputeTask).add(executeComputeTask);
 }
 const terrainTasks = {
   instanceId: instanceIdTask,
@@ -1750,12 +2045,15 @@ const terrainTasks = {
   leafStorage: leafStorageTask,
   surface: surfaceTask,
   leafGpuBuffer: leafGpuBufferTask,
+  gpuSpatialIndexStorage: gpuSpatialIndexStorageTask,
+  gpuSpatialIndexUpload: gpuSpatialIndexUploadTask,
   createUniforms: createUniformsTask,
   updateUniforms: updateUniformsTask,
   positionNode: positionNodeTask,
   createElevationFieldContext: createElevationFieldContextTask,
   createTileNodes: tileNodesTask,
   createTerrainFieldTexture: createTerrainFieldTextureTask,
+  createTerrainSampler: createTerrainSamplerTask,
   elevationFieldStage: elevationFieldStageTask,
   terrainFieldStage: terrainFieldStageTask,
   compileCompute: compileComputeTask,
@@ -1837,6 +2135,8 @@ exports.createSpatialIndex = createSpatialIndex;
 exports.createState = createState;
 exports.createTerrainFieldStorage = createTerrainFieldStorage;
 exports.createTerrainFieldTextureTask = createTerrainFieldTextureTask;
+exports.createTerrainSampler = createTerrainSampler;
+exports.createTerrainSamplerTask = createTerrainSamplerTask;
 exports.createTerrainUniforms = createTerrainUniforms;
 exports.createUniformsTask = createUniformsTask;
 exports.deriveNormalZ = deriveNormalZ;
@@ -1845,6 +2145,8 @@ exports.elevationFn = elevationFn;
 exports.elevationScale = elevationScale;
 exports.executeComputeTask = executeComputeTask;
 exports.getDeviceComputeLimits = getDeviceComputeLimits;
+exports.gpuSpatialIndexStorageTask = gpuSpatialIndexStorageTask;
+exports.gpuSpatialIndexUploadTask = gpuSpatialIndexUploadTask;
 exports.innerTileSegments = innerTileSegments;
 exports.instanceIdTask = instanceIdTask;
 exports.isSkirtUV = isSkirtUV;
@@ -1865,10 +2167,14 @@ exports.quadtreeUpdateTask = quadtreeUpdateTask;
 exports.resetLeafSet = resetLeafSet;
 exports.resetSeamTable = resetSeamTable;
 exports.rootSize = rootSize;
+exports.sampleTerrainField = sampleTerrainField;
+exports.sampleTerrainFieldElevation = sampleTerrainFieldElevation;
+exports.sampleTerrainFieldNormal = sampleTerrainFieldNormal;
 exports.skirtScale = skirtScale;
 exports.storeTerrainField = storeTerrainField;
 exports.surface = surface;
 exports.surfaceTask = surfaceTask;
+exports.terrainFieldFilter = terrainFieldFilter;
 exports.terrainFieldStageTask = terrainFieldStageTask;
 exports.terrainGraph = terrainGraph;
 exports.terrainTasks = terrainTasks;