@zephyr3d/scene 0.9.25 → 0.9.27

package/dist/render/clipmap.js

@@ -1,4 +1,4 @@
-import { AABB, Vector3, Disposable, Matrix4x4, ClipState, Vector2 } from '@zephyr3d/base';
+import { AABB, Vector3, BoxSide, Disposable, Matrix4x4, ClipState, Vector2 } from '@zephyr3d/base';
 import { Primitive } from './primitive.js';
 import { getVertexAttributeIndex, VERTEX_ATTRIB_POSITION, VERTEX_ATTRIB_TEXCOORD0, getVertexAttributeFormat } from '@zephyr3d/device';
 
@@ -10,6 +10,10 @@ const rotationValues = [
     Math.PI * 0.5,
     Math.PI
 ];
+/**
+ * Frustum plane mask covering everything but the far plane, for a clipmap that
+ * reaches past it. @internal
+ */ const ALL_PLANES_EXCEPT_FAR = 0b111111 & ~(1 << BoxSide.BACK);
 /** @internal */ class Clipmap extends Disposable {
     _instanceDataPool;
     _instanceDataPoolSize;
@@ -37,6 +41,8 @@ const rotationValues = [
     _seamMesh;
     _seamMeshLines;
     _seamMeshAABB;
+    _skirtMesh;
+    _skirtMeshLines;
     _wireframe;
     constructor(resolution, extraInstanceBuffers, maxMipLevels = 64){
         super();
@@ -60,6 +66,7 @@ const rotationValues = [
         this.generateSeamMesh();
         this.generateTileMesh();
         this.generateTrimMesh();
+        this.generateSkirtMesh();
     }
     get wireframe() {
         return this._wireframe;
@@ -78,6 +85,7 @@ const rotationValues = [
             this.generateSeamMesh();
             this.generateTileMesh();
             this.generateTrimMesh();
+            this.generateSkirtMesh();
         }
     }
     allocInstanceBuffer() {
@@ -533,6 +541,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');
+        this._nonInstanceDataPoolSize++;
+        for (const fmt of this._extraInstanceBuffers){
+            this._skirtMesh.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+            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');
+        this._nonInstanceDataPoolSize++;
+        for (const fmt of this._extraInstanceBuffers){
+            this._skirtMeshLines.createAndSetVertexBuffer(fmt, this.allocNonInstanceBuffer(0, 0, 0, 0), 'instance');
+            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;
     }
@@ -572,6 +686,14 @@ const rotationValues = [
         const minZ = (tmpAABB.minPoint.y * scale + offset.y) * gridScale;
         const maxZ = (tmpAABB.maxPoint.y * scale + offset.y) * gridScale;
         ctx.calcAABB(ctx.userData, minX, maxX, minZ, maxZ, tmpAABB, level);
+        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) {
@@ -627,11 +749,16 @@ const rotationValues = [
         }
         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,7 +776,7 @@ 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();
@@ -711,7 +838,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, (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 (!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);
                         }
@@ -753,6 +886,22 @@ 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);
         }
@@ -770,6 +919,8 @@ const rotationValues = [
         this._trimMeshLines.dispose();
         this._tileMesh.dispose();
         this._tileMeshLines.dispose();
+        this._skirtMesh.dispose();
+        this._skirtMeshLines.dispose();
     }
 }