@driftengine/core 4.9.0 → 4.11.0

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

@@ -0,0 +1,86 @@
+/**
+ * The cloth solver's layouts and one compute pipeline an entry point of `shaders/clothSolve.wgsl.ts`,
+ * built once a device and shared by every set of garments on it.
+ */
+import { CLOTH_SOLVE_WGSL } from './shaders/clothSolve.wgsl.ts';
+import { shaderModule } from './shaderModules.ts';
+
+const COMPUTE = 0x4;
+
+export const CLOTH_ENTRIES = [
+  'clothPose',
+  'clothRest',
+  'clothBegin',
+  'clothPredict',
+  'clothDistance',
+  'clothBending',
+  'clothTether',
+  'clothLimit',
+  'clothFinish',
+  'clothBlend',
+  'clothPublish',
+] as const;
+export type ClothEntry = (typeof CLOTH_ENTRIES)[number];
+
+export interface ClothKernels {
+  readonly layout: GPUBindGroupLayout;
+  readonly outputLayout: GPUBindGroupLayout;
+  readonly pipelines: Readonly<Record<ClothEntry, GPUComputePipeline>>;
+}
+
+const kernelsByDevice = new WeakMap<GPUDevice, ClothKernels>();
+
+export function clothKernelsFor(device: GPUDevice): ClothKernels {
+  const held = kernelsByDevice.get(device);
+  if (held !== undefined) return held;
+  const uniform = (binding: number, dynamic: boolean): GPUBindGroupLayoutEntry => ({
+    binding,
+    visibility: COMPUTE,
+    buffer: { type: 'uniform', hasDynamicOffset: dynamic },
+  });
+  const storage = (binding: number, type: GPUBufferBindingType): GPUBindGroupLayoutEntry => ({
+    binding,
+    visibility: COMPUTE,
+    buffer: { type },
+  });
+  /* Seven storage buffers of the eight a stage is granted: the shader's header says why so few. */
+  const layout = device.createBindGroupLayout({
+    label: 'cloth.solve',
+    entries: [
+      uniform(0, false),
+      uniform(1, true),
+      uniform(2, true),
+      storage(3, 'storage'),
+      storage(4, 'storage'),
+      storage(5, 'read-only-storage'),
+      storage(6, 'read-only-storage'),
+      storage(7, 'storage'),
+      storage(8, 'read-only-storage'),
+      storage(9, 'read-only-storage'),
+    ],
+  });
+  const outputLayout = device.createBindGroupLayout({
+    label: 'cloth.publish',
+    entries: [
+      {
+        binding: 0,
+        visibility: COMPUTE,
+        storageTexture: { access: 'write-only', format: 'rgba32float' },
+      },
+    ],
+  });
+  const module = shaderModule(device, { label: 'cloth.solve', code: CLOTH_SOLVE_WGSL });
+  const solve = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+  const publish = device.createPipelineLayout({ bindGroupLayouts: [layout, outputLayout] });
+  const pipelines = {} as Record<ClothEntry, GPUComputePipeline>;
+  for (const entry of CLOTH_ENTRIES) {
+    pipelines[entry] = device.createComputePipeline({
+      label: `cloth.${entry}`,
+      layout: entry === 'clothPublish' ? publish : solve,
+      compute: { module, entryPoint: entry },
+    });
+  }
+  const kernels = { layout, outputLayout, pipelines };
+  kernelsByDevice.set(device, kernels);
+  return kernels;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * What one garment of a set has asked the device for and the device has not yet recorded: a pose, a
+ * reset to rest, steps — each with the numbers its round reads, taken when it was asked for.
+ *
+ * **Taken when asked for, because they change after.** `ClothControl` moves its targets to a step's
+ * fraction and calls the device; by the time the set records the step, the next step has moved them
+ * again. So each op keeps the head of its record — fraction, blend, the poses it reads, the carry and
+ * the wind — as it stood, and the set copies it into the round that runs it.
+ *
+ * Grows by doubling and never shrinks, so a settled set allocates nothing a frame.
+ */
+
+/** Words of a garment's record in a round: the shader's `Pace`. */
+export const PACE_WORDS = 44;
+/** The head of it, which an op carries: everything before the garment's own constants. */
+export const PACE_HEAD_WORDS = 32;
+
+export const CLOTH_OP_POSE = 0;
+export const CLOTH_OP_REST = 1;
+export const CLOTH_OP_STEP = 2;
+
+export class ClothOps {
+  private kinds = new Uint8Array(8);
+  private heads = new ArrayBuffer(8 * PACE_HEAD_WORDS * 4);
+  private floats = new Float32Array(this.heads);
+  private words = new Uint32Array(this.heads);
+  private first = 0;
+  private end = 0;
+
+  get pending(): number {
+    return this.end - this.first;
+  }
+
+  /** The kind of the op to run next, or -1 where there is none. */
+  get next(): number {
+    return this.first < this.end ? (this.kinds[this.first] as number) : -1;
+  }
+
+  /** A new op of `kind`, its head zeroed, for the caller to fill: the float and word offset of it. */
+  push(kind: number): number {
+    if (this.end === this.kinds.length) this.grow();
+    const at = this.end * PACE_HEAD_WORDS;
+    this.floats.fill(0, at, at + PACE_HEAD_WORDS);
+    this.kinds[this.end] = kind;
+    this.end++;
+    return at;
+  }
+
+  get headFloats(): Float32Array {
+    return this.floats;
+  }
+
+  get headWords(): Uint32Array {
+    return this.words;
+  }
+
+  /**
+   * The next op's head into `out` at `at`, and the op gone. Copied as words, since a head holds
+   * integers too, and a word at a time, since a view a call would be an allocation a round.
+   */
+  take(out: Uint32Array, at: number): void {
+    const from = this.first * PACE_HEAD_WORDS;
+    for (let w = 0; w < PACE_HEAD_WORDS; w++) out[at + w] = this.words[from + w] as number;
+    this.first++;
+    if (this.first === this.end) {
+      this.first = 0;
+      this.end = 0;
+    }
+  }
+
+  private grow(): void {
+    const live = this.end - this.first;
+    const capacity = this.kinds.length * 2;
+    const kinds = new Uint8Array(capacity);
+    kinds.set(this.kinds.subarray(this.first, this.end));
+    const heads = new ArrayBuffer(capacity * PACE_HEAD_WORDS * 4);
+    const floats = new Float32Array(heads);
+    floats.set(this.floats.subarray(this.first * PACE_HEAD_WORDS, this.end * PACE_HEAD_WORDS));
+    this.kinds = kinds;
+    this.heads = heads;
+    this.floats = floats;
+    this.words = new Uint32Array(heads);
+    this.first = 0;
+    this.end = live;
+  }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * What a set of garments writes once into the buffers its rounds read, and the one per-step number
+ * worked out on the CPU: the constants, each round slot's first record, each colour's and each
+ * garment's batch slot, and the carry a step hands a garment that keeps less than all of its
+ * character's motion. Plain functions over the packed set, apart from the solver that schedules.
+ */
+import type { ResolvedClothParameters } from '@driftengine/physics';
+
+import type { PackedClothSet } from './clothSetPack.ts';
+import { DYNAMIC_ALIGNMENT } from './uniformRing.ts';
+
+/** Bytes of the shader's `Constants`. */
+export const CLOTH_CONSTANT_BYTES = 48;
+
+/** The set's `Constants`: its totals, and the substep length every garment of it shares. */
+export function clothConstants(packed: PackedClothSet, h: number): ArrayBuffer {
+  const bytes = new ArrayBuffer(CLOTH_CONSTANT_BYTES);
+  const u = new Uint32Array(bytes);
+  const f = new Float32Array(bytes);
+  u[0] = packed.count;
+  u[1] = packed.distances;
+  u[2] = packed.bendings;
+  u[3] = packed.joints;
+  u[4] = packed.colliders;
+  f[8] = h;
+  f[9] = 1 / h;
+  f[10] = 1 / (h * h);
+  return bytes;
+}
+
+/** Each of `rounds` round slots' first record: the round's index times the garments. */
+export function clothRoundOffsets(rounds: number, garments: number): Uint32Array<ArrayBuffer> {
+  const words = new Uint32Array((rounds * DYNAMIC_ALIGNMENT) / 4);
+  for (let r = 0; r < rounds; r++) words[(r * DYNAMIC_ALIGNMENT) / 4] = r * garments;
+  return words;
+}
+
+/**
+ * Each colour's range, twice — opening a substep's iterations and not — at a slot each, kind by
+ * kind; then one slot a garment for publishing, its particles' range and its index.
+ */
+export function clothBatchSlots(packed: PackedClothSet): Uint32Array<ArrayBuffer> {
+  const { distanceBatches, bendingBatches, tetherBatches, garments } = packed;
+  const kinds = [distanceBatches, bendingBatches, tetherBatches];
+  let slots = garments.length;
+  for (const batches of kinds) slots += (batches.length - 1) * 2;
+  const words = new Uint32Array((slots * DYNAMIC_ALIGNMENT) / 4);
+  let slot = 0;
+  for (const batches of kinds) {
+    for (let b = 0; b + 1 < batches.length; b++) {
+      for (let first = 0; first < 2; first++) {
+        const at = (slot * DYNAMIC_ALIGNMENT) / 4;
+        words[at] = batches[b] as number;
+        words[at + 1] = batches[b + 1] as number;
+        words[at + 2] = first;
+        slot++;
+      }
+    }
+  }
+  garments.forEach((range, g) => {
+    const at = (slot * DYNAMIC_ALIGNMENT) / 4;
+    words[at] = range.particleBase;
+    words[at + 1] = range.particleBase + range.count;
+    words[at + 2] = g;
+    slot++;
+  });
+  return words;
+}
+
+/**
+ * `carryParticles`' rotation, origin and move, into a record's head at `at`, between the model
+ * matrices before and after the step; nothing where the garment keeps all of its character's
+ * motion, which leaves the head's carry at 0.
+ */
+export function writeClothCarry(
+  parameters: ResolvedClothParameters,
+  previous: Float32Array,
+  next: Float32Array,
+  words: Uint32Array,
+  f: Float32Array,
+  at: number,
+): void {
+  const turn = 1 - parameters.angularInertia;
+  const move = 1 - parameters.linearInertia;
+  if (turn === 0 && move === 0) return;
+  words[at + 3] = 1;
+  /* Column c of R = R_next × R_previousᵀ, at turn0 … turn2. */
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) {
+      let sum = 0;
+      for (let k = 0; k < 3; k++) {
+        sum += (next[k * 4 + row] as number) * (previous[k * 4 + col] as number);
+      }
+      f[at + 8 + col * 4 + row] = sum;
+    }
+  }
+  for (let k = 0; k < 3; k++) {
+    f[at + 20 + k] = previous[12 + k] as number;
+    f[at + 24 + k] = ((next[12 + k] as number) - (previous[12 + k] as number)) * move;
+  }
+  f[at + 23] = turn;
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Several garments' packs as one set of buffers, so that one dispatch solves a colour of one kind of
+ * constraint for every garment at once: `packCloth`'s sections laid end to end, and each kind's
+ * records regrouped so a colour of all of them is one range.
+ *
+ * **Why regrouping by colour keeps each garment's solve.** A batch is a set of constraints that share
+ * no movable particle, and two garments share no particle at all, so colour `b` of every garment is
+ * still such a set. Each garment's own colours still run in its own order, 0 then 1 then 2, so it is
+ * solved exactly as it would be alone: the CPU solver, which steps garments one at a time, is the
+ * reference for every one of them.
+ *
+ * **Every index a record or a static holds is the set's**: a particle is offset by where its garment
+ * starts, a joint by where its garment's skin matrices start. A section `packCloth` lays at `s · n`
+ * lies at `s · N` here, with a garment's particles at its base inside it, and one more section says
+ * which garment each particle is — what a kernel reads its garment's numbers by.
+ *
+ * **What it gives up**: a colour is dispatched over the most records any garment has in it, so a set
+ * of one garment of nine colours and fourteen of three runs nine colours' dispatches for all of them;
+ * and a garment joins a set when the set is made, so changing one rebuilds the set.
+ */
+import { CLOTH_STATIC_FLOATS } from './clothSolvePack.ts';
+import type { PackedCloth } from './clothSolvePack.ts';
+
+/** Floats of statics a particle in a set: a garment's own, and which garment it is. */
+export const CLOTH_SET_STATIC_FLOATS = CLOTH_STATIC_FLOATS + 1;
+
+/** `packCloth`'s sections: where each starts, in particle counts, and its floats a particle. */
+const SECTIONS: readonly (readonly [number, number])[] = [
+  [0, 1],
+  [1, 1],
+  [2, 2],
+  [4, 2],
+  [6, 1],
+  [7, 3],
+  [10, 3],
+  [13, 16],
+];
+/** Where the influences start, and where the garment's index sits, in particle counts. */
+const INFLUENCES = 13;
+const GARMENT = CLOTH_STATIC_FLOATS;
+
+/** Where one garment sits in a set. */
+export interface ClothGarmentRange {
+  readonly particleBase: number;
+  readonly count: number;
+  readonly jointBase: number;
+  readonly joints: number;
+  readonly colliderBase: number;
+  readonly colliders: number;
+  /** `packCloth`'s limit flags, the garment's own. */
+  readonly limits: number;
+  readonly rigged: boolean;
+}
+
+export interface PackedClothSet {
+  /** Particles across every garment. */
+  readonly count: number;
+  readonly statics: Float32Array;
+  readonly constraints: Uint32Array;
+  readonly distances: number;
+  readonly bendings: number;
+  readonly tethers: number;
+  /** Each kind's colours across the set: colour `b` of every garment is `[b]` up to `[b + 1]`. */
+  readonly distanceBatches: Uint32Array;
+  readonly bendingBatches: Uint32Array;
+  readonly tetherBatches: Uint32Array;
+  /** Skin matrices and colliders across every garment. */
+  readonly joints: number;
+  readonly colliders: number;
+  readonly garments: readonly ClothGarmentRange[];
+}
+
+export function packClothSet(packs: readonly PackedCloth[]): PackedClothSet {
+  const garments: ClothGarmentRange[] = [];
+  let count = 0;
+  let joints = 0;
+  let colliders = 0;
+  for (const pack of packs) {
+    garments.push({
+      particleBase: count,
+      count: pack.count,
+      jointBase: joints,
+      joints: pack.joints,
+      colliderBase: colliders,
+      colliders: pack.colliders,
+      limits: pack.limits,
+      rigged: pack.rigged,
+    });
+    count += pack.count;
+    joints += pack.joints;
+    colliders += pack.colliders;
+  }
+
+  const statics = new Float32Array(count * CLOTH_SET_STATIC_FLOATS);
+  packs.forEach((pack, g) => {
+    const { particleBase: base, count: n, jointBase } = garments[g] as ClothGarmentRange;
+    for (const [start, stride] of SECTIONS) {
+      const from = pack.statics.subarray(start * n, (start + stride) * n);
+      statics.set(from, start * count + base * stride);
+    }
+    /* Each influence's joint, the set's: four joints, four weights, four joints, four weights. */
+    for (let i = 0; i < n; i++) {
+      const at = INFLUENCES * count + (base + i) * 16;
+      for (let k = 0; k < 4; k++) {
+        statics[at + k] = (statics[at + k] as number) + jointBase;
+        statics[at + 8 + k] = (statics[at + 8 + k] as number) + jointBase;
+      }
+    }
+    statics.fill(g, GARMENT * count + base, GARMENT * count + base + n);
+  });
+
+  const distances = sum(packs, (pack) => pack.distances);
+  const bendings = sum(packs, (pack) => pack.bendings);
+  const tethers = sum(packs, (pack) => pack.tethers);
+  const constraints = new Uint32Array(distances * 4 + bendings * 6 + tethers * 3);
+  /* Each kind: where its records start, a record's words, how many of them are particles. */
+  const distanceBatches = regroup(packs, garments, constraints, 0, 4, 2, 'distanceBatches');
+  const bendingStart = distances * 4;
+  const bendingBatches = regroup(
+    packs,
+    garments,
+    constraints,
+    bendingStart,
+    6,
+    4,
+    'bendingBatches',
+  );
+  const tetherStart = bendingStart + bendings * 6;
+  const tetherBatches = regroup(packs, garments, constraints, tetherStart, 3, 2, 'tetherBatches');
+  return {
+    count,
+    statics,
+    constraints,
+    distances,
+    bendings,
+    tethers,
+    distanceBatches,
+    bendingBatches,
+    tetherBatches,
+    joints,
+    colliders,
+    garments,
+  };
+}
+
+function sum(packs: readonly PackedCloth[], of: (pack: PackedCloth) => number): number {
+  let total = 0;
+  for (const pack of packs) total += of(pack);
+  return total;
+}
+
+/** Where one kind's records start in a garment's own pack, in words. */
+function kindStart(pack: PackedCloth, kind: BatchKind): number {
+  if (kind === 'distanceBatches') return 0;
+  if (kind === 'bendingBatches') return pack.distances * 4;
+  return pack.distances * 4 + pack.bendings * 6;
+}
+
+type BatchKind = 'distanceBatches' | 'bendingBatches' | 'tetherBatches';
+
+/**
+ * One kind's records, colour by colour and within a colour garment by garment, into `out` from
+ * `start`; each record's first `ids` words offset by its garment's first particle. The set's colours.
+ */
+function regroup(
+  packs: readonly PackedCloth[],
+  garments: readonly ClothGarmentRange[],
+  out: Uint32Array,
+  start: number,
+  words: number,
+  ids: number,
+  kind: BatchKind,
+): Uint32Array {
+  let colours = 0;
+  for (const pack of packs) colours = Math.max(colours, pack[kind].length - 1);
+  const batches = new Uint32Array(colours + 1);
+  let record = 0;
+  for (let b = 0; b < colours; b++) {
+    packs.forEach((pack, g) => {
+      const own = pack[kind];
+      if (b + 1 >= own.length) return;
+      const base = (garments[g] as ClothGarmentRange).particleBase;
+      const from = kindStart(pack, kind);
+      for (let r = own[b] as number; r < (own[b + 1] as number); r++) {
+        const src = from + r * words;
+        const dst = start + record * words;
+        for (let w = 0; w < words; w++) {
+          const word = pack.constraints[src + w] as number;
+          out[dst + w] = w < ids ? word + base : word;
+        }
+        record++;
+      }
+    });
+    batches[b + 1] = record;
+  }
+  return batches;
+}

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

@@ -12,7 +12,8 @@
  * the level nominally has.
  */
 import type { CompressedTextureFormat, CompressedTextureSource } from '../../compressedSource.ts';
-import { BLOCK_BYTES } from '../../compressedSource.ts';
+import { BLOCK_SHAPES, blockFamily } from '../../compressedSource.ts';
+import type { BlockFormat } from '../../compressedSource.ts';
 
 const GPU_FORMAT: Readonly<Record<CompressedTextureFormat, GPUTextureFormat>> = {
   bc1: 'bc1-rgba-unorm',
@@ -25,13 +26,61 @@ const GPU_FORMAT: Readonly<Record<CompressedTextureFormat, GPUTextureFormat>> =
   bc5: 'bc5-rg-unorm',
   bc7: 'bc7-rgba-unorm',
   'bc7-srgb': 'bc7-rgba-unorm-srgb',
+  'etc2-rgb8': 'etc2-rgb8unorm',
+  'etc2-rgb8-srgb': 'etc2-rgb8unorm-srgb',
+  'etc2-rgb8a1': 'etc2-rgb8a1unorm',
+  'etc2-rgb8a1-srgb': 'etc2-rgb8a1unorm-srgb',
+  'etc2-rgba8': 'etc2-rgba8unorm',
+  'etc2-rgba8-srgb': 'etc2-rgba8unorm-srgb',
+  'eac-r11': 'eac-r11unorm',
+  'eac-rg11': 'eac-rg11unorm',
+  'astc-4x4': 'astc-4x4-unorm',
+  'astc-4x4-srgb': 'astc-4x4-unorm-srgb',
+  'astc-5x4': 'astc-5x4-unorm',
+  'astc-5x4-srgb': 'astc-5x4-unorm-srgb',
+  'astc-5x5': 'astc-5x5-unorm',
+  'astc-5x5-srgb': 'astc-5x5-unorm-srgb',
+  'astc-6x5': 'astc-6x5-unorm',
+  'astc-6x5-srgb': 'astc-6x5-unorm-srgb',
+  'astc-6x6': 'astc-6x6-unorm',
+  'astc-6x6-srgb': 'astc-6x6-unorm-srgb',
+  'astc-8x5': 'astc-8x5-unorm',
+  'astc-8x5-srgb': 'astc-8x5-unorm-srgb',
+  'astc-8x6': 'astc-8x6-unorm',
+  'astc-8x6-srgb': 'astc-8x6-unorm-srgb',
+  'astc-8x8': 'astc-8x8-unorm',
+  'astc-8x8-srgb': 'astc-8x8-unorm-srgb',
+  'astc-10x5': 'astc-10x5-unorm',
+  'astc-10x5-srgb': 'astc-10x5-unorm-srgb',
+  'astc-10x6': 'astc-10x6-unorm',
+  'astc-10x6-srgb': 'astc-10x6-unorm-srgb',
+  'astc-10x8': 'astc-10x8-unorm',
+  'astc-10x8-srgb': 'astc-10x8-unorm-srgb',
+  'astc-10x10': 'astc-10x10-unorm',
+  'astc-10x10-srgb': 'astc-10x10-unorm-srgb',
+  'astc-12x10': 'astc-12x10-unorm',
+  'astc-12x10-srgb': 'astc-12x10-unorm-srgb',
+  'astc-12x12': 'astc-12x12-unorm',
+  'astc-12x12-srgb': 'astc-12x12-unorm-srgb',
 };
 
 /** Every BC format, where the device carries the feature; none where it does not. */
+/** The feature that grants each family, which `select.ts` asks for wherever the adapter offers it. */
+const FEATURE: Readonly<Record<'bc' | 'etc2' | 'astc', string>> = {
+  bc: 'texture-compression-bc',
+  etc2: 'texture-compression-etc2',
+  astc: 'texture-compression-astc',
+};
+
 export function gpuCompressedFormats(device: GPUDevice): CompressedTextureFormat[] {
-  return device.features.has('texture-compression-bc')
-    ? (Object.keys(GPU_FORMAT) as CompressedTextureFormat[])
-    : [];
+  return (Object.keys(GPU_FORMAT) as CompressedTextureFormat[]).filter((name) =>
+    device.features.has(FEATURE[blockFamily(baseOf(name))]),
+  );
+}
+
+/** The format a name is of, without its colour space. */
+function baseOf(name: CompressedTextureFormat): BlockFormat {
+  return (name.endsWith('-srgb') ? name.slice(0, -'-srgb'.length) : name) as BlockFormat;
 }
 
 /** A texture holding `layers` as `name`, `levels` levels of each, written as they are. */
@@ -43,21 +92,22 @@ export function createCompressedTexture(
 ): GPUTexture {
   const { format, width, height } = layers[0] as CompressedTextureSource;
   const texture = device.createTexture({
-    label: 'surface.texture.bc',
+    label: `surface.texture.${format}`,
     size: [width, height, layers.length],
     format: GPU_FORMAT[name],
     mipLevelCount: levels,
     usage: 0x2 | 0x4, // COPY_DST | TEXTURE_BINDING
   });
+  const block = BLOCK_SHAPES[format];
   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);
+    const across = Math.ceil(Math.max(1, width >> level) / block.width);
+    const down = Math.ceil(Math.max(1, height >> level) / block.height);
     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 },
+        { bytesPerRow: across * block.bytes, rowsPerImage: down },
+        { width: across * block.width, height: down * block.height, depthOrArrayLayers: 1 },
       );
     }
   }