@driftengine/core 3.61.0

package/src/render/backend/select.ts

@@ -0,0 +1,288 @@
+import type { RenderBackend } from './api.ts';
+import { probeDevice } from './probe.ts';
+import { TIMED_OUT, withDeadline } from './deadline.ts';
+import { adapterRendererName } from '../gpuCapability.ts';
+
+/** What was chosen, what it was chosen with, and why. */
+export interface BackendChoice {
+  readonly backend: RenderBackend;
+  /**
+   * A live device, held only when `backend` is `webgpu`.
+   *
+   * Returned rather than re-requested by the caller, because an adapter request is the
+   * expensive part and asking twice can legitimately give a different answer.
+   */
+  readonly device: GPUDevice | null;
+  /**
+   * What the adapter calls this part, or null where nothing was asked.
+   *
+   * The WebGPU counterpart of `UNMASKED_RENDERER_WEBGL`, and the reason the capability clamp
+   * can fire on this backend at all: `isWeakGpuFamily` matches on a part number, and this
+   * backend used to hand it the literal string `WebGPU`.
+   */
+  readonly rendererName: string | null;
+  /** Why this backend, in words a bug report can carry. */
+  readonly reason: string;
+}
+
+/**
+ * A backend named in the address, or null.
+ *
+ * **Honoured in every build rather than behind a development flag.** A fallback that can
+ * only be reached by owning the wrong device is a fallback nobody tests, and the failure
+ * that produces is a black screen for somebody who cannot be asked to help diagnose it.
+ *
+ * An unrecognised value is *no request* rather than a default, and the strictness is the
+ * point: `?backend=WebGPU` silently selecting WebGL2 is somebody testing the path they
+ * meant to avoid and drawing a confident conclusion from it.
+ */
+export function forcedBackend(search: string): RenderBackend | null {
+  const value = new URLSearchParams(search).get('backend');
+  return value === 'webgl2' || value === 'webgpu' ? value : null;
+}
+
+/**
+ * Decide which backend to build, and prove it by holding a device.
+ *
+ * **The probe is the whole of the decision.** The presence of `navigator.gpu` is not proof
+ * of a working device: a supported browser refuses adapters for blocklisted drivers,
+ * headless contexts and low-power states, and a device request can fail after an adapter
+ * succeeds. So nothing is reported as WebGPU until an adapter *and* a device have both been
+ * handed over, and every other path falls back with a reason attached.
+ *
+ * Nothing here throws. A failure to get WebGPU is an ordinary outcome on most devices in
+ * the world, not an error, and treating it as one would put a try/catch in every consumer's
+ * boot for a case that is expected.
+ */
+/**
+ * How long the whole WebGPU acquisition may take before this answers WebGL2 instead.
+ *
+ * **Because a preference that cannot fall back is not a preference.** Every refusal below is a
+ * refusal somebody receives: an adapter that answers null, a device request that throws, a device
+ * that cannot draw. A request that simply never settles is none of those, and it has no floor under
+ * it — the boot stops at the `await`, nothing throws, nothing is logged, and what a player gets is
+ * the window the game was going to be drawn in. Reported from outside exactly that way, on a driver
+ * and compositor where the adapter is offered and the acquisition never returns.
+ *
+ * **Eight seconds, against 153 ms measured.** On this repository's machine the whole acquisition —
+ * adapter, device at the adapter's own ceilings, and the one-pixel draw and readback that proves it
+ * works — takes 153 ms warm, against 36 ms for the WebGL2 path it would fall back to. Eight seconds
+ * is fifty times that, which leaves room for a cold shader cache on a slower part while still being
+ * inside what a person will wait through. Past it, WebGL2 is not a downgrade so much as the only
+ * backend that is going to draw anything.
+ */
+export const BACKEND_TIMEOUT_MS = 8_000;
+
+/**
+ * @param timeoutMs How long the WebGPU path may take before WebGL2 is answered instead.
+ *   `Infinity` waits forever, which is what this did before the deadline existed.
+ */
+export async function selectBackend(
+  search: string,
+  preferWebGpu: boolean,
+  wantsGpuTiming = false,
+  shaders: readonly string[] = [],
+  timeoutMs: number = BACKEND_TIMEOUT_MS,
+): Promise<BackendChoice> {
+  const forced = forcedBackend(search);
+  if (forced === 'webgl2') {
+    return {
+      backend: 'webgl2',
+      device: null,
+      rendererName: null,
+      reason: 'forced by ?backend=webgl2',
+    };
+  }
+
+  const wanted = forced === 'webgpu' || preferWebGpu;
+  if (!wanted)
+    return { backend: 'webgl2', device: null, rendererName: null, reason: 'WebGPU not requested' };
+
+  const gpu = (globalThis.navigator as Navigator | undefined)?.gpu;
+  if (gpu === undefined || gpu === null) {
+    return {
+      backend: 'webgl2',
+      device: null,
+      rendererName: null,
+      reason: 'WebGPU not supported here',
+    };
+  }
+
+  /*
+   * **What it was doing when it stopped, kept as a word.** A stalled boot in a packaged artifact has
+   * no developer tools behind it and no stack anybody can quote, and the only question worth
+   * answering is which of the three awaits it is sitting in. The reason string carries that instead
+   * of asking for a reproduction under a debugger.
+   */
+  const stage = { at: 'requesting an adapter' };
+  const acquisition = acquireWebGpu(gpu, wantsGpuTiming, shaders, stage);
+  const settled = await withDeadline(acquisition, timeoutMs);
+  if (settled !== TIMED_OUT) return settled;
+
+  /*
+   * **The abandoned request is still running, and it may still produce a device.** Nothing else
+   * will free one that arrives after this point, so it is destroyed on arrival rather than left to
+   * hold a GPU allocation for the life of the process. The rejection is swallowed for the same
+   * reason it is swallowed below: this path has already answered.
+   */
+  void acquisition.then((late) => late.device?.destroy()).catch(() => {});
+  return {
+    backend: 'webgl2',
+    device: null,
+    rendererName: null,
+    reason: `WebGPU stalled while ${stage.at}, fell back after ${timeoutMs} ms`,
+  };
+}
+
+/** Adapter, device and the draw that proves it works, or the reason none of that happened. */
+async function acquireWebGpu(
+  gpu: GPU,
+  wantsGpuTiming: boolean,
+  shaders: readonly string[],
+  stage: { at: string },
+): Promise<BackendChoice> {
+  try {
+    const adapter = await gpu.requestAdapter();
+    if (adapter === null) {
+      return {
+        backend: 'webgl2',
+        device: null,
+        rendererName: null,
+        reason: 'no WebGPU adapter offered',
+      };
+    }
+    /*
+     * **Ask for the sampled-texture limit the flat shader actually needs.**
+     *
+     * A device defaults to `maxSampledTexturesPerShaderStage: 16`, and the widest permutation
+     * of the flat shader declares **seventeen**: one albedo, three directional shadow maps,
+     * twelve point-shadow cubes and the environment probe. Creating the bind group layout for
+     * it is rejected outright — *"The number of sampled textures (17) in the Fragment stage
+     * exceeds the maximum per-stage limit (16)"* — and because that failure lands on a
+     * *pipeline*, the frame goes on drawing everything else and says nothing beyond a device
+     * warning.
+     *
+     * Clamped to what the adapter actually offers rather than demanded, and a request that
+     * cannot be met is a fallback to WebGL2 rather than a throw: this machine's adapter reports
+     * 48, and one that reports 16 is a machine whose widest profile genuinely will not fit.
+     */
+    /*
+     * **Ask for as much binding room as the adapter will give, and never more.**
+     *
+     * A device defaults to 16 sampled textures and 16 samplers per stage, and the widest
+     * permutation of the flat shader declares **seventeen** of each: one albedo, three
+     * directional shadow maps, twelve point-shadow cubes and the environment probe. The default
+     * rejects the bind group layout outright, and because that lands on a *pipeline* the frame
+     * carries on drawing everything else and says nothing but a device warning.
+     *
+     * **Two limits, and the second only appears once the first is raised.** They are counted
+     * separately: raising the textures alone moved the message from "the number of sampled
+     * textures (17)" to "the number of samplers (17)" and changed nothing else.
+     *
+     * **Requested at the adapter's own ceiling rather than at a number chosen here**, because
+     * asking for more than it supports is not a clamp, it is a rejected device — measured on
+     * this machine, which offers 48 sampled textures and exactly 16 samplers, so a flat request
+     * for 20 threw and lost WebGPU entirely. The renderer reads the same numbers back off the
+     * device and drops the probe when the variant will not fit; see `WebGPURenderer`.
+     */
+    /*
+     * **And the buffer ceiling, because a bought model is bigger than a default allows.**
+     *
+     * `maxBufferSize` defaults to 256 MiB while this machine's adapter offers 4 GiB, and a
+     * merged mesh from an imported model passes the default easily: a reported one asked for
+     * **298,273,296 bytes** for a single `mesh.vertices`. WebGL2 has no such ceiling, so the same
+     * model loads on one backend and not the other — and the failure is not a refusal anybody
+     * reads, it is an invalid buffer that then invalidates every command buffer that touches it,
+     * so the console fills with a hundred repeats of *"is invalid due to a previous error"* from
+     * the shadow pass and the frame, and the subject is simply absent.
+     *
+     * Asked for at the adapter's ceiling like the two above and for the same reason: more than
+     * it offers is a rejected device rather than a clamp. A part whose adapter genuinely caps at
+     * the default still refuses the model, and `WebGPURenderer.createMesh` says so in one line
+     * rather than letting the driver say it a hundred times.
+     */
+    const required: Record<string, number> = {};
+    for (const limit of [
+      'maxSampledTexturesPerShaderStage',
+      'maxSamplersPerShaderStage',
+      'maxBufferSize',
+    ] as const) {
+      const ceiling = adapter.limits[limit];
+      if (typeof ceiling === 'number' && ceiling > 0) required[limit] = ceiling;
+    }
+    /*
+     * **Asked for only where the adapter offers it, and never demanded.** A `requiredFeatures`
+     * naming something the adapter lacks does not clamp, it rejects the device outright — the
+     * same trap the limits above carry — and losing WebGPU entirely in exchange for a
+     * diagnostic would be a poor trade. Without it `GpuTimestamps` reports `available: false`,
+     * which is the honest answer rather than a silent zero.
+     */
+    /*
+     * **What part this is, in the same shape `UNMASKED_RENDERER_WEBGL` gives on the other
+     * backend.** Without it `WebGPURenderer.rendererName` was the literal string `WebGPU`, so
+     * `isWeakGpuFamily` had nothing to match and the capability clamp could not fire at all —
+     * the clamp that rescued an Adreno 619 on WebGL2 was dead on the backend that replaced it.
+     *
+     * Every field is optional and browsers withhold them to differing degrees, so they are
+     * joined rather than formatted: a string with a vendor and nothing else is still something
+     * the table can recognise, and an empty one falls back to the old literal so nothing that
+     * reads it gets an empty label.
+     */
+    const rendererName = adapterRendererName(adapter.info as GPUAdapterInfo | undefined);
+
+    const features: GPUFeatureName[] = [];
+    /*
+     * Asked for only when a consumer wants to measure. A feature that is requested is a feature
+     * the device carries, and this one exists to be attached to every render pass — see
+     * `RenderQuality.gpuTiming` for why that was the wrong thing to hand everybody by default.
+     */
+    if (wantsGpuTiming && adapter.features?.has('timestamp-query') === true) {
+      features.push('timestamp-query');
+    }
+    const descriptor: GPUDeviceDescriptor = {};
+    if (Object.keys(required).length > 0) descriptor.requiredLimits = required;
+    if (features.length > 0) descriptor.requiredFeatures = features;
+    stage.at = 'requesting a device';
+    const device = await adapter.requestDevice(descriptor);
+    if (device === null || device === undefined) {
+      return {
+        backend: 'webgl2',
+        device: null,
+        rendererName: null,
+        reason: 'WebGPU device request gave nothing',
+      };
+    }
+    /*
+     * **A device is not a backend until it has drawn.** Everything above this asks whether WebGPU
+     * exists; this asks whether it works, which is a different question and the one the iOS black
+     * screen turned on. A refusal here is an ordinary fallback and not an error: it lands on the
+     * same WebGL2 path as a browser with no `navigator.gpu`, carrying a reason in the device's own
+     * words.
+     *
+     * **Cost:** one pipeline and one 1x1 readback, once, before the first frame. Passing `shaders`
+     * adds their compile — see `CreateRendererOptions.probeShaders` for what that was measured at
+     * and why it is not the default.
+     */
+    stage.at = 'drawing the acceptance probe';
+    const verdict = await probeDevice(device, shaders);
+    if (!verdict.ok) {
+      device.destroy();
+      return { backend: 'webgl2', device: null, rendererName: null, reason: verdict.reason };
+    }
+
+    return {
+      backend: 'webgpu',
+      device,
+      rendererName,
+      reason: 'WebGPU adapter and device acquired',
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      backend: 'webgl2',
+      device: null,
+      rendererName: null,
+      reason: `WebGPU device request failed: ${detail}`,
+    };
+  }
+}

