@driftengine/core 3.61.0

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

@@ -0,0 +1,148 @@
+/**
+ * A device, a configured canvas, and loss adapted to the shape the renderer already handles.
+ *
+ * Everything WebGPU-specific about *owning* a drawing surface lives here, so that
+ * `webgpu/renderer.ts` is about drawing and this is about the context it draws into. The
+ * split matters because these two fail for unrelated reasons: a device is lost by a driver
+ * reset the page did not cause, and a frame is wrong because of something the frame did.
+ */
+
+/** What the renderer needs from the canvas it draws into, with the API's shape absorbed. */
+export interface GpuSurface {
+  readonly device: GPUDevice;
+  readonly context: GPUCanvasContext;
+  /**
+   * The canvas being drawn into.
+   *
+   * Carried because the renderer's public measurements are questions about it and nothing
+   * else: `cssWidth` and `cssHeight` are its CSS box, `aspect` its drawing buffer. WebGL2
+   * answers them off `this.canvas` and a second backend has to answer the same questions
+   * from somewhere.
+   */
+  readonly canvas: HTMLCanvasElement;
+  /** The swap chain's format, which every render pipeline has to be built against. */
+  readonly format: GPUTextureFormat;
+  /** Whether the device has gone. Read per frame; never throws. */
+  readonly lost: boolean;
+  /** Called when the device is lost. Fires immediately if it already has been. */
+  onLost(listener: () => void): void;
+  /** Resize the drawing buffer and reconfigure the swap chain. */
+  configure(width: number, height: number): void;
+  /** Tear down on purpose. A disposed surface never reports a loss. */
+  dispose(): void;
+}
+
+/**
+ * Take a canvas and a device, and hand back the surface the renderer draws into.
+ *
+ * **Device loss is a promise, and that is a different shape from the event WebGL gives.**
+ * `webglcontextlost` fires once and is missed by anybody not already listening;
+ * `device.lost` is a promise that resolves once, never rejects, and stays resolved. A
+ * renderer constructed after the loss therefore gets no event at all from the WebGL-shaped
+ * mental model, and would draw into a dead device forever without ever being told.
+ *
+ * So the resolution is latched here and `onLost` fires immediately for a listener that
+ * arrives late. Adapting it once, at the boundary, is why no call site has to know that the
+ * two APIs disagree about what a failure looks like — the same argument `contextLoss.ts`
+ * makes for owning the WebGL half rather than letting a game listen for it.
+ *
+ * **Disposal is not loss.** Tearing a surface down calls `destroy()`, which resolves
+ * `device.lost` exactly as a driver reset would. Reporting that to listeners would tell a
+ * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
+ * surface stays silent.
+ */
+export function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice): GpuSurface {
+  const context = canvas.getContext('webgpu') as GPUCanvasContext | null;
+  if (context === null) {
+    throw new Error('createGpuSurface: the canvas would not give a webgpu context');
+  }
+
+  const format = navigator.gpu.getPreferredCanvasFormat();
+  const listeners: (() => void)[] = [];
+  let lost = false;
+  let disposed = false;
+
+  void device.lost.then(() => {
+    if (disposed) return;
+    lost = true;
+    for (const listener of listeners) listener();
+  });
+
+  /*
+   * **Say what the device rejected, because otherwise nothing does.**
+   *
+   * WebGPU does not throw on a bad resource. `createBindGroup` with a mismatched sample type
+   * returns an object that is invalid, every pass built on it records nothing, and the frame
+   * still presents — so the failure arrives as a picture that is merely wrong, and gets
+   * attributed to shaders, matrices and orientation in that order. That is not hypothetical:
+   * the shadow peel cost three implementations across two sessions, all of them measuring the
+   * frame produced by a pass that could not run, and one line of this would have named it.
+   * The water shader's invalid pipeline was the same silence.
+   *
+   * **Measured, because when it arrives decides whether it is any use.** Making the peel's
+   * exact mistake and listening gives *nothing* at `createBindGroup` — Dawn defers it — and
+   * then three messages at `queue.submit`, root cause first:
+   *
+   *     None of the supported sample types (UnfilterableFloat|Depth) of
+   *       [Texture "shadow.static"] match the expected sample types (Float).
+   *     [Invalid BindGroup (unlabeled)] is invalid due to a previous error.
+   *     [Invalid CommandBuffer] is invalid due to a previous error.
+   *
+   * So the useful line is there, and it is there a frame later than the call that caused it.
+   * **Label every resource**, because that first message is only readable thanks to
+   * `shadow.static` being one.
+   *
+   * `console.error` rather than a throw, and for that reason: submission is inside the frame
+   * loop, and the house rule is that nothing throws there. Once per distinct message, because
+   * an invalid bind group set per draw arrives every frame — the same argument `warnedFull`
+   * makes in the renderer.
+   */
+  const said = new Set<string>();
+  device.addEventListener('uncapturederror', (event) => {
+    const { error } = event as GPUUncapturedErrorEvent;
+    const message = error.message;
+    if (disposed || said.has(message)) return;
+    said.add(message);
+    console.error(`[driftengine] the GPU rejected something, and drew nothing for it:\n${message}`);
+  });
+
+  const configure = (width: number, height: number): void => {
+    if (disposed) return;
+    canvas.width = width;
+    canvas.height = height;
+    /*
+     * `opaque` rather than `premultiplied`: this engine draws a sky behind everything and
+     * has no use for a transparent canvas, and the opaque path is the one a compositor can
+     * take without a blend.
+     */
+    context.configure({ device, format, alphaMode: 'opaque' });
+  };
+
+  configure(canvas.width, canvas.height);
+
+  return {
+    device,
+    context,
+    canvas,
+    format,
+    get lost() {
+      return lost;
+    },
+    onLost(listener: () => void): void {
+      /* Late is the normal case for a renderer built after a driver reset, not an edge one. */
+      if (lost) {
+        listener();
+        return;
+      }
+      listeners.push(listener);
+    },
+    configure,
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      listeners.length = 0;
+      context.unconfigure();
+      device.destroy();
+    },
+  };
+}

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

