@driftengine/core 3.61.0

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

@@ -0,0 +1,292 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import type { Vec3 } from '../../../math/color.ts';
+import { PLUME_VERTS } from '../../plumeGeometry.ts';
+import { plumeShaders, type PlumeMaterial } from '../../plumeMaterial.ts';
+import { ARCANE_BINDINGS } from '../../shaders/generated/arcane.wgsl.ts';
+import { FIRE_BINDINGS } from '../../shaders/generated/fire.wgsl.ts';
+import { SMOKE_BINDINGS } from '../../shaders/generated/smoke.wgsl.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The plume pass: crossed quads per plume, displaced and faded in the shaders.
+ *
+ * **Two blend modes and one geometry.** A flame adds light and smoke occludes it, which is the
+ * `PlumeBlend` the options carry; everything else about the two is the fragment stage. Neither
+ * writes depth — a soft quad that did would punch a hole in whatever came after it.
+ */
+
+/** The vertex stage is shared by every plume material; only the fragment differs. */
+export const PLUME_VERT_FIELDS: UniformFields = FIRE_BINDINGS.PLUME_VERT.fields;
+export const PLUME_VERT_SIZE = FIRE_BINDINGS.PLUME_VERT.uniformSize;
+
+/*
+ * **The blocks are not all the same shape, and the widest one sizes the binding.**
+ *
+ * Fire and smoke are 128 bytes over the same fourteen fields. Arcane is 144 over the same
+ * fourteen plus `uTint`, at the same offsets for the shared ones — which is asserted below
+ * rather than assumed, because a generator that moved one would put a field where this writer
+ * does not look.
+ *
+ * **Sizing this to fire's block is a pipeline that does not build.** Measured on an RX 9070 XT
+ * through radv, against the device rather than the specification: *"The shader uses more bytes
+ * of the buffer (144) than the layout's minBindingSize (128)"*, raised while validating
+ * `@group(0) @binding(1)`. That lands on `createRenderPipeline`, so by the 2026-08-14 rule the
+ * cost is not a wrong picture, it is no picture — the arcane plumes simply never draw and the
+ * command buffer they were recorded into dies with them. A binding wider than a shader needs is
+ * valid in the other direction, so one size serves all three.
+ */
+export const PLUME_FRAG_FIELDS: UniformFields = ARCANE_BINDINGS.ARCANE_FRAG.fields;
+export const PLUME_FRAG_SIZE = Math.max(
+  FIRE_BINDINGS.FIRE_FRAG.uniformSize,
+  SMOKE_BINDINGS.SMOKE_FRAG.uniformSize,
+  ARCANE_BINDINGS.ARCANE_FRAG.uniformSize,
+);
+
+const VERT_BINDING = FIRE_BINDINGS.PLUME_VERT.uniforms;
+const FRAG_BINDING = FIRE_BINDINGS.FIRE_FRAG.uniforms;
+
+/** Each material's own block, so a change to one and not the others is caught rather than assumed. */
+export const FIRE_FRAG_SIZE = FIRE_BINDINGS.FIRE_FRAG.uniformSize;
+export const SMOKE_FRAG_SIZE = SMOKE_BINDINGS.SMOKE_FRAG.uniformSize;
+export const ARCANE_FRAG_SIZE = ARCANE_BINDINGS.ARCANE_FRAG.uniformSize;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+
+/** `aCenter`, `aCorner`, `aSize`, `aSeed`, `aBlade` — one buffer each, as the GL path holds them. */
+const ATTRIBUTES: readonly { location: number; floats: number }[] = [
+  { location: 0, floats: 3 },
+  { location: 1, floats: 2 },
+  { location: 2, floats: 2 },
+  { location: 3, floats: 1 },
+  { location: 4, floats: 1 },
+];
+
+const FORMATS: Readonly<Record<number, GPUVertexFormat>> = {
+  1: 'float32',
+  2: 'float32x2',
+  3: 'float32x3',
+};
+
+export function plumeVertexLayouts(): GPUVertexBufferLayout[] {
+  return ATTRIBUTES.map((a) => ({
+    arrayStride: a.floats * 4,
+    stepMode: 'vertex' as const,
+    attributes: [
+      { shaderLocation: a.location, offset: 0, format: FORMATS[a.floats] as GPUVertexFormat },
+    ],
+  }));
+}
+
+/** Plume geometry on the device, behind the surface's opaque handle. */
+export interface GpuPlumes {
+  readonly vertexBuffers: readonly GPUBuffer[];
+  readonly indexBuffer: GPUBuffer;
+  readonly indexCount: number;
+  readonly material: PlumeMaterial;
+  readonly blend: 'additive' | 'alpha';
+  readonly sizePulse: number;
+  readonly windResponse: number;
+  /**
+   * Colour handed to the fragment stage as `uTint`, white when the caller named none.
+   *
+   * **Held per batch because it is a batch's property, and written on every draw because the
+   * block comes out of a ring.** `PlumeRenderer` has carried this since before the second
+   * backend and this path dropped it on the floor: `createPlumes` never read `options.tint`,
+   * so the one material that reads the uniform would have drawn with a tint of zero — which,
+   * being additive, is not a wrong colour but an invisible one.
+   */
+  readonly tint: Vec3;
+  /**
+   * Scale one plume, 0 to hide it. See `PlumeRenderer.setScale`, which this mirrors.
+   *
+   * Writes only that plume's own vertices, so turning a slick's fire on costs a handful of
+   * floats rather than a re-upload of the batch.
+   */
+  setScale(index: number, scale: number): void;
+  dispose(): void;
+}
+
+/** The five attribute streams a plume batch is built from, already laid out by the caller. */
+export interface PlumeGeometry {
+  readonly centers: Float32Array;
+  readonly corners: Float32Array;
+  readonly sizes: Float32Array;
+  readonly seeds: Float32Array;
+  readonly blades: Float32Array;
+  readonly indices: Uint32Array;
+}
+
+export function createGpuPlumes(
+  device: GPUDevice,
+  geometry: PlumeGeometry,
+  material: PlumeMaterial,
+  blend: 'additive' | 'alpha',
+  sizePulse: number,
+  windResponse: number,
+  tint: Vec3,
+): GpuPlumes {
+  const buffers: GPUBuffer[] = [];
+  const streams: readonly Float32Array[] = [
+    geometry.centers,
+    geometry.corners,
+    geometry.sizes,
+    geometry.seeds,
+    geometry.blades,
+  ];
+  for (let i = 0; i < streams.length; i++) {
+    const data = streams[i] as Float32Array;
+    const buffer = device.createBuffer({
+      label: `plume.attr${i}`,
+      size: Math.max(4, data.byteLength),
+      usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(buffer, 0, data);
+    buffers.push(buffer);
+  }
+  const indexBuffer = device.createBuffer({
+    label: 'plume.indices',
+    size: Math.max(4, geometry.indices.byteLength),
+    usage: USAGE_INDEX,
+  });
+  device.queue.writeBuffer(indexBuffer, 0, geometry.indices);
+
+  /*
+   * The sizes are kept on the CPU as well as uploaded, and the originals beside them, because
+   * `setScale` multiplies the *base* size rather than the current one — scaling a scaled plume
+   * would compound, and a slick cycling on and off would shrink to nothing.
+   */
+  const sizes = Float32Array.from(geometry.sizes);
+  const baseSizes = Float32Array.from(geometry.sizes);
+  const sizeBuffer = buffers[2] as GPUBuffer;
+
+  return {
+    vertexBuffers: buffers,
+    indexBuffer,
+    indexCount: geometry.indices.length,
+    material,
+    blend,
+    sizePulse,
+    windResponse,
+    tint,
+    setScale(index: number, scale: number): void {
+      const span = PLUME_VERTS * 2;
+      const base = index * span;
+      if (base < 0 || base + span > sizes.length) return;
+      const width = baseSizes[index * 2] ?? 0;
+      const height = baseSizes[index * 2 + 1] ?? 0;
+      for (let c = 0; c < PLUME_VERTS; c++) {
+        sizes[base + c * 2] = width * scale;
+        sizes[base + c * 2 + 1] = height * scale;
+      }
+      device.queue.writeBuffer(sizeBuffer, base * 4, sizes, base, span);
+    },
+    dispose(): void {
+      for (const b of buffers) b.destroy();
+      indexBuffer.destroy();
+    },
+  };
+}
+
+export function createPlumeBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'plume.layout',
+    entries: [
+      /*
+       * **Both blocks are per draw, and that is a bug fix rather than a precaution.**
+       * `sizePulse` and `windResponse` belong to the batch, not the frame — a flame is
+       * `0.12` and the smoke above it `1.35` — and a scene draws both in one pass. With one
+       * buffer per block the second `writeBuffer` won for both draws, so the flame was bent
+       * by the smoke's wind response: a fire leaning forty degrees in still air, on a scene
+       * whose every other surface matched to the byte. See `UniformRing`.
+       */
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PLUME_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PLUME_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+/** Both buffers are rings; the slot each draw takes arrives as a dynamic offset. */
+export function createPlumeBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'plume.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: PLUME_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: PLUME_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The blend each material wants.
+ *
+ * **Additive keeps the source alpha out of the destination factor** — a flame is light added
+ * to what is behind it, and multiplying that by one-minus-alpha would make a bright flame
+ * darken the wall behind it. Alpha is the ordinary over-operator smoke wants.
+ */
+function blendState(blend: 'additive' | 'alpha'): GPUBlendState {
+  return blend === 'additive'
+    ? {
+        color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+        alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+      }
+    : {
+        color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+      };
+}
+
+/**
+ * The pipeline for one material and blend.
+ *
+ * **Depth tested, never written.** These are soft quads drawn after the opaque scene; writing
+ * depth would let a puff occlude something behind it that should have shown through.
+ */
+export function plumePipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  material: PlumeMaterial,
+  blend: 'additive' | 'alpha',
+): GPURenderPipeline {
+  const shaders = plumeShaders(material);
+  return cache.get(`plume:${material}:${blend}`, () => ({
+    label: `plume:${material}`,
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'plume.vert', code: shaders.vertexWgsl }),
+      entryPoint: 'main',
+      buffers: plumeVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, {
+        label: `plume.frag:${material}`,
+        code: shaders.fragmentWgsl,
+      }),
+      entryPoint: 'main',
+      targets: [{ format: cache.format, blend: blendState(blend) }],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}

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

@@ -0,0 +1,368 @@
+import { mat3, type mat4 } from 'gl-matrix';
+
+import { LIVE_POINT_SHADOW_MAPS, POINT_SHADOW_POOL } from '../../lightBudget.ts';
+import { OCTAHEDRAL_EDGE } from '../../pointShadowArray.ts';
+import {
+  createFaceRange,
+  DEFAULT_SOURCE_RADIUS,
+  FACE_COUNT,
+  POINT_SHADOW_NEAR,
+  PointShadowImage,
+  pointShadowFaceRotation,
+  pointShadowFaceViewProj,
+  type FaceRange,
+  type PointShadowSource,
+} from '../../pointShadowImage.ts';
+import {
+  OCTAHEDRAL_RESOLVE_FRAG_WGSL,
+  OCTAHEDRAL_RESOLVE_VERT_WGSL,
+} from '../../shaders/generated/octahedralResolve.wgsl.ts';
+import { SHADOW_FORMAT } from './depthPass.ts';
+import { UniformRing } from './uniformRing.ts';
+
+/**
+ * A point light's shadow on this device: one octahedral layer, filled a face at a time.
+ *
+ * **The state is `PointShadowImage`'s and so is every decision in it**, which is what makes
+ * this file short: a cube texture, six single-layer views to attach, one cube view to sample,
+ * and a loop that opens a pass per face. Six shipped bug fixes come with the image rather than
+ * being re-earned here — see that module.
+ *
+ * **Six passes, not six draws into one.** WebGPU attaches exactly one texture subresource to a
+ * depth attachment, so a face is a render pass of its own; the clear that the GL path gets from
+ * `gl.clear` is the pass's own `depthClearValue`. The cost is the same either way — the caster
+ * set is walked once per face — which is why `pointShadowBudget.ts` exists on both backends.
+ */
+
+const USAGE_RENDER_ATTACHMENT = 0x10;
+const USAGE_TEXTURE_BINDING = 0x4;
+const USAGE_UNIFORM_DST = 0x40 | 0x8; // UNIFORM | COPY_DST
+const VISIBILITY_FRAGMENT = 0x2;
+
+/**
+ * Slots for one frame's resolves: every pool layer's six faces, which no budget ever reaches.
+ *
+ * At 256 bytes a slot that is 24 KB of staging for a ceiling nothing approaches — the face
+ * budget is a handful a frame — and the alternative is `allocate` returning null and a face
+ * silently not landing in its layer.
+ */
+const RESOLVE_SLOTS = (POINT_SHADOW_POOL + LIVE_POINT_SHADOW_MAPS) * FACE_COUNT;
+
+/** `mat3x3<f32>` then four scalars, at std140's sixteen-byte columns: see the generated struct. */
+const RESOLVE_UNIFORM_SIZE = 64;
+
+/** Filled per resolved face, at module scope, because a bake runs inside the frame's budget. */
+const faceRotation = mat3.create();
+/** One mat3x3 column, staged so `writeFloats` takes an array without allocating one. */
+const rotationColumn = new Float32Array(3);
+
+/**
+ * Every point light's shadow as one array texture, and the scratch that fills it.
+ *
+ * The WebGPU half of `pointShadowArray.ts`; the reasoning lives there, and this is one texture,
+ * one scratch and a pipeline. **The scratch is a separate texture on this backend too**, and not
+ * for WebGL2's reason: WebGPU rejects a pass outright for holding a texture it is also sampling,
+ * where WebGL2 raises `INVALID_OPERATION` at the draw. Two ways of saying the same thing, and
+ * both say the resolve reads the scratch.
+ */
+export class GpuPointShadowArray {
+  /** The array, as the shader samples it. */
+  readonly view: GPUTextureView;
+  readonly layers: number;
+  /** Where a face is rendered before it is resolved. One, shared by every light. */
+  readonly scratchView: GPUTextureView;
+
+  private readonly texture: GPUTexture;
+  private readonly scratch: GPUTexture;
+  private readonly layerViews: GPUTextureView[] = [];
+  private readonly pipeline: GPURenderPipeline;
+  private readonly bindGroup: GPUBindGroup;
+  /**
+   * A slot per resolved face, not one buffer written six times.
+   *
+   * **`queue.writeBuffer` does not interleave with encoded commands.** Writes are ordered on
+   * the queue timeline and the encoder is submitted afterwards, so six writes between six
+   * passes give all six passes the *last* face's rotation and index — and five of them then
+   * discard every fragment, because `uFaceIndex` does not match. The layer stays empty and the
+   * light stops casting, which reads as a lighting change rather than as a missing upload.
+   *
+   * That is the failure `UniformRing` exists for, described in its own header, and this file
+   * reproduced it exactly. Found by capturing: WebGPU diverged from WebGL2 by seven times and
+   * came out *brighter*, and flipping a coordinate in the resolve changed the frame by not one
+   * pixel — which is what an empty map looks like.
+   */
+  private readonly ring: UniformRing;
+
+  constructor(
+    device: GPUDevice,
+    faceSize: number,
+    lightCount: number,
+    /** Layers above the point pool, for a world's casting rectangles. See `pointShadowArray.ts`. */
+    extraLayers = 0,
+  ) {
+    this.layers =
+      Math.min(lightCount, POINT_SHADOW_POOL) + LIVE_POINT_SHADOW_MAPS + Math.max(0, extraLayers);
+
+    this.texture = device.createTexture({
+      label: 'pointShadow.array',
+      size: [OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, this.layers],
+      format: SHADOW_FORMAT,
+      usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING,
+    });
+    this.view = this.texture.createView({ dimension: '2d-array' });
+    for (let layer = 0; layer < this.layers; layer++) {
+      this.layerViews.push(
+        this.texture.createView({
+          label: `pointShadow.layer${layer}`,
+          dimension: '2d',
+          baseArrayLayer: layer,
+          arrayLayerCount: 1,
+        }),
+      );
+    }
+
+    this.scratch = device.createTexture({
+      label: 'pointShadow.scratch',
+      size: [faceSize, faceSize],
+      format: SHADOW_FORMAT,
+      usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING,
+    });
+    this.scratchView = this.scratch.createView();
+
+    this.ring = new UniformRing(
+      device,
+      RESOLVE_UNIFORM_SIZE,
+      RESOLVE_SLOTS,
+      USAGE_UNIFORM_DST,
+      'pointShadow.resolve.uniforms',
+    );
+    /*
+     * `non-filtering` and `unfilterable-float`, matching `flatPass.ts`: the scratch is a depth
+     * format, whose supported sample types are UnfilterableFloat and Depth and never plain
+     * Float, and nothing here asks the hardware to filter.
+     */
+    const layout = device.createBindGroupLayout({
+      label: 'pointShadow.resolve.layout',
+      entries: [
+        {
+          binding: 1,
+          visibility: VISIBILITY_FRAGMENT,
+          buffer: {
+            type: 'uniform',
+            hasDynamicOffset: true,
+            minBindingSize: RESOLVE_UNIFORM_SIZE,
+          },
+        },
+        {
+          binding: 32,
+          visibility: VISIBILITY_FRAGMENT,
+          texture: { sampleType: 'unfilterable-float' },
+        },
+        { binding: 33, visibility: VISIBILITY_FRAGMENT, sampler: { type: 'non-filtering' } },
+      ],
+    });
+    this.bindGroup = device.createBindGroup({
+      label: 'pointShadow.resolve',
+      layout,
+      entries: [
+        { binding: 1, resource: { buffer: this.ring.buffer, size: RESOLVE_UNIFORM_SIZE } },
+        { binding: 32, resource: this.scratchView },
+        { binding: 33, resource: device.createSampler({ label: 'pointShadow.resolve.sampler' }) },
+      ],
+    });
+    this.pipeline = device.createRenderPipeline({
+      label: 'pointShadow.resolve',
+      layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      vertex: {
+        module: device.createShaderModule({ code: OCTAHEDRAL_RESOLVE_VERT_WGSL }),
+        entryPoint: 'main',
+      },
+      fragment: {
+        module: device.createShaderModule({ code: OCTAHEDRAL_RESOLVE_FRAG_WGSL }),
+        entryPoint: 'main',
+        targets: [],
+      },
+      primitive: { topology: 'triangle-list' },
+      /*
+       * `always`, because this is a copy and not a render: the layer holds whatever the previous
+       * bake of this light left, and a fragment that lost a comparison would leave half of one
+       * image and half of another.
+       */
+      depthStencil: { format: SHADOW_FORMAT, depthWriteEnabled: true, depthCompare: 'always' },
+    });
+  }
+
+  /**
+   * Write the scratch's contents into `layer`'s region for `face`.
+   *
+   * A pass of its own on the caller's encoder, with `load` rather than `clear`: the other five
+   * faces of this layer are already there and must survive. `discard` in the shader is what
+   * keeps this face to its own region.
+   */
+  resolve(
+    encoder: GPUCommandEncoder,
+    layer: number,
+    face: number,
+    far: number,
+    near: number,
+  ): void {
+    const view = this.layerViews[layer];
+    if (view === undefined) return;
+    const slot = this.ring.allocate();
+    if (slot === null) return;
+
+    pointShadowFaceRotation(face, faceRotation);
+    /* WGSL pads a mat3x3 to three four-float columns; the generated struct expects that. */
+    for (let column = 0; column < 3; column++) {
+      rotationColumn[0] = faceRotation[column * 3] as number;
+      rotationColumn[1] = faceRotation[column * 3 + 1] as number;
+      rotationColumn[2] = faceRotation[column * 3 + 2] as number;
+      this.ring.writeFloats(slot, column * 16, rotationColumn);
+    }
+    this.ring.writeInt(slot, 48, face);
+    this.ring.writeFloat(slot, 52, far);
+    this.ring.writeFloat(slot, 56, near);
+    this.ring.writeFloat(slot, 60, OCTAHEDRAL_EDGE);
+
+    const pass = encoder.beginRenderPass({
+      label: 'pointShadow.resolve',
+      colorAttachments: [],
+      depthStencilAttachment: {
+        view,
+        depthLoadOp: 'load',
+        depthStoreOp: 'store',
+      },
+    });
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.bindGroup, [slot]);
+    pass.draw(3);
+    pass.end();
+  }
+
+  /** Start a frame's bakes. See the ring: slots are reused and nothing is freed. */
+  beginFrame(): void {
+    this.ring.reset();
+  }
+
+  /** Upload every slot this frame's resolves took, in one write, before the encoder is submitted. */
+  flush(): void {
+    this.ring.flush();
+  }
+
+  dispose(): void {
+    this.texture.destroy();
+    this.scratch.destroy();
+    this.ring.dispose();
+  }
+}
+
+/** What a face's pass needs from the caller: somewhere to record, and the casters to record. */
+export type PointShadowFacePass = (view: GPUTextureView, viewProj: mat4) => void;
+
+/** And what turns that face into its region of the light's octahedral layer. */
+export type PointShadowResolve = (layer: number, face: number, far: number, near: number) => void;
+
+export class GpuPointShadowMap implements PointShadowSource {
+  readonly size: number;
+  /** Which layer of the shared array this map's image lives in. See `pointShadowMap.ts`. */
+  readonly layer: number;
+
+  private readonly array: () => GpuPointShadowArray | null;
+  private readonly image = new PointShadowImage();
+  private readonly range: FaceRange = createFaceRange();
+
+  constructor(array: () => GpuPointShadowArray | null, layer: number, size: number) {
+    this.array = array;
+    this.layer = layer;
+    this.size = size;
+  }
+
+  get far(): number {
+    return this.image.far;
+  }
+
+  get near(): number {
+    return this.image.near;
+  }
+
+  get sourceRadius(): number {
+    return this.image.sourceRadius;
+  }
+
+  get hasBaked(): boolean {
+    return this.image.hasBaked;
+  }
+
+  get presence(): number {
+    return this.image.presence;
+  }
+
+  matchesSource(
+    x: number,
+    y: number,
+    z: number,
+    range: number,
+    near: number,
+    sourceRadius = DEFAULT_SOURCE_RADIUS,
+    tolerance = 0,
+  ): boolean {
+    return this.image.matchesSource(x, y, z, range, near, sourceRadius, tolerance);
+  }
+
+  advance(dt: number): void {
+    this.image.advance(dt);
+  }
+
+  forget(): void {
+    this.image.forget();
+  }
+
+  /**
+   * Render up to `maxFaces` of the six, resuming a bake already under way.
+   *
+   * Returns how many faces were rendered. `renderFace` is handed the attachment and the face's
+   * view-projection and is expected to open a pass and draw the casters into it — the renderer
+   * owns the encoder and the pipelines, so it owns the pass.
+   *
+   * The scratch matrix is the caller's for the same reason `pointShadowFaceViewProj` takes one:
+   * this runs once per face of every bake and `AGENTS.md` allows no allocation there.
+   */
+  bake(
+    x: number,
+    y: number,
+    z: number,
+    range: number,
+    renderFace: PointShadowFacePass,
+    resolveFace: PointShadowResolve,
+    scratch: mat4,
+    near = POINT_SHADOW_NEAR,
+    sourceRadius = DEFAULT_SOURCE_RADIUS,
+    maxFaces = FACE_COUNT,
+  ): number {
+    /*
+     * What to render now, **and what to render it for**. A bake in flight owns the parameters
+     * it started with; the arguments here only propose one that is not already under way. See
+     * `planBake` for the permanent artefact reading them unconditionally left in a moving
+     * light's map, and `pointShadowMap.ts` for the other backend making the identical call.
+     */
+    const plan = this.image.planBake(x, y, z, range, near, sourceRadius, maxFaces, this.range);
+    const { first, last } = plan;
+    if (last <= first) return 0;
+    const array = this.array();
+    if (array === null) return 0;
+
+    for (let face = first; face < last; face++) {
+      renderFace(
+        array.scratchView,
+        pointShadowFaceViewProj(face, plan.x, plan.y, plan.z, plan.near, plan.range, scratch),
+      );
+      resolveFace(this.layer, face, plan.range, plan.near);
+    }
+
+    this.image.completeBake(last, plan.x, plan.y, plan.z, plan.range, plan.near, plan.sourceRadius);
+    return last - first;
+  }
+
+  /** Nothing to free: every GPU object belongs to `GpuPointShadowArray` now. */
+  dispose(): void {}
+}