@driftengine/core 4.8.3 → 4.8.5

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.
@@ -43,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;
@@ -82,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,
@@ -166,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:
@@ -187,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 },
@@ -234,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,
@@ -253,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(
@@ -333,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/flatPass.ts

@@ -1,3 +1,6 @@
+import { SURFACE_MODEL_SWITCH } from '../../surfaceModel.ts';
+import type { SurfaceModelKind } from '../../surfaceModel.ts';
+import type { SkinHalf } from '../../shaders/flat/models.ts';
 import { DEPTH_COMPARE, DEPTH_FORMAT, depthOffsetForLayer } from '../../depthConvention.ts';
 import {
   FLAT_BINDINGS,
@@ -6,6 +9,7 @@ import {
 } from '../../shaders/generated/flat.wgsl.ts';
 import { vertexBufferLayouts } from './buffers.ts';
 import type { LitSwitch, PipelineCache } from './pipelineCache.ts';
+import type { ClothViews } from './clothTextures.ts';
 import { shaderModule } from './shaderModules.ts';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
@@ -15,6 +19,7 @@ const SURFACE_MAPS: ReadonlySet<string> = new Set([
   'uNormalMap',
   'uOrmMap',
   'uEmissiveMap',
+  'uModelMap',
 ]);
 
 /**
@@ -146,6 +151,38 @@ export function flatVertexBindings(
 }
 
 const PLAIN_VERTEX = flatVertexBindings(false);
+
+/**
+ * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` in
+ * a skinned stage, nothing in any other. Every override a stage declares is set, and one this does
+ * not know is refused here rather than defaulted. Shared with the shadow and glass-tint casters,
+ * whose skinned stages declare the same switch.
+ */
+export function vertexConstants(
+  bindings: StageBindings,
+  skinEight: boolean,
+  cloth = false,
+): Record<string, number> {
+  const constants: Record<string, number> = {};
+  for (const [name, id] of Object.entries(bindings.overrides ?? {})) {
+    if (name === 'SKIN_EIGHT') constants[String(id)] = skinEight ? 1 : 0;
+    else if (name === 'CLOTH_BOUND') constants[String(id)] = cloth ? 1 : 0;
+    else throw new Error(`flatPass: a vertex stage declares a switch "${name}" nothing sets`);
+  }
+  return constants;
+}
+/** Where a skinned stage declares the cloth binding's three textures: binding, particles, rest. */
+function clothBindings(skinned: boolean, morphed: boolean): [number, number, number] {
+  const textures = flatVertexBindings(skinned, morphed).textures;
+  const at = (name: string): number => {
+    const found = textures[name];
+    if (found === undefined)
+      throw new Error(`flatPass: the skinned vertex shader declares no ${name}`);
+    return found.texture;
+  };
+  return [at('uClothBinding'), at('uClothParticles'), at('uClothRest')];
+}
+
 /*
  * **A variant may drop a field; it may never move one.**
  *
@@ -208,13 +245,33 @@ export function flatFragmentBindings(variant: FlatVariant): StageBindings {
  * "GLASS_SHADOWS" not found*, and the frame drew nothing. Every override the variant declares is
  * set, so a switch added to the shader and not to the cache is refused here rather than defaulted.
  */
-function flatFragmentConstants(variant: FlatVariant, cache: PipelineCache): Record<string, number> {
+function flatFragmentConstants(
+  variant: FlatVariant,
+  cache: PipelineCache,
+  model: SurfaceModelKind | null,
+  skinPass: SkinHalf = 'whole',
+): Record<string, number> {
   const overrides = flatFragmentBindings(variant).overrides;
   if (overrides?.['GLASS_SHADOWS'] === undefined) {
     throw new Error(`flatPass: variant "${variant}" has no glass switch`);
   }
+  const modelSwitch = model === null ? null : SURFACE_MODEL_SWITCH[model];
   const constants: Record<string, number> = {};
   for (const [name, id] of Object.entries(overrides)) {
+    /* A model's switch is the pipeline's own, set from its key rather than from the cache. */
+    if (name.startsWith('MODEL_')) {
+      constants[String(id)] = name === modelSwitch ? 1 : 0;
+      continue;
+    }
+    /* Skin's two halves under the screen-space blur, set from the key as a model's switch is. */
+    if (name === 'SKIN_SCREEN' || name === 'SKIN_DIFFUSE') {
+      constants[String(id)] =
+        (name === 'SKIN_SCREEN' && skinPass === 'scene') ||
+        (name === 'SKIN_DIFFUSE' && skinPass === 'diffuse')
+          ? 1
+          : 0;
+      continue;
+    }
     if (!(name in cache.litSwitches)) {
       throw new Error(`flatPass: variant "${variant}" declares a switch "${name}" no cache sets`);
     }
@@ -395,6 +452,15 @@ export function createFlatBindGroupLayout(
       visibility: VISIBILITY_VERTEX,
       texture: { sampleType: 'unfilterable-float' },
     });
+    /* The cloth binding's three textures, declared by every skinned stage whether a draw sets a
+       cloth or not; see `clothBinding.ts`. */
+    for (const binding of clothBindings(skinned, morphed)) {
+      entries.push({
+        binding,
+        visibility: VISIBILITY_VERTEX,
+        texture: { sampleType: 'unfilterable-float' },
+      });
+    }
   }
 
   return device.createBindGroupLayout({
@@ -408,7 +474,7 @@ export function createFlatBindGroupLayout(
  *
  * `resolve` is asked for a view by the shader's own name for it, so a caller supplies the
  * shadow maps it has and a stand-in for the rest. **Every declared binding must be filled
- * even when the shader never samples it** — `uAlbedoEnabled` is zero for nearly all geometry
+ * even when the shader never samples it** — the albedo's flag is zero for nearly all geometry
  * and WebGPU still requires something there, which is why `renderer.ts` keeps an
  * `emptyTexture2D` for the same reason on the other side.
  */
@@ -423,6 +489,8 @@ export function createFlatBindGroup(
   palette: GPUTextureView | null = null,
   /** The delta view for a morphed bind group, or null for an unmorphed one. */
   deltas: GPUTextureView | null = null,
+  /** A skinned bind group's cloth views — the draw's, or the stand-in where it sets none. */
+  cloth: ClothViews | null = null,
 ): GPUBindGroup {
   const fragment = flatFragmentBindings(variant);
   const entries: GPUBindGroupEntry[] = [
@@ -458,6 +526,15 @@ export function createFlatBindGroup(
       throw new Error('flatPass: the skinned vertex shader declares no uJointPalette');
     }
     entries.push({ binding: binding.texture, resource: palette });
+    if (cloth === null) {
+      throw new Error(
+        'flatPass: a skinned bind group needs cloth views, the stand-in at the least',
+      );
+    }
+    const [bindingAt, particlesAt, restAt] = clothBindings(true, deltas !== null);
+    entries.push({ binding: bindingAt, resource: cloth.binding });
+    entries.push({ binding: particlesAt, resource: cloth.particles });
+    entries.push({ binding: restAt, resource: cloth.rest });
   }
 
   return device.createBindGroup({
@@ -517,6 +594,22 @@ export function flatPipeline(
   oit: OitTarget = 'none',
   /** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
   doubleSided = false,
+  /**
+   * Turns the fragment's alpha into the pixel's samples, for a dithered cutout in a multisampled
+   * frame with no temporal resolve. The key must carry it: `|a2c`. See `cutoutDither.ts`.
+   */
+  alphaToCoverage = false,
+  /**
+   * Whether a skinned pipeline reads the second four influences: the vertex stage's `SKIN_EIGHT`.
+   * The key must carry it: `|s8`. See `skinning.ts`.
+   */
+  skinEight = false,
+  /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+  cloth = false,
+  /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
+  model: SurfaceModelKind | null = null,
+  /** Which half of a skin it draws. The key must carry it: `|ss` or `|sd`. See `SkinHalf`. */
+  skinPass: SkinHalf = 'whole',
 ): GPURenderPipeline {
   return cache.get(
     key,
@@ -536,6 +629,11 @@ export function flatPipeline(
         instanced,
         oit,
         doubleSided,
+        alphaToCoverage,
+        skinEight,
+        cloth,
+        model,
+        skinPass,
       ),
     true,
   );
@@ -562,11 +660,36 @@ export function flatPipelineAsync(
   skinned = false,
   /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
   morphed = false,
+  /** Whether the skinned stage reads the second four influences. See `flatPipeline`. */
+  skinEight = false,
+  /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+  cloth = false,
+  /** Which shading model its fragment stage shades by. See `flatPipeline`. */
+  model: SurfaceModelKind | null = null,
 ): Promise<GPURenderPipeline> {
   return cache.getAsync(
     key,
     () =>
-      flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed),
+      flatDescriptor(
+        cache,
+        device,
+        layout,
+        variant,
+        key,
+        present,
+        translucent,
+        skinned,
+        morphed,
+        true,
+        0,
+        false,
+        'none',
+        false,
+        false,
+        skinEight,
+        cloth,
+        model,
+      ),
     true,
   );
 }
@@ -637,8 +760,15 @@ function flatDescriptor(
   oit: OitTarget = 'none',
   /** Culls nothing: a surface seen from both faces. */
   doubleSided = false,
+  alphaToCoverage = false,
+  skinEight = false,
+  /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
+  cloth = false,
+  model: SurfaceModelKind | null = null,
+  skinPass: SkinHalf = 'whole',
 ): GPURenderPipelineDescriptor {
   const offset = depthOffsetForLayer(depthLayer);
+  const diffuseAlone = skinPass === 'diffuse';
   return {
     label: key,
     layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
@@ -654,6 +784,7 @@ function flatDescriptor(
       }),
       entryPoint: 'main',
       buffers: vertexBufferLayouts(present, instanced),
+      constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced), skinEight, cloth),
     },
     fragment: {
       module: shaderModule(device, {
@@ -662,7 +793,7 @@ function flatDescriptor(
       }),
       entryPoint: 'main',
       /* Every variant declares it, so every lit pipeline may set it: see `PipelineCache`. */
-      constants: flatFragmentConstants(variant, cache),
+      constants: flatFragmentConstants(variant, cache, model, skinPass),
       targets: [
         oitTarget(oit) ??
           (translucent === 'additive'
@@ -689,7 +820,13 @@ function flatDescriptor(
       ],
     },
     primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back' },
-    multisample: { count: cache.sampleCount },
+    /* Coverage only where a sample count can carry it: WebGPU refuses it at one sample. */
+    multisample: {
+      count: cache.sampleCount,
+      ...(alphaToCoverage && cache.sampleCount > 1 && !diffuseAlone
+        ? { alphaToCoverageEnabled: true }
+        : {}),
+    },
     /*
      * `less`, matching the WebGL2 path's `LESS` rather than `LEQUAL`, and for the reason
      * `drawMesh` documents there: under `LEQUAL` two coplanar surfaces do not merely tie,
@@ -697,8 +834,9 @@ function flatDescriptor(
      */
     depthStencil: {
       format: DEPTH_FORMAT,
-      depthWriteEnabled: depthWrite,
-      depthCompare: DEPTH_COMPARE,
+      /* The diffuse half is the same surface again: it finds the depth the frame's half wrote. */
+      depthWriteEnabled: depthWrite && !diffuseAlone,
+      depthCompare: diffuseAlone ? 'equal' : DEPTH_COMPARE,
       /*
        * Baked in, where the other backend toggles it around the draw. Both read
        * `depthOffsetForLayer`, so a layer is worth the same depth on either one, and a pipeline