@driftengine/core 4.4.2 → 4.6.0

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

@@ -0,0 +1,144 @@
+/**
+ * Instance culls on the device: a batch's instances tested against a view and compacted into an
+ * indirect draw, many batches in one compute submit.
+ *
+ * **Queued during the frame, dispatched in one submit from `flushRings`.** Every submit that can carry
+ * a culled draw — the frame, a mirror, a probe face — calls `flushRings` first, so the dispatch that
+ * fills a slot is always on the queue ahead of the pass that draws from it. The parameters and the
+ * zeroed instance count are written with `queue.writeBuffer` when the job is queued, which the queue
+ * orders ahead of both submits.
+ *
+ * **A slot is one (batch, view) pair in one frame.** A batch drawn from the camera, a mirror and a
+ * probe face needs three sets of survivors, so a batch holds up to `MAX_CULL_SLOTS`, taken in order
+ * each frame; past that the renderer draws every instance, which is right and merely slower. Each
+ * slot owns its buffers and a bind group built once, so queueing allocates nothing.
+ */
+import { INSTANCE_STRIDE } from '../../instances.js';
+import { INSTANCE_CULL_WGSL, INSTANCE_CULL_WORKGROUP } from './shaders/instanceCull.wgsl.js';
+import { shaderModule } from './shaderModules.js';
+/** Views a batch can be culled for in one frame. See the header. */
+export const MAX_CULL_SLOTS = 4;
+/** Jobs one frame may queue before the rest draw uncut. A ring size, not an opinion. */
+const MAX_JOBS = 4096;
+/** Bytes of `Params`: six planes, the mesh's sphere, and the instance count padded to 16. */
+const PARAMS_BYTES = 6 * 16 + 16 + 16;
+const USAGE = {
+    VERTEX: 0x0020,
+    UNIFORM: 0x0040,
+    STORAGE: 0x0080,
+    INDIRECT: 0x0100,
+    COPY_DST: 0x0008,
+};
+export class InstanceCullPass {
+    device;
+    pipeline;
+    layout;
+    jobs = new Array(MAX_JOBS).fill(null);
+    queued = 0;
+    paramsStaging = new ArrayBuffer(PARAMS_BYTES);
+    paramFloats = new Float32Array(this.paramsStaging);
+    paramWords = new Uint32Array(this.paramsStaging);
+    argsStaging = new Uint32Array(5);
+    constructor(device) {
+        this.device = device;
+        this.layout = device.createBindGroupLayout({
+            label: 'instances.cull',
+            entries: [
+                { binding: 0, visibility: 0x4, buffer: { type: 'uniform' } },
+                { binding: 1, visibility: 0x4, buffer: { type: 'read-only-storage' } },
+                { binding: 2, visibility: 0x4, buffer: { type: 'storage' } },
+                { binding: 3, visibility: 0x4, buffer: { type: 'storage' } },
+            ],
+        });
+        this.pipeline = device.createComputePipeline({
+            label: 'instances.cull',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.layout] }),
+            compute: {
+                module: shaderModule(device, { label: 'instances.cull', code: INSTANCE_CULL_WGSL }),
+                entryPoint: 'main',
+            },
+        });
+    }
+    /** A slot reading `source`, a batch's full instance buffer of `capacity` instances. */
+    createSlot(source, capacity, label) {
+        const size = Math.max(1, capacity) * INSTANCE_STRIDE;
+        const instances = this.device.createBuffer({
+            label: `${label}.kept`,
+            size,
+            usage: USAGE.VERTEX | USAGE.STORAGE,
+        });
+        const args = this.device.createBuffer({
+            label: `${label}.args`,
+            size: 20,
+            usage: USAGE.INDIRECT | USAGE.STORAGE | USAGE.COPY_DST,
+        });
+        const params = this.device.createBuffer({
+            label: `${label}.params`,
+            size: PARAMS_BYTES,
+            usage: USAGE.UNIFORM | USAGE.COPY_DST,
+        });
+        const group = this.device.createBindGroup({
+            label: `${label}.cull`,
+            layout: this.layout,
+            entries: [
+                { binding: 0, resource: { buffer: params } },
+                { binding: 1, resource: { buffer: source, size } },
+                { binding: 2, resource: { buffer: instances } },
+                { binding: 3, resource: { buffer: args } },
+            ],
+        });
+        return { instances, args, params, group, count: 0 };
+    }
+    /**
+     * Queue a cull of `count` instances against six `planes`, the mesh's local sphere being
+     * (centre, radius). Returns false when the frame's job ring is full, and the caller draws uncut.
+     */
+    queue(slot, planes, centre, radius, count, indexCount) {
+        if (this.queued >= MAX_JOBS)
+            return false;
+        const floats = this.paramFloats;
+        for (let i = 0; i < 24; i++)
+            floats[i] = planes[i];
+        floats[24] = centre[0] ?? 0;
+        floats[25] = centre[1] ?? 0;
+        floats[26] = centre[2] ?? 0;
+        floats[27] = radius;
+        this.paramWords[28] = count;
+        this.device.queue.writeBuffer(slot.params, 0, this.paramsStaging);
+        const args = this.argsStaging;
+        args[0] = indexCount;
+        args[1] = 0;
+        args[2] = 0;
+        args[3] = 0;
+        args[4] = 0;
+        this.device.queue.writeBuffer(slot.args, 0, args);
+        slot.count = count;
+        this.jobs[this.queued++] = slot;
+        return true;
+    }
+    /** Dispatch everything queued, in one compute pass and one submit. Nothing queued is nothing done. */
+    flush() {
+        if (this.queued === 0)
+            return;
+        const encoder = this.device.createCommandEncoder({ label: 'instances.cull' });
+        const pass = encoder.beginComputePass({ label: 'instances.cull' });
+        pass.setPipeline(this.pipeline);
+        for (let i = 0; i < this.queued; i++) {
+            const slot = this.jobs[i];
+            if (slot === null || slot === undefined)
+                continue;
+            pass.setBindGroup(0, slot.group);
+            pass.dispatchWorkgroups(Math.ceil(slot.count / INSTANCE_CULL_WORKGROUP));
+            this.jobs[i] = null;
+        }
+        pass.end();
+        this.device.queue.submit([encoder.finish()]);
+        this.queued = 0;
+    }
+}
+/** Every buffer a slot owns, destroyed with its batch. */
+export function destroySlot(slot) {
+    slot.instances.destroy();
+    slot.args.destroy();
+    slot.params.destroy();
+}

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

