@driftengine/core 4.8.2 → 4.8.4

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

@@ -0,0 +1,452 @@
+/**
+ * A skinned cloth solved on the device: `ClothControl`'s schedule, over buffers rather than arrays.
+ *
+ * **The CPU solver's steps, as dispatches.** A step is `clothBegin`, then per substep
+ * `clothPredict`, every batch of every kind of constraint per iteration, `clothLimit` and
+ * `clothFinish`; then `clothBlend` while a reset blends back in. The particles never leave the
+ * device: a frame ends with `clothPublish` writing them, at the frame's `alpha`, into the particle
+ * texture the bound mesh's vertex stage reads — so a garment costs no upload a frame at all.
+ *
+ * **One submit a frame, everything it needs written before it.** `queue.writeBuffer` lands ahead of
+ * the whole submit rather than between two dispatches, which is the trap `AGENTS.md` (2026-08-27)
+ * records for draws and is no different for dispatches. So every step takes a slot of its own, at a
+ * dynamic offset, and the batches' ranges are slots written once; a frame that runs out of slots
+ * submits what it has first and goes on, and so does a pose, whose matrices are one buffer.
+ *
+ * **What it gives up**: single precision, and a dispatch per batch — a garment of nine colours and
+ * four iterations is about forty dispatches a step, which is cheap on a desktop part and is what the
+ * budget in `demo/dev/skinnedCloth.html` measures. Self-collision is accepted and not simulated, as on
+ * the CPU.
+ */
+import { ClothControl, exactExp, validateClothSetup } from '@driftengine/physics';
+import { packCloth } from './clothSolvePack.js';
+import { GpuClothParticles } from './clothTextures.js';
+import { CLOTH_SOLVE_WGSL, CLOTH_WORKGROUP } from './shaders/clothSolve.wgsl.js';
+import { shaderModule } from './shaderModules.js';
+import { DYNAMIC_ALIGNMENT } from './uniformRing.js';
+const STORAGE = 0x80;
+const UNIFORM = 0x40;
+const COPY_DST = 0x8;
+const COPY_SRC = 0x4;
+const MAP_READ = 0x1;
+const COMPUTE = 0x4;
+/** Step slots a submit holds before it is sent and the ring starts again. */
+const STEP_SLOTS = 64;
+/** Floats in a step's slot that are written: see `Step` in the shader. */
+const STEP_FLOATS = 32;
+const CONSTANT_BYTES = 80;
+const ENTRIES = [
+    'clothPose',
+    'clothRest',
+    'clothBegin',
+    'clothPredict',
+    'clothDistance',
+    'clothBending',
+    'clothTether',
+    'clothLimit',
+    'clothFinish',
+    'clothBlend',
+    'clothPublish',
+];
+const kernelsByDevice = new WeakMap();
+function kernelsFor(device) {
+    const held = kernelsByDevice.get(device);
+    if (held !== undefined)
+        return held;
+    const uniform = (binding, dynamic) => ({
+        binding,
+        visibility: COMPUTE,
+        buffer: { type: 'uniform', hasDynamicOffset: dynamic },
+    });
+    const storage = (binding, type) => ({
+        binding,
+        visibility: COMPUTE,
+        buffer: { type },
+    });
+    const layout = device.createBindGroupLayout({
+        label: 'cloth.solve',
+        entries: [
+            uniform(0, false),
+            uniform(1, true),
+            uniform(2, true),
+            storage(3, 'storage'),
+            storage(4, 'storage'),
+            storage(5, 'read-only-storage'),
+            storage(6, 'read-only-storage'),
+            storage(7, 'storage'),
+            storage(8, 'read-only-storage'),
+        ],
+    });
+    const outputLayout = device.createBindGroupLayout({
+        label: 'cloth.publish',
+        entries: [
+            {
+                binding: 0,
+                visibility: COMPUTE,
+                storageTexture: { access: 'write-only', format: 'rgba32float' },
+            },
+        ],
+    });
+    const module = shaderModule(device, { label: 'cloth.solve', code: CLOTH_SOLVE_WGSL });
+    const solve = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+    const publish = device.createPipelineLayout({ bindGroupLayouts: [layout, outputLayout] });
+    const pipelines = {};
+    for (const entry of ENTRIES) {
+        pipelines[entry] = device.createComputePipeline({
+            label: `cloth.${entry}`,
+            layout: entry === 'clothPublish' ? publish : solve,
+            compute: { module, entryPoint: entry },
+        });
+    }
+    const kernels = { layout, outputLayout, pipelines };
+    kernelsByDevice.set(device, kernels);
+    return kernels;
+}
+/** One garment's solver on the device, and the particle textures it publishes into. */
+export class GpuSkinnedCloth {
+    device;
+    /** The particles a bound mesh draws by: see `RendererApi.setCloth`. */
+    particles;
+    count;
+    control;
+    packed;
+    kernels;
+    buffers = [];
+    state;
+    frameData;
+    stepSlots;
+    group;
+    outputs;
+    frameStaging;
+    stepStaging = new ArrayBuffer(STEP_FLOATS * 4);
+    stepFloats = new Float32Array(this.stepStaging);
+    stepWords = new Uint32Array(this.stepStaging);
+    /** Each batch's slot, by kind and by whether it opens a substep's iterations. */
+    batchSlot;
+    /** The air the steps drag toward: the set-up's until `setWind`, written into every step. */
+    wind = new Float32Array(3);
+    groups;
+    substeps;
+    iterations;
+    encoder = null;
+    pass = null;
+    slot = 0;
+    /** Where the pose a step starts from and the one it moves toward sit in `pose`, in floats. */
+    fromAt = 0;
+    toAt = 0;
+    constructor(device, setup) {
+        this.device = device;
+        validateClothSetup(setup);
+        const packed = packCloth(setup);
+        this.packed = packed;
+        const n = packed.count;
+        this.count = n;
+        this.kernels = kernelsFor(device);
+        this.particles = new GpuClothParticles(device, n, true);
+        this.groups = Math.ceil(n / CLOTH_WORKGROUP);
+        const solver = {
+            targetsChanged: (change) => {
+                this.targetsChanged(change);
+            },
+            rest: () => {
+                this.rest();
+            },
+            step: (fraction, blend) => {
+                this.step(fraction, blend);
+            },
+        };
+        this.control = new ClothControl(setup, solver, false);
+        const parameters = this.control.parameters;
+        this.wind.set(parameters.wind);
+        this.substeps = parameters.substeps;
+        this.iterations = parameters.iterations;
+        const buffer = (label, bytes, usage) => {
+            const made = device.createBuffer({
+                label: `cloth.${label}`,
+                size: Math.max(16, bytes),
+                usage,
+            });
+            this.buffers.push(made);
+            return made;
+        };
+        const constants = buffer('constants', CONSTANT_BYTES, UNIFORM | COPY_DST);
+        this.stepSlots = buffer('steps', STEP_SLOTS * DYNAMIC_ALIGNMENT, UNIFORM | COPY_DST);
+        const batchFloats = this.writeBatches();
+        const batches = buffer('batches', batchFloats.byteLength, UNIFORM | COPY_DST);
+        this.state = buffer('state', n * 12 * 4, STORAGE | COPY_DST | COPY_SRC);
+        const pose = buffer('pose', n * 9 * 4, STORAGE);
+        const statics = buffer('statics', packed.statics.byteLength, STORAGE | COPY_DST);
+        const constraints = buffer('constraints', packed.constraints.byteLength, STORAGE | COPY_DST);
+        const lambda = buffer('lambda', (packed.distances + packed.bendings) * 4, STORAGE);
+        this.frameStaging = new Float32Array(packed.joints * 16 + packed.colliders * 8);
+        this.frameData = buffer('frame', this.frameStaging.byteLength, STORAGE | COPY_DST);
+        const queue = device.queue;
+        queue.writeBuffer(constants, 0, this.constants());
+        queue.writeBuffer(batches, 0, batchFloats);
+        queue.writeBuffer(statics, 0, packed.statics);
+        if (packed.constraints.byteLength > 0) {
+            queue.writeBuffer(constraints, 0, packed.constraints);
+        }
+        /* The rest pose until the first `setPose`, which resets the cloth to its own. */
+        const state = new Float32Array(n * 12);
+        state.set(setup.positions, 0);
+        state.set(setup.positions, n * 9);
+        queue.writeBuffer(this.state, 0, state);
+        const slot = (bufferOf) => ({
+            buffer: bufferOf,
+            size: DYNAMIC_ALIGNMENT,
+        });
+        this.group = device.createBindGroup({
+            label: 'cloth.solve',
+            layout: this.kernels.layout,
+            entries: [
+                { binding: 0, resource: { buffer: constants } },
+                { binding: 1, resource: slot(this.stepSlots) },
+                { binding: 2, resource: slot(batches) },
+                { binding: 3, resource: { buffer: this.state } },
+                { binding: 4, resource: { buffer: pose } },
+                { binding: 5, resource: { buffer: statics } },
+                { binding: 6, resource: { buffer: constraints } },
+                { binding: 7, resource: { buffer: lambda } },
+                { binding: 8, resource: { buffer: this.frameData } },
+            ],
+        });
+        const output = (k) => device.createBindGroup({
+            label: 'cloth.publish',
+            layout: this.kernels.outputLayout,
+            entries: [{ binding: 0, resource: this.particles.viewOf(k) }],
+        });
+        this.outputs = [output(0), output(1)];
+        this.batchSlot = {
+            distance: 0,
+            bending: (packed.distanceBatches.length - 1) * 2,
+            tether: (packed.distanceBatches.length - 1 + packed.bendingBatches.length - 1) * 2,
+        };
+    }
+    /**
+     * One frame: the rig's pose, `dt` of the caller's time in whole fixed steps, and the particles at
+     * the frame's `alpha` published for the draws that follow, as the particles of `frame`.
+     */
+    advance(globals, model, dt, frame) {
+        this.control.setPose(globals, model);
+        this.control.advance(dt);
+        const view = this.particles.publish(frame);
+        this.dispatch('clothPublish', this.takeSlot(0, 0, this.control.alpha, null), 0, view);
+        this.flush();
+    }
+    /** The frame's sample of the scene's wind, for the steps to come. See `SkinnedCloth.setWind`. */
+    setWind(x, y, z) {
+        this.wind[0] = x;
+        this.wind[1] = y;
+        this.wind[2] = z;
+    }
+    /** Back to the skinned pose, settled; the next `advance` publishes it. */
+    reset() {
+        this.control.reset();
+    }
+    /**
+     * The particles where the last step left them, read back: for the parity check, which compares
+     * them with the CPU solver's. Not for a frame — it waits on the device.
+     */
+    async read() {
+        this.flush();
+        const bytes = this.count * 12;
+        const readback = this.device.createBuffer({
+            label: 'cloth.readback',
+            size: bytes,
+            usage: MAP_READ | COPY_DST,
+        });
+        const encoder = this.device.createCommandEncoder({ label: 'cloth.read' });
+        encoder.copyBufferToBuffer(this.state, 0, readback, 0, bytes);
+        this.device.queue.submit([encoder.finish()]);
+        await readback.mapAsync(MAP_READ);
+        const out = new Float32Array(readback.getMappedRange().slice(0));
+        readback.unmap();
+        readback.destroy();
+        return out;
+    }
+    /** Its buffers; the particle textures are the renderer's to retire with the frame. */
+    dispose() {
+        this.flush();
+        for (const made of this.buffers)
+            made.destroy();
+    }
+    targetsChanged(change) {
+        if (change !== 'posed') {
+            this.fromAt = this.toAt;
+            return;
+        }
+        /*
+         * The pose's matrices and colliders are written ahead of the next submit, so anything already
+         * recorded — a reset's settle steps, which read the colliders — is sent first, or it would run
+         * against this pose rather than its own.
+         */
+        this.flush();
+        this.writeFrameData();
+        this.fromAt = this.toAt;
+        this.toAt = this.toAt === 0 ? this.count * 3 : 0;
+        this.dispatch('clothPose', this.takeSlot(0, 0, 0, null), 0, -1);
+    }
+    rest() {
+        this.dispatch('clothRest', this.takeSlot(1, 0, 0, null), 0, -1);
+    }
+    step(fraction, blend) {
+        const at = this.takeSlot(fraction, blend, 0, this.control.targets);
+        this.dispatch('clothBegin', at, 0, -1);
+        const { distanceBatches, bendingBatches, tetherBatches } = this.packed;
+        for (let s = 0; s < this.substeps; s++) {
+            this.dispatch('clothPredict', at, 0, -1);
+            for (let pass = 0; pass < this.iterations; pass++) {
+                const first = pass === 0 ? 1 : 0;
+                this.batches('clothDistance', distanceBatches, this.batchSlot.distance, first, at);
+                this.batches('clothBending', bendingBatches, this.batchSlot.bending, first, at);
+                this.batches('clothTether', tetherBatches, this.batchSlot.tether, first, at);
+            }
+            this.dispatch('clothLimit', at, 0, -1);
+            this.dispatch('clothFinish', at, 0, -1);
+        }
+        if (blend > 0)
+            this.dispatch('clothBlend', at, 0, -1);
+    }
+    /** Every batch of one kind, in colour order, each a dispatch over its range. */
+    batches(entry, batches, firstSlot, first, stepAt) {
+        for (let b = 0; b + 1 < batches.length; b++) {
+            const size = batches[b + 1] - batches[b];
+            if (size === 0)
+                continue;
+            const slot = firstSlot + b * 2 + first;
+            this.dispatch(entry, stepAt, slot * DYNAMIC_ALIGNMENT, -1, Math.ceil(size / CLOTH_WORKGROUP));
+        }
+    }
+    dispatch(entry, stepAt, batchAt, output, groups = this.groups) {
+        const pass = this.passFor();
+        pass.setPipeline(this.kernels.pipelines[entry]);
+        pass.setBindGroup(0, this.group, [stepAt, batchAt]);
+        if (output >= 0)
+            pass.setBindGroup(1, this.outputs[output]);
+        pass.dispatchWorkgroups(groups);
+    }
+    passFor() {
+        if (this.pass === null) {
+            this.encoder = this.device.createCommandEncoder({ label: 'cloth' });
+            this.pass = this.encoder.beginComputePass({ label: 'cloth' });
+        }
+        return this.pass;
+    }
+    /** Send what has been recorded: every slot it reads was written ahead of it on the queue. */
+    flush() {
+        const { pass, encoder } = this;
+        if (pass === null || encoder === null)
+            return;
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        this.pass = null;
+        this.encoder = null;
+        this.slot = 0;
+    }
+    /**
+     * A step's slot: its fraction, blend and alpha, the poses it reads, and — where `targets` is
+     * given — the share of the character's motion the cloth is carried by, as `carryParticles` takes
+     * it. Returns the slot's byte offset.
+     */
+    takeSlot(fraction, blend, alpha, targets) {
+        if (this.slot === STEP_SLOTS)
+            this.flush();
+        const f = this.stepFloats;
+        const u = this.stepWords;
+        f.fill(0);
+        f[0] = fraction;
+        f[1] = blend;
+        f[2] = alpha;
+        u[4] = this.fromAt;
+        u[5] = this.toAt;
+        f.set(this.wind, 28);
+        if (targets !== null)
+            this.writeCarry(targets.modelBefore, targets.modelNow);
+        const at = this.slot * DYNAMIC_ALIGNMENT;
+        this.device.queue.writeBuffer(this.stepSlots, at, this.stepStaging);
+        this.slot++;
+        return at;
+    }
+    /** `carryParticles`' rotation, origin and move, into the step's slot; carry 0 where none. */
+    writeCarry(previous, next) {
+        const { linearInertia, angularInertia } = this.control.parameters;
+        const turn = 1 - angularInertia;
+        const move = 1 - linearInertia;
+        if (turn === 0 && move === 0)
+            return;
+        const f = this.stepFloats;
+        this.stepWords[3] = 1;
+        /* Column c of R = R_next × R_previousᵀ, at turn0 … turn2. */
+        for (let col = 0; col < 3; col++) {
+            for (let row = 0; row < 3; row++) {
+                let sum = 0;
+                for (let k = 0; k < 3; k++) {
+                    sum += next[k * 4 + row] * previous[k * 4 + col];
+                }
+                f[8 + col * 4 + row] = sum;
+            }
+        }
+        for (let k = 0; k < 3; k++) {
+            f[20 + k] = previous[12 + k];
+            f[24 + k] = (next[12 + k] - previous[12 + k]) * move;
+        }
+        f[23] = turn;
+    }
+    /** The pose's skin matrices — or the model, for a cloth with no rig — and its colliders. */
+    writeFrameData() {
+        const targets = this.control.targets;
+        const out = this.frameStaging;
+        const joints = this.packed.joints;
+        out.set(this.packed.rigged && targets.skin !== null ? targets.skin : targets.model, 0);
+        const colliders = this.packed.colliders;
+        out.set(targets.colliderEnds, joints * 16);
+        out.set(targets.colliderRadii, joints * 16 + colliders * 6);
+        if (out.byteLength > 0)
+            this.device.queue.writeBuffer(this.frameData, 0, out);
+    }
+    constants() {
+        const p = this.control.parameters;
+        const packed = this.packed;
+        const bytes = new ArrayBuffer(CONSTANT_BYTES);
+        const u = new Uint32Array(bytes);
+        const f = new Float32Array(bytes);
+        const h = p.step / p.substeps;
+        u[0] = packed.count;
+        u[1] = packed.distances;
+        u[2] = packed.bendings;
+        u[3] = packed.joints;
+        u[4] = packed.colliders;
+        u[5] = packed.limits;
+        u[6] = this.particles.width;
+        f[8] = h;
+        f[9] = 1 / h;
+        f[10] = 1 / (h * h);
+        f[11] = exactExp(p.damping * h);
+        f[12] = exactExp(p.drag * h);
+        f[13] = p.maxDistanceScale;
+        f[14] = p.margin;
+        f.set(p.gravity, 16);
+        return bytes;
+    }
+    /** Each batch's range, twice — opening a substep's iterations and not — at a slot each. */
+    writeBatches() {
+        const { distanceBatches, bendingBatches, tetherBatches } = this.packed;
+        const kinds = [distanceBatches, bendingBatches, tetherBatches];
+        const slots = kinds.reduce((sum, batches) => sum + (batches.length - 1) * 2, 0);
+        const words = new Uint32Array((Math.max(1, slots) * DYNAMIC_ALIGNMENT) / 4);
+        let slot = 0;
+        for (const batches of kinds) {
+            for (let b = 0; b + 1 < batches.length; b++) {
+                for (let first = 0; first < 2; first++) {
+                    const at = (slot * DYNAMIC_ALIGNMENT) / 4;
+                    words[at] = batches[b];
+                    words[at + 1] = batches[b + 1];
+                    words[at + 2] = first;
+                    slot++;
+                }
+            }
+        }
+        return words;
+    }
+}

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

