@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/render/clipmap.js

@@ -1,15 +1,33 @@
-import { AABB, Vector3, Disposable, Matrix4x4, ClipState, Vector2 } from '@zephyr3d/base';
+import { AABB, Vector3, Vector2, BoxSide, Disposable, Matrix4x4, ClipState } from '@zephyr3d/base';
 import { Primitive } from './primitive.js';
 import { getVertexAttributeIndex, VERTEX_ATTRIB_POSITION, VERTEX_ATTRIB_TEXCOORD0, getVertexAttributeFormat } from '@zephyr3d/device';
 
 const tmpAABB = new AABB();
 const tmpV3 = new Vector3();
+// Scratch vectors for gather() and calcLevelAABB(), which run per camera every frame
+const tmpSnappedPos = new Vector2();
+const tmpTileSize = new Vector2();
+const tmpBase = new Vector2();
+const tmpOffset = new Vector2();
+const tmpNextSnappedPos = new Vector2();
+const tmpTileCentre = new Vector2();
+const tmpNextBase = new Vector2();
 const rotationValues = [
     0,
     Math.PI * 1.5,
     Math.PI * 0.5,
     Math.PI
 ];
+/**
+ * Frustum plane mask covering everything but the far plane, for a clipmap that
+ * reaches past it. @internal
+ */ /**
+ * Instance data is rewritten for every camera every frame: dynamic buffers keep their upload
+ * staging buffers for reuse instead of creating and destroying one per upload
+ */ const INSTANCE_BUFFER_OPTIONS = {
+    dynamic: true
+};
+const ALL_PLANES_EXCEPT_FAR = 0b111111 & ~(1 << BoxSide.BACK);
 /** @internal */ class Clipmap extends Disposable {
     _instanceDataPool;
     _instanceDataPoolSize;
@@ -37,7 +55,13 @@ const rotationValues = [
     _seamMesh;
     _seamMeshLines;
     _seamMeshAABB;
+    _skirtMesh;
+    _skirtMeshLines;
     _wireframe;
+    _levelAABBs;
+    /** Grid origin of the gather/cull call in progress, see ClipmapGatherContext.gridOriginX */ _originX;
+    _originZ;
+    _cullScratch;
     constructor(resolution, extraInstanceBuffers, maxMipLevels = 64){
         super();
         if (extraInstanceBuffers && extraInstanceBuffers.findIndex((val)=>getVertexAttributeIndex(val) === VERTEX_ATTRIB_POSITION || getVertexAttributeIndex(val) === VERTEX_ATTRIB_TEXCOORD0 || getVertexAttributeFormat(val) !== 'f32') >= 0) {
@@ -55,11 +79,16 @@ const rotationValues = [
         this._nonInstanceMipLevelDataPool = [];
         this._nonInstanceMipLevelDataPoolSize = 0;
         this._wireframe = false;
+        this._levelAABBs = [];
+        this._originX = 0;
+        this._originZ = 0;
+        this._cullScratch = new Map();
         this.generateCrossMesh();
         this.generateFillerMesh();
         this.generateSeamMesh();
         this.generateTileMesh();
         this.generateTrimMesh();
+        this.generateSkirtMesh();
     }
     get wireframe() {
         return this._wireframe;
@@ -73,11 +102,13 @@ const rotationValues = [
     set tileResolution(val) {
         if (val !== this._tileResolution) {
             this._tileResolution = val;
+            this._cullScratch.clear();
             this.generateCrossMesh();
             this.generateFillerMesh();
             this.generateSeamMesh();
             this.generateTileMesh();
             this.generateTrimMesh();
+            this.generateSkirtMesh();
         }
     }
     allocInstanceBuffer() {
@@ -175,10 +206,10 @@ const rotationValues = [
             }
         }
         this._tileMesh.createAndSetVertexBuffer('position_f32x3', vertices);
-        this._tileMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._tileMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._tileMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._tileMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._tileMesh.createAndSetIndexBuffer(indices);
@@ -198,10 +229,10 @@ const rotationValues = [
         this._tileMeshLines?.dispose();
         this._tileMeshLines = new Primitive();
         this._tileMeshLines.setVertexBuffer(this._tileMesh.getVertexBuffer('position'));
-        this._tileMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._tileMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._tileMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._tileMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._tileMeshLines.createAndSetIndexBuffer(indicesLines);
@@ -273,10 +304,10 @@ const rotationValues = [
             }
         }
         this._fillerMesh.createAndSetVertexBuffer('position_f32x3', vertices);
-        this._fillerMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._fillerMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._fillerMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._fillerMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._fillerMesh.createAndSetIndexBuffer(indices);
@@ -296,10 +327,10 @@ const rotationValues = [
         this._fillerMeshLines?.dispose();
         this._fillerMeshLines = new Primitive();
         this._fillerMeshLines.setVertexBuffer(this._fillerMesh.getVertexBuffer('position'));
-        this._fillerMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._fillerMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._fillerMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._fillerMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._fillerMeshLines.createAndSetIndexBuffer(indicesLines);
@@ -350,10 +381,10 @@ const rotationValues = [
             indices[n++] = startOfHorizonal + (i + 0) * 2 + 1;
         }
         this._trimMesh.createAndSetVertexBuffer('position_f32x3', vertices);
-        this._trimMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._trimMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._trimMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._trimMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._trimMesh.createAndSetIndexBuffer(indices);
@@ -373,10 +404,10 @@ const rotationValues = [
         this._trimMeshLines?.dispose();
         this._trimMeshLines = new Primitive();
         this._trimMeshLines.setVertexBuffer(this._trimMesh.getVertexBuffer('position'));
-        this._trimMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._trimMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._trimMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._trimMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._trimMeshLines.createAndSetIndexBuffer(indicesLines);
@@ -437,10 +468,10 @@ const rotationValues = [
         this._crossMesh?.dispose();
         this._crossMesh = new Primitive();
         this._crossMesh.createAndSetVertexBuffer('position_f32x3', vertices);
-        this._crossMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+        this._crossMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._nonInstanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._crossMesh.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+            this._crossMesh.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._nonInstanceDataPoolSize++;
         }
         this._crossMesh.createAndSetIndexBuffer(indices);
@@ -460,10 +491,10 @@ const rotationValues = [
         this._crossMeshLines?.dispose();
         this._crossMeshLines = new Primitive();
         this._crossMeshLines.setVertexBuffer(this._crossMesh.getVertexBuffer('position'));
-        this._crossMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+        this._crossMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._nonInstanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._crossMeshLines.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+            this._crossMeshLines.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._nonInstanceDataPoolSize++;
         }
         this._crossMeshLines.createAndSetIndexBuffer(indicesLines);
@@ -490,6 +521,16 @@ const rotationValues = [
             vertices[(clipmapVertResolution * 3 + i) * 3 + 1] = clipmapVertResolution - i;
             vertices[(clipmapVertResolution * 3 + i) * 3 + 2] = 0;
         }
+        // Seam triangles are collinear in XZ by design: each odd vertex is the midpoint between two
+        // coarse-level vertices. Flag those midpoints with position.z = -side (1..4) so a shader
+        // clamping the grid to a finite region can snap them onto their previous neighbour when
+        // the whole seam edge lies outside it; otherwise the flap they form stands up as a vertical
+        // curtain along the region border. Negative, so it never reads as the skirt flag.
+        for(let side = 0; side < 4; side++){
+            for(let i = 1; i < clipmapVertResolution; i += 2){
+                vertices[(clipmapVertResolution * side + i) * 3 + 2] = -(side + 1);
+            }
+        }
         const indices = new Uint16Array(clipmapVertResolution * 6);
         let n = 0;
         for(let i = 0; i < clipmapVertResolution * 4; i += 2){
@@ -499,10 +540,10 @@ const rotationValues = [
         }
         indices[indices.length - 1] = 0;
         this._seamMesh.createAndSetVertexBuffer('position_f32x3', vertices);
-        this._seamMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._seamMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._seamMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._seamMesh.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._seamMesh.createAndSetIndexBuffer(indices);
@@ -522,10 +563,10 @@ const rotationValues = [
         this._seamMeshLines?.dispose();
         this._seamMeshLines = new Primitive();
         this._seamMeshLines.setVertexBuffer(this._seamMesh.getVertexBuffer('position'));
-        this._seamMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance');
+        this._seamMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
         this._instanceDataPoolSize++;
         for (const fmt of this._extraInstanceBuffers){
-            this._seamMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance');
+            this._seamMeshLines.createAndSetVertexBuffer(fmt, this.allocInstanceBuffer(), 'instance', INSTANCE_BUFFER_OPTIONS);
             this._instanceDataPoolSize++;
         }
         this._seamMeshLines.createAndSetIndexBuffer(indicesLines);
@@ -533,6 +574,112 @@ const rotationValues = [
         this._seamMeshLines.indexCount = indicesLines.length;
         this._seamMeshLines.primitiveType = 'line-list';
     }
+    /**
+   * Ring of quads welded to the outer boundary of the outermost level, whose
+   * outer edge the vertex shader is expected to push towards the horizon.
+   *
+   * The inner edge has to land on exactly the vertices the outermost tiles end
+   * on, or a displaced surface tears along the join: both sides evaluate the
+   * same wave function, so identical world positions are what keeps them
+   * identical. That boundary runs from `-2 * tileResolution` to
+   * `2 * tileResolution + 1` in the level's local units - the asymmetry is the
+   * `fillX`/`fillY` shift `gather` applies to the far tiles - which is
+   * `clipmapVertResolution` vertices a side, the same density the seam mesh
+   * uses.
+   *
+   * Outer vertices are flagged with `position.z = 1`. Every other clipmap mesh
+   * leaves z at 0 and the shader's clipmap matrix only reads xy, so the
+   * component is free to carry the flag without a second vertex stream.
+   */ generateSkirtMesh() {
+        const clipmapVertResolution = this._tileResolution * 4 + 2;
+        const lo = -2 * this._tileResolution;
+        const hi = 2 * this._tileResolution + 1;
+        // Unique positions around the perimeter: each side contributes all but its
+        // last vertex, which is the next side's first, so the loop closes without
+        // doubling the corners.
+        const perSide = clipmapVertResolution - 1;
+        const ringCount = perSide * 4;
+        const vertices = new Float32Array(ringCount * 2 * 3);
+        // Placeholder extent for the outer ring. The vertex shader relocates these
+        // vertices, so this only has to be outside the inner ring and finite.
+        const outerFactor = 8;
+        const centre = (lo + hi) * 0.5;
+        let n = 0;
+        const putRing = (index, x, y, outer)=>{
+            const px = outer ? centre + (x - centre) * outerFactor : x;
+            const py = outer ? centre + (y - centre) * outerFactor : y;
+            const base = (index + (outer ? ringCount : 0)) * 3;
+            vertices[base + 0] = px;
+            vertices[base + 1] = py;
+            vertices[base + 2] = outer ? 1 : 0;
+        };
+        for(let i = 0; i < perSide; i++){
+            putRing(n, lo + i, lo, false);
+            putRing(n, lo + i, lo, true);
+            n++;
+        }
+        for(let i = 0; i < perSide; i++){
+            putRing(n, hi, lo + i, false);
+            putRing(n, hi, lo + i, true);
+            n++;
+        }
+        for(let i = 0; i < perSide; i++){
+            putRing(n, hi - i, hi, false);
+            putRing(n, hi - i, hi, true);
+            n++;
+        }
+        for(let i = 0; i < perSide; i++){
+            putRing(n, lo, hi - i, false);
+            putRing(n, lo, hi - i, true);
+            n++;
+        }
+        const indices = new Uint16Array(ringCount * 6);
+        n = 0;
+        for(let k = 0; k < ringCount; k++){
+            const j = (k + 1) % ringCount;
+            indices[n++] = k;
+            indices[n++] = j;
+            indices[n++] = ringCount + j;
+            indices[n++] = k;
+            indices[n++] = ringCount + j;
+            indices[n++] = ringCount + k;
+        }
+        this._skirtMesh?.dispose();
+        this._skirtMesh = new Primitive();
+        this._skirtMesh.createAndSetVertexBuffer('position_f32x3', vertices);
+        this._skirtMesh.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
+        this._nonInstanceDataPoolSize++;
+        for (const fmt of this._extraInstanceBuffers){
+            this._skirtMesh.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
+            this._nonInstanceDataPoolSize++;
+        }
+        this._skirtMesh.createAndSetIndexBuffer(indices);
+        this._skirtMesh.indexStart = 0;
+        this._skirtMesh.indexCount = indices.length;
+        this._skirtMesh.primitiveType = 'triangle-list';
+        const indicesLines = new Uint16Array(indices.length * 2);
+        for(let i = 0; i < indices.length / 3; i++){
+            indicesLines[i * 6 + 0] = indices[i * 3 + 0];
+            indicesLines[i * 6 + 1] = indices[i * 3 + 1];
+            indicesLines[i * 6 + 2] = indices[i * 3 + 1];
+            indicesLines[i * 6 + 3] = indices[i * 3 + 2];
+            indicesLines[i * 6 + 4] = indices[i * 3 + 2];
+            indicesLines[i * 6 + 5] = indices[i * 3 + 0];
+        }
+        this._skirtMeshLines?.dispose();
+        this._skirtMeshLines = new Primitive();
+        this._skirtMeshLines.setVertexBuffer(this._skirtMesh.getVertexBuffer('position'));
+        this._skirtMeshLines.createAndSetVertexBuffer('tex0_f32x4', this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
+        this._nonInstanceDataPoolSize++;
+        for (const fmt of this._extraInstanceBuffers){
+            this._skirtMeshLines.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance', INSTANCE_BUFFER_OPTIONS);
+            this._nonInstanceDataPoolSize++;
+        }
+        this._skirtMeshLines.createAndSetIndexBuffer(indicesLines);
+        this._skirtMeshLines.indexStart = 0;
+        this._skirtMeshLines.indexCount = indicesLines.length;
+        this._skirtMeshLines.primitiveType = 'line-list';
+    }
     intervalsOverlap(a0, a1, b0, b1) {
         return a0 <= b1 && b0 <= a1;
     }
@@ -543,10 +690,10 @@ const rotationValues = [
         } else {
             AABB.transform(aabb, Matrix4x4.rotationZ(rotation), tmpAABB);
         }
-        const minX = (tmpAABB.minPoint.x * scale + offset.x) * gridScale;
-        const maxX = (tmpAABB.maxPoint.x * scale + offset.x) * gridScale;
-        const minZ = (tmpAABB.minPoint.y * scale + offset.y) * gridScale;
-        const maxZ = (tmpAABB.maxPoint.y * scale + offset.y) * gridScale;
+        const minX = (tmpAABB.minPoint.x * scale + offset.x) * gridScale + this._originX;
+        const maxX = (tmpAABB.maxPoint.x * scale + offset.x) * gridScale + this._originX;
+        const minZ = (tmpAABB.minPoint.y * scale + offset.y) * gridScale + this._originZ;
+        const maxZ = (tmpAABB.maxPoint.y * scale + offset.y) * gridScale + this._originZ;
         if (minX < outAABB.minPoint.x) {
             outAABB.minPoint.x = minX;
         }
@@ -567,27 +714,46 @@ const rotationValues = [
         } else {
             AABB.transform(aabb, Matrix4x4.rotationZ(rotation), tmpAABB);
         }
-        const minX = (tmpAABB.minPoint.x * scale + offset.x) * gridScale;
-        const maxX = (tmpAABB.maxPoint.x * scale + offset.x) * gridScale;
-        const minZ = (tmpAABB.minPoint.y * scale + offset.y) * gridScale;
-        const maxZ = (tmpAABB.maxPoint.y * scale + offset.y) * gridScale;
+        const minX = (tmpAABB.minPoint.x * scale + offset.x) * gridScale + this._originX;
+        const maxX = (tmpAABB.maxPoint.x * scale + offset.x) * gridScale + this._originX;
+        const minZ = (tmpAABB.minPoint.y * scale + offset.y) * gridScale + this._originZ;
+        const maxZ = (tmpAABB.maxPoint.y * scale + offset.y) * gridScale + this._originZ;
         ctx.calcAABB(ctx.userData, minX, maxX, minZ, maxZ, tmpAABB, level);
+        if (camera.clipMask) {
+            // Shadow cull cameras test only some planes: a directional cascade keeps casters at any
+            // depth along the light.
+            const mask = ctx.skirt ? camera.clipMask & ALL_PLANES_EXCEPT_FAR : camera.clipMask;
+            return tmpAABB.getClipStateWithFrustumMask(camera.frustum, mask) !== ClipState.NOT_CLIPPED;
+        }
+        if (ctx.skirt) {
+            // Every plane except the far one. A skirted clipmap deliberately reaches
+            // past the far plane and pins the depth of whatever lands beyond it, so
+            // culling against that plane here would throw away exactly the tiles the
+            // skirt is there to lead up to - leaving a gap between the last surviving
+            // tile and the ring, with the sky showing through it.
+            return tmpAABB.getClipStateWithFrustumMask(camera.frustum, ALL_PLANES_EXCEPT_FAR) !== ClipState.NOT_CLIPPED;
+        }
         return tmpAABB.getClipStateWithFrustum(camera.frustum) !== ClipState.NOT_CLIPPED;
     }
-    calcLevelAABB(camera, minMaxWorldPos, gridScale) {
+    calcLevelAABB(camera, minMaxWorldPos, gridScale, gridOriginX = 0, gridOriginZ = 0) {
+        this._originX = gridOriginX;
+        this._originZ = gridOriginZ;
         const mipLevels = this.calcMipLevels(camera, minMaxWorldPos, gridScale);
         camera.getWorldPosition(tmpV3);
-        const snappedPos = new Vector2();
-        const tileSize = new Vector2();
-        const base = new Vector2();
-        const offset = new Vector2();
-        const posX = tmpV3.x / gridScale;
-        const posY = tmpV3.z / gridScale;
-        const outAABB = [];
-        for(let i = 0; i < mipLevels; i++){
-            const aabb = new AABB();
+        const snappedPos = tmpSnappedPos;
+        const tileSize = tmpTileSize;
+        const base = tmpBase;
+        const offset = tmpOffset;
+        const posX = (tmpV3.x - gridOriginX) / gridScale;
+        const posY = (tmpV3.z - gridOriginZ) / gridScale;
+        // Reused across calls: callers consume the result before the next one
+        const outAABB = this._levelAABBs;
+        while(outAABB.length < mipLevels){
+            outAABB.push(new AABB());
+        }
+        outAABB.length = mipLevels;
+        for (const aabb of outAABB){
             aabb.beginExtend();
-            outAABB.push(aabb);
         }
         snappedPos.setXY(Math.floor(posX), Math.floor(posY));
         // cross
@@ -613,25 +779,29 @@ const rotationValues = [
             // draw filler
             this.updateAABB(this._fillerMeshAABB, null, snappedPos, scale, gridScale, aabb);
             const nextScale = scale * 2;
-            const nextSnappedPos = new Vector2(Math.floor(posX / nextScale) * nextScale, Math.floor(posY / nextScale) * nextScale);
+            const nextSnappedPos = tmpNextSnappedPos.setXY(Math.floor(posX / nextScale) * nextScale, Math.floor(posY / nextScale) * nextScale);
             // draw trim
-            const tileCentre = new Vector2(snappedPos.x + scale * 0.5, snappedPos.y + scale * 0.5);
-            const d = new Vector2(posX - nextSnappedPos.x, posY - nextSnappedPos.y);
+            const tileCentre = tmpTileCentre.setXY(snappedPos.x + scale * 0.5, snappedPos.y + scale * 0.5);
             let r = 0;
-            r |= d.x >= scale ? 0 : 2;
-            r |= d.y >= scale ? 0 : 1;
+            r |= posX - nextSnappedPos.x >= scale ? 0 : 2;
+            r |= posY - nextSnappedPos.y >= scale ? 0 : 1;
             this.updateAABB(this._trimMeshAABB, rotationValues[r], tileCentre, scale, gridScale, aabb);
             // draw seam
-            const nextBase = new Vector2(nextSnappedPos.x - (this._tileResolution << l + 1), nextSnappedPos.y - (this._tileResolution << l + 1));
+            const nextBase = tmpNextBase.setXY(nextSnappedPos.x - (this._tileResolution << l + 1), nextSnappedPos.y - (this._tileResolution << l + 1));
             this.updateAABB(this._seamMeshAABB, null, nextBase, scale, gridScale, aabb);
         }
         return outAABB;
     }
-    calcMipLevels(camera, minMaxWorldPos, gridScale) {
+    calcMipLevels(camera, minMaxWorldPos, gridScale, viewDistance) {
         camera.getWorldPosition(tmpV3);
         const distX = Math.max(Math.abs(tmpV3.x - minMaxWorldPos.x), Math.abs(tmpV3.x - minMaxWorldPos.z));
         const distY = Math.max(Math.abs(tmpV3.z - minMaxWorldPos.y), Math.abs(tmpV3.z - minMaxWorldPos.w));
-        const maxDist = Math.min(Math.max(distX, distY), camera.getFarPlane());
+        // The reach is the caller's when it supplies one; the far plane is only the
+        // default. An infinite water surface draws its horizon ring beyond the far
+        // plane and clamps the depth in the vertex shader, so capping the levels
+        // here would starve it of the very tiles it needs.
+        const maxReach = viewDistance && viewDistance > 0 ? viewDistance : camera.getFarPlane();
+        const maxDist = Math.min(Math.max(distX, distY), maxReach);
         return Math.min(Math.max(Math.ceil(Math.log2(maxDist / (this._tileResolution * gridScale))), 0) + 1, this._maxMipLevels);
     }
     addInstance(info, rotation, offsetX, offsetY, scale, mipLevel) {
@@ -649,14 +819,16 @@ const rotationValues = [
         this._nonInstanceDataPoolSize = this._nonInstanceDataPool.length;
         this._nonInstanceMipLevelDataPoolSize = this._nonInstanceMipLevelDataPool.length;
         const renderData = [];
-        const mipLevels = this.calcMipLevels(context.camera, context.minMaxWorldPos, context.gridScale);
+        const mipLevels = this.calcMipLevels(context.camera, context.minMaxWorldPos, context.gridScale, context.viewDistance);
         context.camera.getWorldPosition(tmpV3);
-        const snappedPos = new Vector2();
-        const tileSize = new Vector2();
-        const base = new Vector2();
-        const offset = new Vector2();
-        const posX = tmpV3.x / context.gridScale;
-        const posY = tmpV3.z / context.gridScale;
+        const snappedPos = tmpSnappedPos;
+        const tileSize = tmpTileSize;
+        const base = tmpBase;
+        const offset = tmpOffset;
+        this._originX = context.gridOriginX ?? 0;
+        this._originZ = context.gridOriginZ ?? 0;
+        const posX = (tmpV3.x - this._originX) / context.gridScale;
+        const posY = (tmpV3.z - this._originZ) / context.gridScale;
         // draw cross
         snappedPos.setXY(Math.floor(posX), Math.floor(posY));
         if (!context.frustumCulling || this.visible(context, this._crossMeshAABB, context.camera, null, snappedPos, 1, context.gridScale, 0)) {
@@ -711,7 +883,13 @@ const rotationValues = [
                     const fillX = x >= 2 ? scale : 0;
                     const fillY = y >= 2 ? scale : 0;
                     offset.setXY(base.x + x * tileSize.x + fillX, base.y + y * tileSize.y + fillY);
-                    if (this.intervalsOverlap(offset.x * context.gridScale, (offset.x + tileSize.x) * context.gridScale, context.minMaxWorldPos.x, context.minMaxWorldPos.z) && this.intervalsOverlap(offset.y * context.gridScale, (offset.y + tileSize.y) * context.gridScale, context.minMaxWorldPos.y, context.minMaxWorldPos.w)) {
+                    if (// An unbounded surface has no rectangle to keep tiles inside of.
+                    // Passing a very large one instead does not work: the clipmap's
+                    // outermost level reaches 2 * tileResolution << (levels - 1), which
+                    // at a raised camera is tens of kilometres and outgrows any sentinel
+                    // rectangle - dropping the outer tiles and opening a band of sky
+                    // between the last one drawn and the horizon skirt.
+                    context.skirt || this.intervalsOverlap(offset.x * context.gridScale + this._originX, (offset.x + tileSize.x) * context.gridScale + this._originX, context.minMaxWorldPos.x, context.minMaxWorldPos.z) && this.intervalsOverlap(offset.y * context.gridScale + this._originZ, (offset.y + tileSize.y) * context.gridScale + this._originZ, context.minMaxWorldPos.y, context.minMaxWorldPos.w)) {
                         if (!context.frustumCulling || this.visible(context, this._tileMeshBBox, context.camera, null, offset, scale, context.gridScale, l)) {
                             this.addInstance(tilePrimitives, rotationValues[0], offset.x, offset.y, scale, l);
                         }
@@ -724,18 +902,17 @@ const rotationValues = [
             }
             if (l !== mipLevels - 1) {
                 const nextScale = scale * 2;
-                const nextSnappedPos = new Vector2(Math.floor(posX / nextScale) * nextScale, Math.floor(posY / nextScale) * nextScale);
+                const nextSnappedPos = tmpNextSnappedPos.setXY(Math.floor(posX / nextScale) * nextScale, Math.floor(posY / nextScale) * nextScale);
                 // draw trim
-                const tileCentre = new Vector2(snappedPos.x + scale * 0.5, snappedPos.y + scale * 0.5);
-                const d = new Vector2(posX - nextSnappedPos.x, posY - nextSnappedPos.y);
+                const tileCentre = tmpTileCentre.setXY(snappedPos.x + scale * 0.5, snappedPos.y + scale * 0.5);
                 let r = 0;
-                r |= d.x >= scale ? 0 : 2;
-                r |= d.y >= scale ? 0 : 1;
+                r |= posX - nextSnappedPos.x >= scale ? 0 : 2;
+                r |= posY - nextSnappedPos.y >= scale ? 0 : 1;
                 if (!context.frustumCulling || this.visible(context, this._trimMeshAABB, context.camera, rotationValues[r], tileCentre, scale, context.gridScale, l)) {
                     this.addInstance(trimPrimitives, rotationValues[r], tileCentre.x, tileCentre.y, scale, l);
                 }
                 // draw seam
-                const nextBase = new Vector2(nextSnappedPos.x - (this._tileResolution << l + 1), nextSnappedPos.y - (this._tileResolution << l + 1));
+                const nextBase = tmpNextBase.setXY(nextSnappedPos.x - (this._tileResolution << l + 1), nextSnappedPos.y - (this._tileResolution << l + 1));
                 if (!context.frustumCulling || this.visible(context, this._seamMeshAABB, context.camera, null, nextBase, scale, context.gridScale, l)) {
                     this.addInstance(seamPrimitives, rotationValues[0], nextBase.x, nextBase.y, scale, l);
                 }
@@ -753,11 +930,98 @@ const rotationValues = [
         if (seamPrimitives.numInstances > 0) {
             renderData.push(seamPrimitives);
         }
+        if (context.skirt) {
+            // Welded to the outer boundary of the outermost level, so it carries that
+            // level's scale and snapped origin. Never frustum-culled: the ring spans
+            // the whole horizon, and its outer edge is relocated by the vertex shader,
+            // so the AABB tested here would not describe where it actually lands.
+            const outerLevel = mipLevels - 1;
+            const outerScale = 1 << outerLevel;
+            snappedPos.setXY(Math.floor(posX / outerScale) * outerScale, Math.floor(posY / outerScale) * outerScale);
+            renderData.push({
+                primitive: this._wireframe ? this._skirtMeshLines : this._skirtMesh,
+                numInstances: 1,
+                instanceDatas: this.allocNonInstanceBuffer(rotationValues[0], outerScale, snappedPos.x, snappedPos.y),
+                mipLevels: this.allocNonInstanceMipLevelBuffer(outerLevel),
+                maxMiplevel: outerLevel
+            });
+        }
         for (const info of renderData){
             info.primitive.getVertexBuffer('texCoord0').bufferSubData(0, info.instanceDatas, 0, info.numInstances * 4);
         }
         return renderData;
     }
+    /**
+   * Keeps the instances of a set returned by {@link Clipmap.gather} that `context.camera` can
+   * see, and uploads them in place of the gathered ones.
+   *
+   * For passes that render the same clipmap from several cameras - a shadow map culls each
+   * cascade or cube face with its own - gather once without frustum culling, then call this
+   * before each draw. The source set is left untouched, so it can be culled again for the next
+   * camera; the returned set is only valid until the next call.
+   *
+   * Non-instanced meshes (the cross and the skirt) are always kept.
+   *
+   * @param renderData - A set returned by gather() for this clipmap in the current frame
+   * @param context - Gather context whose camera is the one to cull with
+   * @returns The culled set
+   */ cullInstances(renderData, context) {
+        this._originX = context.gridOriginX ?? 0;
+        this._originZ = context.gridOriginZ ?? 0;
+        const result = [];
+        for (const info of renderData){
+            const meshAABB = this.getInstancedMeshAABB(info.primitive);
+            if (!meshAABB) {
+                result.push(info);
+                continue;
+            }
+            let scratch = this._cullScratch.get(info.primitive);
+            if (!scratch) {
+                scratch = {
+                    instanceDatas: new Float32Array(info.instanceDatas.length),
+                    mipLevels: new Float32Array(info.mipLevels.length)
+                };
+                this._cullScratch.set(info.primitive, scratch);
+            }
+            let numInstances = 0;
+            let maxMiplevel = 0;
+            for(let i = 0; i < info.numInstances; i++){
+                const rotation = info.instanceDatas[i * 4 + 0];
+                const scale = info.instanceDatas[i * 4 + 1];
+                const level = info.mipLevels[i];
+                tmpOffset.setXY(info.instanceDatas[i * 4 + 2], info.instanceDatas[i * 4 + 3]);
+                if (this.visible(context, meshAABB, context.camera, rotation, tmpOffset, scale, context.gridScale, level)) {
+                    scratch.instanceDatas.set(info.instanceDatas.subarray(i * 4, i * 4 + 4), numInstances * 4);
+                    scratch.mipLevels[numInstances] = level;
+                    maxMiplevel = Math.max(maxMiplevel, level);
+                    numInstances++;
+                }
+            }
+            if (numInstances > 0) {
+                info.primitive.getVertexBuffer('texCoord0').bufferSubData(0, scratch.instanceDatas, 0, numInstances * 4);
+                result.push({
+                    primitive: info.primitive,
+                    numInstances,
+                    instanceDatas: scratch.instanceDatas,
+                    mipLevels: scratch.mipLevels,
+                    maxMiplevel
+                });
+            }
+        }
+        return result;
+    }
+    /** Local bounds of the instanced mesh behind a primitive, null for the non-instanced ones */ getInstancedMeshAABB(primitive) {
+        if (primitive === this._tileMesh || primitive === this._tileMeshLines) {
+            return this._tileMeshBBox;
+        } else if (primitive === this._fillerMesh || primitive === this._fillerMeshLines) {
+            return this._fillerMeshAABB;
+        } else if (primitive === this._trimMesh || primitive === this._trimMeshLines) {
+            return this._trimMeshAABB;
+        } else if (primitive === this._seamMesh || primitive === this._seamMeshLines) {
+            return this._seamMeshAABB;
+        }
+        return null;
+    }
     /** Disposes the clipmap and release all meshes */ onDispose() {
         super.onDispose();
         this._crossMesh.dispose();
@@ -770,6 +1034,8 @@ const rotationValues = [
         this._trimMeshLines.dispose();
         this._tileMesh.dispose();
         this._tileMeshLines.dispose();
+        this._skirtMesh.dispose();
+        this._skirtMeshLines.dispose();
     }
 }