@driftengine/core 3.61.0

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

@@ -0,0 +1,140 @@
+/**
+ * Render pipelines, built once and looked up by name.
+ *
+ * **Pipeline creation is the expensive operation in WebGPU** — it compiles shaders and
+ * validates state — and `AGENTS.md` forbids allocating in a per-frame path. So a pipeline is
+ * built once per distinct state and found by a string key thereafter.
+ *
+ * The key is the caller's to build, and it must be built at construction time rather than
+ * per frame. A key assembled with template interpolation inside a draw call allocates a
+ * string sixty times a second for every draw, which is the allocation this class exists to
+ * avoid, moved rather than removed.
+ */
+export class PipelineCache {
+    /**
+     * The colour format every pipeline here targets, which is wherever the *world* lands.
+     *
+     * **Not the swap chain's, and the difference is the whole point.** Under a composite the world
+     * is drawn into the scene target and only the resolve reaches the canvas, so a pipeline built
+     * against the swap chain disagrees with its attachment — which WebGPU raises at `finish`,
+     * dropping the frame's entire command buffer. Carried here for the same reason `sampleCount`
+     * is: one number, read by every `describe` callback, so no pass can disagree with the target
+     * it is about to be used on. `webgpu/renderer.ts` chooses it, once.
+     */
+    format;
+    /**
+     * How many samples every pipeline here rasterises at.
+     *
+     * **Carried by the cache so no pipeline can disagree with the attachment.** A pipeline's
+     * sample count must equal the colour target's exactly, and WebGPU rejects the mismatch at
+     * draw time with a message about the pipeline rather than about the target — so a pass that
+     * forgot to ask would fail somewhere other than where the mistake was made. One number, read
+     * by every `describe` callback.
+     */
+    sampleCount;
+    device;
+    pipelines = new Map();
+    /**
+     * Builds still compiling, by key, so two asks for one pipeline share a compile.
+     *
+     * **`createRenderPipeline` does not compile, it defers.** It returns in microseconds and
+     * leaves the driver to finish the shader the first time something draws with it, which puts
+     * the cost inside a frame instead of before one. Measured on an S23 Ultra: twelve pipelines
+     * "built" in 3ms, then seven submits in a row each taking 5.2 seconds and all draining
+     * together, with no allocation, no long task and an idle main thread the whole time. The
+     * queue was blocked on compilation nobody had asked for yet.
+     *
+     * `createRenderPipelineAsync` is the API that exists for this. It compiles across the
+     * driver's own threads and resolves when the pipeline is genuinely ready, so a renderer can
+     * wait for readiness rather than discovering it mid-frame.
+     */
+    compiling = new Map();
+    constructor(device, format, sampleCount = 1) {
+        this.device = device;
+        this.format = format;
+        this.sampleCount = sampleCount;
+    }
+    /** How many distinct pipelines have been built. Read by tests and diagnostics. */
+    get size() {
+        return this.pipelines.size;
+    }
+    /**
+     * The pipeline for this key, compiled off the main thread.
+     *
+     * Preferred wherever the caller is not inside a frame, which `get`'s own contract says is
+     * everywhere: pipelines are built once per distinct state at construction time. The
+     * difference is only *when* the driver does the work, and that difference is the whole bug
+     * this exists for.
+     */
+    async getAsync(key, describe) {
+        const existing = this.pipelines.get(key);
+        if (existing !== undefined)
+            return existing;
+        const inFlight = this.compiling.get(key);
+        if (inFlight !== undefined)
+            return inFlight;
+        /*
+         * **Falls back where the async form is missing.** It is part of the standard, but a device
+         * can be a test double, a polyfill or an older implementation, and a renderer that throws
+         * on a device which can still draw is worse than one that compiles the slow way. The
+         * fallback keeps the same contract — a promise that resolves when the pipeline exists —
+         * so nothing above here has to know which path it got.
+         */
+        const build = typeof this.device.createRenderPipelineAsync === 'function'
+            ? this.device.createRenderPipelineAsync(describe())
+            : Promise.resolve(this.device.createRenderPipeline(describe()));
+        const promise = build.then((built) => {
+            this.pipelines.set(key, built);
+            this.compiling.delete(key);
+            return built;
+        });
+        this.compiling.set(key, promise);
+        return promise;
+    }
+    /**
+     * Resolve once every pipeline asked for so far has finished compiling.
+     *
+     * A renderer awaits this before its first frame, which is what moves the compile out of the
+     * queue and in front of it. A failure is not rethrown: a pipeline that cannot be built will
+     * fail again, loudly, at the draw that needs it, and taking the whole boot down here would
+     * turn one broken material into a blank page.
+     */
+    async ready() {
+        while (this.compiling.size > 0) {
+            await Promise.allSettled([...this.compiling.values()]);
+        }
+    }
+    /** The pipeline for this key if it is already built, without building one. */
+    peek(key) {
+        return this.pipelines.get(key);
+    }
+    /** How many are still compiling. Read by tests and diagnostics. */
+    get compilingCount() {
+        return this.compiling.size;
+    }
+    /**
+     * The pipeline for this key, building it on the first ask only.
+     *
+     * `describe` is a callback rather than a value because **building the descriptor allocates
+     * too**: a nested object with vertex buffer layouts and blend state, constructed to be
+     * thrown away on every hit. Passing a function means a hit costs one `Map` lookup.
+     */
+    get(key, describe) {
+        const existing = this.pipelines.get(key);
+        if (existing !== undefined)
+            return existing;
+        const built = this.device.createRenderPipeline(describe());
+        this.pipelines.set(key, built);
+        return built;
+    }
+    /**
+     * Drop every pipeline.
+     *
+     * WebGPU has no explicit pipeline release — they are freed when nothing references them —
+     * so this is about not handing out pipelines belonging to a destroyed device rather than
+     * about reclaiming memory here and now.
+     */
+    dispose() {
+        this.pipelines.clear();
+    }
+}

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