package/src/render/backend/timer.ts

@@ -0,0 +1,59 @@
+import type { GpuSample, GpuSlot } from '../gpuTimer.ts';
+
+/**
+ * What a frame timer has to answer, with no backend in the question.
+ *
+ * `GpuTimer` is built on `WebGLQuery` and the `EXT_disjoint_timer_query_webgl2` extension,
+ * which most mobile browsers do not have. WebGPU answers the same question through timestamp
+ * queries, with a different shape and a different availability story again. So the shared
+ * surface takes the *question* rather than either answer.
+ *
+ * **`null` from `lastFrameMs` means unmeasured, not free.** Reporting a confident 0.0 is the
+ * worst number available to invent: a frame meter that reads zero where it cannot measure
+ * makes the GPU look idle exactly when somebody is trying to find out why it is not, which
+ * is the failure that cost thirteen milliseconds a frame for six weeks (`AGENTS.md`,
+ * 2026-08-07). An honest absence is what lets a reader distinguish "fast" from "unknown".
+ */
+export interface FrameTimer {
+  /** Whether this timer can measure at all on the device in front of it. */
+  readonly available: boolean;
+
+  /** Whether the frame being drawn is one of the sampled ones. */
+  readonly sampling: boolean;
+
+  /**
+   * Whether this frame is measured. Called once per frame, before any `begin`.
+   *
+   * **The brackets are on this interface rather than under it, because their names are the
+   * engine's own passes and not WebGL's.** `shadows`, `reflection` and `rest` describe what
+   * this renderer draws, so a second backend measuring the same frame owes the same three
+   * numbers; what differs between the APIs is only how the measurement is taken.
+   */
+  beginFrame(): boolean;
+
+  /** Close the frame and queue it for reading. */
+  endFrame(): void;
+
+  /** Open a bracket. Never two at once. */
+  begin(slot: GpuSlot): void;
+
+  /** Close the open bracket. */
+  end(): void;
+
+  /**
+   * The oldest finished sample, or null. **Never blocks**: a diagnostic that stalls the
+   * pipeline in order to measure it is measuring itself.
+   */
+  poll(): GpuSample | null;
+
+  /**
+   * Milliseconds the GPU spent on the most recently *resolved* frame, or null.
+   *
+   * Resolved rather than current: results arrive some frames after the work, because reading
+   * them back any sooner would stall the pipeline the timer exists to observe.
+   */
+  lastFrameMs(): number | null;
+
+  /** Release whatever the timer holds. */
+  dispose(): void;
+}