@@ -1,3 +1,4 @@
+import type { CullSlot } from './instanceCullPass.ts';
 import type { MeshInstances } from '../../instances.ts';
 import type { GpuMesh } from './buffers.ts';
 /**
@@ -15,13 +16,33 @@ export declare class GpuInstancedBatch {
     readonly mesh: GpuMesh;
     readonly capacity: number;
     private readonly staging;
-    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string);
+    /** Whether the camera draw culls this batch. See `InstancedOptions.cull`. */
+    readonly cull: boolean;
+    /** The world box around every live instance, fitted at upload. See `instancesBox`. */
+    readonly box: Float32Array<ArrayBuffer>;
+    /** One set of survivors per view drawn this frame. See `InstanceCullPass`. */
+    readonly slots: CullSlot[];
+    /** The frame the slots were last taken in, and how many were taken. */
+    slotFrame: number;
+    slotsTaken: number;
+    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull?: boolean);
+    /** Last frame's packed slots, for a reconstruction; made on first use by the renderer. */
+    previousBuffer: GPUBuffer | null;
+    /** How many slots the upload before the last one held, and how many the last one holds. */
+    previousCount: number;
+    liveCount: number;
+    /** The frame of the last upload. See `changeFrames.ts`. */
+    changed: number;
     /**
      * Pack and push `data.count` instances, in one write.
      *
      * Only the live prefix, for the reason `uploadScatter` gives: the rest is not drawn and
      * uploading it would be per-frame waste with nothing reading it.
+     *
+     * **Given `previous`, the placement still in the staging array — the last upload, which is last
+     * frame's — is written there first**, so a reconstruction can pair each slot with where it was.
+     * `writeBuffer` copies at the call, so packing afterwards cannot reach that copy.
      */
-    upload(queue: GPUQueue, data: MeshInstances): void;
+    upload(queue: GPUQueue, data: MeshInstances, previous?: GPUBuffer | null): void;
     dispose(): void;
 }

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