@@ -0,0 +1,69 @@
+import type { Vec3 } from '../../../math/color.ts';
+import { type PlumeMaterial } from '../../plumeMaterial.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import type { UniformFields } from './scatterPass.ts';
+/**
+ * The plume pass: crossed quads per plume, displaced and faded in the shaders.
+ *
+ * **Two blend modes and one geometry.** A flame adds light and smoke occludes it, which is the
+ * `PlumeBlend` the options carry; everything else about the two is the fragment stage. Neither
+ * writes depth — a soft quad that did would punch a hole in whatever came after it.
+ */
+/** The vertex stage is shared by every plume material; only the fragment differs. */
+export declare const PLUME_VERT_FIELDS: UniformFields;
+export declare const PLUME_VERT_SIZE: 112;
+export declare const PLUME_FRAG_FIELDS: UniformFields;
+export declare const PLUME_FRAG_SIZE: number;
+/** Each material's own block, so a change to one and not the others is caught rather than assumed. */
+export declare const FIRE_FRAG_SIZE: 128;
+export declare const SMOKE_FRAG_SIZE: 128;
+export declare const ARCANE_FRAG_SIZE: 144;
+export declare function plumeVertexLayouts(): GPUVertexBufferLayout[];
+/** Plume geometry on the device, behind the surface's opaque handle. */
+export interface GpuPlumes {
+    readonly vertexBuffers: readonly GPUBuffer[];
+    readonly indexBuffer: GPUBuffer;
+    readonly indexCount: number;
+    readonly material: PlumeMaterial;
+    readonly blend: 'additive' | 'alpha';
+    readonly sizePulse: number;
+    readonly windResponse: number;
+    /**
+     * Colour handed to the fragment stage as `uTint`, white when the caller named none.
+     *
+     * **Held per batch because it is a batch's property, and written on every draw because the
+     * block comes out of a ring.** `PlumeRenderer` has carried this since before the second
+     * backend and this path dropped it on the floor: `createPlumes` never read `options.tint`,
+     * so the one material that reads the uniform would have drawn with a tint of zero — which,
+     * being additive, is not a wrong colour but an invisible one.
+     */
+    readonly tint: Vec3;
+    /**
+     * Scale one plume, 0 to hide it. See `PlumeRenderer.setScale`, which this mirrors.
+     *
+     * Writes only that plume's own vertices, so turning a slick's fire on costs a handful of
+     * floats rather than a re-upload of the batch.
+     */
+    setScale(index: number, scale: number): void;
+    dispose(): void;
+}
+/** The five attribute streams a plume batch is built from, already laid out by the caller. */
+export interface PlumeGeometry {
+    readonly centers: Float32Array;
+    readonly corners: Float32Array;
+    readonly sizes: Float32Array;
+    readonly seeds: Float32Array;
+    readonly blades: Float32Array;
+    readonly indices: Uint32Array;
+}
+export declare function createGpuPlumes(device: GPUDevice, geometry: PlumeGeometry, material: PlumeMaterial, blend: 'additive' | 'alpha', sizePulse: number, windResponse: number, tint: Vec3): GpuPlumes;
+export declare function createPlumeBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/** Both buffers are rings; the slot each draw takes arrives as a dynamic offset. */
+export declare function createPlumeBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline for one material and blend.
+ *
+ * **Depth tested, never written.** These are soft quads drawn after the opaque scene; writing
+ * depth would let a puff occlude something behind it that should have shown through.
+ */
+export declare function plumePipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, material: PlumeMaterial, blend: 'additive' | 'alpha'): GPURenderPipeline;

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

