@driftengine/core 4.4.2 → 4.6.0

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

@@ -0,0 +1,491 @@
+/**
+ * Where every mover was last frame, drawn into the reconstruction's motion target.
+ *
+ * Moved out of `renderer.ts` when it grew variants: the renderer decides *which* draws moved and
+ * hands them here; this owns how their motion is drawn. See `shaders/recon/motion.wgsl.ts` for what
+ * a texel carries, why it is a pass of its own, and why its matrices are unjittered.
+ */
+import { DEPTH_COMPARE_EQUAL, DEPTH_FORMAT } from '../../depthConvention.js';
+import { MOTION_DRAW_FLOATS, MOTION_DRAW_STRIDE, MOTION_FRAME_FLOATS, MOTION_TARGET_FORMAT, RECON_MOTION_WGSL, } from '../../shaders/recon/motion.wgsl.js';
+import { INSTANCE_STRIDE } from '../../instances.js';
+/** What a record is, which decides the vertex stage and what else it binds. */
+const RIGID = 0;
+const SKINNED = 1;
+const DYNAMIC = 2;
+const INSTANCED = 3;
+/** An instanced record's per-draw matrices are not read; this fills their slot. */
+const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+export class MotionPass {
+    device;
+    /** The frame's movers, in the order they were drawn. */
+    meshes = [];
+    /** Two matrices a mover — this frame's model and last frame's — at `MOTION_DRAW_FLOATS` apart. */
+    matrices = new Float32Array(0);
+    count = 0;
+    /** `RIGID` or `SKINNED` per record, grown beside `matrices`. */
+    kinds = new Uint8Array(0);
+    /** A skinned record's two palettes, this frame's and last frame's, by record index. */
+    paletteNow = [];
+    paletteWas = [];
+    /** A rewritten record's last-frame rows, by record index. */
+    previousRows = [];
+    /** One pipeline per stride for rewritten meshes: current and previous rows at that stride. */
+    dynamicPipelines = new Map();
+    /** An instanced record's placement this frame and last frame, and how many slots pair. */
+    instancesNow = [];
+    instancesWas = [];
+    instanceCounts = new Uint32Array(0);
+    instancedPipelines = new Map();
+    layout = null;
+    paletteLayout = null;
+    skinnedLayout = null;
+    /** Keyed by stride and the two skin offsets, packed into one number so a lookup builds nothing. */
+    skinnedPipelines = new Map();
+    /**
+     * A bind group per pair of palette views. The ring keeps its textures from frame to frame, so a
+     * steady scene settles on a handful of pairs and builds nothing per frame.
+     */
+    paletteGroups = new Map();
+    module = null;
+    pipelineLayout = null;
+    pipelines = new Map();
+    frameBuffer = null;
+    drawBuffer = null;
+    drawCapacity = 0;
+    group = null;
+    frameStaging = new Float32Array(MOTION_FRAME_FLOATS);
+    drawStaging = new Uint8Array(0);
+    /** A float view of `drawStaging`, made when it is, so a frame's upload allocates nothing. */
+    drawFloats = new Float32Array(0);
+    constructor(device) {
+        this.device = device;
+    }
+    /** A frame states its movers afresh. */
+    reset() {
+        this.count = 0;
+    }
+    /** A rigid mover: the same positions under last frame's model. */
+    recordRigid(mesh, model, previousModel) {
+        this.take(mesh, model, previousModel, RIGID);
+    }
+    /** A skinned mover: its positions under last frame's pose as well as last frame's model. */
+    recordSkinned(mesh, model, previousModel, palette, previousPalette) {
+        const at = this.take(mesh, model, previousModel, SKINNED);
+        this.paletteNow[at] = palette;
+        this.paletteWas[at] = previousPalette;
+    }
+    /** A rewritten mesh: its vertices as they were, read from `previous`, under last frame's model. */
+    recordDynamic(mesh, model, previousModel, previous) {
+        const at = this.take(mesh, model, previousModel, DYNAMIC);
+        this.previousRows[at] = previous;
+    }
+    /** An instanced batch: its first `count` slots, each under last frame's placement of that slot. */
+    recordInstanced(mesh, placement, previousPlacement, count) {
+        const at = this.take(mesh, IDENTITY, IDENTITY, INSTANCED);
+        this.instancesNow[at] = placement;
+        this.instancesWas[at] = previousPlacement;
+        this.instanceCounts[at] = count;
+    }
+    /** One record's slot: its mesh, its two matrices and its kind. Returns the record's index. */
+    take(mesh, model, previousModel, kind) {
+        const at = this.count;
+        const wanted = (at + 1) * MOTION_DRAW_FLOATS;
+        if (this.matrices.length < wanted) {
+            /* Doubling, so a scene settles on one allocation rather than one a draw. */
+            const grown = new Float32Array(Math.max(wanted, this.matrices.length * 2, 64));
+            grown.set(this.matrices);
+            this.matrices = grown;
+            const kinds = new Uint8Array(grown.length / MOTION_DRAW_FLOATS);
+            kinds.set(this.kinds);
+            this.kinds = kinds;
+            const counts = new Uint32Array(kinds.length);
+            counts.set(this.instanceCounts);
+            this.instanceCounts = counts;
+        }
+        this.matrices.set(model, at * MOTION_DRAW_FLOATS);
+        this.matrices.set(previousModel, at * MOTION_DRAW_FLOATS + 16);
+        this.meshes[at] = mesh;
+        this.kinds[at] = kind;
+        this.count = at + 1;
+        return at;
+    }
+    /**
+     * The pipeline layout and module, built once.
+     *
+     * **The position alone**, at offset zero of the mesh's interleaved rows: that is all the rigid
+     * stage reads, and positions are the layout's first attribute and never optional.
+     */
+    buildLayout() {
+        if (this.layout !== null)
+            return;
+        this.layout = this.device.createBindGroupLayout({
+            label: 'recon.motion.layout',
+            entries: [
+                { binding: 0, visibility: 0x1, buffer: { type: 'uniform' } },
+                {
+                    binding: 1,
+                    visibility: 0x1,
+                    buffer: { type: 'uniform', hasDynamicOffset: true },
+                },
+            ],
+        });
+        this.module = this.device.createShaderModule({
+            label: 'recon.motion',
+            code: RECON_MOTION_WGSL,
+        });
+        this.pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.layout],
+        });
+        /* The two palettes, read with `textureLoad` at integer texels: unfilterable is exact. */
+        this.paletteLayout = this.device.createBindGroupLayout({
+            label: 'recon.motion.palettes',
+            entries: [
+                { binding: 0, visibility: 0x1, texture: { sampleType: 'unfilterable-float' } },
+                { binding: 1, visibility: 0x1, texture: { sampleType: 'unfilterable-float' } },
+            ],
+        });
+        this.skinnedLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.layout, this.paletteLayout],
+        });
+    }
+    /**
+     * The skinned pipeline for one stride and one placement of the joints and weights in it.
+     *
+     * Same fragment stage, winding and depth test as the rigid one — see `pipelineFor` — with the two
+     * skinning attributes read from the interleaved rows at the offsets the mesh records.
+     */
+    skinnedPipelineFor(stride, offsets) {
+        const key = (stride * 4096 + offsets.joints) * 4096 + offsets.weights;
+        const held = this.skinnedPipelines.get(key);
+        if (held !== undefined)
+            return held;
+        const module = this.module;
+        const layout = this.skinnedLayout;
+        if (module === null || layout === null)
+            return null;
+        const pipeline = this.device.createRenderPipeline({
+            label: `recon.motion.skinned.${String(stride)}`,
+            layout,
+            vertex: {
+                module,
+                entryPoint: 'motionSkinnedVert',
+                buffers: [
+                    {
+                        arrayStride: stride,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+                            { shaderLocation: 11, offset: offsets.joints, format: 'float32x4' },
+                            { shaderLocation: 12, offset: offsets.weights, format: 'float32x4' },
+                        ],
+                    },
+                ],
+            },
+            fragment: { module, entryPoint: 'motionFrag', targets: [{ format: MOTION_TARGET_FORMAT }] },
+            primitive: { topology: 'triangle-list', cullMode: 'back' },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: DEPTH_COMPARE_EQUAL,
+            },
+        });
+        this.skinnedPipelines.set(key, pipeline);
+        return pipeline;
+    }
+    /** The rewritten pipeline for one stride: position from each of two buffers of that stride. */
+    dynamicPipelineFor(stride) {
+        const held = this.dynamicPipelines.get(stride);
+        if (held !== undefined)
+            return held;
+        const module = this.module;
+        const layout = this.pipelineLayout;
+        if (module === null || layout === null)
+            return null;
+        const pipeline = this.device.createRenderPipeline({
+            label: `recon.motion.dynamic.${String(stride)}`,
+            layout,
+            vertex: {
+                module,
+                entryPoint: 'motionDynamicVert',
+                buffers: [
+                    {
+                        arrayStride: stride,
+                        attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+                    },
+                    {
+                        arrayStride: stride,
+                        attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }],
+                    },
+                ],
+            },
+            fragment: { module, entryPoint: 'motionFrag', targets: [{ format: MOTION_TARGET_FORMAT }] },
+            primitive: { topology: 'triangle-list', cullMode: 'back' },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: DEPTH_COMPARE_EQUAL,
+            },
+        });
+        this.dynamicPipelines.set(stride, pipeline);
+        return pipeline;
+    }
+    /**
+     * The instanced pipeline for one mesh stride: the mesh's positions, then this frame's and last
+     * frame's placements, one matrix an instance, as the scene's instanced stage reads them.
+     */
+    instancedPipelineFor(stride) {
+        const held = this.instancedPipelines.get(stride);
+        if (held !== undefined)
+            return held;
+        const module = this.module;
+        const layout = this.pipelineLayout;
+        if (module === null || layout === null)
+            return null;
+        const placement = (first) => ({
+            arrayStride: INSTANCE_STRIDE,
+            stepMode: 'instance',
+            attributes: [
+                { shaderLocation: first, offset: 0, format: 'float32x4' },
+                { shaderLocation: first + 1, offset: 16, format: 'float32x4' },
+                { shaderLocation: first + 2, offset: 32, format: 'float32x4' },
+                { shaderLocation: first + 3, offset: 48, format: 'float32x4' },
+            ],
+        });
+        const pipeline = this.device.createRenderPipeline({
+            label: `recon.motion.instanced.${String(stride)}`,
+            layout,
+            vertex: {
+                module,
+                entryPoint: 'motionInstancedVert',
+                buffers: [
+                    {
+                        arrayStride: stride,
+                        attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+                    },
+                    placement(2),
+                    placement(6),
+                ],
+            },
+            fragment: { module, entryPoint: 'motionFrag', targets: [{ format: MOTION_TARGET_FORMAT }] },
+            primitive: { topology: 'triangle-list', cullMode: 'back' },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: false,
+                depthCompare: DEPTH_COMPARE_EQUAL,
+            },
+        });
+        this.instancedPipelines.set(stride, pipeline);
+        return pipeline;
+    }
+    /** The bind group holding one pair of palettes, built the first time the pair is seen. */
+    paletteGroup(now, was) {
+        const layout = this.paletteLayout;
+        if (layout === null)
+            return null;
+        let byWas = this.paletteGroups.get(now);
+        if (byWas === undefined) {
+            byWas = new Map();
+            this.paletteGroups.set(now, byWas);
+        }
+        let group = byWas.get(was);
+        if (group === undefined) {
+            group = this.device.createBindGroup({
+                label: 'recon.motion.palettes',
+                layout,
+                entries: [
+                    { binding: 0, resource: now },
+                    { binding: 1, resource: was },
+                ],
+            });
+            byWas.set(was, group);
+        }
+        return group;
+    }
+    /** The pipeline for one vertex stride, built on first sight of it. */
+    pipelineFor(stride) {
+        const held = this.pipelines.get(stride);
+        if (held !== undefined)
+            return held;
+        const module = this.module;
+        const layout = this.pipelineLayout;
+        if (module === null || layout === null)
+            return null;
+        const pipeline = this.device.createRenderPipeline({
+            label: `recon.motion.${String(stride)}`,
+            layout,
+            vertex: {
+                module,
+                entryPoint: 'motionVert',
+                buffers: [
+                    {
+                        arrayStride: stride,
+                        attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+                    },
+                ],
+            },
+            fragment: { module, entryPoint: 'motionFrag', targets: [{ format: MOTION_TARGET_FORMAT }] },
+            /*
+             * **The scene's own winding**, because this draws the scene's geometry through the scene's
+             * clip transform — the product the renderer hands over already carries the negation that
+             * `naga` writes into every generated vertex stage, so the faces come out the way they did
+             * and a `cw` front face here would draw the inside of every mesh. §3 row 57.
+             */
+            primitive: { topology: 'triangle-list', cullMode: 'back' },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                /*
+                 * **Tested and not written.** The frame's depth is finished; this pass only wants the
+                 * pixels the scene actually kept, and `DEPTH_COMPARE_EQUAL` is the comparison that admits
+                 * exactly them — the same transform on the same positions gives the same depth, which is
+                 * why the rasterisation matrix is handed over whole rather than rebuilt here.
+                 *
+                 * **And the equality is not fragile here**, which was worth measuring rather than
+                 * assuming: this driver contracts multiply-adds (§3 row 107) and two shader modules can
+                 * contract a matrix product differently, so an equality across them could have admitted
+                 * only some of a surface. Run with `greater-equal` instead, the ghost measured the same
+                 * to the pixel — 5,942 either way — so nothing is being dropped.
+                 */
+                depthWriteEnabled: false,
+                depthCompare: DEPTH_COMPARE_EQUAL,
+            },
+        });
+        this.pipelines.set(stride, pipeline);
+        return pipeline;
+    }
+    /**
+     * Every mover of the frame, into `target`, tested against the finished `depth`.
+     *
+     * **After everything that draws and before the resolve reads it.** `raster` is the scene's clip
+     * transform with the generated stages' y negation folded in; `viewProj` and `previousViewProj`
+     * are this frame's and last frame's unjittered view-projections.
+     *
+     * **Cleared every frame, even when nothing moved.** A texel left from last frame is a flag saying
+     * "a draw wrote this", and the resolve would take a motion belonging to a surface that is no
+     * longer there. The clear is the pass's own load operation, so an empty frame still runs it.
+     */
+    run(encoder, target, depth, raster, viewProj, previousViewProj, timestampWrites) {
+        this.buildLayout();
+        const layout = this.layout;
+        if (layout === null)
+            return;
+        const pass = encoder.beginRenderPass({
+            label: 'recon.motion',
+            timestampWrites,
+            colorAttachments: [
+                { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+            depthStencilAttachment: {
+                view: depth,
+                depthLoadOp: 'load',
+                depthStoreOp: 'store',
+                depthReadOnly: false,
+            },
+        });
+        const count = this.count;
+        if (count > 0) {
+            const bytes = count * MOTION_DRAW_STRIDE;
+            if (this.drawCapacity < count) {
+                this.drawBuffer?.destroy();
+                this.drawCapacity = Math.max(count, this.drawCapacity * 2, 16);
+                this.drawBuffer = this.device.createBuffer({
+                    label: 'recon.motion.draws',
+                    size: this.drawCapacity * MOTION_DRAW_STRIDE,
+                    usage: 0x40 | 0x8, // UNIFORM | COPY_DST
+                });
+                this.drawStaging = new Uint8Array(this.drawCapacity * MOTION_DRAW_STRIDE);
+                this.drawFloats = new Float32Array(this.drawStaging.buffer);
+                this.group = null;
+            }
+            this.frameBuffer ??= this.device.createBuffer({
+                label: 'recon.motion.frame',
+                size: MOTION_FRAME_FLOATS * 4,
+                usage: 0x40 | 0x8,
+            });
+            this.group ??= this.device.createBindGroup({
+                label: 'recon.motion.group',
+                layout,
+                entries: [
+                    { binding: 0, resource: { buffer: this.frameBuffer } },
+                    {
+                        binding: 1,
+                        resource: { buffer: this.drawBuffer, size: MOTION_DRAW_STRIDE },
+                    },
+                ],
+            });
+            this.frameStaging.set(raster, 0);
+            this.frameStaging.set(viewProj, 16);
+            this.frameStaging.set(previousViewProj, 32);
+            this.device.queue.writeBuffer(this.frameBuffer, 0, this.frameStaging);
+            /* Copied a float at a time rather than through `subarray`, which is a view allocated per
+               mover per frame. */
+            for (let i = 0; i < count; i += 1) {
+                const from = i * MOTION_DRAW_FLOATS;
+                const to = (i * MOTION_DRAW_STRIDE) / 4;
+                for (let k = 0; k < MOTION_DRAW_FLOATS; k += 1) {
+                    this.drawFloats[to + k] = this.matrices[from + k];
+                }
+            }
+            this.device.queue.writeBuffer(this.drawBuffer, 0, this.drawStaging, 0, bytes);
+            let bound = null;
+            for (let i = 0; i < count; i += 1) {
+                const mesh = this.meshes[i];
+                if (mesh === undefined)
+                    continue;
+                const kind = this.kinds[i];
+                let pipeline = null;
+                let instances = 1;
+                if (kind === INSTANCED) {
+                    const now = this.instancesNow[i] ?? null;
+                    const was = this.instancesWas[i] ?? null;
+                    if (now === null || was === null)
+                        continue;
+                    pipeline = this.instancedPipelineFor(mesh.vertexStride);
+                    pass.setVertexBuffer(1, now);
+                    pass.setVertexBuffer(2, was);
+                    instances = this.instanceCounts[i] ?? 0;
+                }
+                else if (kind === DYNAMIC) {
+                    const previous = this.previousRows[i] ?? null;
+                    if (previous === null)
+                        continue;
+                    pipeline = this.dynamicPipelineFor(mesh.vertexStride);
+                    pass.setVertexBuffer(1, previous);
+                }
+                else if (kind === SKINNED) {
+                    const offsets = mesh.skinOffsets;
+                    const now = this.paletteNow[i] ?? null;
+                    const was = this.paletteWas[i] ?? null;
+                    if (offsets === null || now === null || was === null)
+                        continue;
+                    pipeline = this.skinnedPipelineFor(mesh.vertexStride, offsets);
+                    const palettes = this.paletteGroup(now, was);
+                    if (pipeline === null || palettes === null)
+                        continue;
+                    pass.setBindGroup(1, palettes);
+                }
+                else {
+                    pipeline = this.pipelineFor(mesh.vertexStride);
+                }
+                if (pipeline === null)
+                    continue;
+                if (pipeline !== bound) {
+                    pass.setPipeline(pipeline);
+                    bound = pipeline;
+                }
+                pass.setBindGroup(0, this.group, [i * MOTION_DRAW_STRIDE]);
+                pass.setVertexBuffer(0, mesh.vertexBuffers[0]);
+                pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
+                pass.drawIndexed(mesh.indexCount, instances);
+            }
+        }
+        pass.end();
+    }
+    dispose() {
+        this.paletteGroups.clear();
+        this.frameBuffer?.destroy();
+        this.drawBuffer?.destroy();
+        this.frameBuffer = null;
+        this.drawBuffer = null;
+        this.drawCapacity = 0;
+        this.group = null;
+    }
+}

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

@@ -32,6 +32,15 @@ export declare class PipelineCache {
      * by every `describe` callback.
      */
     readonly sampleCount: number;
+    /**
+     * Whether the lit pipelines here read glass in their shadows: `glassShadows` other than `'off'`.
+     *
+     * **Carried by the cache for the reason the format is**: one value every lit pipeline is built
+     * with, chosen once by the renderer. It is the `GLASS_SHADOWS` override the generated lit shader
+     * branches on (see `FlatShaderOptions.glassShadows`), so off specialises the lookups away rather
+     * than leaving code that returns at its first line and still costs the pass its registers.
+     */
+    readonly glassShadows: boolean;
     private readonly device;
     private readonly pipelines;
     /**
@@ -49,7 +58,7 @@ export declare class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     private readonly compiling;
-    constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number);
+    constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number, glassShadows?: boolean);
     /** How many distinct pipelines have been built. Read by tests and diagnostics. */
     get size(): number;
     /**

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

@@ -32,6 +32,15 @@ export class PipelineCache {
      * by every `describe` callback.
      */
     sampleCount;
+    /**
+     * Whether the lit pipelines here read glass in their shadows: `glassShadows` other than `'off'`.
+     *
+     * **Carried by the cache for the reason the format is**: one value every lit pipeline is built
+     * with, chosen once by the renderer. It is the `GLASS_SHADOWS` override the generated lit shader
+     * branches on (see `FlatShaderOptions.glassShadows`), so off specialises the lookups away rather
+     * than leaving code that returns at its first line and still costs the pass its registers.
+     */
+    glassShadows;
     device;
     pipelines = new Map();
     /**
@@ -49,10 +58,11 @@ export class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     compiling = new Map();
-    constructor(device, format, sampleCount = 1) {
+    constructor(device, format, sampleCount = 1, glassShadows = true) {
         this.device = device;
         this.format = format;
         this.sampleCount = sampleCount;
+        this.glassShadows = glassShadows;
     }
     /** How many distinct pipelines have been built. Read by tests and diagnostics. */
     get size() {

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

@@ -0,0 +1,32 @@
+import type { MipPipelines } from './surfaceTexturePass.ts';
+export declare class GpuPointGlassTint {
+    readonly texture: GPUTexture;
+    /** The whole array, for the lit pass. */
+    readonly view: GPUTextureView;
+    /** The colour scratch a face's glass is multiplied into. */
+    readonly scratchView: GPUTextureView;
+    readonly edge: number;
+    private readonly device;
+    private readonly pipelines;
+    private readonly scratch;
+    private readonly layerViews;
+    private readonly mips;
+    private readonly pipeline;
+    private readonly bindGroup;
+    private readonly ring;
+    private readonly heldFaces;
+    private readonly dirty;
+    constructor(device: GPUDevice, pipelines: MipPipelines, faceSize: number, edge: number, layers: number, 
+    /** Resolves a frame can make: the array's own figure, since every face resolves once. */
+    slots: number, encoder: GPUCommandEncoder);
+    /** Whether `face` of `layer` holds glass: a face that does must be cleared before it is reused. */
+    held(layer: number, face: number): boolean;
+    /** Copy the colour scratch into `face`'s region of `layer`, and remember whether it held glass. */
+    resolve(encoder: GPUCommandEncoder, layer: number, face: number, drawn: boolean): void;
+    /** The chain frost reads, for every layer touched since the last call. */
+    recordMips(encoder: GPUCommandEncoder): void;
+    beginFrame(): void;
+    /** Before the round's submit: the slots are written and must be up before any pass reads. */
+    flush(): void;
+    dispose(): void;
+}