@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/scene/terrain-cm/terrain-cm.js

@@ -1,9 +1,10 @@
-import { applyMixins, DRef, randomUUID, Vector3, Vector4 } from '@zephyr3d/base';
+import { applyMixins, DRef, randomUUID, Vector3, half2float, Vector4, nextPowerOf2 } from '@zephyr3d/base';
 import { GraphNode } from '../graph_node.js';
 import { mixinDrawable } from '../../render/drawable_mixin.js';
-import { MAX_TERRAIN_MIPMAP_LEVELS, QUEUE_OPAQUE, RENDER_PASS_TYPE_OBJECT_COLOR, RENDER_PASS_TYPE_SHADOWMAP } from '../../values.js';
-import '../../render/render_queue.js';
+import { MAX_TERRAIN_MIPMAP_LEVELS, QUEUE_OPAQUE, RENDER_PASS_TYPE_SHADOWMAP, RENDER_PASS_TYPE_OBJECT_COLOR } from '../../values.js';
 import { getDevice } from '../../app/api.js';
+import { warnUnsupported } from '../../utility/unsupported.js';
+import '../../render/render_queue.js';
 import '../../render/primitive.js';
 import '@zephyr3d/device';
 import { CopyBlitter } from '../../blitter/copy.js';
@@ -11,11 +12,12 @@ import '../../material/shader/helper.js';
 import '../../material/lambert.js';
 import '../../material/blinn.js';
 import '../../material/unlit.js';
+import '../../material/meshmaterial.js';
 import '../../material/particle.js';
 import '../../material/subsurfaceprofile.js';
-import '../../material/skin.js';
+import '../../material/sssprofile.js';
+import '../../material/sss.js';
 import '../../material/eye.js';
-import '../../material/meshmaterial.js';
 import '../../material/hair.js';
 import '../../material/hairstrand.js';
 import '../../material/grassmaterial.js';
@@ -33,18 +35,49 @@ import '../../render/lightpass.js';
 import '../../render/sky.js';
 import { Clipmap } from '../../render/clipmap.js';
 import '../../render/envlight.js';
+import '../../render/lod.js';
 import '../../render/dualdepthpeeling_oit.js';
 import '../../shaders/atmosphere.js';
+import '../../render/water_interaction.js';
 import '../../render/rendergraph/scene_render_context.js';
+import '../../render/sdf/scene_sdf.js';
+import '../../render/sdf/global_sdf.js';
+import '../../render/gi/voxelize_pass.js';
 import { BoundingBox } from '../../utility/bounding_volume.js';
 import { RenderMipmap } from '../../utility/rendermipmap.js';
 import { GrassRenderer } from './grass.js';
+import { TerrainVirtualTexture } from './terrain_rvt.js';
+import { TerrainGIAlbedo } from './terrain_gi_albedo.js';
 
 class HeightMinMaxBlitter extends CopyBlitter {
     filter(scope, type, srcTex, srcUV, srcLayer, sampleType) {
         return this.readTexel(scope, type, srcTex, srcUV, srcLayer, sampleType).xxxx;
     }
 }
