@driftengine/core 4.5.0 → 4.6.1

package/src/render/backend/webgpu/buffers.ts

@@ -103,6 +103,28 @@ export const VERTEX_LAYOUT: readonly VertexAttribute[] = [
 ];
 
 /** Geometry on the device, with the buffers bound in layout order. */
+/**
+ * The texture coordinates of a mesh that names texture-array layers: (u, v, layer), three floats.
+ *
+ * **Three only where layers exist.** Every location is spent, so the layer rides in this attribute,
+ * and widening it for every textured mesh would add four bytes to each of its vertices for nothing.
+ * A mesh without layers keeps two, and the shader's `vec3` input reads z as 0 — WebGPU fills a
+ * component the format does not carry with 0 (and w with 1) — which is layer 0. The pipeline key
+ * carries `:layers`, so the two vertex layouts never share a pipeline.
+ */
+export const LAYERED_UVS: VertexAttribute = {
+  name: 'uvs',
+  shaderLocation: 5,
+  format: 'float32x3',
+  components: 3,
+  optional: true,
+};
+
+/** The attribute as this mesh lays it out: the UV field widens where the mesh names layers. */
+function laidOut(attribute: VertexAttribute, layered: boolean): VertexAttribute {
+  return layered && attribute.name === 'uvs' ? LAYERED_UVS : attribute;
+}
+
 export interface GpuMesh {
   /**
    * The buffers a draw binds, in the order `vertexBufferLayouts` describes them.
@@ -132,6 +154,13 @@ export interface GpuMesh {
    */
   readonly skinOffsets: { readonly joints: number; readonly weights: number } | null;
   readonly indexBuffer: GPUBuffer;
+  /**
+   * How many indices the mesh draws. **Zero is a mesh with nothing to draw, and no pass draws it**:
+   * a level can hold none of some kind of geometry, and a draw of zero indices does nothing but
+   * earn a warning from the device in every pass that issues it. Every place a mesh enters a pass
+   * checks this beside `complete` or its vertex buffers, and WebGL2 skips the same meshes, so the
+   * two backends count the same draws.
+   */
   readonly indexCount: number;
   /**
    * How big this mesh is, in its own space.
@@ -281,9 +310,10 @@ export function createGpuMeshIncremental(
   validateMeshData(data);
   const bounds = boundsOfPositions(data.positions, createBounds());
   const vertexCount = data.positions.length / 3;
+  const layered = data.layers !== undefined;
   const supplied = VERTEX_LAYOUT.filter(
     (attribute) => !attribute.optional || data[attribute.name as keyof MeshData] !== undefined,
-  );
+  ).map((attribute) => laidOut(attribute, layered));
 
   /* Interleaved: one stride holding every attribute the mesh actually supplied. */
   const stride = supplied.reduce((sum, attribute) => sum + attribute.components * 4, 0);
@@ -459,7 +489,21 @@ function* uploadSteps(job: UploadJob): Generator<void, void, void> {
     let fieldOffset = 0;
     for (const attribute of supplied) {
       const source = data[attribute.name as keyof MeshData] as Float32Array;
-      interleaveField(interleaved, source, attribute.components, step, fieldOffset, from, to);
+      if (attribute === LAYERED_UVS) {
+        /* (u, v) from the coordinates and the layer after them, one field of three. */
+        interleaveField(interleaved, source, 2, step, fieldOffset, from, to);
+        interleaveField(
+          interleaved,
+          data.layers as Float32Array,
+          1,
+          step,
+          fieldOffset + 2,
+          from,
+          to,
+        );
+      } else {
+        interleaveField(interleaved, source, attribute.components, step, fieldOffset, from, to);
+      }
       fieldOffset += attribute.components;
     }
     device.queue.writeBuffer(vertices, from * stride, interleaved, from * step, (to - from) * step);
@@ -678,7 +722,9 @@ export function vertexBufferLayouts(
   const constants: GPUVertexAttribute[] = [];
   let offset = 0;
 
-  VERTEX_LAYOUT.forEach((attribute, index) => {
+  const layered = present['layers'] === true;
+  VERTEX_LAYOUT.forEach((declared, index) => {
+    const attribute = laidOut(declared, layered);
     /*
      * **The instanced pipeline reclaims the two skinning locations, and it is allowed to because
      * it cannot skin.** Locations 11 and 12 are the joint indices and weights; the INSTANCED

package/src/render/backend/webgpu/depthPass.ts

@@ -137,7 +137,11 @@ export function createDepthBindGroupLayout(
             {
               binding: CUTOUT_MAP.texture,
               visibility: VISIBILITY_FRAGMENT,
-              texture: { sampleType: 'float' as GPUTextureSampleType },
+              /* A surface texture, and every surface texture is a `2d-array` view. */
+              texture: {
+                sampleType: 'float' as GPUTextureSampleType,
+                viewDimension: '2d-array' as GPUTextureViewDimension,
+              },
             },
             {
               binding: CUTOUT_MAP.sampler,

package/src/render/backend/webgpu/drawCommand.ts

@@ -28,6 +28,11 @@ export interface DrawCommand {
   indexed: boolean;
   count: number;
   instances: number;
+  /**
+   * A `drawIndexedIndirect` record to draw from instead of `count` and `instances`: an instance
+   * cull's survivors, counted on the device. Null for every other draw.
+   */
+  indirect: GPUBuffer | null;
 }
 
 export interface CommandPool {
@@ -50,6 +55,7 @@ function emptyCommand(): DrawCommand {
     indexed: false,
     count: 0,
     instances: 1,
+    indirect: null,
   };
 }
 

package/src/render/backend/webgpu/flatPass.ts

@@ -8,6 +8,14 @@ import { vertexBufferLayouts } from './buffers.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
 
+/** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
+const SURFACE_MAPS: ReadonlySet<string> = new Set([
+  'uAlbedo',
+  'uNormalMap',
+  'uOrmMap',
+  'uEmissiveMap',
+]);
+
 /**
  * The flat pipeline: the shader that draws the world.
  *
@@ -290,9 +298,20 @@ export function createFlatBindGroupLayout(
     const volume = texture.type === 'sampler3D' || texture.type === 'usampler3D';
     /* Glass tints are colour, mipmapped and filtered: a frosted pane is read at a coarser level. */
     const tint = name.endsWith('GlassTints');
+    /*
+     * **The four material maps are arrays too, and they are colour.** Every surface texture is a
+     * `2d-array` view since texture arrays landed, so the rule below — an array is a shadow map —
+     * would declare albedo unfilterable and bind a non-filtering sampler to it, which reads as
+     * every textured surface going nearest-neighbour and losing its mip chain. Named, as
+     * `uEnvironment` is, because a pattern wide enough to catch them catches the shadow arrays.
+     */
+    const surface = SURFACE_MAPS.has(name);
     const isShadow =
       integer ||
-      (!tint && name !== 'uEnvironment' && (name.endsWith('ShadowMap') || cube || array));
+      (!tint &&
+        !surface &&
+        name !== 'uEnvironment' &&
+        (name.endsWith('ShadowMap') || cube || array));
     entries.push({
       binding: texture.texture,
       visibility: VISIBILITY_FRAGMENT,
@@ -462,8 +481,11 @@ export function flatPipeline(
    * `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.
+   *
+   * `'additive'` adds instead: colour times alpha onto the target, its alpha kept. The key must
+   * carry it (`|add`).
    */
-  translucent = false,
+  translucent: boolean | 'additive' = false,
   /** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
   skinned = false,
   /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
@@ -576,7 +598,7 @@ function flatDescriptor(
   variant: FlatVariant,
   key: string,
   present: Readonly<Record<string, boolean>>,
-  translucent: boolean,
+  translucent: boolean | 'additive',
   /** Whether this pipeline reads a joint palette. See `FlatVertexOptions`. */
   skinned: boolean,
   /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
@@ -626,19 +648,27 @@ function flatDescriptor(
       constants: flatFragmentConstants(variant, cache),
       targets: [
         oitTarget(oit) ??
-          (translucent
+          (translucent === 'additive'
             ? {
                 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' },
+                  color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                  alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
                 },
               }
-            : { format: cache.format }),
+            : 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: doubleSided ? 'none' : 'back' },

package/src/render/backend/webgpu/glassTintPass.ts

@@ -90,7 +90,8 @@ export class GpuGlassTint {
           {
             binding: CUTOUT_MAP.texture,
             visibility: VISIBILITY_FRAGMENT,
-            texture: { sampleType: 'float' },
+            /* A surface texture, and every surface texture is a `2d-array` view. */
+            texture: { sampleType: 'float', viewDimension: '2d-array' },
           },
           {
             binding: CUTOUT_MAP.sampler,

package/src/render/backend/webgpu/instanceCullPass.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.ts';
+import { INSTANCE_CULL_WGSL, INSTANCE_CULL_WORKGROUP } from './shaders/instanceCull.wgsl.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/** 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,
+} as const;
+
+/** One set of survivors: the compacted instances, the indirect record, and what the cull reads. */
+export interface CullSlot {
+  readonly instances: GPUBuffer;
+  readonly args: GPUBuffer;
+  readonly params: GPUBuffer;
+  readonly group: GPUBindGroup;
+  /** How many instances the last queued job tested, which sizes its dispatch. */
+  count: number;
+}
+
+export class InstanceCullPass {
+  private readonly pipeline: GPUComputePipeline;
+  private readonly layout: GPUBindGroupLayout;
+  private readonly jobs: (CullSlot | null)[] = new Array<CullSlot | null>(MAX_JOBS).fill(null);
+  private queued = 0;
+  private readonly paramsStaging = new ArrayBuffer(PARAMS_BYTES);
+  private readonly paramFloats = new Float32Array(this.paramsStaging);
+  private readonly paramWords = new Uint32Array(this.paramsStaging);
+  private readonly argsStaging = new Uint32Array(5);
+
+  constructor(private readonly device: GPUDevice) {
+    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: GPUBuffer, capacity: number, label: string): CullSlot {
+    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: CullSlot,
+    planes: Float32Array,
+    centre: ArrayLike<number>,
+    radius: number,
+    count: number,
+    indexCount: number,
+  ): boolean {
+    if (this.queued >= MAX_JOBS) return false;
+    const floats = this.paramFloats;
+    for (let i = 0; i < 24; i++) floats[i] = planes[i] as number;
+    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(): void {
+    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: CullSlot): void {
+  slot.instances.destroy();
+  slot.args.destroy();
+  slot.params.destroy();
+}

package/src/render/backend/webgpu/instanced.ts

@@ -1,9 +1,14 @@
+import { instancesBox } from '../../instanceCull.ts';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.ts';
+import { destroySlot } from './instanceCullPass.ts';
+import type { CullSlot } from './instanceCullPass.ts';
 import type { MeshInstances } from '../../instances.ts';
 import type { GpuMesh } from './buffers.ts';
 
 /** 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.
@@ -21,9 +26,20 @@ export class GpuInstancedBatch {
   readonly capacity: number;
   private readonly staging: Float32Array;
 
-  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 = new Float32Array([1, 1, 1, -1, -1, -1]);
+  /** 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 = -1;
+  slotsTaken = 0;
+
+  constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string, cull = false) {
     this.mesh = mesh;
     this.capacity = capacity;
+    this.cull = cull;
     this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
     this.buffer = device.createBuffer({
       /*
@@ -31,8 +47,8 @@ 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),
     });
   }
 
@@ -55,6 +71,7 @@ export class GpuInstancedBatch {
    * `writeBuffer` copies at the call, so packing afterwards cannot reach that copy.
    */
   upload(queue: GPUQueue, data: MeshInstances, previous: GPUBuffer | null = null): void {
+    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) {
@@ -71,5 +88,6 @@ export class GpuInstancedBatch {
   dispose(): void {
     this.previousBuffer?.destroy();
     this.buffer.destroy();
+    for (const slot of this.slots) destroySlot(slot);
   }
 }

package/src/render/backend/webgpu/latePass.ts

@@ -25,7 +25,8 @@ export class LatePass {
   private readonly layout: GPUBindGroupLayout;
   private readonly pipeline: GPURenderPipeline;
   private readonly sizes: GPUBuffer;
-  private readonly sizeStaging = new Float32Array(4);
+  /** The render size and the output size, then the frame's jitter in render texels. */
+  private readonly sizeStaging = new Float32Array(8);
   private group: GPUBindGroup | null = null;
   private groupSource: GPUTextureView | null = null;
 
@@ -49,7 +50,7 @@ export class LatePass {
     });
     this.sizes = device.createBuffer({
       label: 'recon.lateDepth.sizes',
-      size: 16,
+      size: 32,
       usage: 0x40 | 0x8, // UNIFORM | COPY_DST
     });
   }
@@ -69,7 +70,10 @@ export class LatePass {
     return this.depthTextureView as GPUTextureView;
   }
 
-  /** Fill the output-size depth from `source`, the render's single-sample depth. */
+  /**
+   * 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,
@@ -77,12 +81,16 @@ export class LatePass {
     renderHeight: number,
     outputWidth: number,
     outputHeight: number,
+    jitterX: number,
+    jitterY: number,
   ): void {
     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({
@@ -120,6 +128,7 @@ export class LatePass {
     command.indexBuffer = null;
     command.indexed = false;
     command.instances = 1;
+    command.indirect = null;
     return command;
   }
 

package/src/render/backend/webgpu/motionPass.ts

@@ -509,7 +509,8 @@ export class MotionPass {
         } else {
           pipeline = this.pipelineFor(mesh.vertexStride);
         }
-        if (pipeline === null) continue;
+        /* A mesh with nothing in it draws nothing: see `GpuMesh.indexCount`. */
+        if (pipeline === null || mesh.indexCount === 0) continue;
         if (pipeline !== bound) {
           pass.setPipeline(pipeline);
           bound = pipeline;