@driftengine/core 3.63.0 → 4.0.0

package/dist/render/gi/fieldScene.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The frame's declared distance fields — what the renderer's indirect light may be traced against.
+ *
+ * **A consumer declares this, and the seam is `addOccluder`'s for `addOccluder`'s reason.** A
+ * distance field is the shape of a thing it is *safe* to be traced against, and only the consumer
+ * knows which of its objects that is true of: the terrain and the walls, not the leaves, not the
+ * water, not the thing that is about to be deleted. `quality.occlusionCulling` already makes that
+ * sentence about occluders and culls nothing until somebody declares one. This makes it about
+ * light, and lights nothing until somebody declares a field.
+ *
+ * **A field and its placement are separate arguments on purpose.** Forty identical pillars are one
+ * baked field and forty matrices: the samples are megabytes and the matrices are bytes. So a source
+ * declared twice in a frame is two instances sharing one packed copy of its samples, and the queue
+ * is what knows the difference.
+ *
+ * **The transform is copied and the samples are not.** A consumer holds a matrix and moves it —
+ * that is what a matrix is for — so a queue that kept the reference would replay every field
+ * wearing the last pose written, which is `DecalQueue`'s recorded mistake and is the dangerous
+ * kind: a plausible picture rather than a broken one. A `FieldSource`, by contrast, is baked and
+ * does not move, and copying its samples once a frame would move the whole field across the bus to
+ * say the same thing.
+ *
+ * **Records are pooled and never released**, per `AGENTS.md`: `reset` returns the count to zero
+ * and keeps the storage, so a steady scene allocates on its first frame and never again.
+ */
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { FieldSource } from './globalField.ts';
+/**
+ * How many placed fields one frame may declare.
+ *
+ * **Thirty-two, which is what `composeGlobalField` was measured against** — 707 ms on the CPU for
+ * thirty-two instances over four cascades, and the number the device composition has carried since.
+ * The cost is not in the count itself but in the instance buffer being sized once and bound for
+ * every cascade's dispatch, so it is a cap rather than a growth.
+ */
+export declare const MAX_DISTANCE_FIELDS = 32;
+/**
+ * How many samples the frame's distinct sources may add up to, across all of them.
+ *
+ * Four million floats is sixteen megabytes on the device, which is a 160-cubed field or two
+ * hundred 27-cubed ones. **The budget is over the distinct sources rather than the instances**,
+ * because that is what is actually uploaded.
+ */
+export declare const MAX_DISTANCE_FIELD_SAMPLES: number;
+/** One placed field. `transform` is this queue's own copy; `source` is the consumer's object. */
+export interface DistanceFieldInstance {
+    /** The baked field. Shared by reference: it does not move and it is the large thing. */
+    source: FieldSource;
+    /** World from object, copied at the moment it was declared. Uniform scale only. */
+    readonly transform: Float32Array;
+    /**
+     * What colour this placement's surface is, copied like the transform. White where none was given.
+     *
+     * **A ray that lands on a wall needs to know what colour it is**, because what leaves a surface
+     * is the light arriving times its albedo — and a composed distance field is a union that has
+     * already forgotten which instance won. `demo/dev/bounce.html` is what made it necessary: a
+     * trace without it returned the same answer for a red wall and a white one.
+     *
+     * On the placement rather than the field, because the same baked shape is placed many times and
+     * two pillars cut from one mould may be painted differently.
+     */
+    readonly albedo: Float32Array;
+}
+export declare class DistanceFieldScene {
+    private readonly pool;
+    private count;
+    /** The distinct sources of this frame, in the order they were first declared. */
+    private readonly distinct;
+    /** Where each distinct source's samples start in the packed upload, in floats. */
+    private readonly offsets;
+    private samples;
+    /** The distinct sources of the frame that `reset` last ended, for `packingChanged`. */
+    private packed;
+    /** Set once when a budget is first reached, so a scene over it says so and then draws. */
+    private warnedInstances;
+    private warnedSamples;
+    /** How many placed fields this frame has recorded. */
+    get length(): number;
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity(): number;
+    /** This frame's distinct sources, in the order their samples are packed. */
+    get sources(): readonly FieldSource[];
+    /** Floats the packed upload holds — the sum of the distinct sources' fields. */
+    get sampleCount(): number;
+    /**
+     * Whether the samples have to be uploaded again, or the placements alone will do.
+     *
+     * True when this frame's distinct sources are not the last frame's in the same order, since the
+     * offsets are positional. A scene whose fields never change answers false from its second frame
+     * on, which is what keeps a sixteen-megabyte upload out of the frame loop.
+     */
+    get packingChanged(): boolean;
+    /** Where a source's samples start in the packed upload, or -1 if it is not in this frame. */
+    offsetOf(source: FieldSource): number;
+    /**
+     * Declare a field, placed.
+     *
+     * **A source whose samples do not fit is refused whole rather than clipped.** Half a field on the
+     * device is not a coarser field; it is a field whose far half reads whatever the buffer held, and
+     * that composes as surfaces that are not there — the failure Wave 4A already paid for once, where
+     * a phantom surface passed 111,907 parity samples and was found by looking at a picture.
+     */
+    record(source: FieldSource, model: ReadonlyMat4, albedo?: ArrayLike<number>): void;
+    replay(each: (instance: DistanceFieldInstance) => void): void;
+    /** Empty it for the next frame, keeping the storage and remembering what was packed. */
+    reset(): void;
+}
+/**
+ * The world extent of everything a frame declared, into vectors the caller owns.
+ *
+ * **This is what a probe grid is fitted to when a scene declared none.** A renderer asked for
+ * indirect light has to put its probes somewhere, and the only description of the world it holds is
+ * the set of fields a consumer said its light may be traced against. That is also the *right*
+ * description: a grid sized to include everything drawn would spend its probes on the inside of the
+ * sky sphere, while a grid sized to the traceable geometry is a grid around the room.
+ *
+ * **Every corner is transformed, not the box.** A rotated box's axis-aligned extent is decided by
+ * where its corners went; transforming the two extremes and taking their min and max gives a box
+ * that is too small wherever a rotation is not a multiple of a quarter turn, and too small is a
+ * probe grid that stops short of the wall it is meant to surround.
+ *
+ * False when the frame declared nothing, rather than an empty box at the origin — which
+ * `fitProbeGrid` would answer with a plausible grid of one standing in a place no scene chose.
+ */
+export declare function distanceFieldBounds(scene: DistanceFieldScene, min: Float32Array, max: Float32Array): boolean;

