@driftengine/core 4.8.7 → 4.10.0

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,9 +13,14 @@
 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)[];
@@ -29,6 +34,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 +51,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,6 +22,8 @@ function emptyCommand() {
         bindGroup: null,
         offsetA: 0,
         offsetB: 0,
+        offsetC: 0,
+        offsetD: 0,
         offsetCount: 0,
         vertexBuffers: new Array(VERTEX_BUFFER_SLOTS).fill(null),
         vertexCount: 0,
@@ -30,6 +32,7 @@ function emptyCommand() {
         count: 0,
         instances: 1,
         indirect: null,
+        bundles: null,
     };
 }
 export function createCommandPool(capacity) {
@@ -41,8 +44,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 +57,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,18 +151,63 @@ 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
+ * stage before the probe's permutation can be built. A sampler several textures share counts once,
+ * which is what `// wgsl:share` buys.
+ */
+export declare function probeStageCeilings(): {
+    readonly textures: number;
+    readonly samplers: number;
+};
 /** 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.
  *
@@ -168,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;
 }, 
@@ -177,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.
  *
@@ -236,7 +287,14 @@ 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`, `|sd` or `|sa`. See `SkinHalf`. */
-skinPass?: SkinHalf): GPURenderPipeline;
+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, 
+/** An instanced pipeline that plays a bone animation. The key must carry it: `|anim`. */
+animated?: boolean): GPURenderPipeline;
 /**
  * The same pipeline, compiled off the main thread.
  *