@driftengine/core 3.61.0

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

@@ -0,0 +1,482 @@
+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';
+/**
+ * The key for a set of flags.
+ *
+ * **The rule is `variantKey` in `scripts/wgsl.ts` and this is a second statement of it**, which
+ * is exactly the kind of restatement that drifts — except that a drift here cannot be silent:
+ * `flatFragmentBindings` throws on a key the generated table does not hold, at construction,
+ * naming the key it looked for. `scripts/` is a build tool and nothing under `src/` may import
+ * it, so a copy is the only option and a loud one is the acceptable form of it.
+ */
+export function flatVariant(flags) {
+    const on = Object.keys(flags)
+        .filter((flag) => flags[flag])
+        .sort();
+    return on.length === 0 ? 'none' : on.join('+');
+}
+/*
+ * The generated file is `as const`, which makes every variant its own literal type and makes
+ * indexing it by a computed key an error. Declaring the shape once here is what lets the
+ * renderer choose a variant at runtime, and it is checked against the real object rather than
+ * asserted about it: a generator that stopped emitting `uniformSize` would fail here.
+ */
+const FRAGMENT_BINDINGS = FLAT_BINDINGS.flatFrag;
+/**
+ * The vertex stage's four variants, keyed like the fragment stage's sixteen.
+ *
+ * **The morphed variants have a larger uniform block — 384 bytes against 240 — and every shared
+ * field keeps its offset anyway.** That is not luck: a block is packed in declaration order, and
+ * `flat/index.ts` declares morph's uniforms after every other one for exactly this reason. The
+ * assertion below is on the *offsets* rather than on the size, because the offsets are what the
+ * renderer writes by and a moved one does not fail — it puts the model matrix where the view
+ * projection should be and draws a scrambled frame.
+ *
+ * The first version of this guard compared only the unskinned and skinned sizes, which are equal
+ * because skinning added a sampler and no uniform. It would have stayed silent through exactly the
+ * change it was written to catch.
+ */
+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) {
+    const on = [];
+    /* Alphabetical, because the generator's own `variantKey` sorts and the two keys must agree. */
+    if (instanced)
+        on.push('instanced');
+    if (morphed)
+        on.push('morphed');
+    if (skinned)
+        on.push('skinned');
+    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);
+    const found = VERTEX_BINDINGS[key];
+    if (found === undefined)
+        throw new Error(`flatPass: no vertex bindings for variant "${key}"`);
+    return found;
+}
+const PLAIN_VERTEX = flatVertexBindings(false);
+/*
+ * **A variant may drop a field; it may never move one.**
+ *
+ * The renderer writes this block by offset, so two variants disagreeing about where a shared
+ * field lives is a scrambled frame rather than an error. The check was `undefined || moved` until
+ * the instanced variant, which legitimately declares neither `uModel` nor `uTint` — its placement
+ * and tint arrive as vertex attributes — and an absent field is not a moved one: nothing writes
+ * it, so nothing can write it to the wrong place.
+ *
+ * What still has to hold, and what this asserts, is that every field a variant *does* declare sits
+ * where the plain variant has it. That is what `flat/index.ts` declares the optional uniforms last
+ * for, and it was worth asserting: with `uModel` declared second, the instanced block put
+ * `uHasTangents` at 64 against the plain variant's 128, and a draw writing by the plain table
+ * would have put the tangent flag into the model matrix.
+ *
+ * **What would make this wrong** is a caller writing a field the variant it is drawing does not
+ * declare. That is the failure this no longer catches, and it is `drawInstanced`'s to avoid by
+ * writing the shared fields only.
+ */
+for (const [key, bindings] of Object.entries(VERTEX_BINDINGS)) {
+    for (const [field, shared] of Object.entries(PLAIN_VERTEX.fields)) {
+        const here = bindings.fields[field];
+        if (here !== undefined && here.offset !== shared.offset) {
+            throw new Error(`flatPass: vertex variant "${key}" puts ${field} at ${here.offset} where the ` +
+                `plain variant has it at ${shared.offset}. A variant may omit a field, but every field ` +
+                `it declares must sit where the plain variant has it, because the renderer writes them ` +
+                `by offset — declare a new flag's uniforms after the existing ones.`);
+        }
+    }
+}
+export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
+/**
+ * The **largest** variant's block, because one ring serves every draw.
+ *
+ * A ring strided for the plain block would leave a morphed draw writing its weights into the next
+ * slot, which is a scrambled neighbour rather than an error. The unused tail on a plain draw is
+ * 144 bytes a slot and is what a single ring costs.
+ */
+export const FLAT_VERT_SIZE = Math.max(...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.uniformSize));
+const FLAT_VERT_BINDING = PLAIN_VERTEX.uniforms;
+/** Everything the generator recorded about one permutation of the fragment stage. */
+export function flatFragmentBindings(variant) {
+    const found = FRAGMENT_BINDINGS[variant];
+    if (found === undefined)
+        throw new Error(`flatPass: no bindings for variant "${variant}"`);
+    return found;
+}
+/** 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. */
+export { DEPTH_FORMAT } from '../../depthConvention.js';
+const VISIBILITY_VERTEX = 0x1;
+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.
+ */
+export function createFlatBindGroupLayout(device, variant, skinned = false, morphed = false) {
+    const fragment = flatFragmentBindings(variant);
+    const entries = [
+        {
+            binding: FLAT_VERT_BINDING,
+            visibility: VISIBILITY_VERTEX,
+            buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLAT_VERT_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.
+             */
+            buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: fragment.uniformSize },
+        },
+    ];
+    /** What each sampler binding was declared as, so a shared one is declared once and agrees. */
+    const samplerKind = new Map();
+    for (const [name, texture] of Object.entries(fragment.textures)) {
+        /*
+         * A shadow map is a depth texture, and a depth texture's supported sample types are
+         * `UnfilterableFloat | Depth` — never plain `Float`, which is what an empty `texture: {}`
+         * asks for. Declaring the wrong one is rejected at bind time:
+         *
+         *   None of the supported sample types (UnfilterableFloat|Depth) of [Texture
+         *   "shadow.static"] match the expected sample types (Float)
+         *
+         * Unfilterable rather than a comparison sampler, because the shader does its own PCF
+         * loop over explicit taps rather than asking the hardware to compare and blend.
+         */
+        const cube = texture.type === 'samplerCube';
+        /*
+         * The point-shadow array is a depth texture too, and is read the same way: `pointShadow`
+         * takes one `textureLod(maps, vec3(octEncode(dir), layer), 0.0)` per tap and estimates its
+         * own penumbra, so nothing here asks the hardware to filter.
+         *
+         * **`uEnvironment` is a cube and is *not* a shadow map.** It is a colour cubemap, and its
+         * mip chain **is** the roughness: a polished surface reads level 0 and a satin one reads
+         * further up, blending between them. That needs a filtering sampler and a filterable float,
+         * and declaring it `non-filtering` alongside the depth textures made the pipeline invalid —
+         * which, being a pipeline, drew nothing and said nothing beyond a device warning.
+         *
+         * Named explicitly rather than by a pattern. `uPointShadow0` did not end in `ShadowMap`, so
+         * a rule wide enough to catch the twelve cubes also caught the probe; naming the one
+         * exception was the answer then and there is one binding to catch now.
+         */
+        const array = texture.type === 'sampler2DArray';
+        /*
+         * **An integer texture is its own sample type and cannot be anything else.** The froxel table
+         * is `rgba32uint`; declaring it `float` is rejected at bind time exactly as a depth texture
+         * declared `float` is, with the same shape of message and the same consequence — a bind group
+         * that is invalid, a pass that records nothing, and a frame that presents anyway.
+         *
+         * It is also the reason the entry below asks for a non-filtering sampler: WebGPU permits no
+         * other kind against a `uint` texture, and the shader never samples it — every read is a
+         * `texelFetch`, which is why the declaration shares a sampler rather than bringing its own.
+         */
+        const integer = texture.type === 'usampler2D';
+        const isShadow = integer || (name !== 'uEnvironment' && (name.endsWith('ShadowMap') || cube || array));
+        entries.push({
+            binding: texture.texture,
+            visibility: VISIBILITY_FRAGMENT,
+            texture: {
+                sampleType: integer ? 'uint' : isShadow ? 'unfilterable-float' : 'float',
+                ...(cube ? { viewDimension: 'cube' } : {}),
+                ...(array ? { viewDimension: '2d-array' } : {}),
+            },
+        });
+        /*
+         * **One entry per sampler *binding*, not per texture**, because the fifteen shadow
+         * declarations now share one. `// wgsl:share shadow` in `flat.ts` is what collapsed them,
+         * and it is what lets the environment probe fit under a sixteen-sampler ceiling at all.
+         * Declaring the same binding fifteen times is rejected outright.
+         */
+        const declared = samplerKind.get(texture.sampler);
+        const kind = isShadow ? 'non-filtering' : 'filtering';
+        if (declared === undefined) {
+            samplerKind.set(texture.sampler, kind);
+            entries.push({
+                binding: texture.sampler,
+                visibility: VISIBILITY_FRAGMENT,
+                sampler: { type: kind },
+            });
+        }
+        else if (declared !== kind) {
+            /*
+             * Loud, at init, because the alternative is silent and wrong. A group whose members
+             * disagree about filtering cannot share a sampler — `uEnvironment`'s mip chain *is* its
+             * roughness and needs a filtering one, where a depth cube cannot have it — and a marker
+             * that put them together would otherwise produce a pipeline that draws nothing and says
+             * nothing beyond a device warning.
+             */
+            throw new Error(`flat: ${name} shares sampler binding ${texture.sampler} but wants ${kind} where the ` +
+                `group is ${declared}. Check its wgsl:share marker in flat.ts.`);
+        }
+    }
+    /*
+     * The joint palette, on the **vertex** stage.
+     *
+     * `unfilterable-float`, because `rgba32float` is not filterable without an extension and the
+     * shader reads it with an integer fetch that involves no sampler at all. Declaring it filterable
+     * is a pipeline-creation failure rather than a wrong picture, which is the loud direction.
+     *
+     * Added only for the skinned variant, so an unskinned layout declares nothing the unskinned
+     * shader module cannot reach — a bind group layout and its module must agree exactly or WebGPU
+     * refuses the pipeline.
+     */
+    if (morphed) {
+        const deltas = flatVertexBindings(skinned, true).textures['uMorphDeltas'];
+        if (deltas === undefined) {
+            throw new Error('flatPass: the morphed vertex shader declares no uMorphDeltas');
+        }
+        entries.push({
+            binding: deltas.texture,
+            visibility: VISIBILITY_VERTEX,
+            texture: { sampleType: 'unfilterable-float' },
+        });
+    }
+    if (skinned) {
+        const palette = flatVertexBindings(skinned, morphed).textures['uJointPalette'];
+        if (palette === undefined) {
+            throw new Error('flatPass: the skinned vertex shader declares no uJointPalette');
+        }
+        entries.push({
+            binding: palette.texture,
+            visibility: VISIBILITY_VERTEX,
+            texture: { sampleType: 'unfilterable-float' },
+        });
+    }
+    return device.createBindGroupLayout({
+        label: `flat.layout:${variant}|${flatVertexKey(skinned, morphed)}`,
+        entries,
+    });
+}
+/**
+ * Bind the buffers and one view per declared texture.
+ *
+ * `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
+ * 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, 
+/** 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) {
+    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 } },
+    ];
+    /* 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
+       resolves to the one object anyway — that is why sharing the declaration was free. */
+    const filled = new Set();
+    for (const [name, texture] of Object.entries(fragment.textures)) {
+        const supplied = resolve(name);
+        entries.push({ binding: texture.texture, resource: supplied.view });
+        if (filled.has(texture.sampler))
+            continue;
+        filled.add(texture.sampler);
+        entries.push({ binding: texture.sampler, resource: supplied.sampler });
+    }
+    if (deltas !== null) {
+        const binding = flatVertexBindings(palette !== null, true).textures['uMorphDeltas'];
+        if (binding === undefined) {
+            throw new Error('flatPass: the morphed vertex shader declares no uMorphDeltas');
+        }
+        entries.push({ binding: binding.texture, resource: deltas });
+    }
+    if (palette !== null) {
+        const binding = flatVertexBindings(true, deltas !== null).textures['uJointPalette'];
+        if (binding === undefined) {
+            throw new Error('flatPass: the skinned vertex shader declares no uJointPalette');
+        }
+        entries.push({ binding: binding.texture, resource: palette });
+    }
+    return device.createBindGroup({
+        label: `flat.bindGroup:${variant}|${flatVertexKey(palette !== null, deltas !== null)}`,
+        layout,
+        entries,
+    });
+}
+/**
+ * The pipeline, cached by the state that distinguishes it.
+ *
+ * The key names the variant and which optional attributes the mesh supplied, because those
+ * two decide the fragment module and the vertex layout. Built once per mesh at construction
+ * time rather than per frame, which is the rule `PipelineCache` exists to keep.
+ */
+export function flatPipeline(cache, device, layout, variant, key, present, 
+/**
+ * Alpha-blended, for `drawTranslucentMesh`.
+ *
+ * **A second pipeline rather than a flag on the first**, because blend state is baked into a
+ * WebGPU pipeline where WebGL2 toggles it around the draw with `gl.enable(BLEND)`. Keyed
+ * separately, so one mesh drawn both ways gets both and neither is rebuilt per frame.
+ *
+ * Depth still written, matching the other backend: `drawTranslucentMesh` there leaves
+ * `depthMask` alone and only turns blending on. A translucent part of a loaded model is a
+ * pane of glass in a solid object, not a particle, and it has to occlude what is behind it
+ * for the rest of the model to sort correctly.
+ */
+translucent = false, 
+/** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
+skinned = false, 
+/** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
+morphed = false, 
+/**
+ * Whether this pipeline writes depth, and which coplanar layer it draws on.
+ *
+ * **Both are pipeline state here and per-draw state on the other backend**, which is why they
+ * arrive as arguments and why the caller's key has to carry them: two draws of one mesh that
+ * differ only in these would otherwise share a cached pipeline and the second would silently
+ * get the first one's depth behaviour.
+ */
+depthWrite = true, depthLayer = 0, 
+/** Whether placement and tint arrive per instance. See `FlatVertexOptions`. */
+instanced = false, 
+/** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
+oit = 'none') {
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit));
+}
+/**
+ * The same pipeline, compiled off the main thread.
+ *
+ * **Preferred by everything that builds a mesh**, which is all of them: `createRenderPipeline`
+ * defers the shader compile to the first draw, so a scene that builds its meshes and then
+ * renders pays for every one of them inside a single frame. On a phone that is seconds of a
+ * blocked GPU queue with an idle main thread, which is invisible to every timer that is not
+ * this one. The descriptor is identical; only when the driver does the work changes.
+ */
+export function flatPipelineAsync(cache, device, layout, variant, key, present, translucent = false, 
+/** 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));
+}
+/**
+ * The colour target for an order-independent pass, or null where this is an ordinary draw.
+ *
+ * **The accumulation sums and the revealage multiplies**, which is the whole mechanism: a sum and
+ * a product both commute, so the frame stops depending on the order its fragments arrived in.
+ * `orderIndependent.ts` holds the same arithmetic on the CPU, where it is asserted against numbers.
+ *
+ * The revealage pass draws with the *ordinary* shader — `(zero, one-minus-src-alpha)` multiplies
+ * whatever colour it computed by nothing, so only its alpha lands. Both passes therefore decide a
+ * fragment's alpha with the same code and cannot disagree about it.
+ */
+function oitTarget(oit) {
+    if (oit === 'accum') {
+        return {
+            format: 'rgba16float',
+            blend: {
+                color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+            },
+        };
+    }
+    if (oit === 'reveal') {
+        return {
+            format: 'r8unorm',
+            blend: {
+                color: { srcFactor: 'zero', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                alpha: { srcFactor: 'zero', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            },
+        };
+    }
+    return null;
+}
+/** The descriptor both paths build, written once so the two can never diverge. */
+function flatDescriptor(cache, device, layout, variant, key, present, translucent, 
+/** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
+skinned, 
+/** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
+morphed = false, 
+/** Whether this pipeline writes depth. See `TranslucentMeshOptions.depthWrite`. */
+depthWrite = true, 
+/** Which coplanar layer this pipeline draws on. See `TranslucentMeshOptions.depthLayer`. */
+depthLayer = 0, 
+/** Whether placement and tint arrive per instance. See `FlatVertexOptions`. */
+instanced = false, 
+/**
+ * Which order-independent transparency buffer this pipeline writes, if any.
+ *
+ * **A pipeline variant and not a shader one.** The two buffers are two blend states and two
+ * formats, both of which are pipeline state on this backend; the *shader* is the same one the
+ * ordinary translucent path uses, weighted by a uniform. That is what keeps this off
+ * `flatFrag`'s permutation axis, which `scripts/wgsl.ts` measures at about 247 KB gzipped.
+ */
+oit = 'none') {
+    const offset = depthOffsetForLayer(depthLayer);
+    return {
+        label: key,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            /*
+             * Selected per draw, like the fragment variant beside it — and the layout, the bind group
+             * and the cache key all carry the same flag. Building a skinned module against an unskinned
+             * 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)] ?? '',
+            }),
+            entryPoint: 'main',
+            buffers: vertexBufferLayouts(present, instanced),
+        },
+        fragment: {
+            module: shaderModule(device, {
+                label: `flat.frag:${variant}`,
+                code: FLAT_FRAG_WGSL[variant] ?? '',
+            }),
+            entryPoint: 'main',
+            targets: [
+                oitTarget(oit) ??
+                    (translucent
+                        ? {
+                            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' },
+                            },
+                        }
+                        : { format: cache.format }),
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'back' },
+        multisample: { count: cache.sampleCount },
+        /*
+         * `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,
+         * they overwrite each other, and a unit of rounding decides which survives per pixel.
+         */
+        depthStencil: {
+            format: DEPTH_FORMAT,
+            depthWriteEnabled: depthWrite,
+            depthCompare: 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
+             * that asked for no layer carries the zeroes WebGPU's default already is.
+             */
+            depthBias: offset.units,
+            depthBiasSlopeScale: offset.slope,
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The flock pass: ambient sky life, two triangles a bird, every path in the vertex shader.
+ *
+ * **The one effect in this backend that is neither blended nor additive.** A bird is opaque and
+ * writes depth like any other surface, which is what lets one pass in front of another. Nothing
+ * is culled: they are flat cards seen from both sides as they bank.
+ */
+export declare const FLOCK_VERT_FIELDS: UniformFields;
+export declare const FLOCK_VERT_SIZE: 112;
+export declare const FLOCK_FRAG_FIELDS: UniformFields;
+export declare const FLOCK_FRAG_SIZE: 16;
+/** A flock on the device, behind the surface's opaque handle. */
+export interface GpuFlock {
+    readonly corners: GPUBuffer;
+    readonly wings: GPUBuffer;
+    readonly indices: GPUBuffer;
+    readonly vertexCount: number;
+    dispose(): void;
+}
+export declare function createGpuFlock(device: GPUDevice, count: number): GpuFlock;
+/** `aCorner`, `aWing`, `aIndex` — one buffer each, as `FlockRenderer` holds them. */
+export declare function flockVertexLayouts(): GPUVertexBufferLayout[];
+export declare function createFlockBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createFlockBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * `less` and depth written, matching the flat pass: a bird is geometry in the world rather than
+ * an effect over it, and a flock that did not write depth would show every bird through every
+ * other one.
+ */
+export declare function flockPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

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

@@ -0,0 +1,129 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { FLOCK_BINDINGS, FLOCK_FRAG_WGSL, FLOCK_VERT_WGSL, } from '../../shaders/generated/flock.wgsl.js';
+import { buildFlockGeometry } from '../../flockGeometry.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The flock pass: ambient sky life, two triangles a bird, every path in the vertex shader.
+ *
+ * **The one effect in this backend that is neither blended nor additive.** A bird is opaque and
+ * writes depth like any other surface, which is what lets one pass in front of another. Nothing
+ * is culled: they are flat cards seen from both sides as they bank.
+ */
+export const FLOCK_VERT_FIELDS = FLOCK_BINDINGS.FLOCK_VERT.fields;
+export const FLOCK_VERT_SIZE = FLOCK_BINDINGS.FLOCK_VERT.uniformSize;
+export const FLOCK_FRAG_FIELDS = FLOCK_BINDINGS.FLOCK_FRAG.fields;
+export const FLOCK_FRAG_SIZE = FLOCK_BINDINGS.FLOCK_FRAG.uniformSize;
+const VERT_BINDING = FLOCK_BINDINGS.FLOCK_VERT.uniforms;
+const FRAG_BINDING = FLOCK_BINDINGS.FLOCK_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+export function createGpuFlock(device, count) {
+    const geometry = buildFlockGeometry(count);
+    const upload = (data, label) => {
+        const buffer = device.createBuffer({
+            label,
+            size: Math.max(4, data.byteLength),
+            usage: USAGE_VERTEX,
+        });
+        device.queue.writeBuffer(buffer, 0, data);
+        return buffer;
+    };
+    const corners = upload(geometry.corners, 'flock.corners');
+    const wings = upload(geometry.wings, 'flock.wings');
+    const indices = upload(geometry.indices, 'flock.indices');
+    return {
+        corners,
+        wings,
+        indices,
+        vertexCount: geometry.vertexCount,
+        dispose() {
+            corners.destroy();
+            wings.destroy();
+            indices.destroy();
+        },
+    };
+}
+/** `aCorner`, `aWing`, `aIndex` — one buffer each, as `FlockRenderer` holds them. */
+export function flockVertexLayouts() {
+    return [
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' }],
+        },
+        {
+            arrayStride: 4,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32' }],
+        },
+        {
+            arrayStride: 4,
+            attributes: [{ shaderLocation: 2, offset: 0, format: 'float32' }],
+        },
+    ];
+}
+export function createFlockBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'flock.layout',
+        entries: [
+            /*
+             * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+             *
+             * With one buffer rewritten between draws, every batch reads whatever was written last:
+             * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+             * every one of them. The picture is each batch wearing the last one's colour, width, time
+             * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+             * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+             * nothing drew two, which is exactly how water kept it for eight releases.
+             *
+             * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+             */
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLOCK_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLOCK_FRAG_SIZE },
+            },
+        ],
+    });
+}
+export function createFlockBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'flock.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: FLOCK_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: FLOCK_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * `less` and depth written, matching the flat pass: a bird is geometry in the world rather than
+ * an effect over it, and a flock that did not write depth would show every bird through every
+ * other one.
+ */
+export function flockPipeline(cache, device, layout) {
+    return cache.get('flock', () => ({
+        label: 'flock',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'flock.vert', code: FLOCK_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: flockVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'flock.frag', code: FLOCK_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [{ format: cache.format }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: DEPTH_COMPARE },
+    }));
+}