@driftengine/core 4.8.2 → 4.8.4

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

@@ -10,8 +10,12 @@
  * replays them, which is what turns migrating twenty-three verbs into twenty-three call-site
  * edits rather than twenty-three implementations.
  */
-/** The most vertex buffers any verb on this backend binds is three. Four leaves a margin. */
-const VERTEX_BUFFER_SLOTS = 4;
+/**
+ * WebGPU's guaranteed `maxVertexBuffers`, so no verb can outgrow it. The most any binds is five — a
+ * dynamic mesh's positions, normals, rows and constants, and an instanced batch's placements — and
+ * this said three, then four, while text and bolts already bound four.
+ */
+const VERTEX_BUFFER_SLOTS = 8;
 function emptyCommand() {
     return {
         pipeline: null,

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

@@ -3,6 +3,7 @@ import { FILM_BINDINGS, FILM_FRAG_WGSL, FILM_VERT_WGSL, } from '../../shaders/ge
 import { vertexBufferLayouts } from './buffers.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.js';
 /**
  * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
  *
@@ -85,7 +86,7 @@ export function filmPipeline(cache, device, layout, key, present) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_KEEPS,
                     },
                 },
             ],

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

@@ -1,4 +1,7 @@
+import type { SurfaceModelKind } from '../../surfaceModel.ts';
+import type { SkinHalf } from '../../shaders/flat/models.ts';
 import type { PipelineCache } from './pipelineCache.ts';
+import type { ClothViews } from './clothTextures.ts';
 /**
  * The flat pipeline: the shader that draws the world.
  *
@@ -65,6 +68,13 @@ export interface StageBindings {
 export declare function flatVertexKey(skinned: boolean, morphed: boolean, instanced?: boolean): string;
 /** Everything the generator recorded about one variant of the vertex stage. */
 export declare function flatVertexBindings(skinned: boolean, morphed?: boolean, instanced?: boolean): StageBindings;
+/**
+ * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` in
+ * a skinned stage, nothing in any other. Every override a stage declares is set, and one this does
+ * not know is refused here rather than defaulted. Shared with the shadow and glass-tint casters,
+ * whose skinned stages declare the same switch.
+ */
+export declare function vertexConstants(bindings: StageBindings, skinEight: boolean, cloth?: boolean): Record<string, number>;
 export declare const FLAT_VERT_FIELDS: {
     readonly uViewProj: {
         readonly offset: 0;
@@ -86,6 +96,11 @@ export declare const FLAT_VERT_FIELDS: {
         readonly size: 8;
         readonly type: "vec2";
     };
+    readonly uUvOffset: {
+        readonly offset: 152;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
     readonly uModel: {
         readonly offset: 160;
         readonly size: 64;
@@ -147,7 +162,7 @@ export declare function createFlatBindGroupLayout(device: GPUDevice, variant: Fl
  *
  * `resolve` is asked for a view by the shader's own name for it, so a caller supplies the
  * shadow maps it has and a stand-in for the rest. **Every declared binding must be filled
- * even when the shader never samples it** — `uAlbedoEnabled` is zero for nearly all geometry
+ * even when the shader never samples it** — the albedo's flag is zero for nearly all geometry
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
@@ -158,7 +173,9 @@ export declare function createFlatBindGroup(device: GPUDevice, layout: GPUBindGr
 /** The palette view for a skinned bind group, or null for an unskinned one. */
 palette?: GPUTextureView | null, 
 /** The delta view for a morphed bind group, or null for an unmorphed one. */
-deltas?: GPUTextureView | null): GPUBindGroup;
+deltas?: GPUTextureView | null, 
+/** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
+cloth?: ClothViews | null): GPUBindGroup;
 /**
  * The pipeline, cached by the state that distinguishes it.
  *
@@ -201,7 +218,23 @@ instanced?: boolean,
 /** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
 oit?: OitTarget, 
 /** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
-doubleSided?: boolean): GPURenderPipeline;
+doubleSided?: boolean, 
+/**
+ * Turns the fragment's alpha into the pixel's samples, for a dithered cutout in a multisampled
+ * frame with no temporal resolve. The key must carry it: `|a2c`. See `cutoutDither.ts`.
+ */
+alphaToCoverage?: boolean, 
+/**
+ * Whether a skinned pipeline reads the second four influences: the vertex stage's `SKIN_EIGHT`.
+ * The key must carry it: `|s8`. See `skinning.ts`.
+ */
+skinEight?: boolean, 
+/** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+cloth?: boolean, 
+/** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
+model?: SurfaceModelKind | null, 
+/** Which half of a skin it draws. The key must carry it: `|ss` or `|sd`. See `SkinHalf`. */
+skinPass?: SkinHalf): GPURenderPipeline;
 /**
  * The same pipeline, compiled off the main thread.
  *
@@ -215,6 +248,12 @@ export declare function flatPipelineAsync(cache: PipelineCache, device: GPUDevic
 /** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
 skinned?: boolean, 
 /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
-morphed?: boolean): Promise<GPURenderPipeline>;
+morphed?: boolean, 
+/** Whether the skinned stage reads the second four influences. See `flatPipeline`. */
+skinEight?: boolean, 
+/** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+cloth?: boolean, 
+/** Which shading model its fragment stage shades by. See `flatPipeline`. */
+model?: SurfaceModelKind | null): Promise<GPURenderPipeline>;
 /** Which of the two order-independent buffers a pipeline writes, or neither. */
 export type OitTarget = 'none' | 'accum' | 'reveal';

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

@@ -1,13 +1,16 @@
+import { SURFACE_MODEL_SWITCH } from '../../surfaceModel.js';
 import { DEPTH_COMPARE, DEPTH_FORMAT, depthOffsetForLayer } from '../../depthConvention.js';
 import { FLAT_BINDINGS, FLAT_FRAG_WGSL, FLAT_VERT_WGSL, } from '../../shaders/generated/flat.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS = new Set([
     'uAlbedo',
     'uNormalMap',
     'uOrmMap',
     'uEmissiveMap',
+    'uModelMap',
 ]);
 /**
  * The key for a set of flags.
@@ -67,6 +70,35 @@ export function flatVertexBindings(skinned, morphed = false, instanced = false)
     return found;
 }
 const PLAIN_VERTEX = flatVertexBindings(false);
+/**
+ * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` in
+ * a skinned stage, nothing in any other. Every override a stage declares is set, and one this does
+ * not know is refused here rather than defaulted. Shared with the shadow and glass-tint casters,
+ * whose skinned stages declare the same switch.
+ */
+export function vertexConstants(bindings, skinEight, cloth = false) {
+    const constants = {};
+    for (const [name, id] of Object.entries(bindings.overrides ?? {})) {
+        if (name === 'SKIN_EIGHT')
+            constants[String(id)] = skinEight ? 1 : 0;
+        else if (name === 'CLOTH_BOUND')
+            constants[String(id)] = cloth ? 1 : 0;
+        else
+            throw new Error(`flatPass: a vertex stage declares a switch "${name}" nothing sets`);
+    }
+    return constants;
+}
+/** Where a skinned stage declares the cloth binding's three textures: binding, particles, rest. */
+function clothBindings(skinned, morphed) {
+    const textures = flatVertexBindings(skinned, morphed).textures;
+    const at = (name) => {
+        const found = textures[name];
+        if (found === undefined)
+            throw new Error(`flatPass: the skinned vertex shader declares no ${name}`);
+        return found.texture;
+    };
+    return [at('uClothBinding'), at('uClothParticles'), at('uClothRest')];
+}
 /*
  * **A variant may drop a field; it may never move one.**
  *
@@ -123,13 +155,28 @@ export function flatFragmentBindings(variant) {
  * "GLASS_SHADOWS" not found*, and the frame drew nothing. Every override the variant declares is
  * set, so a switch added to the shader and not to the cache is refused here rather than defaulted.
  */
-function flatFragmentConstants(variant, cache) {
+function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
     const overrides = flatFragmentBindings(variant).overrides;
     if (overrides?.['GLASS_SHADOWS'] === undefined) {
         throw new Error(`flatPass: variant "${variant}" has no glass switch`);
     }
+    const modelSwitch = model === null ? null : SURFACE_MODEL_SWITCH[model];
     const constants = {};
     for (const [name, id] of Object.entries(overrides)) {
+        /* A model's switch is the pipeline's own, set from its key rather than from the cache. */
+        if (name.startsWith('MODEL_')) {
+            constants[String(id)] = name === modelSwitch ? 1 : 0;
+            continue;
+        }
+        /* Skin's two halves under the screen-space blur, set from the key as a model's switch is. */
+        if (name === 'SKIN_SCREEN' || name === 'SKIN_DIFFUSE') {
+            constants[String(id)] =
+                (name === 'SKIN_SCREEN' && skinPass === 'scene') ||
+                    (name === 'SKIN_DIFFUSE' && skinPass === 'diffuse')
+                    ? 1
+                    : 0;
+            continue;
+        }
         if (!(name in cache.litSwitches)) {
             throw new Error(`flatPass: variant "${variant}" declares a switch "${name}" no cache sets`);
         }
@@ -297,6 +344,15 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
             visibility: VISIBILITY_VERTEX,
             texture: { sampleType: 'unfilterable-float' },
         });
+        /* The cloth binding's three textures, declared by every skinned stage whether a draw sets a
+           cloth or not; see `clothBinding.ts`. */
+        for (const binding of clothBindings(skinned, morphed)) {
+            entries.push({
+                binding,
+                visibility: VISIBILITY_VERTEX,
+                texture: { sampleType: 'unfilterable-float' },
+            });
+        }
     }
     return device.createBindGroupLayout({
         label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed)}`,
@@ -308,7 +364,7 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
  *
  * `resolve` is asked for a view by the shader's own name for it, so a caller supplies the
  * shadow maps it has and a stand-in for the rest. **Every declared binding must be filled
- * even when the shader never samples it** — `uAlbedoEnabled` is zero for nearly all geometry
+ * even when the shader never samples it** — the albedo's flag is zero for nearly all geometry
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
@@ -316,7 +372,9 @@ export function createFlatBindGroup(device, layout, variant, perDraw, perFrame,
 /** 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) {
+deltas = null, 
+/** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
+cloth = null) {
     const fragment = flatFragmentBindings(variant);
     const entries = [
         {
@@ -350,6 +408,13 @@ deltas = null) {
             throw new Error('flatPass: the skinned vertex shader declares no uJointPalette');
         }
         entries.push({ binding: binding.texture, resource: palette });
+        if (cloth === null) {
+            throw new Error('flatPass: a skinned bind group needs cloth views, the stand-in at the least');
+        }
+        const [bindingAt, particlesAt, restAt] = clothBindings(true, deltas !== null);
+        entries.push({ binding: bindingAt, resource: cloth.binding });
+        entries.push({ binding: particlesAt, resource: cloth.particles });
+        entries.push({ binding: restAt, resource: cloth.rest });
     }
     return device.createBindGroup({
         label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null)}`,
@@ -399,8 +464,24 @@ instanced = false,
 /** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
 oit = 'none', 
 /** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
-doubleSided = false) {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided), true);
+doubleSided = false, 
+/**
+ * Turns the fragment's alpha into the pixel's samples, for a dithered cutout in a multisampled
+ * frame with no temporal resolve. The key must carry it: `|a2c`. See `cutoutDither.ts`.
+ */
+alphaToCoverage = false, 
+/**
+ * Whether a skinned pipeline reads the second four influences: the vertex stage's `SKIN_EIGHT`.
+ * The key must carry it: `|s8`. See `skinning.ts`.
+ */
+skinEight = false, 
+/** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+cloth = false, 
+/** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
+model = null, 
+/** Which half of a skin it draws. The key must carry it: `|ss` or `|sd`. See `SkinHalf`. */
+skinPass = 'whole') {
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass), true);
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -415,8 +496,14 @@ export function flatPipelineAsync(cache, device, layout, variant, key, present,
 /** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
 skinned = false, 
 /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
-morphed = false) {
-    return cache.getAsync(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed), true);
+morphed = false, 
+/** Whether the skinned stage reads the second four influences. See `flatPipeline`. */
+skinEight = false, 
+/** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+cloth = false, 
+/** Which shading model its fragment stage shades by. See `flatPipeline`. */
+model = null) {
+    return cache.getAsync(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, true, 0, false, 'none', false, false, skinEight, cloth, model), true);
 }
 /**
  * The colour target for an order-independent pass, or null where this is an ordinary draw.
@@ -472,8 +559,11 @@ instanced = false,
  */
 oit = 'none', 
 /** Culls nothing: a surface seen from both faces. */