+/**
+ * Copies the height map into the top-left of a power-of-two target, repeating the last row and
+ * column into the padding. The min/max reduction halves each level with a 2x2 footprint, which
+ * drops the last row or column of an odd sized level; padding with edge copies avoids that
+ * without affecting either extreme.
+ */ class HeightPadBlitter extends CopyBlitter {
+    /** (dest width, dest height, source width, source height) */ sizes = new Vector4();
+    setup(scope, _type) {
+        const pb = scope.$builder;
+        if (pb.shaderKind === 'fragment') {
+            scope.padSizes = pb.vec4().uniform(0);
+        }
+    }
+    setUniforms(bindGroup, _sourceTex) {
+        bindGroup.setValue('padSizes', this.sizes);
+    }
+    filter(scope, type, srcTex, srcUV, srcLayer, sampleType) {
+        const pb = scope.$builder;
+        const sizes = scope.padSizes;
+        const texel = pb.min(pb.floor(pb.mul(srcUV, sizes.xy)), pb.sub(sizes.zw, pb.vec2(1)));
+        const uv = pb.div(pb.add(texel, pb.vec2(0.5)), sizes.zw);
+        return this.readTexel(scope, type, srcTex, uv, srcLayer, sampleType).xxxx;
+    }
+}
 class HeightBoundingGenerator extends RenderMipmap {
     renderPixel(scope, leftTop, rightTop, leftBottom, rightBottom) {
         const pb = scope.$builder;
@@ -70,11 +103,22 @@ class HeightBoundingGenerator extends RenderMipmap {
  */ class ClipmapTerrain extends applyMixins(GraphNode, mixinDrawable) {
     static _heightBoundingGenerator = new HeightBoundingGenerator();
     static _copyBlitter = new HeightMinMaxBlitter();
+    static _padBlitter = new HeightPadBlitter();
     static _tmpBuffer = new Float32Array(MAX_TERRAIN_MIPMAP_LEVELS * 2 * 4);
     _pickTarget;
     _clipmap;
+    _shadowClipmap;
     _renderData;
+    _shadowRenderData;
+    _shadowGatherContext;
     _gridScale;
+    /**
+   * World position of clipmap grid point (0, 0): the centre of the first height map texel.
+   * Texel i holds the height at the centre of cell i (the convention the height sampling,
+   * brushes and grass placement all share), so this is what puts the finest level's vertices
+   * on the samples instead of halfway between them.
+   */ _gridOriginX;
+    _gridOriginZ;
     _material;
     _grassRenderer;
     _castShadow;
@@ -85,7 +129,13 @@ class HeightBoundingGenerator extends RenderMipmap {
     _grassAssetId;
     _minHeight;
     _maxHeight;
+    /** Bumped by every height range update, so a read back overtaken by a newer one is dropped */ _heightRangeSerial;
+    _heightData;
+    _heightReadBack;
+    _heightVersion;
     _tmpTexture;
+    _virtualTexture;
+    _giAlbedo;
     /**
    * Creates a new clipmap terrain instance.
    *
@@ -103,9 +153,16 @@ class HeightBoundingGenerator extends RenderMipmap {
         this._clipmap = new Clipmap(clipMapTileSize, [
             'tex1_f32'
         ], MAX_TERRAIN_MIPMAP_LEVELS);
+        this._shadowClipmap = new Clipmap(clipMapTileSize, [
+            'tex1_f32'
+        ], MAX_TERRAIN_MIPMAP_LEVELS);
         this._renderData = null;
+        this._shadowRenderData = null;
+        this._shadowGatherContext = null;
         this._grassRenderer = new DRef(new GrassRenderer(this));
         this._gridScale = 1;
+        this._gridOriginX = 0;
+        this._gridOriginZ = 0;
         this._castShadow = true;
         this._sizeX = sizeX;
         this._sizeZ = sizeZ;
@@ -114,9 +171,16 @@ class HeightBoundingGenerator extends RenderMipmap {
         this._splatMapAssetId = `assets/.embedded.dir/${this.persistentId}-splatmap.bin`;
         this._minHeight = 0;
         this._maxHeight = 0;
+        this._heightRangeSerial = 0;
+        this._heightData = null;
+        this._heightReadBack = null;
+        this._heightVersion = 0;
         this._material = new DRef(new ClipmapTerrainMaterial(this.createHeightMapTexture(this._sizeX, this._sizeZ)));
         this._tmpTexture = new DRef();
+        this._virtualTexture = null;
+        this._giAlbedo = null;
         this.updateRegion();
+        this.updateHeightPyramid();
         scene.queuePerCameraUpdateNode(this);
     }
     /**
@@ -209,6 +273,83 @@ class HeightBoundingGenerator extends RenderMipmap {
             this.resizeHeightMap(this._sizeX, this._sizeZ);
         }
     }
+    /**
+   * Whether the detail layers are blended into a runtime virtual texture instead of per pixel.
+   * Pages are blended once, as the camera needs them, so shading costs the same whatever the
+   * number of layers. WebGPU only, ignored elsewhere; has no effect without detail layers.
+   *
+   * Code writing into the splat map or the height map directly must call
+   * {@link ClipmapTerrain.invalidateRuntimeVirtualTexture} for the area it changed.
+   */ get runtimeVirtualTexture() {
+        return !!this._virtualTexture;
+    }
+    set runtimeVirtualTexture(val) {
+        if (!!val !== this.runtimeVirtualTexture) {
+            this.setRuntimeVirtualTexture(val ? {} : null);
+        }
+    }
+    /**
+   * Enables the runtime virtual texture with the given options, or disables it with null.
+   * See {@link ClipmapTerrain.runtimeVirtualTexture}.
+   */ setRuntimeVirtualTexture(options) {
+        if (options && getDevice().type !== 'webgpu') {
+            warnUnsupported('Terrain runtime virtual texture (ClipmapTerrain.runtimeVirtualTexture)', 'WebGPU', 'the terrain is shaded directly every frame');
+            return;
+        }
+        if (options && !this.scene) {
+            return;
+        }
+        if (this._virtualTexture && options) {
+            this._virtualTexture.setOptions(options);
+            return;
+        }
+        if (this._virtualTexture) {
+            this.scene?.removeVirtualTextureClient(this._virtualTexture);
+            this._virtualTexture.dispose();
+            this._virtualTexture = null;
+            if (this.material) {
+                this.material.virtualTexture = null;
+            }
+        }
+        if (options && this.material) {
+            this._virtualTexture = new TerrainVirtualTexture(this, options);
+            this.material.virtualTexture = this._virtualTexture.virtualTexture;
+            this.scene.addVirtualTextureClient(this._virtualTexture);
+        }
+    }
+    /**
+   * Refills the runtime virtual texture over a world XZ rectangle, or everywhere without
+   * arguments, and recaptures the albedo global illumination reads there. Needed after writing
+   * into the splat map or the height map directly (brushes); replacing textures or changing
+   * layer parameters through the material is picked up automatically.
+   */ invalidateRuntimeVirtualTexture(x0, z0, x1, z1) {
+        this._giAlbedo?.invalidate(x0, z0, x1, z1);
+        if (!this._virtualTexture) {
+            return;
+        }
+        if (x0 === undefined || z0 === undefined || x1 === undefined || z1 === undefined) {
+            this._virtualTexture.invalidate();
+        } else {
+            this._virtualTexture.invalidateWorldRegion(x0, z0, x1, z1);
+        }
+    }
+    /**
+   * Top-down capture of the material albedo read by global illumination, created on first use.
+   * WebGPU only.
+   * @internal
+   */ get giAlbedo() {
+        if (!this._giAlbedo) {
+            this._giAlbedo = new TerrainGIAlbedo(this);
+        }
+        return this._giAlbedo;
+    }
+    /**
+   * The virtual texture behind {@link ClipmapTerrain.runtimeVirtualTexture}, null when disabled.
+   * For inspection: {@link VirtualTexture.stats}, {@link VirtualTexture.renderDebugTexture}.
+   * It is recreated when the terrain aspect or the options change.
+   */ get runtimeVirtualTextureData() {
+        return this._virtualTexture?.virtualTexture ?? null;
+    }
     /** Wether the mesh node casts shadows */ get castShadow() {
         return this._castShadow;
     }
@@ -239,8 +380,162 @@ class HeightBoundingGenerator extends RenderMipmap {
     set heightMap(val) {
         if (this.material && val) {
             this.material.heightMap = val;
+            this._heightData = null;
             this.updateRegion();
+            this.updateHeightPyramid();
+            this._heightVersion++;
+            this.readBackHeightData();
+        }
+    }
+    /**
+   * Goes up whenever the heights change: a new height map, or edits to the
+   * current one once {@link ClipmapTerrain.updateBoundingBox} is called after
+   * them. Lets CPU-side users such as physics notice they are out of date.
+   */ get heightVersion() {
+        return this._heightVersion;
+    }
+    /**
+   * CPU copy of the heights, half floats row by row (height map texel values, before the terrain
+   * scale and translation); null while unknown.
+   *
+   * @remarks
+   * Lets CPU-side users such as physics and prop placement read heights without a GPU read back.
+   * Known at once when loaded or set with {@link ClipmapTerrain.setHeights}; after other edits
+   * it is null until a read back started by {@link ClipmapTerrain.updateBoundingBox} lands, which
+   * {@link ClipmapTerrain.whenHeightDataReady} waits for.
+   */ get heightData() {
+        return this._heightData;
+    }
+    /**
+   * Records the CPU copy of the heights just uploaded to the height map.
+   * @internal
+   */ setHeightData(data, width, height) {
+        this._heightData = {
+            data,
+            width,
+            height
+        };
+        this._heightVersion++;
+    }
+    /**
+   * Resolves once {@link ClipmapTerrain.heightData} is known, reading the heights back from the
+   * GPU if needed. Resolves to null when the height map format cannot be read back.
+   */ whenHeightDataReady() {
+        if (this._heightData) {
+            return Promise.resolve(this._heightData);
+        }
+        return this.readBackHeightData() ?? Promise.resolve(null);
+    }
+    /**
+   * World height of the terrain surface at a world position, bilinearly interpolated, or null
+   * outside the terrain or while {@link ClipmapTerrain.heightData} is unknown.
+   */ getHeightAt(x, z) {
+        const data = this._heightData;
+        const region = this.worldRegion;
+        if (!data || region.z <= region.x || region.w <= region.y) {
+            return null;
+        }
+        const u = (x - region.x) / (region.z - region.x);
+        const v = (z - region.y) / (region.w - region.y);
+        if (u < 0 || u > 1 || v < 0 || v > 1) {
+            return null;
+        }
+        return this.sampleHeightTexel(data, u, v) * this.scale.y + this.worldMatrix.m13;
+    }
+    /**
+   * Unit surface normal of the terrain at a world position, from central differences one height
+   * map texel apart, or null where {@link ClipmapTerrain.getHeightAt} is.
+   */ getNormalAt(x, z, out) {
+        const data = this._heightData;
+        const region = this.worldRegion;
+        if (!data || region.z <= region.x || region.w <= region.y) {
+            return null;
+        }
+        const rw = region.z - region.x;
+        const rh = region.w - region.y;
+        const u = (x - region.x) / rw;
+        const v = (z - region.y) / rh;
+        if (u < 0 || u > 1 || v < 0 || v > 1) {
+            return null;
+        }
+        const du = 1 / data.width;
+        const dv = 1 / data.height;
+        const sy = this.scale.y;
+        const dx = (this.sampleHeightTexel(data, u + du, v) - this.sampleHeightTexel(data, u - du, v)) * sy;
+        const dz = (this.sampleHeightTexel(data, u, v + dv) - this.sampleHeightTexel(data, u, v - dv)) * sy;
+        out = out ?? new Vector3();
+        out.setXYZ(-dx / (2 * du * rw), 1, -dz / (2 * dv * rh));
+        return out.inplaceNormalize();
+    }
+    sampleHeightTexel(data, u, v) {
+        // Texel i holds the height at the centre of cell i, at u = (i + 0.5) / width
+        const w = data.width;
+        const h = data.height;
+        const fx = Math.min(Math.max(u * w - 0.5, 0), w - 1);
+        const fz = Math.min(Math.max(v * h - 0.5, 0), h - 1);
+        const x0 = Math.floor(fx);
+        const z0 = Math.floor(fz);
+        const x1 = Math.min(x0 + 1, w - 1);
+        const z1 = Math.min(z0 + 1, h - 1);
+        const tx = fx - x0;
+        const tz = fz - z0;
+        const d = data.data;
+        const h00 = half2float(d[z0 * w + x0]);
+        const h10 = half2float(d[z0 * w + x1]);
+        const h01 = half2float(d[z1 * w + x0]);
+        const h11 = half2float(d[z1 * w + x1]);
+        const a = h00 + (h10 - h00) * tx;
+        const b = h01 + (h11 - h01) * tx;
+        return a + (b - a) * tz;
+    }
+    /**
+   * Reads the half float heights back from the GPU into {@link ClipmapTerrain.heightData}.
+   * A read back overtaken by another height change is dropped.
+   */ readBackHeightData() {
+        const map = this.heightMap;
+        if (!map || map.format !== 'r16f' && map.format !== 'rgba16f') {
+            return null;
         }
+        if (this._heightReadBack && this._heightReadBack.version === this._heightVersion) {
+            return this._heightReadBack.promise;
+        }
+        const version = this._heightVersion;
+        const w = map.width;
+        const h = map.height;
+        const channels = map.format === 'r16f' ? 1 : 4;
+        const buffer = new Uint16Array(w * h * channels);
+        const promise = map.readPixels(0, 0, w, h, 0, 0, buffer).then(()=>{
+            if (version !== this._heightVersion || this.heightMap !== map) {
+                return this._heightData;
+            }
+            let data = buffer;
+            if (channels !== 1) {
+                // The height is in the red channel
+                data = new Uint16Array(w * h);
+                for(let i = 0; i < data.length; i++){
+                    data[i] = buffer[i * channels];
+                }
+            }
+            // Same heights as on the GPU: the version stays, physics need not rebuild
+            this._heightData = {
+                data,
+                width: w,
+                height: h
+            };
+            return this._heightData;
+        }).catch((err)=>{
+            console.error(`Terrain height read back failed: ${err}`);
+            return null;
+        }).finally(()=>{
+            if (this._heightReadBack?.promise === promise) {
+                this._heightReadBack = null;
+            }
+        });
+        this._heightReadBack = {
+            version,
+            promise
+        };
+        return promise;
     }
     /** The splat map texture */ get splatMap() {
         return this.material?.getSplatMap() ?? null;
@@ -253,6 +548,7 @@ class HeightBoundingGenerator extends RenderMipmap {
     }
     set wireframe(val) {
         this._clipmap.wireframe = val;
+        this._shadowClipmap.wireframe = val;
     }
     /**
    * {@inheritDoc Drawable.getPickTarget }
@@ -363,37 +659,125 @@ class HeightBoundingGenerator extends RenderMipmap {
    * terrain.updateBoundingBox();
    * ```
    */ updateBoundingBox() {
+        // Called after the heights changed on the GPU: a CPU copy is stale now.
+        this._heightData = null;
+        this._heightVersion++;
+        this.readBackHeightData();
+        const tmp = this.updateHeightPyramid();
+        if (!tmp) {
+            return;
+        }
+        const data = new Float32Array(4);
+        const serial = ++this._heightRangeSerial;
+        tmp.readPixels(0, 0, 1, 1, 0, tmp.mipLevelCount - 1, data).then(()=>{
+            // Loading sets the range synchronously right after a resize has started a read back of
+            // the empty height map; that stale result must not land on top of it.
+            if (serial !== this._heightRangeSerial) {
+                return;
+            }
+            // The reduction stores (max, min) in (r, g)
+            this._maxHeight = data[0];
+            this._minHeight = data[1];
+            this.invalidateWorldBoundingVolume(false);
+        }).catch((_err)=>{
+            console.error('Read pixels failed');
+        });
+    }
+    /**
+   * Replaces every height of an r16f height map with heights from the CPU.
+   *
+   * Unlike writing into {@link ClipmapTerrain.heightMap} and calling
+   * {@link ClipmapTerrain.updateBoundingBox}, the bounds are right at once and the heights stay
+   * available as {@link ClipmapTerrain.heightData}, so physics colliders need no GPU read back.
+   *
+   * @param data - Half float heights, one per height map texel, row by row
+   */ setHeights(data) {
         const heightMap = this.heightMap;
-        if (!heightMap) {
+        if (!heightMap || heightMap.format !== 'r16f' || data.length !== heightMap.width * heightMap.height) {
+            console.error('setHeights() needs one half float per texel of an r16f height map');
             return;
         }
+        heightMap.update(data, 0, 0, heightMap.width, heightMap.height);
+        this.updateHeightPyramid();
+        this.setHeightRangeFromHalfData(data);
+        this.setHeightData(data, heightMap.width, heightMap.height);
+        this.invalidateRuntimeVirtualTexture();
+    }
+    /**
+   * The min/max height pyramid of the height map: (max, min) in (r, g), mip 0 padded to a power
+   * of two by repeating the last row and column, so texel j of mip m covers height map texels
+   * [j * 2^m, (j + 1) * 2^m). Null until built.
+   * @internal
+   */ get heightPyramid() {
+        return this._tmpTexture.get() ?? null;
+    }
+    /**
+   * Tile resolution of the clipmap, in grid cells
+   * @internal
+   */ get clipmapTileResolution() {
+        return this._clipmap.tileResolution;
+    }
+    /**
+   * Rebuilds the min/max height pyramid from the current height map.
+   * Called when the height map is replaced and by {@link ClipmapTerrain.updateBoundingBox}; code
+   * that writes into the height map directly must call one of them afterwards.
+   * @internal
+   */ updateHeightPyramid() {
+        const heightMap = this.heightMap;
+        if (!heightMap) {
+            return null;
+        }
         const device = getDevice();
+        const width = nextPowerOf2(heightMap.width);
+        const height = nextPowerOf2(heightMap.height);
         let tmp = this._tmpTexture.get();
-        if (tmp && (tmp.width !== heightMap.width || tmp.height !== heightMap.height)) {
+        if (tmp && (tmp.width !== width || tmp.height !== height)) {
             this._tmpTexture.dispose();
         }
         if (!this._tmpTexture.get()) {
-            tmp = getDevice().createTexture2D(device.type === 'webgl' ? 'rgba32f' : 'rg32f', heightMap.width, heightMap.height);
+            tmp = getDevice().createTexture2D('rg32f', width, height);
             tmp.name = 'TerrainBoundingBoxTexture';
             this._tmpTexture.set(tmp);
         }
         const tmpFB = device.createFrameBuffer([
             tmp
         ], null);
-        ClipmapTerrain._copyBlitter.blit(heightMap, tmpFB, fetchSampler('clamp_nearest_nomip'));
+        ClipmapTerrain._padBlitter.sizes.setXYZW(width, height, heightMap.width, heightMap.height);
+        ClipmapTerrain._padBlitter.blit(heightMap, tmpFB, fetchSampler('clamp_nearest_nomip'));
         tmpFB.dispose();
         ClipmapTerrain._heightBoundingGenerator.render(tmp);
-        const data = new Float32Array(4);
-        tmp.readPixels(0, 0, 1, 1, 0, tmp.mipLevelCount - 1, data).then(()=>{
-            this._minHeight = data[0];
-            this._maxHeight = data[1];
+        return tmp;
+    }
+    /**
+   * Sets the height range from height map data already on the CPU, e.g. when loading.
+   *
+   * {@link ClipmapTerrain.updateBoundingBox} reads the range back from the GPU, which lands a
+   * few frames later; until then the bounds would stay flat and cull the terrain wrongly.
+   *
+   * @param data - Half float heights, one per texel
+   * @param stride - Number of half floats per texel, the height being the first
+   * @internal
+   */ setHeightRangeFromHalfData(data, stride = 1) {
+        let minHeight = Number.POSITIVE_INFINITY;
+        let maxHeight = Number.NEGATIVE_INFINITY;
+        for(let i = 0; i < data.length; i += stride){
+            const h = half2float(data[i]);
+            if (h < minHeight) {
+                minHeight = h;
+            }
+            if (h > maxHeight) {
+                maxHeight = h;
+            }
+        }
+        if (minHeight <= maxHeight) {
+            this._heightRangeSerial++;
+            this._minHeight = minHeight;
+            this._maxHeight = maxHeight;
             this.invalidateWorldBoundingVolume(false);
-        }).catch((_err)=>{
-            console.error('Read pixels failed');
-        });
+        }
     }
     /** @internal */ createHeightMapTexture(width, height) {
-        return getDevice().createTexture2D(getDevice().type === 'webgl' ? 'rgba16f' : 'r16f', width, height);
+        return getDevice().createTexture2D('r16f', width, height);
     }
     /** @internal */ _onTransformChanged(invalidateLocal) {
         super._onTransformChanged(invalidateLocal);
@@ -404,29 +788,51 @@ class HeightBoundingGenerator extends RenderMipmap {
         if (!mat) {
             return;
         }
-        const that = this;
-        const bv = this.getWorldBoundingVolume().toAABB();
+        const bv = this.getWorldBoundingVolume()?.toAABB() ?? null;
+        const originY = this.worldMatrix.m13;
+        const calcAABB = (_userData, minX, maxX, minZ, maxZ, outAABB)=>{
+            outAABB.minPoint.setXYZ(minX, bv ? bv.minPoint.y : originY - 9999, minZ);
+            outAABB.maxPoint.setXYZ(maxX, bv ? bv.maxPoint.y : originY + 9999, maxZ);
+        };
+        // Passes rendered from this camera only need the tiles inside its frustum. Shadow passes
+        // render from the light and need casters outside of it too, so they get an unculled set
+        // built around the same camera (same levels, so the level data below serves both).
         this._renderData = this._clipmap.gather({
             camera: camera,
             minMaxWorldPos: mat.region,
             gridScale: this._gridScale,
+            gridOriginX: this._gridOriginX,
+            gridOriginZ: this._gridOriginZ,
             userData: this,
-            frustumCulling: !this.castShadow,
-            calcAABB (userData, minX, maxX, minZ, maxZ, outAABB) {
-                const p = that.worldMatrix.transformPointAffine(Vector3.zero());
-                outAABB.minPoint.setXYZ(minX, bv ? bv.minPoint.y : p.y - 9999, minZ);
-                outAABB.maxPoint.setXYZ(maxX, bv ? bv.maxPoint.y : p.y + 9999, maxZ);
-            }
+            frustumCulling: true,
+            calcAABB
         });
+        // Each shadow map camera (cascade, cube face) culls this set again in draw()
+        this._shadowGatherContext = this.castShadow ? {
+            camera: camera,
+            minMaxWorldPos: mat.region,
+            gridScale: this._gridScale,
+            gridOriginX: this._gridOriginX,
+            gridOriginZ: this._gridOriginZ,
+            userData: this,
+            frustumCulling: false,
+            calcAABB
+        } : null;
+        this._shadowRenderData = this._shadowGatherContext ? this._shadowClipmap.gather(this._shadowGatherContext) : null;
         let maxMipLevel = 0;
-        for (const info of this._renderData){
-            const buffer = info.primitive.getVertexBuffer('texCoord1');
-            buffer.bufferSubData(0, info.mipLevels, 0, info.numInstances);
-            if (info.maxMiplevel > maxMipLevel) {
-                maxMipLevel = info.maxMiplevel;
+        for (const renderData of [
+            this._renderData,
+            this._shadowRenderData
+        ]){
+            for (const info of renderData ?? []){
+                const buffer = info.primitive.getVertexBuffer('texCoord1');
+                buffer.bufferSubData(0, info.mipLevels, 0, info.numInstances);
+                if (info.maxMiplevel > maxMipLevel) {
+                    maxMipLevel = info.maxMiplevel;
+                }
             }
         }
-        const levelAABB = this._clipmap.calcLevelAABB(camera, mat.region, this._gridScale);
+        const levelAABB = this._clipmap.calcLevelAABB(camera, mat.region, this._gridScale, this._gridOriginX, this._gridOriginZ);
         const cameraPos = camera.getWorldPosition();
         const tmpBuffer = ClipmapTerrain._tmpBuffer;
         for(let i = 0; i <= maxMipLevel; i++){
@@ -449,6 +855,8 @@ class HeightBoundingGenerator extends RenderMipmap {
             tmpBuffer[i * 8 + 7] = 1 / (currentAABB.maxPoint.z - tmpBuffer[i * 8 + 3]);
         }
         mat.setLevelData(tmpBuffer, 8 * (maxMipLevel + 1));
+        // Grass placed on the GPU is generated around this camera, outside of any render pass
+        this.grassRenderer.updatePerCamera(camera);
         this.scene?.queuePerCameraUpdateNode(this);
     }
     /**
@@ -460,7 +868,11 @@ class HeightBoundingGenerator extends RenderMipmap {
             const z = Math.abs(this.scale.z);
             const px = this.position.x + (this.parent?.worldMatrix.m03 ?? 0);
             const pz = this.position.z + (this.parent?.worldMatrix.m23 ?? 0);
-            this._gridScale = Math.max(x * this._sizeX / this.material.heightMap.width, z * this._sizeZ / this.material.heightMap.height);
+            const cellX = x * this._sizeX / this.material.heightMap.width;
+            const cellZ = z * this._sizeZ / this.material.heightMap.height;
+            this._gridScale = Math.max(cellX, cellZ);
+            this._gridOriginX = px + cellX * 0.5;
+            this._gridOriginZ = pz + cellZ * 0.5;
             this.material.update(new Vector4(px, pz, px + x * this._sizeX, pz + z * this._sizeZ), this.scale);
             this.grassRenderer.updateMaterial();
         }
@@ -469,12 +881,24 @@ class HeightBoundingGenerator extends RenderMipmap {
         const mat = this._material?.get();
         if (mat) {
             this.bind(ctx, renderQueue);
-            mat.setClipmapGridInfo(this._gridScale, this.worldMatrix.m03, this.worldMatrix.m23);
+            // The shader places vertices at grid * gridScale - offset, then adds the world translation
+            mat.setClipmapGridInfo(this._gridScale, this.worldMatrix.m03 - this._gridOriginX, this.worldMatrix.m23 - this._gridOriginZ);
             mat.apply(ctx);
-            for (const info of this._renderData){
+            const isShadowPass = ctx.renderPass.type === RENDER_PASS_TYPE_SHADOWMAP;
+            let renderData = isShadowPass ? this._shadowRenderData : this._renderData;
+            const cullCamera = renderQueue?.cullCamera;
+            if (isShadowPass && renderData && cullCamera && this._shadowGatherContext) {
+                this._shadowGatherContext.camera = cullCamera;
+                renderData = this._shadowClipmap.cullInstances(renderData, this._shadowGatherContext);
+                for (const info of renderData){
+                    info.primitive.getVertexBuffer('texCoord1').bufferSubData(0, info.mipLevels, 0, info.numInstances);
+                }
+            }
+            for (const info of renderData ?? []){
                 mat.draw(info.primitive, ctx, info.numInstances);
             }
-            if (ctx.renderPass.type !== RENDER_PASS_TYPE_OBJECT_COLOR && ctx.renderPass.type !== RENDER_PASS_TYPE_SHADOWMAP) {
+            // In shadow map passes the grass renderer draws the blades that cast shadows only
+            if (ctx.renderPass.type !== RENDER_PASS_TYPE_OBJECT_COLOR) {
                 this.grassRenderer.draw(ctx);
             }
         }
@@ -487,7 +911,7 @@ class HeightBoundingGenerator extends RenderMipmap {
             sizeX = Math.min(Math.max(sizeX, 1), maxTextureSize) >> 0;
             sizeZ = Math.min(Math.max(sizeZ, 1), maxTextureSize) >> 0;
             if (sizeX !== oldHeightMap.width || sizeZ !== oldHeightMap.height) {
-                const newHeightMap = device.createTexture2D(device.type === 'webgl' ? 'rgba16f' : 'r16f', sizeX, sizeZ);
+                const newHeightMap = device.createTexture2D('r16f', sizeX, sizeZ);
                 const fb = device.createFrameBuffer([
                     newHeightMap
                 ], null);
@@ -554,9 +978,14 @@ class HeightBoundingGenerator extends RenderMipmap {
    * Should be called when the terrain is no longer needed.
    */ onDispose() {
         super.onDispose();
+        this.setRuntimeVirtualTexture(null);
+        this._giAlbedo?.dispose();
+        this._giAlbedo = null;
         this._clipmap?.dispose();
+        this._shadowClipmap?.dispose();
         this._material?.dispose();
         this._grassRenderer?.dispose();
+        this._tmpTexture.dispose();
     }
 }