@driftengine/core 3.62.0 → 4.0.0

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

@@ -245,7 +245,21 @@ export function scatterDepthPipeline(
       targets: [],
     },
     primitive: { topology: 'triangle-list', cullMode: 'none' },
-    depthStencil: { format: shadowFormat, depthWriteEnabled: true, depthCompare: DEPTH_COMPARE },
+    /*
+     * **`less`, not the frame's `DEPTH_COMPARE`, because a shadow map is not reversed.**
+     * `depthConvention.ts` says so in as many words: the cascades are orthographic, where depth
+     * is already linear and a float buffer gains nothing, so `SHADOW_DEPTH_CLEAR` is 1 and
+     * `beginShadowPass` clears to 1. This pipeline took the scene's compare, which under
+     * `REVERSED_DEPTH` is `greater` — and a fragment at depth 0.3 tested with `greater` against a
+     * map cleared to 1 fails. **Nothing was ever written**, so a scatter batch cast no shadow at
+     * all on this backend: no error, no warning, an ordinary-looking frame.
+     *
+     * `depthPass.ts` has had `'less'` for the mesh path all along, which is why meshes cast and
+     * scatter did not, and why it took a scene whose only caster is a scatter batch to show it.
+     * `demo/windField.ts` is that scene — turning directional shadows off there changed 2,628
+     * pixels on WebGL2 and 0 on WebGPU.
+     */
+    depthStencil: { format: shadowFormat, depthWriteEnabled: true, depthCompare: 'less' },
   }));
 }
 

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

