@driftengine/core 3.62.0 → 4.0.0

package/dist/render/backend/webgpu/scatterPass.js

@@ -177,7 +177,21 @@ export function scatterDepthPipeline(cache, device, layout, shadowFormat, depthF
             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/dist/render/backend/webgpu/surfaceTexturePass.d.ts

@@ -2,27 +2,65 @@ import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
 export declare function mipLevelCount(width: number, height: number): number;
+/**
+ * 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 declare function generateMipChain(device: GPUDevice, pipelines: MipPipelines, texture: GPUTexture, format: GPUTextureFormat, levels: number): void;
 /** An image uploaded once and bound per material. */
 export declare class GpuSurfaceTexture {
     private readonly device;
     private readonly pipelines;
-    readonly view: GPUTextureView;
     readonly sampler: GPUSampler;
     private texture;
+    private current;
     private readonly format;
     private readonly mipmapped;
-    private readonly levels;
-    private readonly width;
-    private readonly height;
+    private levels;
+    private width;
+    private height;
     constructor(device: GPUDevice, pipelines: PipelineCache, source: TexImageSource, options?: SurfaceTextureOptions);
+    /** The view every binding of this image holds. A new one when `update` changes the size. */
+    get view(): GPUTextureView;
     /**
-     * Replace the pixels, keeping the texture, its view and its sampler.
+     * Replace the pixels, keeping the handle and its sampler.
+     *
+     * **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.
      *
-     * 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 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;
+    update(source: TexImageSource): GPUTexture | null;
+    private allocate;
     dispose(): void;
     private upload;
     /**
@@ -33,9 +71,4 @@ export declare class GpuSurfaceTexture {
      * an attachment and a resource at once — rejected, and rejected silently enough to matter.
      */
     private generateMips;
-    /**
-     * 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;
 }

package/dist/render/backend/webgpu/surfaceTexturePass.js

@@ -48,6 +48,75 @@ fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
 export function mipLevelCount(width, height) {
     return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
+/**
+ * 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, pipelines, texture, format, levels) {
+    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, pipelines, format) {
+    return pipelines.get(`surface.mip:${format}`, () => ({
+        label: `surface.mip:${format}`,
+        layout: 'auto',
+        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' },
+    }));
+}
 function sourceSize(source) {
     const candidate = source;
     const width = candidate.videoWidth ?? candidate.width ?? 0;
@@ -58,9 +127,9 @@ function sourceSize(source) {
 export class GpuSurfaceTexture {
     device;
     pipelines;
-    view;
     sampler;
     texture;
+    current;
     format;
     mipmapped;
     levels;
@@ -70,35 +139,15 @@ export class GpuSurfaceTexture {
         this.device = device;
         this.pipelines = pipelines;
         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 = (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
         /*
          * Nearest where the caller said their pixels are the subject. `mipmapFilter` stays as it was:
@@ -131,17 +180,63 @@ export class GpuSurfaceTexture {
         });
         this.upload(source);
     }
+    /** The view every binding of this image holds. A new one when `update` changes the size. */
+    get view() {
+        return this.current;
+    }
     /**
-     * Replace the pixels, keeping the texture, its view and its sampler.
+     * Replace the pixels, keeping the handle and its sampler.
+     *
+     * **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.
      *
-     * 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 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) {
-        if (this.texture === null)
-            return;
+        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;
+    }
+    allocate() {
+        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() {
         if (this.texture === null)
@@ -176,53 +271,6 @@ export class GpuSurfaceTexture {
      * an attachment and a resource at once — rejected, and rejected silently enough to matter.
      */
     generateMips(texture) {
-        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.
-     */
-    mipPipeline() {
-        return this.pipelines.get(`surface.mip:${this.format}`, () => ({
-            label: `surface.mip:${this.format}`,
-            layout: 'auto',
-            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' },
-        }));
+        generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
     }
 }

package/dist/render/causticsRenderer.d.ts

@@ -57,7 +57,9 @@ export declare 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, camera: FrameView, timeSeconds: number, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, windX?: number, windZ?: number, strength?: number): void;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, windX?: number, windZ?: number, strength?: number): boolean;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/causticsRenderer.js

@@ -62,10 +62,12 @@ 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, camera, timeSeconds, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, windX = 0, windZ = 0, strength = 1) {
         if (this.vertexCount === 0)
-            return;
+            return false;
         const u = this.uniforms;
         gl.useProgram(this.program);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
@@ -109,6 +111,7 @@ export class CausticsRenderer {
         gl.enable(gl.CULL_FACE);
         gl.depthMask(true);
         gl.disable(gl.BLEND);
+        return true;
     }
     dispose(gl) {
         for (const buffer of this.buffers)

package/dist/render/depthConvention.d.ts

@@ -139,6 +139,18 @@ export declare function conventionalDepth(stored: number): number;
  * `%s` is the name of the depth variable at the call site.
  */
 export declare function glslSceneDepthToNdc(depth: string): string;
+/**
+ * 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 declare function wgslSceneDepthToNdc(depth: string): string;
 /**
  * The clip-space z of the far plane, as GLSL, for geometry that writes a fixed depth.
  *

package/dist/render/depthConvention.js

@@ -145,6 +145,20 @@ export function conventionalDepth(stored) {
 export function glslSceneDepthToNdc(depth) {
     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) {
+    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/dist/render/deviceFeatures.d.ts

@@ -0,0 +1,32 @@
+/** 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;
+}
+export declare function probeCapabilities(device: DeviceShape, backend: 'webgl2' | 'webgpu'): GpuCapabilities;

package/dist/render/deviceFeatures.js

@@ -0,0 +1,41 @@
+/**
+ * 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.js';
+function limit(device, name) {
+    /*
+     * 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, backend) {
+    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/dist/render/fog.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { type Atmosphere } 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 declare const MEDIUM_FOG = 0;
+/** A ramp between two distances, which is a look rather than a medium. `uFogMode` 1. */
+export declare 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;
+}
+/** What distance converges toward: the day's haze, or the water column. */
+export declare function mediumColour(fog: FogOptions): [number, number, number];
+/**
+ * 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 declare function mediumFog(fog: FogOptions, dist: number, pointY: number): number;
+/** `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 declare function createFogTarget(): FogTarget;
+/**
+ * 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 declare function atmosphereFog(atmosphere: Atmosphere, eyeY: number, underwater: boolean, out: FogTarget): FogTarget;