@@ -0,0 +1,79 @@
+/**
+ * One recorded draw, in the only shape this backend ever issues.
+ *
+ * Sampled across three unrelated verbs — panels, particles, wind streaks — the sequence is the
+ * same every time: a pipeline, a bind group with up to two dynamic offsets, some vertex
+ * buffers, perhaps an index buffer, then a draw. Nothing in it is specific to what is being
+ * drawn except the values.
+ *
+ * So the frame graph does not need to know what a plume is. It records these fields and
+ * replays them, which is what turns migrating twenty-three verbs into twenty-three call-site
+ * 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;
+
+export interface DrawCommand {
+  pipeline: GPURenderPipeline | null;
+  bindGroup: GPUBindGroup | null;
+  /** Dynamic offsets, held as two numbers rather than an array so a reset stays free. */
+  offsetA: number;
+  offsetB: number;
+  offsetCount: number;
+  /** Fixed length; `vertexCount` says how many slots are live. */
+  readonly vertexBuffers: (GPUBuffer | null)[];
+  vertexCount: number;
+  indexBuffer: GPUBuffer | null;
+  indexed: boolean;
+  count: number;
+  instances: number;
+}
+
+export interface CommandPool {
+  commands: DrawCommand[];
+  taken: number;
+  /** The most any frame has taken, so growth converges instead of repeating. */
+  highWater: number;
+}
+
+function emptyCommand(): DrawCommand {
+  return {
+    pipeline: null,
+    bindGroup: null,
+    offsetA: 0,
+    offsetB: 0,
+    offsetCount: 0,
+    vertexBuffers: new Array<GPUBuffer | null>(VERTEX_BUFFER_SLOTS).fill(null),
+    vertexCount: 0,
+    indexBuffer: null,
+    indexed: false,
+    count: 0,
+    instances: 1,
+  };
+}
+
+export function createCommandPool(capacity: number): CommandPool {
+  const commands: DrawCommand[] = [];
+  for (let i = 0; i < capacity; i += 1) commands.push(emptyCommand());
+  return { commands, taken: 0, highWater: 0 };
+}
+
+/**
+ * Hand out the next command, growing if a frame overruns.
+ *
+ * The entry is **not cleared**. Every caller fills every field it uses, and clearing here would
+ * be a write per field per draw for no reader — the same reasoning the node arena uses.
+ */
+export function takeCommand(pool: CommandPool): number {
+  const at = pool.taken;
+  while (at >= pool.commands.length) pool.commands.push(emptyCommand());
+  pool.taken = at + 1;
+  if (pool.taken > pool.highWater) pool.highWater = pool.taken;
+  return at;
+}
+
+/** Empty the pool for a new frame. Keeps every entry; that is the whole point. */
+export function resetPool(pool: CommandPool): void {
+  pool.taken = 0;
+}

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