@@ -0,0 +1,213 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { PLUME_VERTS } from '../../plumeGeometry.js';
+import { plumeShaders } from '../../plumeMaterial.js';
+import { ARCANE_BINDINGS } from '../../shaders/generated/arcane.wgsl.js';
+import { FIRE_BINDINGS } from '../../shaders/generated/fire.wgsl.js';
+import { SMOKE_BINDINGS } from '../../shaders/generated/smoke.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The plume pass: crossed quads per plume, displaced and faded in the shaders.
+ *
+ * **Two blend modes and one geometry.** A flame adds light and smoke occludes it, which is the
+ * `PlumeBlend` the options carry; everything else about the two is the fragment stage. Neither
+ * writes depth — a soft quad that did would punch a hole in whatever came after it.
+ */
+/** The vertex stage is shared by every plume material; only the fragment differs. */
+export const PLUME_VERT_FIELDS = FIRE_BINDINGS.PLUME_VERT.fields;
+export const PLUME_VERT_SIZE = FIRE_BINDINGS.PLUME_VERT.uniformSize;
+/*
+ * **The blocks are not all the same shape, and the widest one sizes the binding.**
+ *
+ * Fire and smoke are 128 bytes over the same fourteen fields. Arcane is 144 over the same
+ * fourteen plus `uTint`, at the same offsets for the shared ones — which is asserted below
+ * rather than assumed, because a generator that moved one would put a field where this writer
+ * does not look.
+ *
+ * **Sizing this to fire's block is a pipeline that does not build.** Measured on an RX 9070 XT
+ * through radv, against the device rather than the specification: *"The shader uses more bytes
+ * of the buffer (144) than the layout's minBindingSize (128)"*, raised while validating
+ * `@group(0) @binding(1)`. That lands on `createRenderPipeline`, so by the 2026-08-14 rule the
+ * cost is not a wrong picture, it is no picture — the arcane plumes simply never draw and the
+ * command buffer they were recorded into dies with them. A binding wider than a shader needs is
+ * valid in the other direction, so one size serves all three.
+ */
+export const PLUME_FRAG_FIELDS = ARCANE_BINDINGS.ARCANE_FRAG.fields;
+export const PLUME_FRAG_SIZE = Math.max(FIRE_BINDINGS.FIRE_FRAG.uniformSize, SMOKE_BINDINGS.SMOKE_FRAG.uniformSize, ARCANE_BINDINGS.ARCANE_FRAG.uniformSize);
+const VERT_BINDING = FIRE_BINDINGS.PLUME_VERT.uniforms;
+const FRAG_BINDING = FIRE_BINDINGS.FIRE_FRAG.uniforms;
+/** Each material's own block, so a change to one and not the others is caught rather than assumed. */
+export const FIRE_FRAG_SIZE = FIRE_BINDINGS.FIRE_FRAG.uniformSize;
+export const SMOKE_FRAG_SIZE = SMOKE_BINDINGS.SMOKE_FRAG.uniformSize;
+export const ARCANE_FRAG_SIZE = ARCANE_BINDINGS.ARCANE_FRAG.uniformSize;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+/** `aCenter`, `aCorner`, `aSize`, `aSeed`, `aBlade` — one buffer each, as the GL path holds them. */
+const ATTRIBUTES = [
+    { location: 0, floats: 3 },
+    { location: 1, floats: 2 },
+    { location: 2, floats: 2 },
+    { location: 3, floats: 1 },
+    { location: 4, floats: 1 },
+];
+const FORMATS = {
+    1: 'float32',
+    2: 'float32x2',
+    3: 'float32x3',
+};
+export function plumeVertexLayouts() {
+    return ATTRIBUTES.map((a) => ({
+        arrayStride: a.floats * 4,
+        stepMode: 'vertex',
+        attributes: [
+            { shaderLocation: a.location, offset: 0, format: FORMATS[a.floats] },
+        ],
+    }));
+}
+export function createGpuPlumes(device, geometry, material, blend, sizePulse, windResponse, tint) {
+    const buffers = [];
+    const streams = [
+        geometry.centers,
+        geometry.corners,
+        geometry.sizes,
+        geometry.seeds,
+        geometry.blades,
+    ];
+    for (let i = 0; i < streams.length; i++) {
+        const data = streams[i];
+        const buffer = device.createBuffer({
+            label: `plume.attr${i}`,
+            size: Math.max(4, data.byteLength),
+            usage: USAGE_VERTEX,
+        });
+        device.queue.writeBuffer(buffer, 0, data);
+        buffers.push(buffer);
+    }
+    const indexBuffer = device.createBuffer({
+        label: 'plume.indices',
+        size: Math.max(4, geometry.indices.byteLength),
+        usage: USAGE_INDEX,
+    });
+    device.queue.writeBuffer(indexBuffer, 0, geometry.indices);
+    /*
+     * The sizes are kept on the CPU as well as uploaded, and the originals beside them, because
+     * `setScale` multiplies the *base* size rather than the current one — scaling a scaled plume
+     * would compound, and a slick cycling on and off would shrink to nothing.
+     */
+    const sizes = Float32Array.from(geometry.sizes);
+    const baseSizes = Float32Array.from(geometry.sizes);
+    const sizeBuffer = buffers[2];
+    return {
+        vertexBuffers: buffers,
+        indexBuffer,
+        indexCount: geometry.indices.length,
+        material,
+        blend,
+        sizePulse,
+        windResponse,
+        tint,
+        setScale(index, scale) {
+            const span = PLUME_VERTS * 2;
+            const base = index * span;
+            if (base < 0 || base + span > sizes.length)
+                return;
+            const width = baseSizes[index * 2] ?? 0;
+            const height = baseSizes[index * 2 + 1] ?? 0;
+            for (let c = 0; c < PLUME_VERTS; c++) {
+                sizes[base + c * 2] = width * scale;
+                sizes[base + c * 2 + 1] = height * scale;
+            }
+            device.queue.writeBuffer(sizeBuffer, base * 4, sizes, base, span);
+        },
+        dispose() {
+            for (const b of buffers)
+                b.destroy();
+            indexBuffer.destroy();
+        },
+    };
+}
+export function createPlumeBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'plume.layout',
+        entries: [
+            /*
+             * **Both blocks are per draw, and that is a bug fix rather than a precaution.**
+             * `sizePulse` and `windResponse` belong to the batch, not the frame — a flame is
+             * `0.12` and the smoke above it `1.35` — and a scene draws both in one pass. With one
+             * buffer per block the second `writeBuffer` won for both draws, so the flame was bent
+             * by the smoke's wind response: a fire leaning forty degrees in still air, on a scene
+             * whose every other surface matched to the byte. See `UniformRing`.
+             */
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PLUME_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PLUME_FRAG_SIZE },
+            },
+        ],
+    });
+}
+/** Both buffers are rings; the slot each draw takes arrives as a dynamic offset. */
+export function createPlumeBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'plume.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: PLUME_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: PLUME_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The blend each material wants.
+ *
+ * **Additive keeps the source alpha out of the destination factor** — a flame is light added
+ * to what is behind it, and multiplying that by one-minus-alpha would make a bright flame
+ * darken the wall behind it. Alpha is the ordinary over-operator smoke wants.
+ */
+function blendState(blend) {
+    return blend === 'additive'
+        ? {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+            alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+        }
+        : {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        };
+}
+/**
+ * The pipeline for one material and blend.
+ *
+ * **Depth tested, never written.** These are soft quads drawn after the opaque scene; writing
+ * depth would let a puff occlude something behind it that should have shown through.
+ */
+export function plumePipeline(cache, device, layout, material, blend) {
+    const shaders = plumeShaders(material);
+    return cache.get(`plume:${material}:${blend}`, () => ({
+        label: `plume:${material}`,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'plume.vert', code: shaders.vertexWgsl }),
+            entryPoint: 'main',
+            buffers: plumeVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, {
+                label: `plume.frag:${material}`,
+                code: shaders.fragmentWgsl,
+            }),
+            entryPoint: 'main',
+            targets: [{ format: cache.format, blend: blendState(blend) }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

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

@@ -0,0 +1,88 @@
+import { type mat4 } from 'gl-matrix';
+import { type PointShadowSource } from '../../pointShadowImage.ts';
+/**
+ * Every point light's shadow as one array texture, and the scratch that fills it.
+ *
+ * The WebGPU half of `pointShadowArray.ts`; the reasoning lives there, and this is one texture,
+ * one scratch and a pipeline. **The scratch is a separate texture on this backend too**, and not
+ * for WebGL2's reason: WebGPU rejects a pass outright for holding a texture it is also sampling,
+ * where WebGL2 raises `INVALID_OPERATION` at the draw. Two ways of saying the same thing, and
+ * both say the resolve reads the scratch.
+ */
+export declare class GpuPointShadowArray {
+    /** The array, as the shader samples it. */
+    readonly view: GPUTextureView;
+    readonly layers: number;
+    /** Where a face is rendered before it is resolved. One, shared by every light. */
+    readonly scratchView: GPUTextureView;
+    private readonly texture;
+    private readonly scratch;
+    private readonly layerViews;
+    private readonly pipeline;
+    private readonly bindGroup;
+    /**
+     * A slot per resolved face, not one buffer written six times.
+     *
+     * **`queue.writeBuffer` does not interleave with encoded commands.** Writes are ordered on
+     * the queue timeline and the encoder is submitted afterwards, so six writes between six
+     * passes give all six passes the *last* face's rotation and index — and five of them then
+     * discard every fragment, because `uFaceIndex` does not match. The layer stays empty and the
+     * light stops casting, which reads as a lighting change rather than as a missing upload.
+     *
+     * That is the failure `UniformRing` exists for, described in its own header, and this file
+     * reproduced it exactly. Found by capturing: WebGPU diverged from WebGL2 by seven times and
+     * came out *brighter*, and flipping a coordinate in the resolve changed the frame by not one
+     * pixel — which is what an empty map looks like.
+     */
+    private readonly ring;
+    constructor(device: GPUDevice, faceSize: number, lightCount: number, 
+    /** Layers above the point pool, for a world's casting rectangles. See `pointShadowArray.ts`. */
+    extraLayers?: number);
+    /**
+     * Write the scratch's contents into `layer`'s region for `face`.
+     *
+     * A pass of its own on the caller's encoder, with `load` rather than `clear`: the other five
+     * faces of this layer are already there and must survive. `discard` in the shader is what
+     * keeps this face to its own region.
+     */
+    resolve(encoder: GPUCommandEncoder, layer: number, face: number, far: number, near: number): void;
+    /** Start a frame's bakes. See the ring: slots are reused and nothing is freed. */
+    beginFrame(): void;
+    /** Upload every slot this frame's resolves took, in one write, before the encoder is submitted. */
+    flush(): void;
+    dispose(): void;
+}
+/** What a face's pass needs from the caller: somewhere to record, and the casters to record. */
+export type PointShadowFacePass = (view: GPUTextureView, viewProj: mat4) => void;
+/** And what turns that face into its region of the light's octahedral layer. */
+export type PointShadowResolve = (layer: number, face: number, far: number, near: number) => void;
+export declare class GpuPointShadowMap implements PointShadowSource {
+    readonly size: number;
+    /** Which layer of the shared array this map's image lives in. See `pointShadowMap.ts`. */
+    readonly layer: number;
+    private readonly array;
+    private readonly image;
+    private readonly range;
+    constructor(array: () => GpuPointShadowArray | null, layer: number, size: number);
+    get far(): number;
+    get near(): number;
+    get sourceRadius(): number;
+    get hasBaked(): boolean;
+    get presence(): number;
+    matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius?: number, tolerance?: number): boolean;
+    advance(dt: number): void;
+    forget(): void;
+    /**
+     * Render up to `maxFaces` of the six, resuming a bake already under way.
+     *
+     * Returns how many faces were rendered. `renderFace` is handed the attachment and the face's
+     * view-projection and is expected to open a pass and draw the casters into it — the renderer
+     * owns the encoder and the pipelines, so it owns the pass.
+     *
+     * The scratch matrix is the caller's for the same reason `pointShadowFaceViewProj` takes one:
+     * this runs once per face of every bake and `AGENTS.md` allows no allocation there.
+     */
+    bake(x: number, y: number, z: number, range: number, renderFace: PointShadowFacePass, resolveFace: PointShadowResolve, scratch: mat4, near?: number, sourceRadius?: number, maxFaces?: number): number;
+    /** Nothing to free: every GPU object belongs to `GpuPointShadowArray` now. */
+    dispose(): void;
+}