package/dist/render/gi/fieldScene.js

@@ -0,0 +1,219 @@
+/**
+ * The frame's declared distance fields — what the renderer's indirect light may be traced against.
+ *
+ * **A consumer declares this, and the seam is `addOccluder`'s for `addOccluder`'s reason.** A
+ * distance field is the shape of a thing it is *safe* to be traced against, and only the consumer
+ * knows which of its objects that is true of: the terrain and the walls, not the leaves, not the
+ * water, not the thing that is about to be deleted. `quality.occlusionCulling` already makes that
+ * sentence about occluders and culls nothing until somebody declares one. This makes it about
+ * light, and lights nothing until somebody declares a field.
+ *
+ * **A field and its placement are separate arguments on purpose.** Forty identical pillars are one
+ * baked field and forty matrices: the samples are megabytes and the matrices are bytes. So a source
+ * declared twice in a frame is two instances sharing one packed copy of its samples, and the queue
+ * is what knows the difference.
+ *
+ * **The transform is copied and the samples are not.** A consumer holds a matrix and moves it —
+ * that is what a matrix is for — so a queue that kept the reference would replay every field
+ * wearing the last pose written, which is `DecalQueue`'s recorded mistake and is the dangerous
+ * kind: a plausible picture rather than a broken one. A `FieldSource`, by contrast, is baked and
+ * does not move, and copying its samples once a frame would move the whole field across the bus to
+ * say the same thing.
+ *
+ * **Records are pooled and never released**, per `AGENTS.md`: `reset` returns the count to zero
+ * and keeps the storage, so a steady scene allocates on its first frame and never again.
+ */
+import { assertCubicVoxels } from './globalField.js';
+/**
+ * How many placed fields one frame may declare.
+ *
+ * **Thirty-two, which is what `composeGlobalField` was measured against** — 707 ms on the CPU for
+ * thirty-two instances over four cascades, and the number the device composition has carried since.
+ * The cost is not in the count itself but in the instance buffer being sized once and bound for
+ * every cascade's dispatch, so it is a cap rather than a growth.
+ */
+export const MAX_DISTANCE_FIELDS = 32;
+/**
+ * How many samples the frame's distinct sources may add up to, across all of them.
+ *
+ * Four million floats is sixteen megabytes on the device, which is a 160-cubed field or two
+ * hundred 27-cubed ones. **The budget is over the distinct sources rather than the instances**,
+ * because that is what is actually uploaded.
+ */
+export const MAX_DISTANCE_FIELD_SAMPLES = 1 << 22;
+function newRecord() {
+    return {
+        source: EMPTY_SOURCE,
+        transform: new Float32Array(16),
+        albedo: Float32Array.from([1, 1, 1]),
+    };
+}
+/** A placeholder a pooled record holds before its first use, so `source` is never null. */
+const EMPTY_SOURCE = {
+    field: new Float32Array(0),
+    dims: [0, 0, 0],
+    bounds: new Float32Array(6),
+};
+export class DistanceFieldScene {
+    pool = [];
+    count = 0;
+    /** The distinct sources of this frame, in the order they were first declared. */
+    distinct = [];
+    /** Where each distinct source's samples start in the packed upload, in floats. */
+    offsets = new Map();
+    samples = 0;
+    /** The distinct sources of the frame that `reset` last ended, for `packingChanged`. */
+    packed = [];
+    /** Set once when a budget is first reached, so a scene over it says so and then draws. */
+    warnedInstances = false;
+    warnedSamples = false;
+    /** How many placed fields this frame has recorded. */
+    get length() {
+        return this.count;
+    }
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity() {
+        return this.pool.length;
+    }
+    /** This frame's distinct sources, in the order their samples are packed. */
+    get sources() {
+        return this.distinct;
+    }
+    /** Floats the packed upload holds — the sum of the distinct sources' fields. */
+    get sampleCount() {
+        return this.samples;
+    }
+    /**
+     * Whether the samples have to be uploaded again, or the placements alone will do.
+     *
+     * True when this frame's distinct sources are not the last frame's in the same order, since the
+     * offsets are positional. A scene whose fields never change answers false from its second frame
+     * on, which is what keeps a sixteen-megabyte upload out of the frame loop.
+     */
+    get packingChanged() {
+        if (this.distinct.length !== this.packed.length)
+            return true;
+        for (let i = 0; i < this.distinct.length; i += 1) {
+            if (this.distinct[i] !== this.packed[i])
+                return true;
+        }
+        return false;
+    }
+    /** Where a source's samples start in the packed upload, or -1 if it is not in this frame. */
+    offsetOf(source) {
+        return this.offsets.get(source) ?? -1;
+    }
+    /**
+     * Declare a field, placed.
+     *
+     * **A source whose samples do not fit is refused whole rather than clipped.** Half a field on the
+     * device is not a coarser field; it is a field whose far half reads whatever the buffer held, and
+     * that composes as surfaces that are not there — the failure Wave 4A already paid for once, where
+     * a phantom surface passed 111,907 parity samples and was found by looking at a picture.
+     */
+    record(source, model, albedo) {
+        /*
+         * **Before anything else, because a malformed source is not a budget.** The two warnings below
+         * are a frame asking for more than it can carry and dropping the surplus is the honest answer;
+         * there is none to a source the composer cannot read. The renderer composes on the device and
+         * never reaches `composeGlobalField`, so its own check protects only the reference path.
+         */
+        assertCubicVoxels(source);
+        if (this.count >= MAX_DISTANCE_FIELDS) {
+            if (!this.warnedInstances) {
+                this.warnedInstances = true;
+                console.warn(`driftengine: more than ${MAX_DISTANCE_FIELDS} distance fields were declared in one ` +
+                    'frame, so the rest are not traced against. Fields that never move are cheaper baked ' +
+                    'into one source, which is composed as a single instance.');
+            }
+            return;
+        }
+        const known = this.offsets.get(source);
+        if (known === undefined) {
+            if (this.samples + source.field.length > MAX_DISTANCE_FIELD_SAMPLES) {
+                if (!this.warnedSamples) {
+                    this.warnedSamples = true;
+                    console.warn(`driftengine: the frame's distance fields exceed ${MAX_DISTANCE_FIELD_SAMPLES} ` +
+                        'samples, so this one is not traced against at all. A field composed in part reads ' +
+                        'whatever the buffer held beyond it, which is surfaces that are not there.');
+                }
+                return;
+            }
+            this.offsets.set(source, this.samples);
+            this.distinct.push(source);
+            this.samples += source.field.length;
+        }
+        let record = this.pool[this.count];
+        if (record === undefined) {
+            record = newRecord();
+            this.pool.push(record);
+        }
+        record.source = source;
+        for (let at = 0; at < 16; at += 1)
+            record.transform[at] = model[at] ?? 0;
+        /* Copied like the transform, and white where none was declared. */
+        for (let at = 0; at < 3; at += 1)
+            record.albedo[at] = albedo?.[at] ?? 1;
+        this.count += 1;
+    }
+    replay(each) {
+        for (let i = 0; i < this.count; i += 1) {
+            const record = this.pool[i];
+            if (record !== undefined)
+                each(record);
+        }
+    }
+    /** Empty it for the next frame, keeping the storage and remembering what was packed. */
+    reset() {
+        this.packed = this.distinct.slice();
+        this.count = 0;
+        this.distinct.length = 0;
+        this.offsets.clear();
+        this.samples = 0;
+    }
+}
+/**
+ * The world extent of everything a frame declared, into vectors the caller owns.
+ *
+ * **This is what a probe grid is fitted to when a scene declared none.** A renderer asked for
+ * indirect light has to put its probes somewhere, and the only description of the world it holds is
+ * the set of fields a consumer said its light may be traced against. That is also the *right*
+ * description: a grid sized to include everything drawn would spend its probes on the inside of the
+ * sky sphere, while a grid sized to the traceable geometry is a grid around the room.
+ *
+ * **Every corner is transformed, not the box.** A rotated box's axis-aligned extent is decided by
+ * where its corners went; transforming the two extremes and taking their min and max gives a box
+ * that is too small wherever a rotation is not a multiple of a quarter turn, and too small is a
+ * probe grid that stops short of the wall it is meant to surround.
+ *
+ * False when the frame declared nothing, rather than an empty box at the origin — which
+ * `fitProbeGrid` would answer with a plausible grid of one standing in a place no scene chose.
+ */
+export function distanceFieldBounds(scene, min, max) {
+    if (scene.length === 0)
+        return false;
+    for (let axis = 0; axis < 3; axis += 1) {
+        min[axis] = Infinity;
+        max[axis] = -Infinity;
+    }
+    scene.replay((instance) => {
+        const box = instance.source.bounds;
+        const m = instance.transform;
+        for (let corner = 0; corner < 8; corner += 1) {
+            const x = box[(corner & 1) === 0 ? 0 : 3];
+            const y = box[(corner & 2) === 0 ? 1 : 4];
+            const z = box[(corner & 4) === 0 ? 2 : 5];
+            for (let axis = 0; axis < 3; axis += 1) {
+                const value = m[axis] * x +
+                    m[4 + axis] * y +
+                    m[8 + axis] * z +
+                    m[12 + axis];
+                if (value < min[axis])
+                    min[axis] = value;
+                if (value > max[axis])
+                    max[axis] = value;
+            }
+        }
+    });
+    return true;
+}

