@driftengine/core 4.9.0 → 4.11.0

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

@@ -52,9 +52,13 @@ const FRAGMENT_BINDINGS = FLAT_BINDINGS.flatFrag;
  */
 const VERTEX_BINDINGS = FLAT_BINDINGS.flatVert;
 /** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
-export function flatVertexKey(skinned, morphed, instanced = false) {
+export function flatVertexKey(skinned, morphed, instanced = false, 
+/** Whether an instanced variant plays a bone animation. See `shaders/boneAnimation.ts`. */
+animated = false) {
     const on = [];
     /* Alphabetical, because the generator's own `variantKey` sorts and the two keys must agree. */
+    if (animated)
+        on.push('animated');
     if (instanced)
         on.push('instanced');
     if (morphed)
@@ -64,8 +68,8 @@ export function flatVertexKey(skinned, morphed, instanced = false) {
     return on.length === 0 ? 'none' : on.join('+');
 }
 /** Everything the generator recorded about one variant of the vertex stage. */
-export function flatVertexBindings(skinned, morphed = false, instanced = false) {
-    const key = flatVertexKey(skinned, morphed, instanced);
+export function flatVertexBindings(skinned, morphed = false, instanced = false, animated = false) {
+    const key = flatVertexKey(skinned, morphed, instanced, animated);
     const found = VERTEX_BINDINGS[key];
     if (found === undefined)
         throw new Error(`flatPass: no vertex bindings for variant "${key}"`);
@@ -136,6 +140,8 @@ for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
     }
 }
 export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
+/** The animated instanced variant's block: the instanced fields, and the clip's `uBoneClip`. */
+export const FLAT_ANIMATED_VERT_FIELDS = FLAT_BINDINGS.flatVert['animated+instanced'].fields;
 /**
  * The **largest** variant's block, because one ring serves every draw.
  *
@@ -145,6 +151,30 @@ export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
  */
 export const FLAT_VERT_SIZE = Math.max(...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.uniformSize));
 const FLAT_VERT_BINDING = PLAIN_VERTEX.uniforms;
+/*
+ * **The view block may be shorter in a variant, never different.** One slot serves every lit draw
+ * of a pass, plain and instanced alike, so every field a variant's view block declares must sit
+ * where the plain variant has it. The instanced variant declares no wind, and its block is the plain
+ * one's first two matrices.
+ */
+const PLAIN_VIEW_FIELDS = PLAIN_VERTEX.viewFields ?? {};
+for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
+    if (bindings.viewUniforms !== PLAIN_VERTEX.viewUniforms) {
+        throw new Error(`flatPass: vertex variant "${key}" binds its view block elsewhere`);
+    }
+    for (const [field, here] of Object.entries(bindings.viewFields ?? {})) {
+        if (PLAIN_VIEW_FIELDS[field]?.offset !== here.offset) {
+            throw new Error(`flatPass: vertex variant "${key}" puts view field ${field} at ${here.offset} where the ` +
+                `plain variant has it at ${PLAIN_VIEW_FIELDS[field]?.offset}.`);
+        }
+    }
+}
+/** The view block's fields, binding and size: the largest variant's, as `FLAT_VERT_SIZE` is. */
+export const FLAT_VIEW_FIELDS = PLAIN_VIEW_FIELDS;
+export const FLAT_VIEW_SIZE = Math.max(...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.viewSize ?? 0));
+const FLAT_VIEW_BINDING = PLAIN_VERTEX.viewUniforms ?? -1;
+if (FLAT_VIEW_BINDING < 0)
+    throw new Error('flatPass: the lit vertex stage declares no view block');
 /**
  * The most sampled textures and distinct samplers any lit variant carrying the environment probe
  * binds in its fragment stage, counted from the generated bindings: what a device must allow per
@@ -170,6 +200,26 @@ export function flatFragmentBindings(variant) {
         throw new Error(`flatPass: no bindings for variant "${variant}"`);
     return found;
 }
+export function flatFragmentScratch(variant) {
+    const bindings = flatFragmentBindings(variant);
+    const { materialUniforms, materialSize, materialFields } = bindings;
+    if (materialUniforms === undefined ||
+        materialSize === undefined ||
+        materialFields === undefined) {
+        throw new Error(`flatPass: variant "${variant}" has no material block`);
+    }
+    const fields = { ...bindings.fields };
+    for (const [name, field] of Object.entries(materialFields)) {
+        fields[name] = { ...field, offset: bindings.uniformSize + field.offset };
+    }
+    return {
+        fields,
+        passSize: bindings.uniformSize,
+        passBinding: bindings.uniforms,
+        materialSize,
+        materialBinding: materialUniforms,
+    };
+}
 /**
  * The lit fragment stage's constants, set from the cache's switches, keyed by each one's **id**.
  *
@@ -209,6 +259,13 @@ function flatFragmentConstants(variant, cache, model, skinPass = 'whole', reflec
     }
     return constants;
 }
+/** The material block's binding, which every lit variant declares. */
+function materialBinding(fragment) {
+    if (fragment.materialUniforms === undefined) {
+        throw new Error('flatPass: the lit fragment stage declares no material block');
+    }
+    return fragment.materialUniforms;
+}
 /** The depth format both backends compare with. */
 /* Re-exported so the twenty passes that already import it from here do not each learn a new
    module; `depthConvention.ts` is where the decision lives and why. */
