@driftengine/core 4.8.2 → 4.8.4

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

@@ -0,0 +1,194 @@
+/**
+ * A cloth binding's textures on WebGPU: the binding and the rest particles once, a mesh's; the
+ * particles every frame, a character's — the twin of `webgl2/clothTextures.ts`.
+ *
+ * `rgba32float`, read by `textureLoad` in the vertex stage, so bound as `unfilterable-float` and
+ * never sampled. Two particle textures that swap on each update, so last frame's positions stay for
+ * a motion vector with no copy. **Written with `writeTexture`, whose queue order is the trap the
+ * per-draw rings exist for**: an update lands before every draw of the frame, so a character's
+ * particles are updated once a frame, before its draws, never between two draws of it.
+ *
+ * `clothStandIn` is what a skinned pipeline binds where no cloth is set: its layout declares the
+ * three textures whatever the draw, and WebGPU binds every declared texture.
+ */
+import { clothTextureSize, packClothBinding, packClothParticles } from '../../clothBindingData.ts';
+import type { ClothBindingData } from '../../clothBindingData.ts';
+
+const USAGE = 0x4 | 0x2; // TEXTURE_BINDING | COPY_DST
+const STORAGE_BINDING = 0x8;
+
+function floatTexture(
+  device: GPUDevice,
+  label: string,
+  width: number,
+  height: number,
+  texels: Float32Array | null,
+  storage = false,
+): GPUTexture {
+  const texture = device.createTexture({
+    label,
+    size: [width, height],
+    format: 'rgba32float',
+    usage: storage ? USAGE | STORAGE_BINDING : USAGE,
+  });
+  if (texels !== null) {
+    device.queue.writeTexture(
+      { texture },
+      texels as Float32Array<ArrayBuffer>,
+      { bytesPerRow: width * 16, rowsPerImage: height },
+      { width, height },
+    );
+  }
+  return texture;
+}
+
+/** The three views a skinned bind group takes for its cloth. */
+export interface ClothViews {
+  readonly binding: GPUTextureView;
+  readonly particles: GPUTextureView;
+  readonly rest: GPUTextureView;
+}
+
+/** A one-texel float texture, as all three views, for every draw with no cloth. */
+export function clothStandIn(device: GPUDevice): { texture: GPUTexture; views: ClothViews } {
+  const texture = floatTexture(device, 'cloth.standIn', 1, 1, new Float32Array(4));
+  const view = texture.createView();
+  return { texture, views: { binding: view, particles: view, rest: view } };
+}
+
+/** A mesh's binding and its particles at rest. */
+export class GpuClothBinding {
+  readonly binding: GPUTexture;
+  readonly rest: GPUTexture;
+  readonly bindingView: GPUTextureView;
+  readonly restView: GPUTextureView;
+  readonly particles: number;
+
+  constructor(device: GPUDevice, data: ClothBindingData) {
+    const size = clothTextureSize(data.weights.length * 2);
+    this.binding = floatTexture(
+      device,
+      'cloth.binding',
+      size.width,
+      size.height,
+      packClothBinding(data),
+    );
+    this.particles = data.rest.length / 3;
+    const rest = clothTextureSize(this.particles);
+    const texels = new Float32Array(rest.width * rest.height * 4);
+    packClothParticles(data.rest, texels);
+    this.rest = floatTexture(device, 'cloth.rest', rest.width, rest.height, texels);
+    this.bindingView = this.binding.createView();
+    this.restView = this.rest.createView();
+  }
+
+  /** Its textures, for the renderer to retire once no draw of this frame can read them. */
+  get textures(): readonly GPUTexture[] {
+    return [this.binding, this.rest];
+  }
+}
+
+/**
+ * One character's particles: this frame's and the last, in two textures that swap. Written from
+ * the CPU with `update`, or — `storage` — by the device solver's publish pass, `publish` then
+ * saying which texture it writes.
+ */
+export class GpuClothParticles {
+  readonly count: number;
+  /** Texels a row, which the publish pass wraps a particle index by. */
+  readonly width: number;
+  private readonly height: number;
+  private readonly staging: Float32Array<ArrayBuffer>;
+  /** Both textures, for the renderer to retire once no draw of this frame can read them. */
+  readonly textures: readonly [GPUTexture, GPUTexture];
+  private readonly views: [GPUTextureView, GPUTextureView];
+  private latest = 0;
+  /** The frame each texture was last written for, so a motion knows whether the other is last frame's. */
+  private readonly written = [-1, -1];
+  private paired: GpuClothBinding | null = null;
+  private pairedViews: ClothViews[] = [];
+
+  constructor(device: GPUDevice, count: number, storage = false) {
+    this.count = count;
+    const size = clothTextureSize(count);
+    this.width = size.width;
+    this.height = size.height;
+    this.staging = new Float32Array(size.width * size.height * 4);
+    this.textures = [
+      floatTexture(device, 'cloth.particles', size.width, size.height, this.staging, storage),
+      floatTexture(device, 'cloth.particles', size.width, size.height, this.staging, storage),
+    ];
+    this.views = [this.textures[0].createView(), this.textures[1].createView()];
+  }
+
+  /** This frame's particles. */
+  get current(): GPUTextureView {
+    return this.views[this.latest] as GPUTextureView;
+  }
+
+  /** Last frame's. */
+  get previous(): GPUTextureView {
+    return this.views[1 - this.latest] as GPUTextureView;
+  }
+
+  /**
+   * Where they were last frame, for a motion vector at `frame`: the other texture where it was
+   * written the frame before this one's update, and this frame's otherwise — particles not updated
+   * this frame did not move, and a first update has no past to measure from.
+   */
+  previousAt(frame: number): GPUTextureView {
+    const fresh =
+      this.written[this.latest] === frame && this.written[1 - this.latest] === frame - 1;
+    return fresh ? this.previous : this.current;
+  }
+
+  /** A texture's view, by index: the publish pass binds both, one at a time. */
+  viewOf(k: number): GPUTextureView {
+    return this.views[k] as GPUTextureView;
+  }
+
+  /**
+   * The device is about to write the particles of `frame`: the older texture becomes this frame's,
+   * as an `update` makes it, and its index is returned for the pass that writes it.
+   */
+  publish(frame: number): number {
+    this.latest = 1 - this.latest;
+    this.written[this.latest] = frame;
+    return this.latest;
+  }
+
+  /** Write `positions` as the particles of `frame`; last frame's stays. */
+  update(device: GPUDevice, positions: Float32Array, frame: number): void {
+    if (positions.length !== this.count * 3) {
+      throw new Error(
+        `cloth: ${this.count} particles and an update of ${positions.length / 3}; a cloth's ` +
+          'particle count is fixed when its particles are created',
+      );
+    }
+    packClothParticles(positions, this.staging);
+    this.latest = 1 - this.latest;
+    this.written[this.latest] = frame;
+    device.queue.writeTexture(
+      { texture: this.textures[this.latest] as GPUTexture },
+      this.staging,
+      { bytesPerRow: this.width * 16, rowsPerImage: this.height },
+      { width: this.width, height: this.height },
+    );
+  }
+
+  /**
+   * The three views a draw of `binding` with these particles binds, kept so a cached bind group
+   * compares equal frame after frame. Two objects, one for each texture that is current.
+   */
+  viewsWith(binding: GpuClothBinding): ClothViews {
+    if (this.paired !== binding) {
+      this.paired = binding;
+      this.pairedViews = [0, 1].map((k) => ({
+        binding: binding.bindingView,
+        particles: this.views[k] as GPUTextureView,
+        rest: binding.restView,
+      }));
+    }
+    return this.pairedViews[this.latest] as ClothViews;
+  }
+}

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