@@ -0,0 +1,96 @@
+/** Linear RGBA floats packed into whatever format the environment cube was actually allocated as. */
+
+import { toHalfFloats } from '../../halfFloat.ts';
+
+/** The packed texels and how wide one is, which is what a `writeTexture` layout needs. */
+export interface PackedTexels {
+  readonly data: ArrayBufferView;
+  readonly bytesPerTexel: number;
+}
+
+/**
+ * Pack linear RGBA floats for `format`.
+ *
+ * **`writeTexture` does not convert, and that is the whole reason this exists.** Its `bytesPerRow`
+ * describes the *source* stride and it reads `width * bytesPerTexel-of-the-destination` bytes from
+ * each row — so float data handed to an eight-bit cube is a legal layout that reinterprets the raw
+ * bytes of the floats as unorm bytes. Nothing raises anything: no validation error, no device
+ * message, and a cube full of a plausible-looking environment.
+ *
+ * That is the 2026-08-14 family of WebGPU failure wearing its quietest face. The others at least
+ * invalidate a command buffer and leave an empty canvas; this one draws a picture.
+ *
+ * **Measured, because it was found by measuring rather than by reading.** On a uniform sky the
+ * other backend read 81 of 255 and this one read 45.7 from the same file. Neither number looks
+ * wrong on its own — the two backends being a control for each other is the only thing that
+ * separated them.
+ *
+ * **What it costs** is one conversion pass over six faces at load. **What would make it wrong** is
+ * a format this does not know, which is why the default arm throws rather than guessing: a guess
+ * here is exactly the silent picture this function exists to prevent.
+ */
+export function environmentTexels(pixels: Float32Array, format: GPUTextureFormat): PackedTexels {
+  switch (format) {
+    /* Already what the source is. No copy, because there is nothing to change. */
+    case 'rgba32float':
+      return { data: pixels, bytesPerTexel: 16 };
+
+    case 'rgba16float':
+      return { data: toHalf(pixels), bytesPerTexel: 8 };
+
+    case 'rgba8unorm':
+      return { data: toUnorm(pixels, false, false), bytesPerTexel: 4 };
+    case 'bgra8unorm':
+      return { data: toUnorm(pixels, true, false), bytesPerTexel: 4 };
+
+    /*
+     * An sRGB view decodes what it samples, so the byte stored has to be the *encoded* value or
+     * every environment comes back roughly twice as bright as the file. The engine's own scene
+     * targets are linear, so this arm is for a surface format a device chose rather than one this
+     * renderer asked for.
+     */
+    case 'rgba8unorm-srgb':
+      return { data: toUnorm(pixels, false, true), bytesPerTexel: 4 };
+    case 'bgra8unorm-srgb':
+      return { data: toUnorm(pixels, true, true), bytesPerTexel: 4 };
+
+    default:
+      throw new Error(
+        `environmentTexels: no packing for "${format}". Add one rather than letting a wrong ` +
+          'layout through — WebGPU accepts a mismatched stride without complaint and draws a ' +
+          'plausible picture from reinterpreted bytes.',
+      );
+  }
+}
+
+function toHalf(pixels: Float32Array): Uint16Array {
+  return toHalfFloats(pixels);
+}
+
+/**
+ * Eight bits a channel, clipped at white.
+ *
+ * **Clipped rather than tone-mapped**, matching what the other backend does with a non-float cube
+ * and for the reason a bake documents at length: the cube stores radiance, and a curve applied here
+ * would be a viewing transform baked into stored light.
+ */
+function toUnorm(pixels: Float32Array, swapRedAndBlue: boolean, encodeSrgb: boolean): Uint8Array {
+  const texels = pixels.length / 4;
+  const out = new Uint8Array(texels * 4);
+  for (let texel = 0; texel < texels; texel++) {
+    for (let channel = 0; channel < 3; channel++) {
+      const linear = pixels[texel * 4 + channel] ?? 0;
+      const clipped = linear <= 0 ? 0 : linear >= 1 ? 1 : linear;
+      const value = encodeSrgb ? srgbEncode(clipped) : clipped;
+      const at = texel * 4 + (swapRedAndBlue ? 2 - channel : channel);
+      out[at] = Math.round(value * 255);
+    }
+    out[texel * 4 + 3] = 255;
+  }
+  return out;
+}
+
+/** The sRGB transfer function, in the direction that prepares a value for a decoding sampler. */
+function srgbEncode(linear: number): number {
+  return linear <= 0.0031308 ? linear * 12.92 : 1.055 * linear ** (1 / 2.4) - 0.055;
+}

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

