@driftengine/core 3.63.0 → 4.1.0

package/dist/render/backend/webgpu/buffers.js

@@ -209,45 +209,24 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
     const indicesPerStep = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / indexWidth));
     const totalSteps = Math.max(1, Math.ceil(vertexCount / verticesPerStep)) +
         Math.max(1, Math.ceil(data.indices.length / indicesPerStep));
-    let uploaded = false;
-    function* uploadSteps() {
-        let taken = 0;
-        for (let from = 0; from < vertexCount; from += verticesPerStep) {
-            const to = Math.min(from + verticesPerStep, vertexCount);
-            let fieldOffset = 0;
-            for (const attribute of supplied) {
-                const source = data[attribute.name];
-                const width = attribute.components;
-                for (let vertex = from; vertex < to; vertex++) {
-                    for (let component = 0; component < width; component++) {
-                        interleaved[vertex * step + fieldOffset + component] =
-                            source[vertex * width + component] ?? 0;
-                    }
-                }
-                fieldOffset += width;
-            }
-            device.queue.writeBuffer(vertices, from * stride, interleaved, from * step, (to - from) * step);
-            taken += 1;
-            if (taken < totalSteps)
-                yield;
-        }
-        for (let from = 0; from < data.indices.length; from += indicesPerStep) {
-            const to = Math.min(from + indicesPerStep, data.indices.length);
-            device.queue.writeBuffer(indexBuffer, from * indexWidth, data.indices, from, to - from);
-            taken += 1;
-            if (taken < totalSteps)
-                yield;
-        }
-        uploaded = true;
-    }
-    const mesh = {
-        vertexBuffers: [vertices, constants],
+    /*
+     * **The mesh is assembled out here, by functions of its own, and that is the fix for a copy
+     * nobody named.** It was an object literal in this scope, and its `complete` getter shared this
+     * scope's context with the upload generator and the `filter` above, which both read `data` — V8
+     * gives every closure in a scope one context — so a getter returning a boolean held the whole
+     * `MeshData` and the interleaved rows for as long as the mesh lived. The voxel sandbox's forward
+     * path held 2,058 MB of ArrayBuffers at radius 32 against the second pipeline's 368.
+     * `meshRetention.test.ts` holds it: a mesh keeps its buffers, and a dynamic one its rows.
+     */
+    const progress = { uploaded: false };
+    const mesh = gpuMeshOf({
+        vertices,
+        constants,
         indexBuffer,
+        stride,
         indexCount: data.indices.length,
         bounds,
-        get complete() {
-            return uploaded;
-        },
+        progress,
         hasTangents: data.tangents !== undefined,
         isSkinned: data.joints !== undefined,
         hasChannel: data.channel !== undefined,
@@ -256,35 +235,114 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
             : new MorphTexture(device, data.morphTargets, data.positions.length / 3, data.morphTargetCount),
         update: !dynamic
             ? null
-            : (target, positions, normals) => {
-                if (positions.length !== vertexCount * 3) {
-                    throw new Error(`this mesh has ${vertexCount} vertices and the update has ${positions.length / 3}. ` +
-                        "A mesh's vertex count is fixed at creation: the index buffer, the pipeline and " +
-                        'every other attribute are sized against it.');
-                }
-                /* Everything that decides whether this is on screen starts from the bounds, so a cloth
-                   that blew sideways out of its original box would be culled while still visible. */
-                boundsOfPositions(positions, bounds);
-                for (let vertex = 0; vertex < vertexCount; vertex++) {
-                    const at = vertex * step;
-                    interleaved[at + positionField] = positions[vertex * 3] ?? 0;
-                    interleaved[at + positionField + 1] = positions[vertex * 3 + 1] ?? 0;
-                    interleaved[at + positionField + 2] = positions[vertex * 3 + 2] ?? 0;
-                    if (normals === undefined)
-                        continue;
-                    interleaved[at + normalField] = normals[vertex * 3] ?? 0;
-                    interleaved[at + normalField + 1] = normals[vertex * 3 + 1] ?? 0;
-                    interleaved[at + normalField + 2] = normals[vertex * 3 + 2] ?? 0;
+            : dynamicUpdate(interleaved, vertices, bounds, vertexCount, step, positionField, normalField),
+    });
+    const job = {
+        data,
+        interleaved,
+        device,
+        supplied,
+        vertices,
+        indexBuffer,
+        vertexCount,
+        step,
+        stride,
+        verticesPerStep,
+        indicesPerStep,
+        totalSteps,
+        progress,
+    };
+    return { mesh, upload: uploadSteps(job) };
+}
+function* uploadSteps(job) {
+    const { device, supplied, vertices, indexBuffer, vertexCount, step, stride } = job;
+    let taken = 0;
+    for (let from = 0; from < vertexCount; from += job.verticesPerStep) {
+        const data = job.data;
+        const interleaved = job.interleaved;
+        const to = Math.min(from + job.verticesPerStep, vertexCount);
+        let fieldOffset = 0;
+        for (const attribute of supplied) {
+            const source = data[attribute.name];
+            const width = attribute.components;
+            for (let vertex = from; vertex < to; vertex++) {
+                for (let component = 0; component < width; component++) {
+                    interleaved[vertex * step + fieldOffset + component] =
+                        source[vertex * width + component] ?? 0;
                 }
-                target.queue.writeBuffer(vertices, 0, interleaved);
-            },
+            }
+            fieldOffset += width;
+        }
+        device.queue.writeBuffer(vertices, from * stride, interleaved, from * step, (to - from) * step);
+        taken += 1;
+        if (taken < job.totalSteps)
+            yield;
+    }
+    const indices = job.data.indices;
+    const indexWidth = indices.BYTES_PER_ELEMENT;
+    for (let from = 0; from < indices.length; from += job.indicesPerStep) {
+        const to = Math.min(from + job.indicesPerStep, indices.length);
+        device.queue.writeBuffer(indexBuffer, from * indexWidth, indices, from, to - from);
+        taken += 1;
+        if (taken < job.totalSteps)
+            yield;
+    }
+    job.data = null;
+    job.interleaved = null;
+    job.progress.uploaded = true;
+}
+/** The handle, made where it can see only what it hands out. */
+function gpuMeshOf(parts) {
+    const { vertices, constants, indexBuffer, progress } = parts;
+    return {
+        vertexBuffers: [vertices, constants],
+        vertexStride: parts.stride,
+        indexBuffer,
+        indexCount: parts.indexCount,
+        bounds: parts.bounds,
+        get complete() {
+            return progress.uploaded;
+        },
+        hasTangents: parts.hasTangents,
+        isSkinned: parts.isSkinned,
+        hasChannel: parts.hasChannel,
+        morph: parts.morph,
+        update: parts.update,
         dispose() {
             vertices.destroy();
             constants.destroy();
             indexBuffer.destroy();
         },
     };
-    return { mesh, upload: uploadSteps() };
+}
+/**
+ * A dynamic mesh's `update`, which keeps the interleaved rows and nothing else: it rewrites the
+ * positions and normals in them and uploads the whole buffer, so the other attributes it does not
+ * receive have to still be there.
+ */
+function dynamicUpdate(interleaved, vertices, bounds, vertexCount, step, positionField, normalField) {
+    return (target, positions, normals) => {
+        if (positions.length !== vertexCount * 3) {
+            throw new Error(`this mesh has ${vertexCount} vertices and the update has ${positions.length / 3}. ` +
+                "A mesh's vertex count is fixed at creation: the index buffer, the pipeline and " +
+                'every other attribute are sized against it.');
+        }
+        /* Everything that decides whether this is on screen starts from the bounds, so a cloth
+           that blew sideways out of its original box would be culled while still visible. */
+        boundsOfPositions(positions, bounds);
+        for (let vertex = 0; vertex < vertexCount; vertex++) {
+            const at = vertex * step;
+            interleaved[at + positionField] = positions[vertex * 3] ?? 0;
+            interleaved[at + positionField + 1] = positions[vertex * 3 + 1] ?? 0;
+            interleaved[at + positionField + 2] = positions[vertex * 3 + 2] ?? 0;
+            if (normals === undefined)
+                continue;
+            interleaved[at + normalField] = normals[vertex * 3] ?? 0;
+            interleaved[at + normalField + 1] = normals[vertex * 3 + 1] ?? 0;
+            interleaved[at + normalField + 2] = normals[vertex * 3 + 2] ?? 0;
+        }
+        target.queue.writeBuffer(vertices, 0, interleaved);
+    };
 }
 /**
  * The buffer layouts a pipeline is built with, matching what `createGpuMesh` uploaded.

package/dist/render/backend/webgpu/fieldCompose.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The world's distance field, composed on the device from what the frame declared.
+ *
+ * **Extracted from `GiFieldPass` rather than written beside it**, because two copies of this
+ * arithmetic is exactly the hazard `composeField.wgsl.ts` opens by naming: a shader and a
+ * TypeScript function cannot import a struct from each other, so every restatement of the layout
+ * is a place the two can drift. There was already one restatement — the reference and the shader,
+ * which `scripts/gi-parity.mjs` holds together. A third, in a renderer that composed its own field
+ * while a contributed pass composed another, would be one nothing checks.
+ *
+ * **What changed from the pass is where the instances come from.** `GiFieldPass` took them in its
+ * constructor and uploaded them once at `init`, which is right for a rig whose scene is fixed and
+ * wrong for a renderer whose consumer declares its fields every frame. Here the instances arrive
+ * in a `DistanceFieldScene`, the instance count reaches the shader through the params, and the
+ * samples live in a buffer that grows to fit the scene and is never reallocated by a steady one.
+ *
+ * **The samples are uploaded only when the packing changed.** A field is megabytes and a placement
+ * is bytes; a composer that rewrote the samples every frame would move the whole world across the
+ * bus to say what it said last frame. `DistanceFieldScene.packingChanged` is what knows.
+ */
+import type { ReadonlyMat4, ReadonlyVec3 } from 'gl-matrix';
+import type { DistanceFieldScene } from '../../gi/fieldScene.ts';
+import type { PassDistanceField } from '../../pass.ts';
+/**
+ * What a composed field is, to anything that reads it.
+ *
+ * **Declared in `pass.ts` rather than here**, because it is what the seam hands a contributed pass
+ * and a second declaration of one shape is the drift this file's header is about. This is an alias
+ * so a reader of the composer does not have to leave it to learn what it produces.
+ */
+export type ComposedField = PassDistanceField;
+/**
+ * What the renderer composes with when a consumer only said `quality.indirectLight`.
+ *
+ * **Three cascades of 49, four metres at the innermost**, which is `demo/giFieldRig.ts`'s
+ * measurement and its reasoning: 49 rather than 33 puts the innermost cascade's step at 16.7 cm
+ * rather than 25, the difference between a 1.1 m object having six samples across it and four.
+ * The three together are 1.4 MB on the device, and the outermost reaches sixteen metres — beyond
+ * which the chain's probe level answers and never declines.
+ */
+export declare const DEFAULT_FIELD_COMPOSE: FieldComposeOptions;
+export interface FieldComposeOptions {
+    /** Samples a side, every cascade. */
+    readonly resolution: number;
+    readonly cascades: number;
+    /** The innermost cascade's half-extent in metres. Each one out reaches twice as far. */
+    readonly radius: number;
+}
+export declare class FieldComposer {
+    private readonly options;
+    private readonly samples;
+    /** The cascade geometry, kept on the CPU because `placeCascade` is what decides it. */
+    private readonly cascades;
+    private readonly device;
+    private readonly pipeline;
+    /** One a cascade, each binding that cascade's own params at its own aligned offset. */
+    private groups;
+    private readonly paramBuffer;
+    private readonly instanceBuffer;
+    private readonly fieldBuffer;
+    /** The colour of whatever won the union at each sample, three floats. */
+    private readonly albedoBuffer;
+    /**
+     * Where each cascade stands, as the field's readers see it: moved by a copy encoded after the
+     * composition, never written by the queue. See `cascadeStaged`.
+     */
+    private readonly cascadeBuffer;
+    /**
+     * **This frame's bounds, on their way to `cascadeBuffer`.** A queue write lands when it is made
+     * and an encoded command when its command buffer runs, and a reader of the field — the march in
+     * a contributed pass's `prepare` — is encoded before the composition. Written straight into the
+     * buffer readers bind, the bounds arrived a frame ahead of the samples they describe, and every
+     * frame a cascade stepped the field was read one voxel off. Staged here and copied after the
+     * composition's dispatches, a reader before them sees last frame's bounds with last frame's
+     * samples and a reader after them sees this frame's with this frame's.
+     */
+    private readonly cascadeStaged;
+    /**
+     * The declared sources' samples, grown to fit rather than allocated at the budget.
+     *
+     * **The budget is a ceiling and not a size.** `MAX_DISTANCE_FIELD_SAMPLES` is sixteen megabytes;
+     * a scene with two 33-cubed fields wants two hundred and eighty kilobytes, and a renderer that
+     * reserved the ceiling would charge every consumer for the largest one imaginable. It grows when
+     * a frame declares more than it holds and never shrinks, so a scene that cycles between two sets
+     * of fields settles rather than reallocating.
+     */
+    private sourceBuffer;
+    private sourceFloats;
+    private readonly paramScratch;
+    private readonly cascadeScratch;
+    private readonly instanceScratch;
+    private readonly outerBounds;
+    /** False until a frame has actually composed something, so a reader knows not to trace. */
+    private composed;
+    /**
+     * The device's own clock around the dispatch, where it has one.
+     *
+     * **Moved here from `GiFieldPass` with the dispatch it measures.** A timestamp belongs beside
+     * the work, and this is now the only place the world's field is composed — so the figure a rig
+     * reports is the figure the renderer actually pays rather than a second composition's.
+     */
+    private queries;
+    private queryResolve;
+    private queryRead;
+    private queryCopied;
+    private queryMapping;
+    private timed;
+    private composeMsValue;
+    constructor(device: GPUDevice, options: FieldComposeOptions);
+    /** One bind group a cascade. Rebuilt whenever the source buffer is replaced by a larger one. */
+    private rebuildGroups;
+    /**
+     * Make room for `floats` of samples, replacing the buffer and its bind groups if it is short.
+     *
+     * **Grown to exactly what is asked rather than doubled.** A doubling policy is for something
+     * appended to; this is rewritten whole whenever the packing changes, and the sizes involved are
+     * a scene's whole set of baked fields — a quantity that changes when the world does and not
+     * between frames of a steady one.
+     */
+    private ensureSources;
+    private storage;
+    /** The composed field, or null until a frame has composed one. */
+    get field(): ComposedField | null;
+    /**
+     * Compose every cascade from what the frame declared, centred on the eye.
+     *
+     * One dispatch a cascade rather than one for all of them: each has its own origin and step, and
+     * a single dispatch would carry them in a buffer indexed by the invocation's own cascade — a
+     * divide and a dependent read per thread to save a handful of dispatches.
+     *
+     * **A frame that declared nothing composes nothing and says so.** An empty instance list would
+     * otherwise fill every cascade with the "no surface anywhere" value, which a march reads as an
+     * infinite empty room — a ray that travels its whole reach and reports a miss. That is the right
+     * answer, but it costs a full dispatch to write it and the field it produces was already there.
+     */
+    compose(encoder: GPUCommandEncoder, scene: DistanceFieldScene, eye: ReadonlyVec3): void;
+    /**
+     * The device milliseconds the last measured composition took, or null where nothing measured it.
+     *
+     * One frame behind, because a timestamp is read back and a readback that blocked would be the
+     * measurement changing what it measures.
+     */
+    get composeMs(): number | null;
+    /** Ask for the last frame's figure, once the frame that recorded it has been submitted. */
+    readTimings(): void;
+    dispose(): void;
+}
+/**
+ * The inverse of a rigid transform with a uniform scale, written into `out` at `at`.
+ *
+ * **Not a general inverse**, because `composeGlobalField` refuses anything else: a distance is not
+ * preserved by a non-uniform scale and there is no factor to correct one by. Transposing the
+ * rotation and dividing by the scale squared is exact for what is allowed, and a general inverse
+ * here would be a fourth spelling of a constraint stated three times already.
+ */
+export declare function writeInverse(m: ReadonlyMat4, out: Float32Array, at: number): void;