@driftengine/core 4.8.7 → 4.10.0

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

@@ -29,8 +29,8 @@ import { SkinPaletteTexture } from './skinPaletteTexture.ts';
  * different rig at every set — the comparison is what tells the two apart.
  *
  * **It was capped at 128 until 4.8.6, and the cap declined draws.** A stage of three dozen idling
- * extras beside two fighters filled it in one frame and every skinned draw past it was refused, so
- * the consumer stood its crowd in the bind pose. The ring now holds as many palettes as a frame
+ * extras beside two characters filled it in one frame and every skinned draw past it was refused,
+ * so the consumer stood its crowd in the bind pose. The ring now holds as many palettes as a frame
  * holds draws (`RenderQuality.drawsPerFrame`), since no frame can bind more palettes than it draws;
  * a slot still allocates its texture only the first time a frame reaches it, so a scene with two
  * characters holds two. **What it costs** is a texture and a cached bind group a slot, 1.5 KB for a
@@ -46,8 +46,12 @@ import { SkinPaletteTexture } from './skinPaletteTexture.ts';
  */
 export class SkinPaletteRing {
   private readonly slots: SkinPaletteTexture[] = [];
-  /** What each slot was last written with, for the comparison that lets a pass reuse it. */
+  /**
+   * What each slot was last written with, for the comparison that lets a pass reuse it: a copy
+   * that grows with the largest rig the slot has held, and how much of it the last rig filled.
+   */
   private readonly held: Float32Array[] = [];
+  private readonly heldLength: number[] = [];
   /** The slot each palette array last went into, by identity. Weak, so a caller's array can go. */
   private readonly lastSlot = new WeakMap<Float32Array, number>();
   private used = 0;
@@ -119,12 +123,13 @@ export class SkinPaletteRing {
     slot.update(device, palette);
     this.uploads += 1;
     let copy = this.held[at];
-    if (copy === undefined || copy.length !== palette.length) {
-      /* Once per slot and joint count, the way the slot's own texture is: never per frame. */
+    if (copy === undefined || copy.length < palette.length) {
+      /* Once per slot and larger rig, the way the slot's own texture is: never per frame. */
       copy = new Float32Array(palette.length);
       this.held[at] = copy;
     }
     copy.set(palette);
+    this.heldLength[at] = palette.length;
     this.lastSlot.set(palette, at);
     return at;
   }
@@ -138,14 +143,15 @@ export class SkinPaletteRing {
     for (const slot of this.slots) slot.dispose();
     this.slots.length = 0;
     this.held.length = 0;
+    this.heldLength.length = 0;
     this.used = 0;
   }
 
   /** Whether a slot was last written with exactly these numbers. */
   private holds(slot: number, palette: Float32Array): boolean {
     const copy = this.held[slot];
-    if (copy === undefined || copy.length !== palette.length) return false;
-    for (let i = 0; i < copy.length; i++) if (copy[i] !== palette[i]) return false;
+    if (copy === undefined || this.heldLength[slot] !== palette.length) return false;
+    for (let i = 0; i < palette.length; i++) if (copy[i] !== palette[i]) return false;
     return true;
   }
 }

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

@@ -22,6 +22,12 @@ const TEXTURE_USAGE = {
 
 export class SkinPaletteTexture {
   private texture: GPUTexture | null = null;
+  /**
+   * How many joints the texture has room for, which is the most any rig in this slot has had.
+   * **It grows and never shrinks**: the shader reads a joint by index, so a texture wider than the
+   * rig is read exactly as one that fits, and a slot that a 10-joint prop and a 296-joint character
+   * take in turn keeps one texture rather than making one at every change of rig.
+   */
   private joints = 0;
   /**
    * The view, cached rather than created per call.
@@ -38,7 +44,7 @@ export class SkinPaletteTexture {
     const joints = palette.length / 16;
     const width = paletteTextureWidth(joints);
 
-    if (this.texture === null || this.joints !== joints) {
+    if (this.texture === null || joints > this.joints) {
       this.texture?.destroy();
       this.cachedView = null;
       this.texture = device.createTexture({

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

@@ -0,0 +1,363 @@
+/**
+ * A static list on this backend: its draws recorded once, through the renderer's own draw path,
+ * into slots the list owns, and replayed as one render bundle per view.
+ *
+ * **What a recording holds is the frame's draws as the renderer would have recorded them**, taken
+ * from a pool of the list's instead of the frame graph's: a pipeline, a bind group, vertex buffers
+ * and four dynamic offsets each. Three of the four never change once recorded — the draw's own
+ * slot in `entries`, written once, and its material's slot in the store, pinned. The other two are
+ * the view's: the pass block and the view block, which differ between the frame, a mirror and a
+ * capture of the same frame. So each view a frame draws the list into takes a *copy* — a slot of
+ * `passes` and one of `views`, written for that view — and a bundle is encoded per copy from the
+ * same commands with that copy's two offsets. A frame that draws a list twice uploads two blocks
+ * and executes two bundles, and records nothing.
+ *
+ * **Its own buffers, and bind groups over them.** A bundle bakes the buffers its groups bind, and
+ * the frame's rings are reset every frame, so a list binds rings of its own: the renderer swaps
+ * them in while it records the list's draws, and the groups that recording builds go into the
+ * list's cache rather than the frame's.
+ *
+ * **Recorded again when what it baked has moved**: the renderer's groups (a texture forgotten, a
+ * frame texture rebound, a ring grown), the pipeline cache's lit set, the store's slots, or the
+ * list's own rings. Each is a number compared at replay, so a stale recording is never replayed.
+ *
+ * What it gives up: culling, since a bundle draws everything recorded into it; and memory, a pass
+ * block a view a list, which is a few kilobytes.
+ */
+import type { StaticDrawsList, StaticEntry } from '../../staticDraws.ts';
+import type { CommandPool, DrawCommand } from './drawCommand.ts';
+import { createCommandPool, resetPool, takeCommand } from './drawCommand.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { UniformRing } from './uniformRing.ts';
+
+const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
+/** Views a list starts with room for: the frame's and one capture's. Doubles when a frame asks more. */
+const FIRST_COPIES = 2;
+/** Recordings a list keeps before letting the oldest go: a target and a starting state each. */
+const MOST_RECORDINGS = 4;
+
+/** What one recording was made against, and what it recorded. */
+export interface StaticRecording {
+  readonly cache: PipelineCache;
+  /** The material block's words the list started from: the pass's state, which entries patch. */
+  readonly start: Int32Array;
+  readonly startHash: number;
+  readonly cutout: string;
+  readonly surfaceKept: boolean;
+  /** Stamps compared at replay; any that moved makes the recording stale. */
+  cacheVersion: number;
+  groupEpoch: number;
+  storeEpoch: number;
+  ringEpoch: number;
+  /** The frame pass's commands, and the reflection pass's surface halves, with the record's offsets. */
+  readonly frame: CommandPool;
+  readonly surface: CommandPool;
+  /** Material slots pinned for these commands, and the material changes recording them asked for. */
+  readonly pins: number[];
+  materialAsks: number;
+  /** Under the screen-space skin blur a skin entry splits into halves no bundle replays. */
+  immediate: boolean;
+  /** Per copy, the bundles `executeBundles` takes; null until a copy is first replayed. */
+  readonly frameBundles: (readonly GPURenderBundle[] | null)[];
+  readonly surfaceBundles: (readonly GPURenderBundle[] | null)[];
+  /** The frame it was last replayed in, which picks the one to let go. */
+  usedIn: number;
+}
+
+export class GpuStaticDraws implements StaticDrawsList {
+  disposed = false;
+  /** The draws' own slots, one a draw, written by the recording. */
+  readonly drawRing: UniformRing;
+  /** A pass block and a view block a copy. */
+  passes: UniformRing;
+  views: UniformRing;
+  /** Bumped whenever the three rings are made again, which invalidates every recording. */
+  ringEpoch = 0;
+  /** The list's own lit groups and blank group, built over its rings by the renderer. */
+  groups: Map<unknown, unknown> = new Map();
+  blank: GPUBindGroup | null = null;
+  /** The group epoch the cache above was built in. */
+  groupEpoch = -1;
+  /** The store epoch the list's pins were taken in: pins from before a forgetting are let go of. */
+  pinEpoch = -1;
+  readonly recordings: StaticRecording[] = [];
+  private copies = 0;
+  private copyFrame = -1;
+
+  constructor(
+    private readonly device: GPUDevice,
+    readonly list: StaticDrawsList,
+    private readonly passSize: number,
+    private readonly viewSize: number,
+    drawSize: number,
+  ) {
+    this.drawRing = new UniformRing(
+      device,
+      drawSize,
+      Math.max(1, list.draws),
+      USAGE_UNIFORM_DST,
+      'static.draws',
+    );
+    this.passes = new UniformRing(
+      device,
+      passSize,
+      FIRST_COPIES,
+      USAGE_UNIFORM_DST,
+      'static.passes',
+    );
+    this.views = new UniformRing(device, viewSize, FIRST_COPIES, USAGE_UNIFORM_DST, 'static.views');
+    this.claimCopies();
+  }
+
+  /** The captured entries, which the renderer replays to record them. */
+  get entries(): readonly StaticEntry[] {
+    return this.list.entries;
+  }
+
+  get draws(): number {
+    return this.list.draws;
+  }
+
+  /**
+   * The next view's copy in frame `frame`, growing the copies when a frame asks for more than there
+   * are — which makes every recording stale, since the groups bound the old rings.
+   */
+  takeCopy(frame: number): number {
+    if (frame !== this.copyFrame) {
+      this.copyFrame = frame;
+      this.copies = 0;
+    }
+    const copy = this.copies;
+    this.copies += 1;
+    if (copy >= this.passes.slots) this.growCopies(this.passes.slots * 2);
+    return copy;
+  }
+
+  /** The two offsets copy `copy` binds. */
+  passOffset(copy: number): number {
+    return copy * this.passes.slotSize;
+  }
+
+  viewOffset(copy: number): number {
+    return copy * this.views.slotSize;
+  }
+
+  /** Copy `copy`'s pass block, written whole. Uploaded by `uploadCopy`. */
+  writePass(copy: number, block: Int32Array): void {
+    this.passes.writeBlock(this.passOffset(copy), block);
+  }
+
+  /** Copy `copy`'s two blocks to the device, and no other copy's: each view writes only its own. */
+  uploadCopy(copy: number): void {
+    this.passes.uploadSlot(this.passOffset(copy));
+    this.views.uploadSlot(this.viewOffset(copy));
+  }
+
+  /** The draws' own slots, after a recording wrote them. */
+  uploadDraws(): void {
+    this.drawRing.flush();
+  }
+
+  /** A recording that matches, if one does: the same target, starting state and side passes. */
+  find(
+    cache: PipelineCache,
+    start: Int32Array,
+    startHash: number,
+    cutout: string,
+    surfaceKept: boolean,
+  ): StaticRecording | null {
+    for (const recording of this.recordings) {
+      if (
+        recording.cache === cache &&
+        recording.startHash === startHash &&
+        recording.cutout === cutout &&
+        recording.surfaceKept === surfaceKept &&
+        sameWords(recording.start, start)
+      ) {
+        return recording;
+      }
+    }
+    return null;
+  }
+
+  /** A new, empty recording, letting the least recently used go past the most kept. */
+  open(
+    cache: PipelineCache,
+    start: Int32Array,
+    startHash: number,
+    cutout: string,
+    surfaceKept: boolean,
+    unpin: (offset: number) => void,
+  ): StaticRecording {
+    if (this.recordings.length >= MOST_RECORDINGS) {
+      let oldest = 0;
+      for (let i = 1; i < this.recordings.length; i++) {
+        if (
+          (this.recordings[i] as StaticRecording).usedIn <
+          (this.recordings[oldest] as StaticRecording).usedIn
+        )
+          oldest = i;
+      }
+      const [gone] = this.recordings.splice(oldest, 1);
+      if (gone !== undefined) release(gone, unpin);
+    }
+    const recording: StaticRecording = {
+      cache,
+      start: new Int32Array(start),
+      startHash,
+      cutout,
+      surfaceKept,
+      cacheVersion: -1,
+      groupEpoch: -1,
+      storeEpoch: -1,
+      ringEpoch: -1,
+      frame: createCommandPool(this.list.draws),
+      surface: createCommandPool(0),
+      pins: [],
+      materialAsks: 0,
+      immediate: false,
+      frameBundles: [],
+      surfaceBundles: [],
+      usedIn: -1,
+    };
+    this.recordings.push(recording);
+    return recording;
+  }
+
+  /** Empty a recording to record it again: its pins let go, its commands and bundles dropped. */
+  clear(recording: StaticRecording, unpin: (offset: number) => void): void {
+    release(recording, unpin);
+    resetPool(recording.frame);
+    resetPool(recording.surface);
+    recording.frameBundles.length = 0;
+    recording.surfaceBundles.length = 0;
+    recording.immediate = false;
+    recording.materialAsks = 0;
+  }
+
+  /** Every recording, let go; what disposal and a forgetting store both do. */
+  forget(unpin: ((offset: number) => void) | null): void {
+    for (const recording of this.recordings) release(recording, unpin);
+    this.recordings.length = 0;
+  }
+
+  dispose(unpin: ((offset: number) => void) | null): void {
+    this.disposed = true;
+    this.forget(unpin);
+    this.drawRing.dispose();
+    this.passes.dispose();
+    this.views.dispose();
+  }
+
+  private growCopies(copies: number): void {
+    this.passes.dispose();
+    this.views.dispose();
+    this.passes = new UniformRing(
+      this.device,
+      this.passSize,
+      copies,
+      USAGE_UNIFORM_DST,
+      'static.passes',
+    );
+    this.views = new UniformRing(
+      this.device,
+      this.viewSize,
+      copies,
+      USAGE_UNIFORM_DST,
+      'static.views',
+    );
+    this.claimCopies();
+    this.ringEpoch += 1;
+    this.groups = new Map();
+    this.blank = null;
+  }
+
+  /** Every copy's slot, taken once: a copy is a fixed offset, never handed out again. */
+  private claimCopies(): void {
+    for (let copy = 0; copy < this.passes.slots; copy++) {
+      this.passes.allocate();
+      this.views.allocate();
+    }
+  }
+}
+
+/** A command the recording takes in place of the frame graph's. */
+export function takeRecorded(pool: CommandPool): DrawCommand {
+  const command = pool.commands[takeCommand(pool)] as DrawCommand;
+  command.offsetCount = 0;
+  command.vertexCount = 0;
+  command.indexBuffer = null;
+  command.indexed = false;
+  command.instances = 1;
+  command.indirect = null;
+  return command;
+}
+
+/** What a render bundle must agree with: the pass it is executed in. */
+export interface BundleTarget {
+  readonly colorFormats: (GPUTextureFormat | null)[];
+  readonly depthStencilFormat: GPUTextureFormat;
+  readonly sampleCount: number;
+  readonly depthReadOnly: boolean;
+}
+
+/**
+ * One copy's bundle of a pool's commands: each lit command as recorded but for the pass and view
+ * offsets, which are the copy's. Allocates, and runs once a copy a recording, never per frame.
+ */
+export function encodeBundle(
+  device: GPUDevice,
+  target: BundleTarget,
+  pool: CommandPool,
+  passOffset: number,
+  viewOffset: number,
+  label: string,
+): readonly GPURenderBundle[] {
+  const encoder = device.createRenderBundleEncoder({
+    label,
+    colorFormats: target.colorFormats,
+    depthStencilFormat: target.depthStencilFormat,
+    sampleCount: target.sampleCount,
+    depthReadOnly: target.depthReadOnly,
+    stencilReadOnly: target.depthReadOnly,
+  });
+  for (let i = 0; i < pool.taken; i++) {
+    const command = pool.commands[i] as DrawCommand;
+    if (command.pipeline === null || command.bindGroup === null) continue;
+    if (command.offsetCount !== 4) {
+      throw new Error(
+        `static draws: a recorded command bound ${command.offsetCount} offsets, not a lit draw's four`,
+      );
+    }
+    encoder.setPipeline(command.pipeline);
+    encoder.setBindGroup(0, command.bindGroup, [
+      command.offsetA,
+      passOffset,
+      command.offsetC,
+      viewOffset,
+    ]);
+    for (let slot = 0; slot < command.vertexCount; slot++) {
+      const buffer = command.vertexBuffers[slot];
+      if (buffer != null) encoder.setVertexBuffer(slot, buffer);
+    }
+    if (command.indexed && command.indexBuffer !== null) {
+      encoder.setIndexBuffer(command.indexBuffer, 'uint32');
+      if (command.indirect !== null) encoder.drawIndexedIndirect(command.indirect, 0);
+      else encoder.drawIndexed(command.count, command.instances);
+    } else {
+      encoder.draw(command.count, command.instances);
+    }
+  }
+  return [encoder.finish({ label })];
+}
+
+function release(recording: StaticRecording, unpin: ((offset: number) => void) | null): void {
+  if (unpin !== null) for (const offset of recording.pins) unpin(offset);
+  recording.pins.length = 0;
+}
+
+function sameWords(a: Int32Array, b: Int32Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}

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

@@ -6,7 +6,12 @@ import type { LightmapTexels } from '../../lightmap.ts';
 import { isSceneCaptureTexels } from '../../sceneCapture.ts';
 import type { SceneCaptureTexels } from '../../sceneCapture.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.ts';
-import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.ts';
+import {
+  compressedLayers,
+  isCompressedSource,
+  planBlocks,
+  refuseBlockUpdate,
+} from '../../compressedSource.ts';
 import type {
   BlockFormat,
   CompressedTextureFormat,
@@ -192,7 +197,9 @@ export class GpuSurfaceTexture {
   /** Its view, which the flat group binds beside this image when it is a material's albedo. */
   effectsView: GPUTextureView | null = null;
   /** The block format a compressed texture holds, or null for one uploaded from images. */
-  private readonly blockFormat: BlockFormat | null;
+  private blockFormat: BlockFormat | null;
+  /** Whether the image is colour, decoded from sRGB as it is sampled: what blocks swapped in keep. */
+  private readonly srgb: boolean;
 
   constructor(
     private readonly device: GPUDevice,
@@ -210,6 +217,7 @@ export class GpuSurfaceTexture {
     ) as readonly SurfaceSource[];
     const blocks = compressedLayers(listed);
     const srgb = (options.colorSpace ?? 'linear') === 'srgb';
+    this.srgb = srgb;
     /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
        place it is correct — `surfaceTexture.ts` makes the argument in full. A capture takes the
        world's own format, which its pass resolves into. */
@@ -358,11 +366,29 @@ export class GpuSurfaceTexture {
    * hit that whenever the preview's decode won the race. The view is new then, and the texture it
    * replaced is handed back rather than destroyed: a draw recorded earlier in this frame may still
    * read it, so the renderer destroys it once nothing can, and drops every binding of the old view.
+   *
+   * **Blocks replace an image the same way**, at any size: a texture of their format holds them,
+   * read in the colour space this one was made for, and the image's is handed back. Refused, as a
+   * texture made from them would be, where `compressed` — the formats the device samples — does not
+   * take them. The way back is refused: an image cannot replace blocks.
    */
-  update(source: TexImageSource): GPUTexture | null {
+  update(
+    source: TexImageSource | CompressedTextureSource,
+    compressed: readonly CompressedTextureFormat[] = [],
+  ): GPUTexture | null {
     const replaced = this.texture;
     if (replaced === null) return null;
     refuseArrayUpdate(this.layers);
+    if (isCompressedSource(source)) {
+      const plan = planBlocks([source], this.srgb, compressed);
+      this.blockFormat = source.format;
+      this.width = source.width;
+      this.height = source.height;
+      this.levels = this.mipmapped ? plan.levels : 1;
+      this.texture = createCompressedTexture(this.device, plan.name, [source], this.levels);
+      this.current = this.arrayView(this.texture);
+      return replaced;
+    }
     refuseBlockUpdate(this.blockFormat);
     const { width, height } = sourceSize(source);
     if (width === this.width && height === this.height) {

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

@@ -23,7 +23,7 @@ export const DYNAMIC_ALIGNMENT = 256;
  * is five thousand material changes in one frame. The device buffer matches the staging, so a ring
  * at this ceiling holds 128 MiB in total and only ever reaches it by being asked to.
  */
-const MAX_RING_BYTES = 64 * 1024 * 1024;
+export const MAX_RING_BYTES = 64 * 1024 * 1024;
 
 /**
  * Per-draw uniforms, in slots, written once and bound by offset.
@@ -268,6 +268,15 @@ export class UniformRing {
     this.clean = end;
   }
 
+  /**
+   * Upload one slot now, and nothing else: for a ring whose slots are all claimed once and written
+   * one at a time — a static list's copies — where `flush` would send every slot above the lowest
+   * one written. Leaves the watermark as it was, so a later `flush` still owes what it owed.
+   */
+  uploadSlot(slot: number): void {
+    this.device.queue.writeBuffer(this.buffer, slot, this.staging, slot, this.slotSize);
+  }
+
   dispose(): void {
     this.buffer.destroy();
   }

package/src/render/bloomChain.ts

@@ -86,7 +86,7 @@ export function bloomProfileWarning(quality: {
  * already takes. Absent, or a field absent, is the response every frame had before 4.8.6.
  *
  * **Why it exists: one band over the colour less the threshold washes a stage built for another
- * engine.** Unreal's standard bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
+ * engine.** A ramped bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
  * the colour less the threshold, and spreads it over six bands, each in a tint of its own. A
  * stage authored against that — a threshold of 0.1 and tints summing below one — came out white
  * here, because subtracting so low a threshold keeps nearly every light in the frame at full
@@ -96,8 +96,8 @@ export interface BloomResponse {
   /**
    * Scene units over which a colour comes in, from none of it at the threshold to all of it this
    * far past. **0, the default, subtracts instead**: a colour keeps what it has past the threshold,
-   * the response since bloom shipped. Unreal's is 2 after exposure, so a frame exposed by `e` that
-   * wants it passes `2 / e`, as it passes the threshold over the exposure.
+   * the response since bloom shipped. A ramped bloom's is 2 after exposure, so a frame exposed by
+   * `e` that wants it passes `2 / e`, as it passes the threshold over the exposure.
    *
    * Brightness is still the largest channel rather than luminance, for the reason
    * `shaders/bloom.ts` gives; on a neutral colour the two are equal.