@@ -1,6 +1,10 @@
+import { instancesBox } from '../../instanceCull.js';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.js';
+import { destroySlot } from './instanceCullPass.js';
 /** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
 const USAGE_VERTEX = 0x0020 | 0x0008;
+/** A culling batch's source is read by the cull as storage too. */
+const USAGE_STORAGE = 0x0080;
 /**
  * One mesh's per-instance buffer on the device.
  *
@@ -16,9 +20,19 @@ export class GpuInstancedBatch {
     mesh;
     capacity;
     staging;
-    constructor(device, mesh, capacity, label) {
+    /** Whether the camera draw culls this batch. See `InstancedOptions.cull`. */
+    cull;
+    /** The world box around every live instance, fitted at upload. See `instancesBox`. */
+    box = new Float32Array([1, 1, 1, -1, -1, -1]);
+    /** One set of survivors per view drawn this frame. See `InstanceCullPass`. */
+    slots = [];
+    /** The frame the slots were last taken in, and how many were taken. */
+    slotFrame = -1;
+    slotsTaken = 0;
+    constructor(device, mesh, capacity, label, cull = false) {
         this.mesh = mesh;
         this.capacity = capacity;
+        this.cull = cull;
         this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
         this.buffer = device.createBuffer({
             /*
@@ -26,24 +40,47 @@ export class GpuInstancedBatch {
              * naming the resource it was about, and an unlabelled buffer names nothing.
              */
             label,
-            size: capacity * INSTANCE_STRIDE,
-            usage: USAGE_VERTEX,
+            size: Math.max(1, capacity) * INSTANCE_STRIDE,
+            usage: USAGE_VERTEX | (cull ? USAGE_STORAGE : 0),
         });
     }
+    /** Last frame's packed slots, for a reconstruction; made on first use by the renderer. */
+    previousBuffer = null;
+    /** How many slots the upload before the last one held, and how many the last one holds. */
+    previousCount = 0;
+    liveCount = 0;
+    /** The frame of the last upload. See `changeFrames.ts`. */
+    changed = -1;
     /**
      * Pack and push `data.count` instances, in one write.
      *
      * Only the live prefix, for the reason `uploadScatter` gives: the rest is not drawn and
      * uploading it would be per-frame waste with nothing reading it.
+     *
+     * **Given `previous`, the placement still in the staging array — the last upload, which is last
+     * frame's — is written there first**, so a reconstruction can pair each slot with where it was.
+     * `writeBuffer` copies at the call, so packing afterwards cannot reach that copy.
      */
-    upload(queue, data) {
+    upload(queue, data, previous = null) {
+        if (this.cull)
+            instancesBox(data, this.mesh.bounds, this.box);
         const count = Math.min(data.count, this.capacity);
+        if (previous !== null) {
+            if (this.liveCount > 0) {
+                queue.writeBuffer(previous, 0, this.staging, 0, this.liveCount * INSTANCE_FLOATS);
+            }
+            this.previousCount = this.liveCount;
+        }
+        this.liveCount = count;
         if (count === 0)
             return;
         packInstances(data, this.staging);
         queue.writeBuffer(this.buffer, 0, this.staging, 0, count * INSTANCE_FLOATS);
     }
     dispose() {
+        this.previousBuffer?.destroy();
         this.buffer.destroy();
+        for (const slot of this.slots)
+            destroySlot(slot);
     }
 }

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