-doubleSided = false) {
+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') {
     const offset = depthOffsetForLayer(depthLayer);
+    const diffuseAlone = skinPass === 'diffuse';
     return {
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
@@ -489,6 +579,7 @@ doubleSided = false) {
             }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
+            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced), skinEight, cloth),
         },
         fragment: {
             module: shaderModule(device, {
@@ -497,7 +588,7 @@ doubleSided = false) {
             }),
             entryPoint: 'main',
             /* Every variant declares it, so every lit pipeline may set it: see `PipelineCache`. */
-            constants: flatFragmentConstants(variant, cache),
+            constants: flatFragmentConstants(variant, cache, model, skinPass),
             targets: [
                 oitTarget(oit) ??
                     (translucent === 'additive'
@@ -517,14 +608,20 @@ doubleSided = false) {
                                         dstFactor: 'one-minus-src-alpha',
                                         operation: 'add',
                                     },
-                                    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                                    alpha: SCENE_ALPHA_COVERS,
                                 },
                             }
                             : { format: cache.format }),
             ],
         },
         primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back' },
-        multisample: { count: cache.sampleCount },
+        /* Coverage only where a sample count can carry it: WebGPU refuses it at one sample. */
+        multisample: {
+            count: cache.sampleCount,
+            ...(alphaToCoverage && cache.sampleCount > 1 && !diffuseAlone
+                ? { alphaToCoverageEnabled: true }
+                : {}),
+        },
         /*
          * `less`, matching the WebGL2 path's `LESS` rather than `LEQUAL`, and for the reason
          * `drawMesh` documents there: under `LEQUAL` two coplanar surfaces do not merely tie,
@@ -532,8 +629,9 @@ doubleSided = false) {
          */
         depthStencil: {
             format: DEPTH_FORMAT,
-            depthWriteEnabled: depthWrite,
-            depthCompare: DEPTH_COMPARE,
+            /* The diffuse half is the same surface again: it finds the depth the frame's half wrote. */
+            depthWriteEnabled: depthWrite && !diffuseAlone,
+            depthCompare: diffuseAlone ? 'equal' : DEPTH_COMPARE,
             /*
              * Baked in, where the other backend toggles it around the draw. Both read
              * `depthOffsetForLayer`, so a layer is worth the same depth on either one, and a pipeline

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

@@ -0,0 +1,74 @@
+import type { SkinnedClothSetup } from '@driftengine/physics';
+import { GpuClothParticles } from './clothTextures.ts';
+/** One garment's solver on the device, and the particle textures it publishes into. */
+export declare class GpuSkinnedCloth {
+    private readonly device;
+    /** The particles a bound mesh draws by: see `RendererApi.setCloth`. */
+    readonly particles: GpuClothParticles;
+    readonly count: number;
+    private readonly control;
+    private readonly packed;
+    private readonly kernels;
+    private readonly buffers;
+    private readonly state;
+    private readonly frameData;
+    private readonly stepSlots;
+    private readonly group;
+    private readonly outputs;
+    private readonly frameStaging;
+    private readonly stepStaging;
+    private readonly stepFloats;
+    private readonly stepWords;
+    /** Each batch's slot, by kind and by whether it opens a substep's iterations. */
+    private readonly batchSlot;
+    /** The air the steps drag toward: the set-up's until `setWind`, written into every step. */
+    private readonly wind;
+    private readonly groups;
+    private readonly substeps;
+    private readonly iterations;
+    private encoder;
+    private pass;
+    private slot;
+    /** Where the pose a step starts from and the one it moves toward sit in `pose`, in floats. */
+    private fromAt;
+    private toAt;
+    constructor(device: GPUDevice, setup: SkinnedClothSetup);
+    /**
+     * 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: Float32Array, model: Float32Array, dt: number, frame: number): void;
+    /** The frame's sample of the scene's wind, for the steps to come. See `SkinnedCloth.setWind`. */
+    setWind(x: number, y: number, z: number): void;
+    /** Back to the skinned pose, settled; the next `advance` publishes it. */
+    reset(): void;
+    /**
+     * 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.
+     */
+    read(): Promise<Float32Array>;
+    /** Its buffers; the particle textures are the renderer's to retire with the frame. */
+    dispose(): void;
+    private targetsChanged;
+    private rest;
+    private step;
+    /** Every batch of one kind, in colour order, each a dispatch over its range. */
+    private batches;
+    private dispatch;
+    private passFor;
+    /** Send what has been recorded: every slot it reads was written ahead of it on the queue. */
+    private flush;
+    /**
+     * 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.
+     */
+    private takeSlot;
+    /** `carryParticles`' rotation, origin and move, into the step's slot; carry 0 where none. */
+    private writeCarry;
+    /** The pose's skin matrices — or the model, for a cloth with no rig — and its colliders. */
+    private writeFrameData;
+    private constants;
+    /** Each batch's range, twice — opening a substep's iterations and not — at a slot each. */
+    private writeBatches;
+}