@@ -218,11 +275,15 @@ const VISIBILITY_FRAGMENT = 0x2;
 /**
  * The layout this variant binds against.
  *
- * The vertex block is **dynamic**, because every draw supplies its own model matrix and tint
- * from its own slot of one buffer. The fragment block is not: it holds the lights, the fog
- * and the camera, settled once by `bindMeshPass` and unchanged between draws.
+ * All four blocks are **dynamic**: the vertex block because every draw supplies its own model
+ * matrix and tint from its own slot of one buffer; the fragment stage's pass block — the lights, the
+ * fog, the camera — and the vertex stage's view block because a frame binds more than one pass; and
+ * the material block because a material changes between draws. Their dynamic offsets go in binding
+ * order: the draw's, the pass's, the material's, the view's.
  */
-export function createFlatBindGroupLayout(device, variant, skinned = false, morphed = false) {
+export function createFlatBindGroupLayout(device, variant, skinned = false, morphed = false, 
+/** The instanced variant that plays a bone animation: its three vertex textures. */
+animated = false) {
     const fragment = flatFragmentBindings(variant);
     const entries = [
         {
@@ -230,15 +291,31 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
             visibility: VISIBILITY_VERTEX,
             buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VERT_SIZE },
         },
+        {
+            binding: FLAT_VIEW_BINDING,
+            visibility: VISIBILITY_VERTEX,
+            /* Dynamic, a slot a pass, for the reason the fragment stage's pass block is. */
+            buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VIEW_SIZE },
+        },
         {
             binding: fragment.uniforms,
             visibility: VISIBILITY_FRAGMENT,
             /*
-             * Dynamic, because this block carries the material and a material changes between draws.
-             * See `WebGPURenderer.perFrame` for why one buffer cannot hold two answers.
+             * Dynamic, because a pass's lights and camera change between passes of one frame — a
+             * mirror's, a capture's — and one buffer cannot hold two answers. See `WebGPURenderer.passRing`.
              */
             buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: fragment.uniformSize },
         },
+        {
+            binding: materialBinding(fragment),
+            visibility: VISIBILITY_FRAGMENT,
+            /* Dynamic, because a material changes between draws. See `MaterialStore`. */
+            buffer: {
+                type: 'uniform',
+                hasDynamicOffset: true,
+                minBindingSize: fragment.materialSize ?? 0,
+            },
+        },
     ];
     /** What each sampler binding was declared as, so a shared one is declared once and agrees. */
     const samplerKind = new Map();
@@ -379,11 +456,33 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
             });
         }
     }
+    /* A bone animation's places, turns and the batch's clocks, read by index as the palette is. */
+    if (animated) {
+        for (const binding of animationBindings()) {
+            entries.push({
+                binding,
+                visibility: VISIBILITY_VERTEX,
+                texture: { sampleType: 'unfilterable-float' },
+            });
+        }
+    }
     return device.createBindGroupLayout({
-        label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed)}`,
+        label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed, animated, animated)}`,
         entries,
     });
 }