@@ -0,0 +1,30 @@
+import type { DrawCommand } from './drawCommand.ts';
+export declare class LatePass {
+    private readonly device;
+    private readonly commands;
+    private depth;
+    private depthTextureView;
+    private readonly layout;
+    private readonly pipeline;
+    private readonly sizes;
+    /** The render size and the output size, then the frame's jitter in render texels. */
+    private readonly sizeStaging;
+    private group;
+    private groupSource;
+    constructor(device: GPUDevice);
+    /** The output-size depth, (re)made when the output changes size. */
+    depthView(width: number, height: number): GPUTextureView;
+    /**
+     * Fill the output-size depth from `source`, the render's single-sample depth, drawn jittered by
+     * (`jitterX`, `jitterY`) render texels — which the fill takes back out (`recon/lateDepth.ts`).
+     */
+    upscale(encoder: GPUCommandEncoder, source: GPUTextureView, renderWidth: number, renderHeight: number, outputWidth: number, outputHeight: number, jitterX: number, jitterY: number): void;
+    /** A command slot for one late draw. Every field a caller uses it fills; see `takeCommand`. */
+    take(): DrawCommand;
+    /** Late draws recorded this frame. */
+    get pending(): number;
+    /** Every late draw, in the order it was recorded, through the renderer's own issue. */
+    replay(pass: GPURenderPassEncoder, issue: (pass: GPURenderPassEncoder, command: DrawCommand) => void): void;
+    reset(): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,140 @@
+/**
+ * What a reconstructing frame draws after the upscale: its blended draws, at the output size.
+ *
+ * **Why late.** A blended surface writes no depth the motion pass could test against and has no
+ * single motion per pixel — a caption over a wall is two surfaces moving two ways — so a
+ * reconstruction can only smear it. Drawn after the resolve, at output resolution and unjittered,
+ * it is as sharp as a native frame and has no history to ghost.
+ *
+ * **What it holds**: a command pool of its own, because the frame graph's pool is spent at every
+ * scene flush and these must survive until the reconstruction has run; an output-size depth
+ * target; and the pass that fills it from the render's depth. Cost: translucent pixels are shaded
+ * at output resolution — 2.25x as many at ratio 1.5, only where translucency is — plus one
+ * full-screen depth pass.
+ */
+import { DEPTH_CLEAR, DEPTH_FORMAT } from '../../depthConvention.js';
+import { LATE_DEPTH_WGSL } from '../../shaders/recon/lateDepth.wgsl.js';
+import { createCommandPool, resetPool, takeCommand } from './drawCommand.js';
+export class LatePass {
+    device;
+    commands = createCommandPool(64);
+    depth = null;
+    depthTextureView = null;
+    layout;
+    pipeline;
+    sizes;
+    /** The render size and the output size, then the frame's jitter in render texels. */
+    sizeStaging = new Float32Array(8);
+    group = null;
+    groupSource = null;
+    constructor(device) {
+        this.device = device;
+        this.layout = device.createBindGroupLayout({
+            label: 'recon.lateDepth.layout',
+            entries: [
+                { binding: 0, visibility: 0x2, texture: { sampleType: 'depth' } },
+                { binding: 1, visibility: 0x2, buffer: { type: 'uniform' } },
+            ],
+        });
+        const module = device.createShaderModule({ label: 'recon.lateDepth', code: LATE_DEPTH_WGSL });
+        this.pipeline = device.createRenderPipeline({
+            label: 'recon.lateDepth',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.layout] }),
+            vertex: { module, entryPoint: 'lateDepthVert' },
+            fragment: { module, entryPoint: 'lateDepthFrag', targets: [] },
+            primitive: { topology: 'triangle-list' },
+            depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: 'always' },
+        });
+        this.sizes = device.createBuffer({
+            label: 'recon.lateDepth.sizes',
+            size: 32,
+            usage: 0x40 | 0x8, // UNIFORM | COPY_DST
+        });
+    }
+    /** The output-size depth, (re)made when the output changes size. */
+    depthView(width, height) {
+        if (this.depth === null || this.depth.width !== width || this.depth.height !== height) {
+            this.depth?.destroy();
+            this.depth = this.device.createTexture({
+                label: 'recon.lateDepth',
+                size: [width, height],
+                format: DEPTH_FORMAT,
+                usage: 0x10, // RENDER_ATTACHMENT
+            });
+            this.depthTextureView = this.depth.createView();
+        }
+        return this.depthTextureView;
+    }
+    /**
+     * Fill the output-size depth from `source`, the render's single-sample depth, drawn jittered by
+     * (`jitterX`, `jitterY`) render texels — which the fill takes back out (`recon/lateDepth.ts`).
+     */
+    upscale(encoder, source, renderWidth, renderHeight, outputWidth, outputHeight, jitterX, jitterY) {
+        const target = this.depthView(outputWidth, outputHeight);
+        this.sizeStaging[0] = renderWidth;
+        this.sizeStaging[1] = renderHeight;
+        this.sizeStaging[2] = outputWidth;
+        this.sizeStaging[3] = outputHeight;
+        this.sizeStaging[4] = jitterX;
+        this.sizeStaging[5] = jitterY;
+        this.device.queue.writeBuffer(this.sizes, 0, this.sizeStaging);
+        if (this.group === null || this.groupSource !== source) {
+            this.group = this.device.createBindGroup({
+                label: 'recon.lateDepth.group',
+                layout: this.layout,
+                entries: [
+                    { binding: 0, resource: source },
+                    { binding: 1, resource: { buffer: this.sizes } },
+                ],
+            });
+            this.groupSource = source;
+        }
+        const pass = encoder.beginRenderPass({
+            label: 'recon.lateDepth',
+            colorAttachments: [],
+            depthStencilAttachment: {
+                view: target,
+                depthClearValue: DEPTH_CLEAR,
+                depthLoadOp: 'clear',
+                depthStoreOp: 'store',
+            },
+        });
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, this.group);
+        pass.draw(3);
+        pass.end();
+    }
+    /** A command slot for one late draw. Every field a caller uses it fills; see `takeCommand`. */
+    take() {
+        const at = takeCommand(this.commands);
+        const command = this.commands.commands[at];
+        command.offsetCount = 0;
+        command.vertexCount = 0;
+        command.indexBuffer = null;
+        command.indexed = false;
+        command.instances = 1;
+        command.indirect = null;
+        return command;
+    }
+    /** Late draws recorded this frame. */
+    get pending() {
+        return this.commands.taken;
+    }
+    /** Every late draw, in the order it was recorded, through the renderer's own issue. */
+    replay(pass, issue) {
+        for (let i = 0; i < this.commands.taken; i += 1) {
+            const command = this.commands.commands[i];
+            if (command !== undefined)
+                issue(pass, command);
+        }
+    }
+    reset() {
+        resetPool(this.commands);
+    }
+    dispose() {
+        this.depth?.destroy();
+        this.depth = null;
+        this.depthTextureView = null;
+        this.sizes.destroy();
+    }
+}

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

