@driftengine/core 4.9.0 → 4.11.0

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

@@ -1,4 +1,4 @@
-import { DEPTH_BINDINGS, DEPTH_CUTOUT_FRAG_WGSL, DEPTH_CUTOUT_VERT_WGSL, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
+import { DEPTH_BINDINGS, DEPTH_CUTOUT_FRAG_WGSL, DEPTH_CUTOUT_VERT_WGSL, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_ANIMATED_VERT_WGSL, DEPTH_INSTANCED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
 import { vertexConstants } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
@@ -37,6 +37,14 @@ const CLOTH_TEXTURES = [
     DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothParticles,
     DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothRest,
 ];
+/** A bone animation's three textures, at the bindings both animated depth variants declare them. */
+const ANIMATION_TEXTURES = [
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBonePlaces,
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uBoneTurns,
+    DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.textures.uInstanceClocks,
+];
+export const DEPTH_INSTANCED_ANIMATED_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_VERT.fields;
+export const DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT.fields;
 const VISIBILITY_VERTEX = 0x1;
 const VISIBILITY_FRAGMENT = 0x2;
 /**
@@ -63,10 +71,19 @@ skinned = false,
  * Separate for the palette's reason: the plain layout stays exactly what it was, and a frame with
  * no cutout caster pays nothing.
  */
-cutout = false) {
+cutout = false, 
+/** An instanced caster playing a bone animation: its three vertex textures. */
+animated = false) {
     return device.createBindGroupLayout({
-        label: skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout',
+        label: `${skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout'}${animated ? '.animated' : ''}`,
         entries: [
+            ...(animated
+                ? ANIMATION_TEXTURES.map((binding) => ({
+                    binding: binding.texture,
+                    visibility: VISIBILITY_VERTEX,
+                    texture: { sampleType: 'unfilterable-float' },
+                }))
+                : []),
             /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
                coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
                palette. naga declares a sampler for it and nothing ever reads one. */
@@ -147,7 +164,9 @@ palette = null,
 /** The cutout map and its sampler, for a layout built with `cutout`. */
 cutout = null, 
 /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
-cloth = null) {
+cloth = null, 
+/** An animated caster's clip and clocks. See `AnimationViews`. */
+animation = null) {
     return device.createBindGroup({
         label: palette !== null
             ? 'depth.bindGroup.skinned'
@@ -180,6 +199,13 @@ cloth = null) {
                     { binding: CUTOUT_MAP.sampler, resource: cutout.sampler },
                 ]
                 : []),
+            ...(animation !== null
+                ? [
+                    { binding: ANIMATION_TEXTURES[0].texture, resource: animation.places },
+                    { binding: ANIMATION_TEXTURES[1].texture, resource: animation.turns },
+                    { binding: ANIMATION_TEXTURES[2].texture, resource: animation.clocks },
+                ]
+                : []),
         ],
     });
 }
@@ -221,20 +247,29 @@ cutout = false,
  */
 skinEight = false, 
 /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
-cloth = false) {
+cloth = false, 
+/** An instanced caster playing a bone animation. The key must carry it. */
+animated = false) {
     return cache.get(key, () => ({
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
         vertex: {
-            module: shaderModule(device, cutout
-                ? instanced
-                    ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
-                    : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
-                : instanced
-                    ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
-                    : skinned
-                        ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
-                        : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
+            module: shaderModule(device, animated
+                ? cutout
+                    ? {
+                        label: 'depth.instanced.animated.cutout.vert',
+                        code: DEPTH_INSTANCED_ANIMATED_CUTOUT_VERT_WGSL,
+                    }
+                    : { label: 'depth.instanced.animated.vert', code: DEPTH_INSTANCED_ANIMATED_VERT_WGSL }
+                : cutout
+                    ? instanced
+                        ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
+                        : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
+                    : instanced
+                        ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+                        : skinned
+                            ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+                            : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
             ...(skinned && !instanced && !cutout

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

@@ -2,7 +2,7 @@
  * One recorded draw, in the only shape this backend ever issues.
  *
  * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
- * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * same every time: a pipeline, a bind group with up to four dynamic offsets, some vertex
  * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
  * drawn except the values.
  *
@@ -13,14 +13,21 @@
 export interface DrawCommand {
     pipeline: GPURenderPipeline | null;
     bindGroup: GPUBindGroup | null;
-    /** Dynamic offsets, held as two numbers rather than an array so a reset stays free. */
+    /**
+     * Dynamic offsets, held as numbers rather than an array so a reset stays free. Four only for a
+     * lit mesh: its draw's slot, its pass's, its material's and its view's, in binding order.
+     */
     offsetA: number;
     offsetB: number;
+    offsetC: number;
+    offsetD: number;
     offsetCount: number;
     /** Fixed length; `vertexCount` says how many slots are live. */
     readonly vertexBuffers: (GPUBuffer | null)[];
     vertexCount: number;
     indexBuffer: GPUBuffer | null;
+    /** How wide an index of `indexBuffer` is: a mesh's own, thirty-two bits for everything else. */
+    indexFormat: GPUIndexFormat;
     indexed: boolean;
     count: number;
     instances: number;
@@ -29,6 +36,12 @@ export interface DrawCommand {
      * cull's survivors, counted on the device. Null for every other draw.
      */
     indirect: GPUBuffer | null;
+    /**
+     * Render bundles to execute instead of everything above: a static list recorded once, replayed
+     * as one command. Held as the array `executeBundles` takes, kept by the list, so issuing it
+     * allocates nothing. Null for every other command, and put back to null by every take.
+     */
+    bundles: readonly GPURenderBundle[] | null;
 }
 export interface CommandPool {
     commands: DrawCommand[];
@@ -40,8 +53,11 @@ export declare function createCommandPool(capacity: number): CommandPool;
 /**
  * Hand out the next command, growing if a frame overruns.
  *
- * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
- * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ * The entry is **not cleared**, but for `bundles`. Every caller fills every field it uses, and
+ * clearing here would be a write per field per draw for no reader — the same reasoning the node
+ * arena uses. `bundles` is the exception because almost no caller knows it exists: a pooled command
+ * that once carried a static list's bundles and was then taken for an ordinary draw would replay the
+ * list instead, so the one field nobody fills is the one field put back here.
  */
 export declare function takeCommand(pool: CommandPool): number;
 /** Empty the pool for a new frame. Keeps every entry; that is the whole point. */

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

@@ -2,7 +2,7 @@
  * One recorded draw, in the only shape this backend ever issues.
  *
  * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
- * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * same every time: a pipeline, a bind group with up to four dynamic offsets, some vertex
  * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
  * drawn except the values.
  *
@@ -22,14 +22,18 @@ function emptyCommand() {
         bindGroup: null,
         offsetA: 0,
         offsetB: 0,
+        offsetC: 0,
+        offsetD: 0,
         offsetCount: 0,
         vertexBuffers: new Array(VERTEX_BUFFER_SLOTS).fill(null),
         vertexCount: 0,
         indexBuffer: null,
+        indexFormat: 'uint32',
         indexed: false,
         count: 0,
         instances: 1,
         indirect: null,
+        bundles: null,
     };
 }
 export function createCommandPool(capacity) {
@@ -41,8 +45,11 @@ export function createCommandPool(capacity) {
 /**
  * Hand out the next command, growing if a frame overruns.
  *
- * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
- * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ * The entry is **not cleared**, but for `bundles`. Every caller fills every field it uses, and
+ * clearing here would be a write per field per draw for no reader — the same reasoning the node
+ * arena uses. `bundles` is the exception because almost no caller knows it exists: a pooled command
+ * that once carried a static list's bundles and was then taken for an ordinary draw would replay the
+ * list instead, so the one field nobody fills is the one field put back here.
  */
 export function takeCommand(pool) {
     const at = pool.taken;
@@ -51,6 +58,7 @@ export function takeCommand(pool) {
     pool.taken = at + 1;
     if (pool.taken > pool.highWater)
         pool.highWater = pool.taken;
+    pool.commands[at].bundles = null;
     return at;
 }
 /** Empty the pool for a new frame. Keeps every entry; that is the whole point. */

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

@@ -63,11 +63,27 @@ export interface StageBindings {
     readonly textures: Readonly<Record<string, TextureBinding>>;
     /** Each pipeline-overridable constant's id, by the GLSL name it was declared under. */
     readonly overrides?: Readonly<Record<string, number>>;
+    /**
+     * The second block, of the uniforms marked `// wgsl:material`: its binding, size and fields.
+     * Absent from a stage that marks none, which is every stage but the lit fragment's.
+     */
+    readonly materialUniforms?: number;
+    readonly materialSize?: number;
+    readonly materialFields?: StageBindings['fields'];
+    /**
+     * The vertex stage's view block, of the uniforms marked `// wgsl:view`: the camera, the light's
+     * matrix and the wind, which a pass settles. Absent from every stage but the lit vertex one.
+     */
+    readonly viewUniforms?: number;
+    readonly viewSize?: number;
+    readonly viewFields?: StageBindings['fields'];
 }
 /** The key for a set of vertex flags: the same rule `variantKey` uses, flags on, sorted, joined. */
-export declare function flatVertexKey(skinned: boolean, morphed: boolean, instanced?: boolean): string;
+export declare function flatVertexKey(skinned: boolean, morphed: boolean, instanced?: boolean, 
+/** Whether an instanced variant plays a bone animation. See `shaders/boneAnimation.ts`. */
+animated?: boolean): string;
 /** Everything the generator recorded about one variant of the vertex stage. */
-export declare function flatVertexBindings(skinned: boolean, morphed?: boolean, instanced?: boolean): StageBindings;
+export declare function flatVertexBindings(skinned: boolean, morphed?: boolean, instanced?: boolean, animated?: boolean): StageBindings;
 /**
  * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` and
  * `CLOTH_BOUND` in a skinned stage, `LIGHTMAP_REGIONS` in an instanced one, nothing in any other. Every override a stage declares is set, and one this does
@@ -78,63 +94,51 @@ export declare function vertexConstants(bindings: StageBindings, skinEight: bool
 /** Whether an instanced stage reads its tint lane as a lightmap region. See `lightmap.ts`. */
 lightmapRegions?: boolean): Record<string, number>;
 export declare const FLAT_VERT_FIELDS: {
-    readonly uViewProj: {
-        readonly offset: 0;
-        readonly size: 64;
-        readonly type: "mat4";
-    };
     readonly uHasTangents: {
-        readonly offset: 64;
+        readonly offset: 0;
         readonly size: 4;
         readonly type: "int";
     };
-    readonly uLightViewProj: {
-        readonly offset: 80;
-        readonly size: 64;
-        readonly type: "mat4";
-    };
     readonly uUvScale: {
-        readonly offset: 144;
+        readonly offset: 8;
         readonly size: 8;
         readonly type: "vec2";
     };
     readonly uUvOffset: {
-        readonly offset: 152;
+        readonly offset: 16;
         readonly size: 8;
         readonly type: "vec2";
     };
     readonly uModel: {
-        readonly offset: 160;
+        readonly offset: 32;
         readonly size: 64;
         readonly type: "mat4";
     };
     readonly uTint: {
-        readonly offset: 224;
+        readonly offset: 96;
         readonly size: 12;
         readonly type: "vec3";
     };
-    readonly uWindDirection: {
-        readonly offset: 240;
-        readonly size: 8;
-        readonly type: "vec2";
-    };
-    readonly uWindSpeed: {
-        readonly offset: 248;
+};
+/** The animated instanced variant's block: the instanced fields, and the clip's `uBoneClip`. */
+export declare const FLAT_ANIMATED_VERT_FIELDS: {
+    readonly uHasTangents: {
+        readonly offset: 0;
         readonly size: 4;
-        readonly type: "float";
+        readonly type: "int";
     };
-    readonly uWindGust: {
-        readonly offset: 252;
-        readonly size: 4;
-        readonly type: "float";
+    readonly uUvScale: {
+        readonly offset: 8;
+        readonly size: 8;
+        readonly type: "vec2";
     };
-    readonly uWindTime: {
-        readonly offset: 256;
-        readonly size: 4;
-        readonly type: "float";
+    readonly uUvOffset: {
+        readonly offset: 16;
+        readonly size: 8;
+        readonly type: "vec2";
     };
-    readonly uWindSpatialPhase: {
-        readonly offset: 264;
+    readonly uBoneClip: {
+        readonly offset: 24;
         readonly size: 8;
         readonly type: "vec2";
     };
@@ -147,6 +151,14 @@ export declare const FLAT_VERT_FIELDS: {
  * 144 bytes a slot and is what a single ring costs.
  */
 export declare const FLAT_VERT_SIZE: number;
+/** The view block's fields, binding and size: the largest variant's, as `FLAT_VERT_SIZE` is. */
+export declare const FLAT_VIEW_FIELDS: Readonly<Record<string, {
+    readonly offset: number;
+    readonly size: number;
+    readonly length?: number;
+    readonly stride?: number;
+}>>;
+export declare const FLAT_VIEW_SIZE: number;
 /**
  * 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
@@ -159,16 +171,43 @@ export declare function probeStageCeilings(): {
 };
 /** Everything the generator recorded about one permutation of the fragment stage. */
 export declare function flatFragmentBindings(variant: FlatVariant): StageBindings;
+/**
+ * The lit fragment stage's two blocks as the renderer keeps them on the CPU: the pass's, then the
+ * material's straight after it, in one scratch, with every field at its offset in that scratch.
+ *
+ * **One scratch rather than two, so no setter has to know which block its field is in.** A setter
+ * writes by name, as it always has; the draw copies the material's bytes — `passSize` onwards — into
+ * the store and the pass's bytes into a ring slot, each only when something has changed it.
+ */
+export interface FlatFragmentScratch {
+    readonly fields: StageBindings['fields'];
+    /** Bytes of the pass's block, which is where the material's starts in the scratch. */
+    readonly passSize: number;
+    readonly passBinding: number;
+    readonly materialSize: number;
+    readonly materialBinding: number;
+}
+export declare function flatFragmentScratch(variant: FlatVariant): FlatFragmentScratch;
 /** The depth format both backends compare with. */
 export { DEPTH_FORMAT } from '../../depthConvention.ts';
 /**
  * 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 declare function createFlatBindGroupLayout(device: GPUDevice, variant: FlatVariant, skinned?: boolean, morphed?: boolean): GPUBindGroupLayout;
+export declare function createFlatBindGroupLayout(device: GPUDevice, variant: FlatVariant, skinned?: boolean, morphed?: boolean, 
+/** The instanced variant that plays a bone animation: its three vertex textures. */
+animated?: boolean): GPUBindGroupLayout;
+/** What an animated draw binds besides its material: the clip's two textures and its batch's clocks. */
+export interface AnimationViews {
+    readonly places: GPUTextureView;
+    readonly turns: GPUTextureView;
+    readonly clocks: GPUTextureView;
+}
 /**
  * Bind the buffers and one view per declared texture.
  *
@@ -178,7 +217,7 @@ export declare function createFlatBindGroupLayout(device: GPUDevice, variant: Fl
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
-export declare function createFlatBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, variant: FlatVariant, perDraw: GPUBuffer, perFrame: GPUBuffer, resolve: (name: string) => {
+export declare function createFlatBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, variant: FlatVariant, perDraw: GPUBuffer, passes: GPUBuffer, materials: GPUBuffer, views: GPUBuffer, resolve: (name: string) => {
     view: GPUTextureView;
     sampler: GPUSampler;
 }, 
@@ -187,7 +226,9 @@ palette?: GPUTextureView | null,
 /** The delta view for a morphed bind group, or null for an unmorphed one. */
 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;
+cloth?: ClothViews | null, 
+/** An animated instanced group's views. See `AnimationViews`. */
+animation?: AnimationViews | null): GPUBindGroup;
 /**
  * The pipeline, cached by the state that distinguishes it.
  *
@@ -251,7 +292,9 @@ skinPass?: SkinHalf,
  * 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?: boolean): GPURenderPipeline;
+reflectionSurface?: boolean, 
+/** An instanced pipeline that plays a bone animation. The key must carry it: `|anim`. */
+animated?: boolean): GPURenderPipeline | null;
 /**
  * The same pipeline, compiled off the main thread.
  *