package/src/render/backend/webgl2/instanced.ts

@@ -0,0 +1,46 @@
+import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.ts';
+import type { MeshInstances } from '../../instances.ts';
+import type { Mesh } from '../../mesh.ts';
+
+/**
+ * One mesh's per-instance buffer, bound to that mesh's own vertex array.
+ *
+ * The twin of the WebGPU batch and deliberately the same shape, because which floats go where is
+ * a decision shared through `instances.ts` and only the binding is per-backend.
+ *
+ * The staging array is allocated here and rewritten in place, so a frame re-uploading a moving
+ * batch allocates nothing.
+ */
+export class InstancedBatch {
+  readonly mesh: Mesh;
+  readonly capacity: number;
+  private readonly buffer: WebGLBuffer;
+  private readonly staging: Float32Array;
+
+  constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number) {
+    const buffer = gl.createBuffer();
+    if (buffer === null) throw new Error('InstancedBatch: createBuffer failed');
+    this.mesh = mesh;
+    this.capacity = capacity;
+    this.buffer = buffer;
+    this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, capacity * INSTANCE_STRIDE, gl.DYNAMIC_DRAW);
+    /* `DYNAMIC_DRAW` because a batch of vehicles is rewritten every frame — advisory, but a
+       driver told the truth can place the buffer where a rewrite is cheap. */
+    mesh.attachInstances(gl, buffer, INSTANCE_STRIDE);
+  }
+
+  /** Pack and push the live prefix, in one call. */
+  upload(gl: WebGL2RenderingContext, data: MeshInstances): void {
+    const count = Math.min(data.count, this.capacity);
+    if (count === 0) return;
+    packInstances(data, this.staging);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteBuffer(this.buffer);
+  }
+}

