@driftengine/core 3.63.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

@@ -34,23 +34,33 @@ export declare function generateMipChain(device: GPUDevice, pipelines: MipPipeli
 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.
      *
-     * 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;
+    update(source: TexImageSource): GPUTexture | null;
+    private allocate;
     dispose(): void;
     private upload;
     /**

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

@@ -127,9 +127,9 @@ function sourceSize(source) {
 export class GpuSurfaceTexture {
     device;
     pipelines;
-    view;
     sampler;
     texture;
+    current;
     format;
     mipmapped;
     levels;
@@ -139,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:
@@ -200,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)

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;

package/dist/render/fog.js

@@ -0,0 +1,138 @@
+/**
+ * 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 } from './atmosphere.js';
+/** 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;
+/**
+ * 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, y, a) {
+    return x * (1 - a) + y * a;
+}
+/** What distance converges toward: the day's haze, or the water column. */
+export function mediumColour(fog) {
+    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, dist, pointY) {
+    /*
+     * **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);
+}
+/** A target for `atmosphereFog`, allocated once, outside the frame loop. */
+export function createFogTarget() {
+    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 = {
+    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, eyeY, underwater, out) {
+    const medium = resolveAtmosphere(atmosphere, eyeY, underwater, RESOLVED);
+    out.colour[0] = medium.fogColor[0];
+    out.colour[1] = medium.fogColor[1];
+    out.colour[2] = medium.fogColor[2];
+    out.density = medium.fogDensity;
+    out.heightFalloff = medium.fogHeightFalloff;
+    out.eyeY = medium.fogEyeY;
+    out.underwaterColour[0] = medium.underwaterColor[0];
+    out.underwaterColour[1] = medium.underwaterColor[1];
+    out.underwaterColour[2] = medium.underwaterColor[2];
+    out.underwaterDensity = medium.underwaterFogDensity;
+    out.underwaterFactor = medium.underwaterFactor;
+    out.mode = medium.fogMode;
+    out.near = medium.fogNear;
+    out.far = medium.fogFar;
+    return out;
+}

package/dist/render/frame/alias.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where each transient resource lives in the frame's arena, so that two which are never alive
+ * together share the memory.
+ *
+ * **First fit over slots, in declaration order.** Not best fit and not a bin-packing search:
+ * the input is tens of resources whose order is already meaningful, the packing runs once per
+ * frame composition rather than per frame, and a first-fit result is stable — which matters far
+ * more than a few saved bytes, because an allocator whose output moves between frames moves
+ * every binding with it.
+ *
+ * A slot records the widest resource it has held and the node at which its current occupant
+ * dies. A later resource may take the slot when it is born strictly after that node.
+ */
+import type { Lifetimes } from './lifetime.ts';
+import type { VirtualTable } from './virtual.ts';
+export interface AliasPlan {
+    /** Byte offset into the arena per identifier, or -1 when nothing writes it. */
+    offsets: Int32Array;
+    /** Byte offset of each slot, parallel to `slotEnd` and `slotSize`. */
+    slotAt: Int32Array;
+    /** Node at which each slot's current occupant is last read. */
+    slotEnd: Int32Array;
+    /** Widest resource each slot has held. */
+    slotSize: Int32Array;
+    /** How many slots are in use. */
+    slots: number;
+}
+export declare function createAliasPlan(capacity: number): AliasPlan;
+export declare function planAliases(table: VirtualTable, lifetimes: Lifetimes, out: AliasPlan): number;
+export declare function offsetOf(plan: AliasPlan, id: number): number;

package/dist/render/frame/alias.js

@@ -0,0 +1,61 @@
+import { firstWrite, lastRead } from './lifetime.js';
+import { virtualBytes } from './virtual.js';
+export function createAliasPlan(capacity) {
+    return {
+        offsets: new Int32Array(capacity),
+        slotAt: new Int32Array(capacity),
+        slotEnd: new Int32Array(capacity),
+        slotSize: new Int32Array(capacity),
+        slots: 0,
+    };
+}
+/** Alignment every slot starts on. 256 is the widest uniform-buffer alignment WebGPU requires. */
+const ALIGN = 256;
+function aligned(bytes) {
+    return Math.ceil(bytes / ALIGN) * ALIGN;
+}
+export function planAliases(table, lifetimes, out) {
+    out.offsets.fill(-1);
+    out.slots = 0;
+    let total = 0;
+    for (let id = 0; id < table.count; id += 1) {
+        const born = firstWrite(lifetimes, id);
+        if (born === -1)
+            continue;
+        const dies = lastRead(lifetimes, id);
+        const size = aligned(virtualBytes(table, id));
+        let placed = -1;
+        for (let slot = 0; slot < out.slots; slot += 1) {
+            if ((out.slotEnd[slot] ?? 0) < born) {
+                placed = slot;
+                break;
+            }
+        }
+        if (placed === -1) {
+            placed = out.slots;
+            out.slotAt[placed] = total;
+            out.slotSize[placed] = size;
+            total += size;
+            out.slots = placed + 1;
+        }
+        else if (size > (out.slotSize[placed] ?? 0)) {
+            /*
+             * The slot has to widen, and widening in place would overlap whatever follows it. Retiring
+             * the slot and opening a new one is correct and costs one wasted slot; compacting would
+             * move every offset after it, which is the stability the header refuses to give up.
+             */
+            out.slotEnd[placed] = Number.MAX_SAFE_INTEGER;
+            placed = out.slots;
+            out.slotAt[placed] = total;
+            out.slotSize[placed] = size;
+            total += size;
+            out.slots = placed + 1;
+        }
+        out.offsets[id] = out.slotAt[placed] ?? 0;
+        out.slotEnd[placed] = dies;
+    }
+    return total;
+}
+export function offsetOf(plan, id) {
+    return plan.offsets[id] ?? -1;
+}