+/** The three textures a bone animation binds, in the order `AnimationViews` holds them. */
+function animationBindings() {
+    const textures = flatVertexBindings(false, false, true, true).textures;
+    const at = (name) => {
+        const found = textures[name];
+        if (found === undefined) {
+            throw new Error(`flatPass: the animated vertex shader declares no ${name}`);
+        }
+        return found.texture;
+    };
+    return [at('uBonePlaces'), at('uBoneTurns'), at('uInstanceClocks')];
+}
 /**
  * Bind the buffers and one view per declared texture.
  *
@@ -393,20 +492,27 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
-export function createFlatBindGroup(device, layout, variant, perDraw, perFrame, resolve, 
+export function createFlatBindGroup(device, layout, variant, perDraw, passes, materials, views, resolve, 
 /** The palette view for a skinned bind group, or null for an unskinned one. */
 palette = null, 
 /** The delta view for a morphed bind group, or null for an unmorphed one. */
 deltas = null, 
 /** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
-cloth = null) {
+cloth = null, 
+/** An animated instanced group's views. See `AnimationViews`. */
+animation = null) {
     const fragment = flatFragmentBindings(variant);
     const entries = [
         {
             binding: FLAT_VERT_BINDING,
             resource: { buffer: perDraw, size: FLAT_VERT_SIZE },
         },
-        { binding: fragment.uniforms, resource: { buffer: perFrame, size: fragment.uniformSize } },
+        { binding: FLAT_VIEW_BINDING, resource: { buffer: views, size: FLAT_VIEW_SIZE } },
+        { binding: fragment.uniforms, resource: { buffer: passes, size: fragment.uniformSize } },
+        {
+            binding: materialBinding(fragment),
+            resource: { buffer: materials, size: fragment.materialSize ?? 0 },
+        },
     ];
     /* The same dedupe the layout does, and for the same reason: the shadow bindings share one
        sampler, and a bind group that filled it fifteen times would be rejected. Every member
@@ -441,8 +547,14 @@ cloth = null) {
         entries.push({ binding: particlesAt, resource: cloth.particles });
         entries.push({ binding: restAt, resource: cloth.rest });
     }
+    if (animation !== null) {
+        const [places, turns, clocks] = animationBindings();
+        entries.push({ binding: places, resource: animation.places });
+        entries.push({ binding: turns, resource: animation.turns });
+        entries.push({ binding: clocks, resource: animation.clocks });
+    }
     return device.createBindGroup({
-        label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null)}`,
+        label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null, animation !== null, animation !== null)}`,
         layout,
         entries,
     });
@@ -510,8 +622,11 @@ skinPass = 'whole',
  * The reflection pass's surface half: the draw again, against its own depth, into the two
  * targets `reflectionSurfacePass.ts` holds. The key must carry it: `|rs`.
  */
-reflectionSurface = false) {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass, reflectionSurface), true);
+reflectionSurface = false, 
+/** An instanced pipeline that plays a bone animation. The key must carry it: `|anim`. */
+animated = false) {
+    /* None where draws skip a compile and this one has not landed: see `PipelineCache.lit`. */
+    return cache.lit(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass, reflectionSurface, animated));
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -591,7 +706,9 @@ oit = 'none',
 /** Culls nothing: a surface seen from both faces. */
 doubleSided = false, alphaToCoverage = false, skinEight = false, 
 /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
-cloth = false, model = null, skinPass = 'whole', reflectionSurface = false) {
+cloth = false, model = null, skinPass = 'whole', reflectionSurface = false, 
+/** An instanced pipeline that plays a bone animation. See `shaders/boneAnimation.ts`. */
+animated = false) {
     const offset = depthOffsetForLayer(depthLayer);
     /* The diffuse and colour halves are the same surface again, into the blur's targets; and so is
        the reflection pass's surface half, into its two. */
@@ -606,12 +723,12 @@ cloth = false, model = null, skinPass = 'whole', reflectionSurface = false) {
              * layout validates, draws, and is wrong, exactly as this file's header says.
              */
             module: shaderModule(device, {
-                label: `flat.vert:${flatVertexKey(skinned, morphed, instanced)}`,
-                code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced)] ?? '',
+                label: `flat.vert:${flatVertexKey(skinned, morphed, instanced, animated)}`,
+                code: FLAT_VERT_WGSL[flatVertexKey(skinned, morphed, instanced, animated)] ?? '',
             }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