package/dist/render/gi/globalField.d.ts

@@ -0,0 +1,157 @@
+/** The world near the camera as one distance field, assembled from the objects standing in it. */
+import type { ReadonlyMat4, ReadonlyVec3 } from 'gl-matrix';
+import type { Vec3 } from '../../math/color.ts';
+/**
+ * A baked object field, as this package can describe one.
+ *
+ * **Structural rather than imported**, because `@driftengine/core` does not depend on
+ * `@driftengine/assets` and must not start: the baker is a build step and this is a frame. What
+ * `bakeObjectSdf` returns satisfies this shape, and so does what `readSdfv` hands back from a
+ * container. That is the arrangement `Terrain` already has with `Heightfield` across the physics
+ * boundary and `DTEX` has with `@driftengine/texture` across the container one.
+ */
+export interface FieldSource {
+    /** Distance in metres, negative inside. `x` fastest, then `y`, then `z`. */
+    readonly field: Float32Array;
+    readonly dims: readonly [number, number, number];
+    /** The field's own extent in **object** space, `[minX, minY, minZ, maxX, maxY, maxZ]`. */
+    readonly bounds: Float32Array;
+}
+export interface GlobalFieldInstance {
+    readonly source: FieldSource;
+    /**
+     * What colour this instance's surface is, or white where it did not say.
+     *
+     * On the instance rather than the source, because the same baked field is placed many times and
+     * two pillars cut from one mould may be painted differently. Optional so that every caller
+     * written before the trace needed a colour is unchanged.
+     */
+    readonly albedo?: Vec3;
+    /**
+     * World from object.
+     *
+     * **Uniform scale only, and `composeGlobalField` refuses the rest rather than approximating.**
+     * A distance is not preserved by a non-uniform scale: the factor to correct by depends on the
+     * direction to the nearest surface, which is exactly what a distance field does not record. An
+     * instance squashed on one axis and sampled anyway produces something that is a distance in no
+     * direction and looks like one in every slice.
+     */
+    readonly transform: ReadonlyMat4;
+}
+/** One level of the clipmap: a grid the composer fills and `sampleGlobalField` reads. */
+export interface GlobalFieldCascade {
+    readonly field: Float32Array;
+    /**
+     * The colour of whatever surface won the union at each sample, three floats a sample.
+     *
+     * **A union loses which instance won, and a ray that lands on a wall needs to know what colour
+     * it is.** `demo/dev/bounce.html` is what made this necessary: a trace whose radiance came from
+     * a rasterised capture could not follow a wall that changed colour, and one that read the probe
+     * volume's irradiance returned the same answer for a red wall and a white one — irradiance is
+     * light arriving, and what leaves a surface is that times its albedo.
+     *
+     * **White where no instance reached**, rather than black: the colour of a sample no ray can hit
+     * is never read, and black would turn a read that did happen into light quietly vanishing
+     * instead of a picture that is obviously wrong.
+     */
+    readonly albedo: Float32Array;
+    readonly dims: readonly [number, number, number];
+    /** Where this cascade stands, written by `composeGlobalField`. Six floats. */
+    readonly bounds: Float32Array;
+    /** Metres between samples, the same on all three axes. Written by `composeGlobalField`. */
+    step: number;
+}
+/**
+ * The composed world, as nested cascades centred on the camera.
+ *
+ * **A clipmap and not a sparse brick tree, which is a smaller claim than the plan made and is
+ * what is here.** Fine near the viewer and coarse further out is the requirement, and nesting
+ * grids of equal sample count at doubling extents meets it exactly: cascade 0 resolves a room and
+ * cascade 3 resolves a district, at one allocation each and no indirection to traverse. What a
+ * brick tree buys on top is *memory* — skipping the volume no surface is near — and nothing yet
+ * measured says this needs it. `traceField.ts` will say, because it is the thing that pays.
+ */
+export interface GlobalField {
+    /** Finest first. Each is twice the reach and twice the step of the one before it. */
+    readonly cascades: readonly GlobalFieldCascade[];
+}
+/**
+ * How much of a cascade's extent, at each face, fades into the cascade outside it.
+ *
+ * **A hard switch between cascades is worse than either cascade's own error.** An error that is
+ * wrong everywhere reads as a coarse solution; one that changes abruptly along a surface reads as
+ * a crack, and the crack moves with the camera because the boundary does. A tenth of the extent
+ * is wide enough that the fade is below a voxel per step and narrow enough that the inner
+ * cascade's resolution is what most of the inner cascade actually delivers.
+ */
+export declare const GLOBAL_FIELD_BLEND = 0.1;
+/** Allocate a field. Called once; `composeGlobalField` fills it and allocates nothing. */
+export declare function createGlobalField(resolution: number, cascades: number): GlobalField;
+/**
+ * Put one cascade where the camera is, and answer its half-extent.
+ *
+ * **Exported because the compute path needs the same placement and two spellings drift.** A pass
+ * filling these on a device has to agree with this about where every cascade stands, to the last
+ * bit: disagree by a fraction of a step and the fade between cascades lands somewhere different on
+ * each side, which is a seam that appears only when both paths are compared.
+ *
+ * The snapping is the decision. See `composeGlobalField` for why a grid centred on the exact camera
+ * position makes the whole field shimmer.
+ */
+export declare function placeCascade(cascade: GlobalFieldCascade, level: number, radius: number, cameraPos: ReadonlyVec3): number;
+/**
+ * Fill every cascade from the instances standing near the camera.
+ *
+ * `radius` is the innermost cascade's half-extent in metres; each cascade outside it reaches twice
+ * as far at the same sample count.
+ *
+ * **Every cascade's centre is snapped to a multiple of its own step, and that is the decision this
+ * function exists to make.** A grid centred on the exact camera position resamples the entire
+ * world at a new sub-pixel offset every frame, so every value changes slightly every frame and the
+ * indirect light shimmers — worst on a slow camera, which is exactly when a viewer is looking at
+ * it. Snapped, a camera move is either nothing at all or a whole voxel, and a whole voxel leaves
+ * every sample the two grids share bit-identical.
+ *
+ * **A point no instance is near takes the cascade's own reach rather than infinity.** That is an
+ * underestimate of the true distance, which is the safe direction: a march that steps by it takes
+ * a shorter step than it could and converges anyway, where an overestimate steps through the wall
+ * it was meant to stop at.
+ *
+ * **This is the reference, and it visits every sample of every cascade for every instance that is
+ * not culled outright.** `scripts/gpu-parity.mjs` is the pattern the WGSL will be checked against,
+ * and the WGSL is where the brick culling belongs — a CPU implementation that was already
+ * accelerated would be a second thing to be wrong rather than the thing the first is checked by.
+ */
+export declare function composeGlobalField(instances: readonly GlobalFieldInstance[], cameraPos: ReadonlyVec3, radius: number, out: GlobalField): void;
+/**
+ * The field at a world point, from the finest cascade that holds it.
+ *
+ * A point past every cascade reads the outermost one clamped to its edge, rather than a sentinel:
+ * a caller marching outward wants a number it can step by, and the outermost cascade's own reach
+ * is the honest one.
+ */
+export declare function sampleGlobalField(field: GlobalField, x: number, y: number, z: number): number;
+/**
+ * Refuse a source whose voxels are not cubic, which `sourceAt` and the shader both assume.
+ *
+ * **One step for all three axes is the contract, and it was unwritten until it cost a feature.**
+ * `bakeObjectSdf` picks its step from the object's longest axis and gives each axis whatever count
+ * it needs at that step, so `dims` differ per axis and the spacing does not. Both readers rely on
+ * that: `sourceAt` here derives the step from x alone, and `composeField.wgsl.ts` says so in a
+ * comment. A source sampled with the same count on every axis of a box that is not a cube has
+ * oblong voxels, and every sample of it is taken at the wrong place along y and z — far enough
+ * wrong that a point at the centre of a slab reads the slab's corner.
+ *
+ * **Measured on `demo/dev/bounce.html`**, whose room is five such slabs: the composed field held
+ * almost no room, 98.9% of every probe's rays left a closed room, and the traced bounce delivered a
+ * thirty-fifth of the light. Nothing failed; the field was simply empty. Refusing is the only
+ * honest answer, because a distance field carries no record of the axis it was sampled along and
+ * there is nothing here to correct it with — the same reason a non-uniform scale is refused above.
+ *
+ * **An axis of one sample is refused here too, and by its own sentence**, because `read` addresses
+ * `index` and `index + 1` on every axis and cannot be given an axis with no pair. `bakeObjectSdf`
+ * never produces one — its counts are a ceiling plus one over a span that includes two voxels of
+ * padding — but `FieldSource` is a shape a consumer may build by hand, which is the whole reason
+ * this function exists.
+ */
+export declare function assertCubicVoxels(source: FieldSource): void;