@driftengine/core 4.9.0 → 4.11.0

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

@@ -0,0 +1,364 @@
+/**
+ * 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.indexFormat = 'uint32';
+  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, command.indexFormat);
+      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/backend/webgpu/vertexFormats.ts

@@ -0,0 +1,113 @@
+import {
+  PACKED_ATTRIBUTES,
+  toFixed16,
+  type AttributePacking,
+  type VertexPacking,
+} from '../../vertexPacking.ts';
+
+/**
+ * A mesh's packed attributes as a WebGPU vertex reads them: each one's format and bytes, the words
+ * a pipeline key carries for them, and the writers that put sixteen-bit fixed point into the
+ * interleaved rows. What is packed how is `vertexPacking.ts`'s decision; this is only its binding.
+ *
+ * **Sixteen-bit fields are four wide, never three**, because WebGPU has no three-component
+ * sixteen-bit format: a normal or a colour takes `x4` and leaves the fourth zero, and the shader's
+ * `vec3` input reads the first three. So a normal costs eight bytes here against six on WebGL2,
+ * which reads three. Every field stays a whole number of four-byte words, so a vertex does too.
+ */
+
+/** The ways an attribute can travel other than as floats, as the key words name them. */
+const PACKINGS = ['snorm16', 'unorm16', 'constant'] as const;
+
+/** The pipeline key's word for one attribute's packing. Not a prefix of any other word. */
+function word(name: string, packing: AttributePacking): string {
+  return `${name}~${packing}`;
+}
+
+/** The key's suffix for this packing: one word each attribute not travelling as floats. */
+export function packingKey(packing: VertexPacking): string {
+  let key = '';
+  for (const name of PACKED_ATTRIBUTES) {
+    if (packing[name] !== 'float') key += `:${word(name, packing[name])}`;
+  }
+  return key;
+}
+
+/** Mark this packing in a pipeline's `present`, which is what `vertexBufferLayouts` reads. */
+export function markPacking(present: Record<string, boolean>, packing: VertexPacking): void {
+  for (const name of PACKED_ATTRIBUTES) {
+    if (packing[name] !== 'float') present[word(name, packing[name])] = true;
+  }
+}
+
+/** Mark the packing a mesh's key names, for a pass that has the mesh and not its data. */
+export function markPackingOfKey(present: Record<string, boolean>, key: string): void {
+  for (const name of PACKED_ATTRIBUTES) {
+    for (const packing of PACKINGS) {
+      if (key.includes(`:${word(name, packing)}`)) present[word(name, packing)] = true;
+    }
+  }
+}
+
+/** How `present` says this attribute travels: floats unless a word says otherwise. */
+export function packingIn(
+  present: Readonly<Record<string, boolean>>,
+  name: string,
+): AttributePacking {
+  for (const packing of PACKINGS) {
+    if (present[word(name, packing)] === true) return packing;
+  }
+  return 'float';
+}
+
+/** The format an attribute is read with, packed this way, or `float` as given. */
+export function packedFormat(float: GPUVertexFormat, packing: AttributePacking): GPUVertexFormat {
+  if (packing === 'snorm16') return 'snorm16x4';
+  if (packing === 'unorm16') return 'unorm16x4';
+  return float;
+}
+
+/** Bytes a vertex spends on one attribute read with `format`. */
+export function formatBytes(format: GPUVertexFormat): number {
+  if (format === 'snorm16x4' || format === 'unorm16x4') return 8;
+  if (format === 'float32x4') return 16;
+  if (format === 'float32x3') return 12;
+  if (format === 'float32x2') return 8;
+  return 4;
+}
+
+/**
+ * One attribute of vertices `from` to `to` into its sixteen-bit field of the interleaved rows,
+ * `scale` being `SNORM16_ONE` or `UNORM16_ONE`. Rounded by `toFixed16`, as `fixedArray` rounds
+ * for the other backend; the range was checked when the packing was chosen.
+ *
+ * Unrolled by width, as `interleaveField` is and for its reason: the general loop was most of a
+ * heavy load's upload. Three and four are the widths a packed attribute has.
+ */
+export function interleaveFixed(
+  rows: Int16Array | Uint16Array,
+  source: Float32Array,
+  width: number,
+  step: number,
+  fieldOffset: number,
+  from: number,
+  to: number,
+  scale: number,
+): void {
+  let write = from * step + fieldOffset;
+  const end = to * width;
+  if (width === 3) {
+    for (let read = from * 3; read < end; read += 3, write += step) {
+      rows[write] = toFixed16(source[read] as number, scale);
+      rows[write + 1] = toFixed16(source[read + 1] as number, scale);
+      rows[write + 2] = toFixed16(source[read + 2] as number, scale);
+    }
+  } else {
+    for (let read = from * 4; read < end; read += 4, write += step) {
+      rows[write] = toFixed16(source[read] as number, scale);
+      rows[write + 1] = toFixed16(source[read + 1] as number, scale);
+      rows[write + 2] = toFixed16(source[read + 2] as number, scale);
+      rows[write + 3] = toFixed16(source[read + 3] as number, scale);
+    }
+  }
+}

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.