@@ -0,0 +1,123 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  FILM_BINDINGS,
+  FILM_FRAG_WGSL,
+  FILM_VERT_WGSL,
+} from '../../shaders/generated/film.wgsl.ts';
+import { vertexBufferLayouts } from './buffers.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The film pass: a thin wet layer — an oil slick, a puddle — lying over the world.
+ *
+ * Its own pass because it is its own material: view-dependent iridescence and a dissolving
+ * edge, neither of which the flat shader can express. `renderer.ts` says the rest, including
+ * why `sheen` is iridescence rather than wetness and where its usable range is.
+ *
+ * The geometry is an ordinary mesh, so the vertex layout is the flat pass's own — the shader
+ * reads position, normal, colour and a coverage weight, and the pipeline still has to describe
+ * every attribute the module declares.
+ */
+
+export const FILM_VERT_FIELDS: UniformFields = FILM_BINDINGS.FILM_VERT.fields;
+export const FILM_VERT_SIZE = FILM_BINDINGS.FILM_VERT.uniformSize;
+export const FILM_FRAG_FIELDS: UniformFields = FILM_BINDINGS.FILM_FRAG.fields;
+export const FILM_FRAG_SIZE = FILM_BINDINGS.FILM_FRAG.uniformSize;
+
+const VERT_BINDING = FILM_BINDINGS.FILM_VERT.uniforms;
+const FRAG_BINDING = FILM_BINDINGS.FILM_FRAG.uniforms;
+const REFLECTION = FILM_BINDINGS.FILM_FRAG.textures.uReflectionMap;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+
+export function createFilmBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'film.layout',
+    entries: [
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FILM_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FILM_FRAG_SIZE },
+      },
+      /*
+       * The mirror is an ordinary colour target, so a filtering sampler is right here — unlike
+       * every `...ShadowMap`, which is a depth format and cannot take one. `depthPass.ts` has
+       * the message the device gives when the two are confused.
+       */
+      { binding: REFLECTION.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+      { binding: REFLECTION.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+    ],
+  });
+}
+
+/** Bound once against both rings; a dynamic offset per film. See `createPanelBindGroup`. */
+export function createFilmBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+  reflection: GPUTextureView,
+  sampler: GPUSampler,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'film.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: FILM_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: FILM_FRAG_SIZE } },
+      { binding: REFLECTION.texture, resource: reflection },
+      { binding: REFLECTION.sampler, resource: sampler },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written.** A slick lies on the surface it was built
+ * against instead of fighting it for the depth buffer, which is what `renderer.ts` says by
+ * turning `depthMask` off around the draw. Writing depth would let a translucent patch occlude
+ * whatever is drawn after it.
+ */
+export function filmPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  key: string,
+  present: Readonly<Record<string, boolean>>,
+): GPURenderPipeline {
+  return cache.get(key, () => ({
+    label: key,
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'film.vert', code: FILM_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: vertexBufferLayouts(present),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'film.frag', code: FILM_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'back' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}