@@ -55,7 +55,11 @@ export function createLightVolumeBindGroupLayout(device, variant) {
         entries.push({
             binding: texture.texture,
             visibility: VISIBILITY_FRAGMENT,
-            texture: { sampleType: 'unfilterable-float' },
+            texture: {
+                sampleType: 'unfilterable-float',
+                /* The sun's maps are one array since 4.5.0; see `shadowMap.ts`. */
+                ...(texture.type === 'sampler2DArray' ? { viewDimension: '2d-array' } : {}),
+            },
         });
         entries.push({
             binding: texture.sampler,

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

@@ -0,0 +1,95 @@
+import type { GpuMesh } from './buffers.ts';
+export declare class MotionPass {
+    private readonly device;
+    /** The frame's movers, in the order they were drawn. */
+    private readonly meshes;
+    /** Two matrices a mover — this frame's model and last frame's — at `MOTION_DRAW_FLOATS` apart. */
+    private matrices;
+    private count;
+    /** `RIGID` or `SKINNED` per record, grown beside `matrices`. */
+    private kinds;
+    /** A skinned record's two palettes, this frame's and last frame's, by record index. */
+    private readonly paletteNow;
+    private readonly paletteWas;
+    /** A rewritten record's last-frame rows, by record index. */
+    private readonly previousRows;
+    /** One pipeline per stride for rewritten meshes: current and previous rows at that stride. */
+    private readonly dynamicPipelines;
+    /** An instanced record's placement this frame and last frame, and how many slots pair. */
+    private readonly instancesNow;
+    private readonly instancesWas;
+    private instanceCounts;
+    private readonly instancedPipelines;
+    private layout;
+    private paletteLayout;
+    private skinnedLayout;
+    /** Keyed by stride and the two skin offsets, packed into one number so a lookup builds nothing. */
+    private readonly skinnedPipelines;
+    /**
+     * 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.
+     */
+    private readonly paletteGroups;
+    private module;
+    private pipelineLayout;
+    private readonly pipelines;
+    private frameBuffer;
+    private drawBuffer;
+    private drawCapacity;
+    private group;
+    private readonly frameStaging;
+    private drawStaging;
+    /** A float view of `drawStaging`, made when it is, so a frame's upload allocates nothing. */
+    private drawFloats;
+    constructor(device: GPUDevice);
+    /** A frame states its movers afresh. */
+    reset(): void;
+    /** A rigid mover: the same positions under last frame's model. */
+    recordRigid(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>): void;
+    /** A skinned mover: its positions under last frame's pose as well as last frame's model. */
+    recordSkinned(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>, palette: GPUTextureView, previousPalette: GPUTextureView): void;
+    /** A rewritten mesh: its vertices as they were, read from `previous`, under last frame's model. */
+    recordDynamic(mesh: GpuMesh, model: ArrayLike<number>, previousModel: ArrayLike<number>, previous: GPUBuffer): void;
+    /** An instanced batch: its first `count` slots, each under last frame's placement of that slot. */
+    recordInstanced(mesh: GpuMesh, placement: GPUBuffer, previousPlacement: GPUBuffer, count: number): void;
+    /** One record's slot: its mesh, its two matrices and its kind. Returns the record's index. */
+    private take;
+    /**
+     * 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.
+     */
+    private buildLayout;
+    /**
+     * 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.
+     */
+    private skinnedPipelineFor;
+    /** The rewritten pipeline for one stride: position from each of two buffers of that stride. */
+    private dynamicPipelineFor;
+    /**
+     * 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.
+     */
+    private instancedPipelineFor;
+    /** The bind group holding one pair of palettes, built the first time the pair is seen. */
+    private paletteGroup;
+    /** The pipeline for one vertex stride, built on first sight of it. */
+    private pipelineFor;
+    /**
+     * 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: GPUCommandEncoder, target: GPUTextureView, depth: GPUTextureView, raster: Float32Array, viewProj: Float32Array, previousViewProj: Float32Array, timestampWrites: GPURenderPassTimestampWrites | undefined): void;
+    dispose(): void;
+}