@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/render/gi/voxel_scene.js

@@ -0,0 +1,642 @@
+import { Vector4 } from '@zephyr3d/base';
+import { getDevice } from '../../app/api.js';
+import { VoxelMaterialAtlas } from './voxel_atlas.js';
+import { Voxelizer } from './voxelize_pass.js';
+import { VoxelLighting } from './voxel_lighting.js';
+import { buildSDFProgram } from '../sdf/sdf_programs.js';
+import { fetchSampler } from '../../utility/misc.js';
+import { declareGlobalSDFUniforms, declareDynamicSDFUniforms } from '../../shaders/sdf.js';
+import { VOXEL_SCENE_ALBEDO, VOXEL_SCENE_EMISSIVE, VOXEL_SCENE_RADIANCE, VOXEL_SCENE_ANISO0, VOXEL_SCENE_ANISO1, declareVoxelSceneUniforms, voxelSceneTexel, loadVoxelSceneAlbedo, loadVoxelSceneEmissive } from '../../shaders/gi.js';
+
+/** Most points per {@link VoxelScene.queryVoxels} call. */ const MAX_QUERY_POINTS = 1024;
+/** Seconds a material's uniforms must have been stable before it is voxelized again. */ const REVOXELIZE_COOLDOWN = 0.5;
+/** Seconds an entry nobody wants is kept before it is forgotten. */ const ENTRY_LIFETIME = 30;
+/**
+ * Material side of the scene's voxel representation: each static mesh in the scene SDF
+ * is rasterized once per (primitive, material) into a {@link VoxelMaterialAtlas}, and
+ * global SDF compositing carries the nearest mesh's albedo and emissive into two clipmaps
+ * laid out like the field at half its resolution, giving GI ray hits their colour.
+ *
+ * Voxelizations are budgeted per frame, nearest first, and redone on material change.
+ * Materials that cannot be voxelized (see {@link MeshMaterial.supportsVoxelization}) are
+ * skipped. The terrain's albedo comes from its top-down capture, see TerrainGIAlbedo. WebGPU only.
+ *
+ * @public
+ */ class VoxelScene {
+    /** Meshes voxelized per frame. */ voxelizeBudget;
+    atlas;
+    _scene;
+    _voxelizer;
+    _lighting;
+    _albedo;
+    _emissive;
+    _resolution;
+    _levels;
+    _entries;
+    _time;
+    _atlasFull;
+    _atlasFullWarned;
+    _voxelizations;
+    _lastVoxelizations;
+    _queryProgram;
+    _queryLevels;
+    _queryBindGroup;
+    _queryPoints;
+    _queryOutput;
+    _queryChain;
+    constructor(scene, atlasSize = 256){
+        this._scene = scene;
+        this.voxelizeBudget = 8;
+        this.atlas = new VoxelMaterialAtlas([
+            atlasSize,
+            atlasSize,
+            atlasSize
+        ]);
+        this._voxelizer = null;
+        this._lighting = null;
+        this._albedo = null;
+        this._emissive = null;
+        this._resolution = 0;
+        this._levels = 0;
+        this._entries = new Map();
+        this._time = 0;
+        this._atlasFull = 0;
+        this._atlasFullWarned = false;
+        this._voxelizations = 0;
+        this._lastVoxelizations = 0;
+        this._queryProgram = null;
+        this._queryLevels = 0;
+        this._queryBindGroup = null;
+        this._queryPoints = null;
+        this._queryOutput = null;
+        this._queryChain = Promise.resolve();
+    }
+    get atlasAlbedo() {
+        return this.atlas.albedo;
+    }
+    get atlasEmissive() {
+        return this.atlas.emissive;
+    }
+    get atlasSize() {
+        return this.atlas.size;
+    }
+    /** Albedo clipmap: rgba8unorm, levels stacked along z, rgb the albedo and a = 1 where a surface is. */ get albedo() {
+        if (!this._albedo) {
+            throw new Error('VoxelScene: no clipmap before the first update');
+        }
+        return this._albedo;
+    }
+    /** Emissive clipmap: rgba16float, levels stacked along z. */ get emissive() {
+        if (!this._emissive) {
+            throw new Error('VoxelScene: no clipmap before the first update');
+        }
+        return this._emissive;
+    }
+    /** Outgoing radiance clipmap: rgba16float, laid out like the albedo; see {@link VoxelLighting}. */ get radiance() {
+        if (!this._lighting?.ready) {
+            throw new Error('VoxelScene: no radiance before the first lighting update');
+        }
+        return this._lighting.radiance;
+    }
+    /** Share of the radiance each voxel face carries, (+x, +y, +z, -x); see declareVoxelSceneUniforms. */ get radianceAniso0() {
+        if (!this._lighting?.ready) {
+            throw new Error('VoxelScene: no radiance before the first lighting update');
+        }
+        return this._lighting.aniso0;
+    }
+    /** Share of the radiance each voxel face carries, (-y, -z) in rg. */ get radianceAniso1() {
+        if (!this._lighting?.ready) {
+            throw new Error('VoxelScene: no radiance before the first lighting update');
+        }
+        return this._lighting.aniso1;
+    }
+    /** True once the radiance clipmap exists. */ get lit() {
+        return !!this._lighting?.ready;
+    }
+    /** Voxels per axis of a clipmap level, half the field's. */ get resolution() {
+        return this._resolution;
+    }
+    get levels() {
+        return this._levels;
+    }
+    /** True once the clipmaps exist. */ get ready() {
+        return !!this._albedo;
+    }
+    getSlot(inst) {
+        const key = keyOf(inst.mesh);
+        const entry = key ? this._entries.get(key) : null;
+        return entry && entry.voxelized ? this.atlas.getSlot(entry) : null;
+    }
+    /**
+   * How the voxel scene holds an instance's material, for tools: `unsupported` when it
+   * never will, `unknown` before first wanted, else the voxelization state and atlas slot.
+   */ describeInstance(inst) {
+        const mesh = inst.mesh;
+        const primitive = mesh.primitive;
+        const material = mesh.material;
+        if (!primitive || !material || primitive.primitiveType !== 'triangle-list' || !material.supportsVoxelization()) {
+            return {
+                state: 'unsupported',
+                voxelized: false,
+                slot: null
+            };
+        }
+        const key = keyOf(mesh);
+        const entry = key ? this._entries.get(key) : null;
+        if (!entry) {
+            return {
+                state: 'unknown',
+                voxelized: false,
+                slot: null
+            };
+        }
+        return {
+            state: entry.state,
+            voxelized: entry.voxelized,
+            slot: this.atlas.getSlot(entry)
+        };
+    }
+    getStats() {
+        const stats = {
+            entries: this._entries.size,
+            ready: 0,
+            pending: 0,
+            failed: 0,
+            atlasResident: this.atlas.count,
+            atlasOccupancy: this.atlas.occupancy,
+            atlasFull: this._atlasFull,
+            voxelizations: this._voxelizations,
+            lastVoxelizations: this._lastVoxelizations,
+            lightingPasses: this._lighting?.passes ?? 0
+        };
+        for (const entry of this._entries.values()){
+            stats[entry.state]++;
+        }
+        return stats;
+    }
+    /**
+   * Voxelizes meshes that entered the scene field, nearest first within the budget.
+   * Called once a frame, before the field's own update.
+   */ update(sdf, cameraPos, deltaSeconds) {
+        const global = sdf.enabled ? sdf.global : null;
+        if (!global) {
+            return;
+        }
+        this._time += deltaSeconds;
+        this.ensureClipmaps(global);
+        if (global.materials !== this) {
+            global.materials = this;
+        }
+        const wanted = new Map();
+        for (const inst of sdf.instances){
+            if (inst.mode !== 'static') {
+                continue;
+            }
+            const header = inst.asset?.state === 'ready' ? inst.asset.header : null;
+            if (!header) {
+                continue;
+            }
+            const mesh = inst.mesh;
+            const primitive = mesh.primitive;
+            const material = mesh.material;
+            const key = keyOf(mesh);
+            if (!key || !primitive || !material || primitive.primitiveType !== 'triangle-list' || !material.supportsVoxelization()) {
+                continue;
+            }
+            let entry = this._entries.get(key);
+            if (!entry) {
+                const resolved = resolveMaterial(material);
+                entry = {
+                    key,
+                    primitive,
+                    material: resolved.material,
+                    ownsMaterial: resolved.owned,
+                    source: material,
+                    resolution: header.resolution.map((v)=>Math.max(1, Math.ceil(v / 2))),
+                    boxMin: [
+                        ...header.boxMin
+                    ],
+                    voxelSize: header.voxelSize * 2,
+                    state: 'pending',
+                    voxelized: false,
+                    materialTag: '',
+                    lastWanted: 0,
+                    readyTime: -Infinity,
+                    failedVersion: -1
+                };
+                this._entries.set(key, entry);
+            }
+            entry.lastWanted = this._time;
+            // A material edit shows up in its change tag; wait for the edits to settle
+            if (entry.state === 'ready' && entry.materialTag !== materialTagOf(material) && this._time - entry.readyTime > REVOXELIZE_COOLDOWN) {
+                entry.state = 'pending';
+            }
+            const d = distanceToBox(cameraPos, inst.bounds);
+            const prev = wanted.get(entry);
+            wanted.set(entry, prev === undefined ? d : Math.min(prev, d));
+        }
+        const candidates = [
+            ...wanted.entries()
+        ].filter((e)=>e[0].state === 'pending' && e[0].failedVersion !== this.atlas.version).sort((a, b)=>a[1] - b[1]).map((e)=>e[0]);
+        let done = 0;
+        for (const entry of candidates){
+            if (done >= this.voxelizeBudget) {
+                break;
+            }
+            const slot = this.atlas.getSlot(entry) ?? this.place(entry, wanted);
+            if (!slot) {
+                continue;
+            }
+            if (entry.ownsMaterial) {
+                // A copy carries the values of its making; take them again
+                entry.material.dispose();
+                const resolved = resolveMaterial(entry.source);
+                entry.material = resolved.material;
+                entry.ownsMaterial = resolved.owned;
+            }
+            const ok = this.voxelizer.voxelize(entry.primitive, entry.material, {
+                albedo: this.atlas.albedo,
+                emissive: this.atlas.emissive,
+                slot,
+                boxMin: entry.boxMin,
+                voxelSize: entry.voxelSize
+            });
+            entry.state = ok ? 'ready' : 'failed';
+            entry.voxelized = ok;
+            entry.materialTag = materialTagOf(entry.source);
+            entry.readyTime = this._time;
+            done++;
+            this._voxelizations++;
+            this.dirtyInstances(sdf, global, entry.key);
+        }
+        this._lastVoxelizations = done;
+        // Entries nobody has wanted for a while are forgotten
+        for (const entry of this._entries.values()){
+            if (!wanted.has(entry) && this._time - entry.lastWanted > ENTRY_LIFETIME) {
+                this.atlas.remove(entry);
+                this._entries.delete(entry.key);
+                if (entry.ownsMaterial) {
+                    entry.material.dispose();
+                }
+            }
+        }
+    }
+    /**
+   * Lights the next slab of voxels. Called once a frame after the field's update,
+   * which composites the materials it reads.
+   */ updateLighting(sdf, camera, options) {
+        const global = sdf.enabled ? sdf.global : null;
+        if (!global || !this._albedo || !this._emissive) {
+            return;
+        }
+        if (!this._lighting) {
+            this._lighting = new VoxelLighting(this._scene);
+        }
+        this._lighting.update(global, this._albedo, this._emissive, this._resolution, camera, options);
+    }
+    /** Stops the global field compositing materials, when it still composites this. */ detach(sdf) {
+        const global = sdf.enabled ? sdf.global : null;
+        if (global && global.materials === this) {
+            global.materials = null;
+        }
+    }
+    /**
+   * Reads back what the clipmaps hold at world positions, as a GI ray hit would; resolves
+   * a frame or two later. For tools, at most 1024 points.
+   */ queryVoxels(global, points) {
+        const run = async ()=>{
+            const n = Math.min(points.length, MAX_QUERY_POINTS);
+            if (n === 0 || !this._albedo || !this._emissive) {
+                return [];
+            }
+            const device = getDevice();
+            const pixels = new Float32Array(MAX_QUERY_POINTS * 4 * 3);
+            // Recorded at the start of a frame, as the field's distance queries are
+            await device.runNextFrameAsync(async ()=>{
+                if (!this._queryProgram || this._queryLevels !== global.levels) {
+                    this._queryProgram?.dispose();
+                    this._queryBindGroup?.dispose();
+                    this._queryProgram = this.createQueryProgram(global.levels);
+                    this._queryLevels = global.levels;
+                    this._queryBindGroup = device.createBindGroup(this._queryProgram.bindGroupLayouts[0]);
+                }
+                if (!this._queryPoints) {
+                    this._queryPoints = device.createBuffer(MAX_QUERY_POINTS * 16, {
+                        usage: 'uniform',
+                        storage: true
+                    });
+                    this._queryOutput = device.createTexture2D('rgba32f', MAX_QUERY_POINTS, 3, {
+                        mipmapping: false,
+                        writable: true
+                    });
+                }
+                const data = new Float32Array(MAX_QUERY_POINTS * 4);
+                for(let i = 0; i < n; i++){
+                    data.set([
+                        points[i].x,
+                        points[i].y,
+                        points[i].z,
+                        0
+                    ], i * 4);
+                }
+                this._queryPoints.bufferSubData(0, data);
+                const bg = this._queryBindGroup;
+                global.applyBindGroup(bg);
+                const lit = this.lit;
+                const nearest = fetchSampler('clamp_nearest_nomip');
+                bg.setTexture(VOXEL_SCENE_ALBEDO, this._albedo, nearest);
+                bg.setTexture(VOXEL_SCENE_EMISSIVE, this._emissive, nearest);
+                // Before the first lighting any volume of the layout stands in, the radiance read as zero
+                bg.setTexture(VOXEL_SCENE_RADIANCE, lit ? this.radiance : this._emissive, nearest);
+                bg.setTexture(VOXEL_SCENE_ANISO0, lit ? this.radianceAniso0 : this._albedo, nearest);
+                bg.setTexture(VOXEL_SCENE_ANISO1, lit ? this.radianceAniso1 : this._albedo, nearest);
+                bg.setBuffer('points', this._queryPoints);
+                bg.setTexture('result', this._queryOutput);
+                bg.setValue('count', new Vector4(n, lit ? 1 : 0, 0, 0));
+                device.setProgram(this._queryProgram);
+                device.setBindGroup(0, bg);
+                device.compute(Math.ceil(n / 64), 1, 1);
+                const read = this._queryOutput.readPixels(0, 0, MAX_QUERY_POINTS, 3, 0, 0, pixels);
+                device.flush();
+                await read;
+            });
+            const row = MAX_QUERY_POINTS * 4;
+            return Array.from({
+                length: n
+            }, (_, i)=>{
+                const a = pixels.subarray(i * 4, i * 4 + 4);
+                const e = pixels.subarray(row + i * 4, row + i * 4 + 4);
+                const r = pixels.subarray(2 * row + i * 4, 2 * row + i * 4 + 4);
+                return {
+                    level: Math.round(e[3]),
+                    albedo: [
+                        a[0],
+                        a[1],
+                        a[2],
+                        a[3]
+                    ],
+                    emissive: [
+                        e[0],
+                        e[1],
+                        e[2]
+                    ],
+                    radiance: [
+                        r[0],
+                        r[1],
+                        r[2]
+                    ]
+                };
+            });
+        };
+        const next = this._queryChain.then(run, run);
+        this._queryChain = next.catch(()=>undefined);
+        return next;
+    }
+    dispose() {
+        this._queryProgram?.dispose();
+        this._queryBindGroup?.dispose();
+        this._queryPoints?.dispose();
+        this._queryOutput?.dispose();
+        this._queryProgram = null;
+        this._queryBindGroup = null;
+        this._queryPoints = null;
+        this._queryOutput = null;
+        this._voxelizer?.dispose();
+        this._voxelizer = null;
+        this._lighting?.dispose();
+        this._lighting = null;
+        this.atlas.dispose();
+        this._albedo?.dispose();
+        this._emissive?.dispose();
+        this._albedo = null;
+        this._emissive = null;
+        for (const entry of this._entries.values()){
+            if (entry.ownsMaterial) {
+                entry.material.dispose();
+            }
+        }
+        this._entries.clear();
+    }
+    /** @internal */ createQueryProgram(levels) {
+        return buildSDFProgram({
+            label: 'VoxelSceneQuery',
+            workgroupSize: [
+                64,
+                1,
+                1
+            ],
+            compute (pb) {
+                this.points = pb.vec4[0]().storageBufferReadonly(0);
+                // (point count, 1 once lit)
+                this.count = pb.vec4().uniform(0);
+                this.result = pb.texStorage2D.rgba32float().storage(0);
+                declareGlobalSDFUniforms(this, 0, levels);
+                declareDynamicSDFUniforms(this, 0);
+                declareVoxelSceneUniforms(this, 0);
+                pb.main(function() {
+                    this.$l.i = this.$builtins.globalInvocationId.x;
+                    this.$if(pb.lessThan(this.i, pb.uint(this.count.x)), function() {
+                        this.$l.texel = voxelSceneTexel(this, this.points.at(this.i).xyz, levels);
+                        this.$l.radiance = pb.vec3(0);
+                        this.$if(pb.and(pb.greaterThanEqual(this.texel.w, 0), pb.greaterThan(this.count.y, 0)), function() {
+                            this.radiance = pb.textureLoad(this[VOXEL_SCENE_RADIANCE], this.texel.xyz, 0).rgb;
+                        });
+                        pb.textureStore(this.result, pb.uvec2(this.i, 0), loadVoxelSceneAlbedo(this, this.texel));
+                        pb.textureStore(this.result, pb.uvec2(this.i, 1), pb.vec4(loadVoxelSceneEmissive(this, this.texel), pb.float(this.texel.w)));
+                        pb.textureStore(this.result, pb.uvec2(this.i, 2), pb.vec4(this.radiance, 0));
+                    });
+                });
+            }
+        });
+    }
+    /** @internal */ get voxelizer() {
+        if (!this._voxelizer) {
+            this._voxelizer = new Voxelizer(this._scene);
+        }
+        return this._voxelizer;
+    }
+    /** @internal */ ensureClipmaps(global) {
+        const resolution = global.resolution / 2;
+        if (this._albedo && this._resolution === resolution && this._levels === global.levels) {
+            return;
+        }
+        this._albedo?.dispose();
+        this._emissive?.dispose();
+        const device = getDevice();
+        this._resolution = resolution;
+        this._levels = global.levels;
+        this._albedo = device.createTexture3D('rgba8unorm', resolution, resolution, resolution * global.levels, {
+            mipmapping: false,
+            writable: true
+        });
+        this._albedo.name = '@VoxelSceneAlbedo';
+        this._emissive = device.createTexture3D('rgba16f', resolution, resolution, resolution * global.levels, {
+            mipmapping: false,
+            writable: true
+        });
+        this._emissive.name = '@VoxelSceneEmissive';
+        // The field must write the new textures everywhere
+        if (global.materials === this) {
+            global.materials = null;
+            global.materials = this;
+        }
+    }
+    /**
+   * A slot for an entry, evicting unwanted meshes then farther wanted ones when full.
+   * Nearer meshes are never evicted for it, so meshes that don't all fit don't thrash.
+   * @internal
+   */ place(entry, wanted) {
+        let slot = this.atlas.add(entry, entry.resolution);
+        if (slot) {
+            return slot;
+        }
+        const resident = [
+            ...this._entries.values()
+        ].filter((e)=>e !== entry && this.atlas.getSlot(e));
+        const dist = wanted.get(entry);
+        const kept = resident.filter((e)=>wanted.has(e) && wanted.get(e) <= dist);
+        if (!this.atlas.fits([
+            entry.resolution,
+            ...kept.map((e)=>e.resolution)
+        ])) {
+            this.fail(entry);
+            return null;
+        }
+        const victims = [
+            ...resident.filter((e)=>!wanted.has(e)).sort((a, b)=>a.lastWanted - b.lastWanted),
+            ...resident.filter((e)=>wanted.get(e) > dist).sort((a, b)=>wanted.get(b) - wanted.get(a))
+        ];
+        for (const victim of victims){
+            this.atlas.remove(victim);
+            victim.state = 'pending';
+            victim.voxelized = false;
+            slot = this.atlas.add(entry, entry.resolution);
+            if (slot) {
+                return slot;
+            }
+        }
+        // Fits packed afresh but not around the freed gaps: repack, re-rasterizing only those moved
+        const moved = this.atlas.repack([
+            entry,
+            ...kept
+        ].map((e)=>({
+                key: e,
+                resolution: e.resolution
+            })));
+        if (moved) {
+            for (const e of this._entries.values()){
+                if (e !== entry && e.voxelized && (moved.has(e) || !this.atlas.getSlot(e))) {
+                    e.voxelized = false;
+                    e.state = 'pending';
+                }
+            }
+            return this.atlas.getSlot(entry);
+        }
+        this.fail(entry);
+        return null;
+    }
+    /** Records an entry that found no room, not to be tried until the atlas changes. @internal */ fail(entry) {
+        entry.failedVersion = this.atlas.version;
+        this._atlasFull++;
+        if (!this._atlasFullWarned) {
+            this._atlasFullWarned = true;
+            const s = this.atlas.size;
+            console.warn(`VoxelScene: the materials of the meshes in the scene field do not fit the ${s.join('×')} material atlas; the farthest are left out and read black where global illumination rays hit them. Raise SceneGI.atlasSize.`);
+        }
+    }
+    /** Rebuilds the field around every instance drawing a (primitive, material). @internal */ dirtyInstances(sdf, global, key) {
+        for (const inst of sdf.instances){
+            if (inst.mode === 'static' && keyOf(inst.mesh) === key && boxValid(inst.bounds)) {
+                global.markDirty(inst.bounds.minPoint, inst.bounds.maxPoint);
+            }
+        }
+    }
+}
+/**
+ * Identity of what a mesh voxelizes to: primitive plus core material, with a material
+ * instance's overridden uniform values appended so differently tinted instances differ.
+ */ function keyOf(mesh) {
+    const primitive = mesh.primitive;
+    const material = mesh.material;
+    if (!primitive || !material) {
+        return null;
+    }
+    const core = material.coreMaterial;
+    return `${primitive.id}:${core.instanceId}${instanceSuffix(material)}`;
+}
+/**
+ * What a voxelization depends on in a material: the core's appearance tag (look-changing
+ * edits, not the per-frame picking color) and change tag (texture loads).
+ */ function materialTagOf(material) {
+    const core = material.coreMaterial;
+    return `${core.appearanceTag}:${core.changeTag}`;
+}
+/** The instance uniform values a material instance overrides its core with, as a key suffix, else empty. */ function instanceSuffix(material) {
+    if (!material.$isInstance) {
+        return '';
+    }
+    const core = material.coreMaterial;
+    const parts = [];
+    for (const { prop } of core.getInstancedUniforms()){
+        const a = material[prop];
+        const b = core[prop];
+        if (!sameValue(a, b)) {
+            parts.push(`${prop}=${String(a)}`);
+        }
+    }
+    return parts.length ? `:${parts.join(',')}` : '';
+}
+function sameValue(a, b) {
+    if (typeof a === 'number' || typeof b === 'number') {
+        return a === b;
+    }
+    const va = a;
+    const vb = b;
+    if (!va || !vb || va.length !== vb.length) {
+        return a === b;
+    }
+    for(let i = 0; i < va.length; i++){
+        if (va[i] !== vb[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The material to draw: the core, or for an instance with overrides a copy of the core
+ * carrying its values, since the voxelize pass draws non-instanced.
+ */ function resolveMaterial(material) {
+    if (!material.$isInstance || !instanceSuffix(material)) {
+        return {
+            material: material.coreMaterial,
+            owned: false
+        };
+    }
+    const core = material.coreMaterial;
+    const copy = core.clone?.();
+    if (!copy) {
+        return {
+            material: core,
+            owned: false
+        };
+    }
+    for (const { prop } of core.getInstancedUniforms()){
+        copy[prop] = material[prop];
+    }
+    return {
+        material: copy,
+        owned: true
+    };
+}
+function boxValid(box) {
+    return box.minPoint.x <= box.maxPoint.x;
+}
+function distanceToBox(p, box) {
+    const dx = Math.max(box.minPoint.x - p.x, 0, p.x - box.maxPoint.x);
+    const dy = Math.max(box.minPoint.y - p.y, 0, p.y - box.maxPoint.y);
+    const dz = Math.max(box.minPoint.z - p.z, 0, p.z - box.maxPoint.z);
+    return Math.hypot(dx, dy, dz);
+}
+
+export { VoxelScene };
+//# sourceMappingURL=voxel_scene.js.map