-            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced), skinEight, cloth, model === 'lightmap'),
+            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced, animated), skinEight, cloth, model === 'lightmap'),
         },
         fragment: {
             module: shaderModule(device, {

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

@@ -0,0 +1,80 @@
+import type { SkinnedClothSetup } from '@driftengine/physics';
+import { GpuClothParticles } from './clothTextures.ts';
+export declare class GpuClothSet {
+    private readonly device;
+    private readonly garments;
+    private readonly packed;
+    private readonly kernels;
+    private readonly buffers;
+    private readonly state;
+    private readonly frameData;
+    private readonly paces;
+    private readonly group;
+    /** One round's records, every garment's: the head an op's, the rest each garment's own. */
+    private readonly staging;
+    private readonly stagingWords;
+    private readonly stagingFloats;
+    /** Each kind's first batch slot, and the first garment's publishing slot. */
+    private readonly batchSlot;
+    private readonly groups;
+    private readonly substeps;
+    private readonly iterations;
+    private encoder;
+    private pass;
+    private round;
+    constructor(device: GPUDevice, setups: readonly SkinnedClothSetup[]);
+    /** How many garments the set holds. */
+    get size(): number;
+    /** Garment `g`'s particles, what `setCloth` draws its bound meshes by. */
+    particles(g: number): GpuClothParticles;
+    /** Garment `g`'s rig for the steps to come; see `ClothControl.setPose`. */
+    setPose(g: number, globals: Float32Array, model: Float32Array): void;
+    /** The frame's sample of the scene's wind for garment `g`. See `SkinnedCloth.setWind`. */
+    setWind(g: number, x: number, y: number, z: number): void;
+    /** Garment `g` back to its skinned pose, settled; the next `step` publishes it. */
+    reset(g: number): void;
+    /**
+     * `dt` of the caller's time in whole fixed steps for every garment, and each garment's particles
+     * at its `alpha` published for the draws that follow, as the particles of `frame`.
+     */
+    step(dt: number, frame: number): void;
+    /**
+     * Garment `g`'s particles where its last step left them, three floats each: for the parity check,
+     * which compares them with the CPU solver's positions. Not for a frame — it waits on the device.
+     */
+    read(g: number): Promise<Float32Array>;
+    /** Its buffers; the particle textures are the renderer's to retire with the frame. */
+    dispose(): void;
+    private at;
+    /** Garment `g`: its schedule over a device that queues, its particles and its own numbers. */
+    private garment;
+    /**
+     * A garment's own words of its record, which every round carries: its colliders, its texture's
+     * width and its constants. Its limits ride in the head beside `live`, written as it joins a round.
+     */
+    private writeOwn;
+    /** Garments that cannot step together, refused by the first number they disagree on. */
+    private refuseStrangers;
+    private targetsChanged;
+    private queueOp;
+    private queueStep;
+    /** Every op every garment is waiting on, a round of one kind at a time, in each garment's order. */
+    private run;
+    /** Whether any garment has `kind` next. */
+    private waiting;
+    /** One round: every garment with `kind` next takes part, and the rest sit it out. */
+    private runRound;
+    private stepRound;
+    /** Every colour of one kind across the set, in colour order, each a dispatch over its range. */
+    private batches;
+    private dispatch;
+    private passFor;
+    /** A round's slot, sending what is recorded first where the slots are spent: its byte offset. */
+    private takeRound;
+    /** Where the records of the round at `roundAt` sit in `paces`. */
+    private paceOffset;
+    /** Send what has been recorded: every slot it reads was written ahead of it on the queue. */
+    private flush;
+    /** A garment's skin matrices — or its model, with no rig — and its colliders, into the set's. */
+    private writeFrameData;
+}