package/src/render/backend/webgl2/morphTexture.ts

@@ -0,0 +1,58 @@
+import { morphTextureRows, morphTextureWidth } from '../../skinPalette.ts';
+
+/**
+ * A mesh's morph deltas as an `RGB32F` texture, on WebGL2.
+ *
+ * **Owned by the mesh rather than set per draw**, which is the difference between this and the
+ * joint palette beside it. A palette changes every frame and belongs to a *pose*; deltas are
+ * geometry and never change, so they are uploaded once with the vertex buffers and bound by the
+ * draw that uses them. Only the weights are per-draw state.
+ *
+ * `RGB32F` rather than `RGBA32F`: a delta is three floats and the fourth would be a quarter of the
+ * texture holding nothing. Both are colour-renderable-optional in WebGL2 core and neither is
+ * filtered here, so the narrower one costs nothing and saves a third.
+ */
+export class MorphTexture {
+  private texture: WebGLTexture | null = null;
+  readonly width: number;
+  readonly rows: number;
+  readonly targetCount: number;
+
+  constructor(gl: WebGL2RenderingContext, deltas: Float32Array, vertices: number, targets: number) {
+    this.targetCount = targets;
+    this.width = morphTextureWidth(vertices, targets);
+    this.rows = morphTextureRows(vertices, targets);
+
+    const created = gl.createTexture();
+    if (created === null) throw new Error('morph targets: failed to create the delta texture');
+    this.texture = created;
+    gl.bindTexture(gl.TEXTURE_2D, created);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGB32F, this.width, this.rows);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    /*
+     * The last row is usually short, and `texSubImage2D` reads a full row's worth whatever it is
+     * told — so uploading the whole rectangle from a source that stops early walks off the end.
+     * Padded to the rectangle once, here, rather than uploaded row by row: this runs at mesh
+     * construction and the padding is at most one row of zeroes. The splat streaming path found
+     * the row-by-row version of this the hard way, on one backend only.
+     */
+    const padded = new Float32Array(this.width * this.rows * 3);
+    padded.set(deltas.subarray(0, Math.min(deltas.length, padded.length)));
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, this.width, this.rows, gl.RGB, gl.FLOAT, padded);
+  }
+
+  bind(gl: WebGL2RenderingContext, unit: number): void {
+    if (this.texture === null) return;
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    if (this.texture !== null) gl.deleteTexture(this.texture);
+    this.texture = null;
+  }
+}