@@ -0,0 +1,65 @@
+/**
+ * BC on WebGPU: which formats this device samples, and the upload of a stored chain.
+ *
+ * **One feature covers every BC format**, `texture-compression-bc`, which `select.ts` asks for
+ * wherever the adapter offers it and never demands: a device without it is still a device, and the
+ * loader decodes for it. Desktop adapters have it; phones have ASTC and ETC2 instead.
+ *
+ * **Written with `writeTexture`, level by level**, because `copyExternalImageToTexture` takes images
+ * and a compressed format cannot be a render attachment, so neither the image upload nor the mip
+ * blit applies. Each level's copy is whole blocks: a level smaller than a block is still one, and
+ * its copy extent is the block's four texels — WebGPU's physical size — rather than the one or two
+ * the level nominally has.
+ */
+import type { CompressedTextureFormat, CompressedTextureSource } from '../../compressedSource.ts';
+import { BLOCK_BYTES } from '../../compressedSource.ts';
+
+const GPU_FORMAT: Readonly<Record<CompressedTextureFormat, GPUTextureFormat>> = {
+  bc1: 'bc1-rgba-unorm',
+  'bc1-srgb': 'bc1-rgba-unorm-srgb',
+  bc2: 'bc2-rgba-unorm',
+  'bc2-srgb': 'bc2-rgba-unorm-srgb',
+  bc3: 'bc3-rgba-unorm',
+  'bc3-srgb': 'bc3-rgba-unorm-srgb',
+  bc4: 'bc4-r-unorm',
+  bc5: 'bc5-rg-unorm',
+  bc7: 'bc7-rgba-unorm',
+  'bc7-srgb': 'bc7-rgba-unorm-srgb',
+};
+
+/** Every BC format, where the device carries the feature; none where it does not. */
+export function gpuCompressedFormats(device: GPUDevice): CompressedTextureFormat[] {
+  return device.features.has('texture-compression-bc')
+    ? (Object.keys(GPU_FORMAT) as CompressedTextureFormat[])
+    : [];
+}
+
+/** A texture holding `layers` as `name`, `levels` levels of each, written as they are. */
+export function createCompressedTexture(
+  device: GPUDevice,
+  name: CompressedTextureFormat,
+  layers: readonly CompressedTextureSource[],
+  levels: number,
+): GPUTexture {
+  const { format, width, height } = layers[0] as CompressedTextureSource;
+  const texture = device.createTexture({
+    label: 'surface.texture.bc',
+    size: [width, height, layers.length],
+    format: GPU_FORMAT[name],
+    mipLevelCount: levels,
+    usage: 0x2 | 0x4, // COPY_DST | TEXTURE_BINDING
+  });
+  for (let level = 0; level < levels; level++) {
+    const across = Math.ceil(Math.max(1, width >> level) / 4);
+    const down = Math.ceil(Math.max(1, height >> level) / 4);
+    for (let layer = 0; layer < layers.length; layer++) {
+      device.queue.writeTexture(
+        { texture, mipLevel: level, origin: [0, 0, layer] },
+        (layers[layer] as CompressedTextureSource).levels[level] as Uint8Array<ArrayBuffer>,
+        { bytesPerRow: across * BLOCK_BYTES[format], rowsPerImage: down },
+        { width: across * 4, height: down * 4, depthOrArrayLayers: 1 },
+      );
+    }
+  }
+  return texture;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * What compute a consumer opts into needs from the WebGPU renderer: its device, whether the device
+ * is gone, which frame a change made now belongs to, and a place to retire textures the frame being
+ * recorded may still read.
+ *
+ * **Why a door rather than renderer methods.** A skinned cloth's solver is fifteen kilobytes
+ * gzipped of compute, WGSL and the CPU solver beneath it, and a renderer method that constructs it
+ * is a static reference no bundler can shake — every game would ship a garment solver whether or
+ * not it draws a garment. Behind this, `createSkinnedCloth` is a barrel function, and only a game
+ * that imports it carries it. **What it gives up**: a function reaching the renderer through a door
+ * the public surface does not show; the door stays this narrow so that is all it reaches.
+ */
+export interface ComputeHost {
+  device(): GPUDevice;
+  lost(): boolean;
+  /** The frame a change made now is drawn in: this one inside a frame, the next between frames. */
+  changeFrame(): number;
+  retire(textures: readonly GPUTexture[]): void;
+}
+
+/** The host of a renderer that has one: the WebGPU backend, and nothing else. */
+export function computeHostOf(renderer: object): ComputeHost | null {
+  const asked = (renderer as { computeHost?: () => ComputeHost }).computeHost;
+  return typeof asked === 'function' ? asked.call(renderer) : null;
+}

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

@@ -9,8 +9,10 @@ import {
   DEPTH_VERT_WGSL,
 } from '../../shaders/generated/depth.wgsl.ts';
 import { vertexBufferLayouts } from './buffers.ts';
+import { vertexConstants } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import type { ClothViews } from './clothTextures.ts';
 
 /**
  * The shadow pass: the world drawn from the light, into a depth map.
@@ -24,9 +26,10 @@ export const DEPTH_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_VERT.fields;
 export const DEPTH_VERT_SIZE = DEPTH_BINDINGS.DEPTH_VERT.uniformSize;
 export const DEPTH_FRAG_SIZE = DEPTH_BINDINGS.DEPTH_FRAG.uniformSize;
 /*
- * The cutout variants' vertex blocks. The rigid one is the plain block with `uUvScale` and
- * `uAlphaCutout` after every other field, so a slot written for it is written with the plain
- * offsets plus these two; the instanced one has no model and no wind, so its two sit earlier.
+ * The cutout variants' vertex blocks. The rigid one is the plain block with `uUvScale`,
+ * `uUvOffset` and `uAlphaCutout` after every other field, so a slot written for it is written with
+ * the plain offsets plus these three; the instanced one has no model and no wind, so its three sit
+ * earlier.
  */
 export const DEPTH_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.fields;
 export const DEPTH_CUTOUT_VERT_SIZE = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.uniformSize;
@@ -42,6 +45,12 @@ const FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
 const PREVIOUS = DEPTH_BINDINGS.DEPTH_FRAG.textures.uPreviousShadowMap;
 /** Where the skinned vertex stage reads the joint palette. Generated, not chosen here. */
 export const DEPTH_PALETTE_BINDING = DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uJointPalette;
+/** And the cloth binding's three textures, which every skinned caster declares. */
+const CLOTH_TEXTURES = [
+  DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothBinding,
+  DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothParticles,
+  DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uClothRest,
+] as const;
 
 const VISIBILITY_VERTEX = 0x1;
 const VISIBILITY_FRAGMENT = 0x2;
@@ -81,13 +90,11 @@ export function createDepthBindGroupLayout(
          coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
          palette. naga declares a sampler for it and nothing ever reads one. */
       ...(skinned
-        ? [
-            {
-              binding: DEPTH_PALETTE_BINDING.texture,
-              visibility: VISIBILITY_VERTEX,
-              texture: { sampleType: 'unfilterable-float' as GPUTextureSampleType },
-            },
-          ]
+        ? [DEPTH_PALETTE_BINDING, ...CLOTH_TEXTURES].map((binding) => ({
+            binding: binding.texture,
+            visibility: VISIBILITY_VERTEX,
+            texture: { sampleType: 'unfilterable-float' as GPUTextureSampleType },
+          }))
         : []),
       {
         binding: VERT_BINDING,
@@ -165,6 +172,8 @@ export function createDepthBindGroup(
   palette: GPUTextureView | null = null,
   /** The cutout map and its sampler, for a layout built with `cutout`. */
   cutout: { readonly view: GPUTextureView; readonly sampler: GPUSampler } | null = null,
+  /** A skinned group's cloth views: the caster's, or the stand-in where it has none. */
+  cloth: ClothViews | null = null,
 ): GPUBindGroup {
   return device.createBindGroup({
     label:
@@ -186,6 +195,13 @@ export function createDepthBindGroup(
       { binding: PREVIOUS.texture, resource: previous },
       { binding: PREVIOUS.sampler, resource: sampler },
       ...(palette !== null ? [{ binding: DEPTH_PALETTE_BINDING.texture, resource: palette }] : []),
+      ...(palette !== null
+        ? [
+            { binding: CLOTH_TEXTURES[0].texture, resource: clothOf(cloth).binding },
+            { binding: CLOTH_TEXTURES[1].texture, resource: clothOf(cloth).particles },
+            { binding: CLOTH_TEXTURES[2].texture, resource: clothOf(cloth).rest },
+          ]
+        : []),
       ...(cutout !== null
         ? [
             { binding: CUTOUT_MAP.texture, resource: cutout.view },
@@ -233,6 +249,13 @@ export function depthPipeline(
   instanced = false,
   /** Whether this pipeline casts a cutout: the variant that reads a map and discards by it. */
   cutout = false,
+  /**
+   * Whether a skinned caster reads its second four influences, as its visible draw does. The key
+   * must carry it, so the shadow parts from nothing the body does. See `skinning.ts`.
+   */
+  skinEight = false,
+  /** Whether a skinned caster is placed by a cloth binding, as its visible draw is. The key carries it. */
+  cloth = false,
 ): GPURenderPipeline {
   return cache.get(key, () => ({
     label: key,
@@ -252,6 +275,9 @@ export function depthPipeline(
       ),
       entryPoint: 'main',
       buffers: vertexBufferLayouts(present, instanced),
+      ...(skinned && !instanced && !cutout
+        ? { constants: vertexConstants(DEPTH_BINDINGS.DEPTH_SKINNED_VERT, skinEight, cloth) }
+        : {}),
     },
     fragment: {
       module: shaderModule(
@@ -332,3 +358,10 @@ export function depthPipeline(
     },
   }));
 }
+
+function clothOf(cloth: ClothViews | null): ClothViews {
+  if (cloth === null) {
+    throw new Error('depthPass: a skinned bind group needs cloth views, the stand-in at the least');
+  }
+  return cloth;
+}

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

@@ -11,8 +11,12 @@
  * edits rather than twenty-three implementations.
  */
 
-/** The most vertex buffers any verb on this backend binds is three. Four leaves a margin. */
-const VERTEX_BUFFER_SLOTS = 4;
+/**
+ * WebGPU's guaranteed `maxVertexBuffers`, so no verb can outgrow it. The most any binds is five — a
+ * dynamic mesh's positions, normals, rows and constants, and an instanced batch's placements — and
+ * this said three, then four, while text and bolts already bound four.
+ */
+const VERTEX_BUFFER_SLOTS = 8;
 
 export interface DrawCommand {
   pipeline: GPURenderPipeline | null;

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

@@ -9,6 +9,7 @@ import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.ts';
 
 /**
  * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
@@ -111,7 +112,7 @@ export function filmPipeline(
           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' },
+            alpha: SCENE_ALPHA_KEEPS,
           },
         },
       ],