@@ -55,6 +55,100 @@ export function mipLevelCount(width: number, height: number): number {
   return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
 
+/**
+ * Somewhere to keep one pipeline per format. `PipelineCache` satisfies it; so does a `Map`.
+ *
+ * Taken as an interface rather than as the class, because the other caller of the chain below is
+ * `@driftengine/ui2d`, which builds its own pipeline from the device and has no cache of the
+ * renderer's to hand.
+ */
+export interface MipPipelines {
+  get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+}
+
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export function generateMipChain(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  texture: GPUTexture,
+  format: GPUTextureFormat,
+  levels: number,
+): void {
+  if (levels < 2) return;
+  const pipeline = mipBlitPipeline(device, pipelines, format);
+  const sampler = device.createSampler({
+    label: 'mip.sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+  });
+  const encoder = device.createCommandEncoder({ label: 'mip.chain' });
+  for (let level = 1; level < levels; level++) {
+    const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+    const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+    const pass = encoder.beginRenderPass({
+      label: `mip.level${level}`,
+      colorAttachments: [
+        { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+      ],
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: source },
+          { binding: 1, resource: sampler },
+        ],
+      }),
+    );
+    pass.draw(3);
+    pass.end();
+  }
+  device.queue.submit([encoder.finish()]);
+}
+
+/**
+ * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting a
+ * linear chain through a pipeline declared for the other one is a gamma error per level.
+ */
+function mipBlitPipeline(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  format: GPUTextureFormat,
+): GPURenderPipeline {
+  return pipelines.get(`surface.mip:${format}`, () => ({
+    label: `surface.mip:${format}`,
+    layout: 'auto' as const,
+    vertex: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'vertexMain',
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'fragmentMain',
+      targets: [{ format }],
+    },
+    primitive: { topology: 'triangle-list' as const },
+  }));
+}
+
 function sourceSize(source: TexImageSource): { width: number; height: number } {
   const candidate = source as {
     width?: number;
@@ -69,15 +163,15 @@ function sourceSize(source: TexImageSource): { width: number; height: number } {
 
 /** An image uploaded once and bound per material. */
 export class GpuSurfaceTexture {
-  readonly view: GPUTextureView;
   readonly sampler: GPUSampler;
 
   private texture: GPUTexture | null;
+  private current: GPUTextureView;
   private readonly format: GPUTextureFormat;
   private readonly mipmapped: boolean;
-  private readonly levels: number;
-  private readonly width: number;
-  private readonly height: number;
+  private levels: number;
+  private width: number;
+  private height: number;
 
   constructor(
     private readonly device: GPUDevice,
@@ -86,36 +180,15 @@ export class GpuSurfaceTexture {
     options: SurfaceTextureOptions = {},
   ) {
     const { width, height } = sourceSize(source);
-    this.width = width;
-    this.height = height;
     this.mipmapped = options.mipmap ?? true;
-    this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
     /* `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. */
     this.format = (options.colorSpace ?? 'linear') === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
-
-    this.texture = device.createTexture({
-      label: 'surface.texture',
-      size: [width, height],
-      format: this.format,
-      mipLevelCount: this.levels,
-      /*
-       * **`RENDER_ATTACHMENT` is required by `copyExternalImageToTexture`, not by the mip
-       * chain**, and the difference matters enough to state.
-       *
-       * This used to say the flag was there "because building the chain renders into levels 1
-       * and below", which is true and is not the reason. The upload itself demands it: Dawn
-       * rejects a destination without `CopyDst | RenderAttachment` outright, whatever its mip
-       * count. Gating it on `levels > 1` therefore breaks every unmipped texture, and the read
-       * of the old comment that led there cost a broken build to disprove.
-       *
-       * So it cannot be dropped to make a sampled-only allocation, and anything that wants one
-       * has to leave `copyExternalImageToTexture` behind and write raw pixels instead, which
-       * trades a driver cost for a CPU readback.
-       */
-      usage: 0x2 | 0x4 | 0x10, // COPY_DST | TEXTURE_BINDING | RENDER_ATTACHMENT
-    });
-    this.view = this.texture.createView();
+    this.width = width;
+    this.height = height;
+    this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
+    this.texture = this.allocate();
+    this.current = this.texture.createView();
 
     const wrap: GPUAddressMode =
       (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
@@ -153,16 +226,64 @@ export class GpuSurfaceTexture {
     this.upload(source);
   }
 
+  /** The view every binding of this image holds. A new one when `update` changes the size. */
+  get view(): GPUTextureView {
+    return this.current;
+  }
+
   /**
-   * Replace the pixels, keeping the texture, its view and its sampler.
+   * Replace the pixels, keeping the handle and its sampler.
    *
-   * The binding a draw loop already holds stays valid, so the swap is a swap rather than a
-   * rebuild — the same argument `surfaceTexture.ts` makes. Not a hot path: it re-uploads the
-   * whole image and rebuilds the chain.
+   * **At the same size, the texture and its view are kept**, so a binding a draw loop already holds
+   * stays valid and the swap is a swap rather than a rebuild — the same argument `surfaceTexture.ts`
+   * makes. Not a hot path: it re-uploads the whole image and rebuilds the chain.
+   *
+   * **At another size, a texture of that size replaces it**, which is what WebGL2's `texImage2D`
+   * does by itself. This used to keep the old size and copy that much of the new image — its
+   * top-left corner, stretched — and a model loader updating a small preview with the real image
+   * 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.
    */
-  update(source: TexImageSource): void {
-    if (this.texture === null) return;
+  update(source: TexImageSource): GPUTexture | null {
+    const replaced = this.texture;
+    if (replaced === null) return null;
+    const { width, height } = sourceSize(source);
+    if (width === this.width && height === this.height) {
+      this.upload(source);
+      return null;
+    }
+    this.width = width;
+    this.height = height;
+    this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
+    this.texture = this.allocate();
+    this.current = this.texture.createView();
     this.upload(source);
+    return replaced;
+  }
+
+  private allocate(): GPUTexture {
+    return this.device.createTexture({
+      label: 'surface.texture',
+      size: [this.width, this.height],
+      format: this.format,
+      mipLevelCount: this.levels,
+      /*
+       * **`RENDER_ATTACHMENT` is required by `copyExternalImageToTexture`, not by the mip
+       * chain**, and the difference matters enough to state.
+       *
+       * This used to say the flag was there "because building the chain renders into levels 1
+       * and below", which is true and is not the reason. The upload itself demands it: Dawn
+       * rejects a destination without `CopyDst | RenderAttachment` outright, whatever its mip
+       * count. Gating it on `levels > 1` therefore breaks every unmipped texture, and the read
+       * of the old comment that led there cost a broken build to disprove.
+       *
+       * So it cannot be dropped to make a sampled-only allocation, and anything that wants one
+       * has to leave `copyExternalImageToTexture` behind and write raw pixels instead, which
+       * trades a driver cost for a CPU readback.
+       */
+      usage: 0x2 | 0x4 | 0x10, // COPY_DST | TEXTURE_BINDING | RENDER_ATTACHMENT
+    });
   }
 
   dispose(): void {
@@ -201,57 +322,6 @@ export class GpuSurfaceTexture {
    * an attachment and a resource at once — rejected, and rejected silently enough to matter.
    */
   private generateMips(texture: GPUTexture): void {
-    const pipeline = this.mipPipeline();
-    const sampler = this.device.createSampler({
-      label: 'surface.mipSampler',
-      magFilter: 'linear',
-      minFilter: 'linear',
-    });
-    const encoder = this.device.createCommandEncoder({ label: 'surface.mips' });
-    for (let level = 1; level < this.levels; level++) {
-      const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
-      const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
-      const pass = encoder.beginRenderPass({
-        label: `surface.mip${level}`,
-        colorAttachments: [
-          { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
-        ],
-      });
-      pass.setPipeline(pipeline);
-      pass.setBindGroup(
-        0,
-        this.device.createBindGroup({
-          layout: pipeline.getBindGroupLayout(0),
-          entries: [
-            { binding: 0, resource: source },
-            { binding: 1, resource: sampler },
-          ],
-        }),
-      );
-      pass.draw(3);
-      pass.end();
-    }
-    this.device.queue.submit([encoder.finish()]);
-  }
-
-  /**
-   * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
-   * a linear chain through a pipeline declared for the other one is a gamma error per level.
-   */
-  private mipPipeline(): GPURenderPipeline {
-    return this.pipelines.get(`surface.mip:${this.format}`, () => ({
-      label: `surface.mip:${this.format}`,
-      layout: 'auto' as const,
-      vertex: {
-        module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-        entryPoint: 'vertexMain',
-      },
-      fragment: {
-        module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
-        entryPoint: 'fragmentMain',
-        targets: [{ format: this.format }],
-      },
-      primitive: { topology: 'triangle-list' as const },
-    }));
+    generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
   }
 }

package/src/render/causticsRenderer.ts

@@ -100,6 +100,8 @@ export class CausticsRenderer {
    * pass: this is light arriving at a surface, not the surface.
    *
    * @param strength scales the whole effect; 1 is the calibrated default.
+   *
+   * Answers whether it drew, which the renderer counts on its frame budget.
    */
   draw(
     gl: WebGL2RenderingContext,
@@ -113,8 +115,8 @@ export class CausticsRenderer {
     windX = 0,
     windZ = 0,
     strength = 1,
-  ): void {
-    if (this.vertexCount === 0) return;
+  ): boolean {
+    if (this.vertexCount === 0) return false;
     const u = this.uniforms;
     gl.useProgram(this.program);
     gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
@@ -161,6 +163,7 @@ export class CausticsRenderer {
     gl.enable(gl.CULL_FACE);
     gl.depthMask(true);
     gl.disable(gl.BLEND);
+    return true;
   }
 
   dispose(gl: WebGL2RenderingContext): void {

package/src/render/depthConvention.ts

@@ -153,6 +153,21 @@ export function glslSceneDepthToNdc(depth: string): string {
   return REVERSED_DEPTH ? `(1.0 - ${depth} * 2.0)` : `(${depth} * 2.0 - 1.0)`;
 }
 
+/**
+ * The same conversion as WGSL, for the hand-written compute shaders that have no GLSL to generate
+ * from.
+ *
+ * **It is the same text, and that is the point of it being here.** The reconstruction resolve picks
+ * the *nearest* of nine depths and dilates that texel's motion, which is the rule every temporal
+ * upscaler uses because an edge's motion belongs to the nearer of the two surfaces meeting there.
+ * Under a reversed buffer the nearest is the largest number, so a shader reading the attachment
+ * without this conversion picks the furthest and drags the background's motion over every
+ * silhouette — a defect that draws a plausible picture and moves the wrong way.
+ */
+export function wgslSceneDepthToNdc(depth: string): string {
+  return REVERSED_DEPTH ? `(1.0 - ${depth} * 2.0)` : `(${depth} * 2.0 - 1.0)`;
+}
+
 /**
  * The clip-space z of the far plane, as GLSL, for geometry that writes a fixed depth.
  *

package/src/render/deviceFeatures.ts

@@ -0,0 +1,77 @@
+/**
+ * What this device can do, asked once, in one place.
+ *
+ * **Not `gpuCapability.ts`, which answers a different question.** That module identifies the
+ * *part* — a renderer string, matched against families known to struggle — so that a consumer can
+ * choose a quality profile. This one reads the optional features and limits a device actually
+ * reports. A weak part may support half precision and a strong one may not; neither answer
+ * predicts the other.
+ *
+ * **One place, because the alternative is each subsystem asking the device itself.** Every
+ * capability below has more than one consumer waiting for it, and a feature string spelled two
+ * ways in two subsystems is a capability that is present in one and absent in the other on the
+ * same machine.
+ *
+ * **Takes the device's shape as a parameter rather than reaching for a global**, which is the
+ * rule `AGENTS.md` applies to persistence applied here — and is what lets every branch below be
+ * asserted without a graphics device.
+ */
+import { indirectSupport } from './backend/api.ts';
+
+/** The subset of a device this needs. A real `GPUDevice` satisfies it. */
+export interface DeviceShape {
+  readonly features: { has(name: string): boolean };
+  readonly limits: Readonly<Record<string, number | undefined>>;
+}
+
+export interface GpuCapabilities {
+  /** Half-precision arithmetic in shaders. */
+  readonly shaderF16: boolean;
+  /** Subgroup operations, which make a compute reduction far cheaper where present. */
+  readonly subgroups: boolean;
+  /** Timestamp queries. Absent by default in more browsers than people expect. */
+  readonly timestampQuery: boolean;
+  /** Whether this backend can be driven from buffers the GPU wrote. See `indirectSupport`. */
+  readonly indirect: boolean;
+  /**
+   * The three compressed families, reported separately.
+   *
+   * **Separately, because a device may have exactly one.** Desktop parts carry block compression,
+   * mobile carries one of the other two, and a single `compressed: boolean` would be true on
+   * every device and useful on none.
+   */
+  readonly compressedBc: boolean;
+  readonly compressedEtc2: boolean;
+  readonly compressedAstc: boolean;
+  /** Limits, with an absent one reported as 0 so arithmetic on it is safe. */
+  readonly maxStorageBufferBytes: number;
+  readonly maxComputeWorkgroupStorageBytes: number;
+  readonly maxComputeInvocationsPerWorkgroup: number;
+}
+
+function limit(device: DeviceShape, name: string): number {
+  /*
+   * Zero rather than undefined for a limit the device does not report. A consumer sizing a buffer
+   * against `undefined` gets NaN and allocates nothing while believing it allocated something;
+   * against 0 it gets a refusal it can see.
+   */
+  return device.limits[name] ?? 0;
+}
+
+export function probeCapabilities(
+  device: DeviceShape,
+  backend: 'webgl2' | 'webgpu',
+): GpuCapabilities {
+  return {
+    shaderF16: device.features.has('shader-f16'),
+    subgroups: device.features.has('subgroups'),
+    timestampQuery: device.features.has('timestamp-query'),
+    indirect: indirectSupport(backend),
+    compressedBc: device.features.has('texture-compression-bc'),
+    compressedEtc2: device.features.has('texture-compression-etc2'),
+    compressedAstc: device.features.has('texture-compression-astc'),
+    maxStorageBufferBytes: limit(device, 'maxStorageBufferBindingSize'),
+    maxComputeWorkgroupStorageBytes: limit(device, 'maxComputeWorkgroupStorageSize'),
+    maxComputeInvocationsPerWorkgroup: limit(device, 'maxComputeInvocationsPerWorkgroup'),
+  };
+}

package/src/render/fog.ts

@@ -0,0 +1,185 @@
+/**
+ * The medium between the camera and everything it can see, as arithmetic.
+ *
+ * **`shaders/fog.ts` was the only copy and it is GLSL**, which two things now make a problem. The
+ * GPU-driven pipeline is written in WGSL and cannot include it, so the second pipeline drew no fog
+ * at all; and a term that exists only as a shader is a term nothing can disagree with, which is the
+ * argument `gpudriven/lit.ts` and `gpudriven/alphaTest.ts` were both written under.
+ *
+ * So this is the expression in TypeScript, and both shaders are checked against it:
+ * `scripts/gpu-parity.mjs` runs the WGSL over generated cases, and `shaders/fog.ts` stays exactly
+ * as it is. **This is a second reader of one decision rather than a second decision** — every
+ * guard, every constant and the order of the two mixes are the GLSL's, and where a line looks odd
+ * that file's header is the long version of why.
+ *
+ * **What it does not carry** is the uniform block. `shaders/fog.ts` declares ten uniforms because a
+ * block that declares everything it uses can be pasted into any program; a function takes them as
+ * one argument instead, and the backends keep their own packing.
+ */
+
+import { resolveAtmosphere, type Atmosphere, type ResolvedAtmosphere } from './atmosphere.ts';
+
+/** A colour as three numbers, matching `render/orderIndependent.ts`'s own `Rgb`. */
+export type Rgb = readonly [number, number, number];
+
+/** Beer-Lambert through a haze layer that thins with height. `uFogMode` 0. */
+export const MEDIUM_FOG = 0;
+/** A ramp between two distances, which is a look rather than a medium. `uFogMode` 1. */
+export const LINEAR_FOG = 1;
+
+export interface FogOptions {
+  readonly colour: Rgb;
+  /** Extinction per metre **at the camera's own height**, not at the base. */
+  readonly density: number;
+  /** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */
+  readonly heightFalloff: number;
+  /** The camera's height, so a fragment's own height is one subtraction away. */
+  readonly eyeY: number;
+  readonly underwaterColour: Rgb;
+  readonly underwaterDensity: number;
+  readonly underwaterFactor: number;
+  /** `MEDIUM_FOG` integrates a medium; `LINEAR_FOG` ramps between near and far. */
+  readonly mode: number;
+  /** Linear mode only: where haze begins, and where it is total. */
+  readonly near: number;
+  readonly far: number;
+}
+
+/**
+ * Linear interpolation **written the way `mix` is defined**, which is not the same arithmetic as
+ * the fused form.
+ *
+ * GLSL and WGSL both define `mix(x, y, a)` as `x * (1 - a) + y * a`. Written `x + (y - x) * a` the
+ * two agree to within rounding everywhere except the endpoints, where the fused form is off by an
+ * ulp — `0.82 + (0.2 - 0.82) * 1` is 0.20000000000000007 rather than 0.2. That is invisible in a
+ * picture and fatal in a parity check, and it is what the first run of this file's tests found: the
+ * reference and the device have to be the same *expression*, not the same function.
+ */
+function mix(x: number, y: number, a: number): number {
+  return x * (1 - a) + y * a;
+}
+
+/** What distance converges toward: the day's haze, or the water column. */
+export function mediumColour(fog: FogOptions): [number, number, number] {
+  const t = fog.underwaterFactor;
+  return [
+    mix(fog.colour[0], fog.underwaterColour[0], t),
+    mix(fog.colour[1], fog.underwaterColour[1], t),
+    mix(fog.colour[2], fog.underwaterColour[2], t),
+  ];
+}
+
+/**
+ * How much of a surface standing at `pointY`, `dist` metres away, is lost to the medium between.
+ * 0 is perfectly clear, 1 is the medium's own colour.
+ */
+export function mediumFog(fog: FogOptions, dist: number, pointY: number): number {
+  /*
+   * **A depth ramp rather than a medium, for worlds authored against one.** Before `near` the air
+   * is perfectly clear, which Beer-Lambert can never be, and height falloff has no meaning here
+   * because a ramp is defined on distance alone. `shaders/fog.ts` argues the whole of it.
+   */
+  if (fog.mode === LINEAR_FOG) {
+    /* A consumer asking for a hard cut writes `far === near`; the guard is why that is a cut. */
+    const span = Math.max(fog.far - fog.near, 1e-4);
+    const ramp = Math.min(1, Math.max(0, (dist - fog.near) / span));
+    if (fog.underwaterFactor <= 0) return ramp;
+    const wetLinear = fog.underwaterDensity * dist;
+    return mix(ramp, 1 - Math.pow(2, -wetLinear * wetLinear * 1.442695), fog.underwaterFactor);
+  }
+
+  const t = (pointY - fog.eyeY) * fog.heightFalloff;
+  /*
+   * `(1 - e^-t)/t`, which tends to 1 as the ray levels out. **Guarded rather than branched**: at
+   * `t = 0` the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
+   */
+  const denom = Math.abs(t) < 1e-4 ? 1e-4 : t;
+  const air = 1 - Math.exp((-fog.density * dist * (1 - Math.exp(-denom))) / denom);
+  if (fog.underwaterFactor <= 0) return air;
+  /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
+     about how the water column reads. */
+  const wet = fog.underwaterDensity * dist;
+  return mix(air, 1 - Math.pow(2, -wet * wet * 1.442695), fog.underwaterFactor);
+}
+
+/** `FogOptions` with its fields writable, which is what a caller holds and refills a frame at a time. */
+export interface FogTarget {
+  colour: [number, number, number];
+  density: number;
+  heightFalloff: number;
+  eyeY: number;
+  underwaterColour: [number, number, number];
+  underwaterDensity: number;
+  underwaterFactor: number;
+  mode: number;
+  near: number;
+  far: number;
+}
+
+/** A target for `atmosphereFog`, allocated once, outside the frame loop. */
+export function createFogTarget(): FogTarget {
+  return {
+    colour: [0, 0, 0],
+    density: 0,
+    heightFalloff: 0,
+    eyeY: 0,
+    underwaterColour: [0, 0, 0],
+    underwaterDensity: 0,
+    underwaterFactor: 0,
+    mode: MEDIUM_FOG,
+    near: 0,
+    far: 1,
+  };
+}
+
+/** `resolveAtmosphere`'s own target, reused, because this runs a frame at a time. */
+const RESOLVED: ResolvedAtmosphere = {
+  fogColor: new Float32Array(3),
+  underwaterColor: new Float32Array(3),
+  fogDensity: 0,
+  fogHeightFalloff: 0,
+  fogEyeY: 0,
+  fogMode: 0,
+  fogNear: 0,
+  fogFar: 1,
+  underwaterFogDensity: 0,
+  underwaterFactor: 0,
+};
+
+/**
+ * The haze an `Environment` makes at a camera's height, as `GpuDrivenView.fog` takes it.
+ *
+ * **The forward path's own decision, handed over rather than made again.** A consumer drawing
+ * both pipelines in one frame has one environment and needs one haze from it, and
+ * `resolveAtmosphere` is where the forward path decides which medium the camera is in and what it
+ * looks like — the density at the eye, the linear ramp's two radii, how far under water the eye
+ * is. This calls it and copies the answer across field for field, so the two pipelines cannot
+ * disagree about where the fog begins or whether the camera is submerged. Both mode numbers are
+ * the shaders' `uFogMode`, which is why no mapping stands between them.
+ *
+ * @param underwater The renderer's `underwaterAtmosphere` quality, which gates the second medium
+ * on the forward path; pass the same.
+ */
+export function atmosphereFog(
+  atmosphere: Atmosphere,
+  eyeY: number,
+  underwater: boolean,
+  out: FogTarget,
+): FogTarget {
+  const medium = resolveAtmosphere(atmosphere, eyeY, underwater, RESOLVED);
+  out.colour[0] = medium.fogColor[0] as number;
+  out.colour[1] = medium.fogColor[1] as number;
+  out.colour[2] = medium.fogColor[2] as number;
+  out.density = medium.fogDensity;
+  out.heightFalloff = medium.fogHeightFalloff;
+  out.eyeY = medium.fogEyeY;
+  out.underwaterColour[0] = medium.underwaterColor[0] as number;
+  out.underwaterColour[1] = medium.underwaterColor[1] as number;
+  out.underwaterColour[2] = medium.underwaterColor[2] as number;
+  out.underwaterDensity = medium.underwaterFogDensity;
+  out.underwaterFactor = medium.underwaterFactor;
+  out.mode = medium.fogMode;
+  out.near = medium.fogNear;
+  out.far = medium.fogFar;
+  return out;
+}