@@ -3,6 +3,7 @@ import { LINE_BINDINGS, LINE_FRAG_WGSL, LINE_VERT_WGSL, } from '../../shaders/ge
 import { buildSegmentQuads } from '../../segmentQuads.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The line pass: a polyline with a real width, four vertices a segment.
  *
@@ -179,7 +180,7 @@ additive = false) {
                                 dstFactor: 'one-minus-src-alpha',
                                 operation: 'add',
                             },
-                            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                            alpha: SCENE_ALPHA_COVERS,
                         },
                 },
             ],

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

@@ -11,6 +11,19 @@ export declare class MotionPass {
     /** A skinned record's two palettes, this frame's and last frame's, by record index. */
     private readonly paletteNow;
     private readonly paletteWas;
+    /** A cloth record's binding and its particles now and last frame, by record index. */
+    private readonly clothBinding;
+    private readonly clothNow;
+    private readonly clothWas;
+    private clothLayout;
+    private clothPipelineLayout;
+    /** Keyed as `skinnedPipelines` is. */
+    private readonly clothPipelines;
+    /**
+     * A bind group per particles now, particles then and binding. Weak at the top, by this frame's
+     * particles, so a character's groups go when its particles do; a steady garment settles on three.
+     */
+    private clothGroups;
     /** A rewritten record's last-frame rows, by record index. */
     private readonly previousRows;
     /** One pipeline per stride for rewritten meshes: current and previous rows at that stride. */
@@ -48,6 +61,11 @@ export declare class MotionPass {
     recordRigid(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>): void;
     /** A skinned mover: its positions under last frame's pose as well as last frame's model. */
     recordSkinned(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>, palette: GPUTextureView, previousPalette: GPUTextureView): void;
+    /**
+     * A cloth-bound skinned draw: its skinned positions under both poses, each carried toward the
+     * cloth by its painted weight — this frame's `particles` and last frame's `previousParticles`.
+     */
+    recordCloth(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>, palette: GPUTextureView, previousPalette: GPUTextureView, binding: GPUTextureView, particles: GPUTextureView, previousParticles: GPUTextureView): void;
     /** A rewritten mesh: its vertices as they were, read from `previous`, under last frame's model. */
     recordDynamic(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>, previous: GPUBuffer): void;
     /** An instanced batch: its first `count` slots, each under last frame's placement of that slot. */
@@ -77,6 +95,8 @@ export declare class MotionPass {
     private instancedPipelineFor;
     /** The bind group holding one pair of palettes, built the first time the pair is seen. */
     private paletteGroup;
+    /** The bind group holding a cloth's binding and its two particle textures, built on first sight. */
+    private clothGroup;
     /** The pipeline for one vertex stride, built on first sight of it. */
     private pipelineFor;
     /**